Skip to content

Commit 2e347ac

Browse files
committed
docs(agent): scope the 0.12.0 ledger's v2 entries to logged-in projects
Only migration 10 applies to every project; check refuses to run until it is applied, logged in or not. The v2 entries (pre-v2 runtime rules, edited and copied rules, rule create's requestId) matter only when info --json reports loggedIn: logged out, nothing is reconciled and runtime rules are skipped as before.
1 parent e2eb315 commit 2e347ac

1 file changed

Lines changed: 40 additions & 42 deletions

File tree

‎packages/cli/src/agent/update.md‎

Lines changed: 40 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -295,48 +295,46 @@ narrowed by hand.
295295

296296
### Migrating to 0.12.0
297297

298-
**The CLI speaks the Taskless v2 rule API, and a rule is addressed by
299-
its own id: its directory name under `.taskless/rules/<engine>/`.**
300-
Five things follow for existing rules.
301-
302-
**Rules issued before 0.12.0 are treated as locally written.** They
303-
came through the v1 API, which v2 does not know, so reconcile answers
304-
them `unknown` and nothing can restore them. An ast-grep or Vale rule
305-
keeps running, as any rule you wrote yourself. A runtime rule does not:
306-
an `unknown` runtime rule never executes, so `check` skips it and names
307-
it. Regenerate each such runtime rule with
308-
`%(TASKLESS_CLI)s agent create-remote-rule`, then delete the old
309-
directory. List them with `%(TASKLESS_CLI)s check --json` and read
310-
`skipped`.
311-
312-
**An edited issued rule fails `check`.** Logged in, `check` compares
313-
every file of every issued rule, of every engine, with what Taskless
314-
issued. An edited ast-grep or Vale rule does not run and fails the run,
315-
naming each changed, removed or added file; an edited runtime rule does
316-
not run. Do not edit a rule back by hand: run
317-
`%(TASKLESS_CLI)s rule restore <ruleId>`, which writes only bytes whose
318-
signatures verify. On a plan without rule recovery it prints how to
319-
recover the rule from git instead. `check` itself never rewrites a rule.
320-
321-
**A copied or renamed issued rule fails `check` too.** A rule under a
322-
new id that still carries a file Taskless issued to another rule does
323-
not run, and the failure names the rule it came from. If the original
324-
was deleted, the pair is reported as one rename: restore the original
325-
with `rule restore <originalId>`, then delete the copy. Never restore
326-
the copy's own id.
327-
328-
**`rule create --json` prints `requestId`, not `ruleId`.** The old
329-
field always held the request id. The ids of the rules written are in
330-
`rules`, and those are what `rule improve`, `rule restore`,
331-
`rule revisions` and `rule rollback` take. Update anything that read
332-
`ruleId` from `rule create`.
333-
334-
**Run `%(TASKLESS_CLI)s init` once.** Migration 10 moves test files an
335-
earlier migration left in `.taskless/sg/rule-tests/` (from rules whose
336-
ids ended in a timestamp) into each rule's `.tests/`, and removes the
337-
emptied legacy directory. A test that matches no rule is left where it
338-
is. `check` refuses to run until the project is migrated, and names
339-
`init`. Commit the moved files.
298+
**Every project: run `%(TASKLESS_CLI)s init` once.** Migration 10 moves
299+
test files an earlier migration left in `.taskless/sg/rule-tests/` (from
300+
rules whose ids ended in a timestamp) into each rule's `.tests/`, and
301+
removes the emptied legacy directory. A test that matches no rule is
302+
left where it is. `check` refuses to run until the project is migrated,
303+
logged in or not, and names `init`. Commit the moved files.
304+
305+
**Only if `loggedIn` is `true` in `%(TASKLESS_CLI)s info --json`:** the
306+
CLI now speaks the Taskless v2 rule API, which addresses a rule by its
307+
own id (its directory name under `.taskless/rules/<engine>/`) and checks
308+
every issued rule against what Taskless issued. Logged out, nothing is
309+
checked, runtime rules are skipped as before, and none of the four
310+
entries below applies.
311+
312+
- **Rules issued before 0.12.0 are treated as locally written.** They
313+
came through the v1 API, which v2 does not know, so reconcile answers
314+
them `unknown` and nothing can restore them. An ast-grep or Vale rule
315+
keeps running, as any rule you wrote yourself. A runtime rule does
316+
not: an `unknown` runtime rule never executes, so `check` skips it and
317+
names it in `skipped` under `--json`. Regenerate each one with
318+
`%(TASKLESS_CLI)s agent create-remote-rule`, then delete the old
319+
directory.
320+
- **An edited issued rule fails `check`.** An edited ast-grep or Vale
321+
rule does not run and fails the run, naming each changed, removed or
322+
added file; an edited runtime rule does not run. Do not edit a rule
323+
back by hand: run `%(TASKLESS_CLI)s rule restore <ruleId>`, which
324+
writes only bytes whose signatures verify. On a plan without rule
325+
recovery it prints how to recover the rule from git instead. `check`
326+
itself never rewrites a rule.
327+
- **A copied or renamed issued rule fails `check` too.** A rule under a
328+
new id that still carries a file Taskless issued to another rule does
329+
not run, and the failure names the rule it came from. If the original
330+
was deleted, the pair is reported as one rename: restore the original
331+
with `rule restore <originalId>`, then delete the copy. Never restore
332+
the copy's own id.
333+
- **`rule create --json` prints `requestId`, not `ruleId`.** The old
334+
field always held the request id. The ids of the rules written are in
335+
`rules`, and those are what `rule improve`, `rule restore`,
336+
`rule revisions` and `rule rollback` take. Update anything that read
337+
`ruleId` from `rule create`.
340338

341339
**Files over 128KB are linted again.** 0.11.2 skipped any target file
342340
over 128KB that a matcher's section reached, naming it in a `notices`

0 commit comments

Comments
 (0)