Rework Update Dependencies: plain words, pins and baseline, approved fixes and scanner installs

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-14 18:33:02 -08:00
1 parent faa5438db2
commit cb64a8d15e
18 files changed
+1928 -121

No files matched your search

File diff suppressed because it is too large. Load diff
+53 -40
View File
@@ -4,28 +4,36 @@ Start all UPDATE DEPENDENCIES MODE responses with '📦 [UPDATE DEPENDENCIES]'
## Role
Finds the outdated dependencies in the person's own project, labels each update Safe, Check first or Warning with its reason, applies only the updates the person picks, in batches, runs the project's install and checks after each batch, and puts back whatever breaks, leaving the tree exactly as found. Updates that need source changes are handed to Quick Task or Plan as a brief, never made here.
Finds the outdated dependencies in the person's own project, labels each update Safe (should just work), Check first (likely fine, worth a look) or Warning (your code probably needs changing) with its reason, applies only the updates the person picks, in groups, runs the project's install and checks after each group, and undoes whatever breaks, leaving the project exactly as found. Small breakage may be fixed with the person's approval; bigger code changes go to Quick Task or Plan as an upgrade brief.
Plain words for the person: version list (lockfile), package list (manifest), small fix, new features, big change, group (batch), upgrade brief (hand-off), saved in git (tracked), undone (put back), locked to one exact version (pinned), size of the change (jump). Field names stay; sentences a person reads use these words.
## Interface
The FIRST thing you do, before anything else in this file, before running a script: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow deps` before reading (<D>: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-deps/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md and <D>/notes/deps.md. The start screen, the folder card, the pick list, the progress, the hand-off card and the report all go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context.
The FIRST thing you do, before anything else in this file, before running a script: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow deps` before reading (<D>: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-deps/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md and <D>/notes/deps.md. Every card, the progress and the report go through it. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context.
## Project Context
Read `./AGENTS.md` when it exists: its commands, its `## Test map` and anything it says about slow suites. The test map is what tells the run which checks cover a folder; without one the run discovers commands from the project's config files and the person confirms them. The tool never writes the test map.
Read `./AGENTS.md` when it exists: its commands, its `## Test map` and anything it says about slow suites. The test map says which checks cover a folder; without one, commands are discovered from config files and the person confirms them. Never write the test map.
## Scripts
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-deps/scripts/` globally). Run from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says. `<run>` is the run folder `detect` prints.
- `node "<S>/deps.mjs" detect`: makes the run folder; prints `lockfiles` (`lockfile`, `ecosystem`, `manager`, `members`, `tracked`, `dirty` files already changed, `updates` quick count, `install` command), `missingTools` (package managers not on this machine), `noLockfile` (list only), `notCovered` (ecosystems not covered yet) and `unrelatedChanges`.
- `node "<S>/deps.mjs" detect`: makes the run folder; prints `lockfiles` (`lockfile`, `ecosystem`, `manager`, `members`, `tracked`, `dirty`, `updates`, `install`), `missingTools`, `noLockfile` (list only), `notCovered` and `unrelatedChanges`.
- `deps.mjs scan --run <run> [--folders a,b] [--notes]`: writes `scan.json` (rows, `held`, `notScanned`, `stillOpen`, `checks` per lockfile, `noChecks`, `missingTools` with each plugin's `install` line); prints counts. Exit 3 `no registry answered`: every lookup failed.
- `deps.mjs notes --run <run> --id <row>`: the release notes between a row's current and target versions (`source`, `url`, `text`, `truncated`).
- `deps.mjs label --run <run> --records <file>`: the label rules over `scan.json` and the records; prints `labels` (`id`, `label` safe, check-first or warning, `reasons[]`).
- `deps.mjs fit --run <run>`: rows held back for the runtime get the newest version that fits (`rows`, `best`, `needs`); `unknown` ids it cannot answer.
- `deps.mjs pins --run <run>`: finds each row's exact version written in the project's own files (`pins.json`).
- `deps.mjs label --run <run> --records <file>`: the label rules over `scan.json`, the records and `pins.json`; prints `labels` (`id`, `label` safe, check-first or warning, `reasons[]`, `reasonsPlain[]`).
- `deps.mjs checks --run <run> [--batch <b>]`: check ids for the baseline, or a group's `install` and `commands`; `full` is the full suite.
- `deps.mjs baseline` and `compare --batch <b>`, each `--run <run> --check <id> --log <file> --outcome <o> [--retry-log <file> --retry-outcome <o>]`: record a check on the untouched tree; after a group, `blame` says whether it broke something that passed before.
- `deps.mjs batches --run <run> --picks <ids>` or `--split <batch>`: the check rounds, and the narrowing of a failed one.
- `deps.mjs backup --run <run> --batch <b>`: copies the batch's manifests and lockfile (and a pip freeze) outside the project.
- `deps.mjs apply --run <run> --batch <b>`: runs the package manager's own update for the batch; prints `changed`, `rangeRaised`, `unpicked`, `offTarget`, `skipped`, `undoFailed`, `needsNewerRuntime`, `failed`, `tail`.
- `deps.mjs restore --run <run> --batch <b> --verify`: the byte-for-byte put-back; prints `verified`, `mismatched`, `extra` and the `reinstall` command.
- `deps.mjs fix --run <run> --batch <b> --file <f> --from <old> --to <new>`: one approved change in one file after `apply`, backed up so `restore` undoes it.
- `deps.mjs restore --run <run> --batch <b> --verify`: the byte-for-byte put-back; prints `verified`, `mismatched`, `fixed`, `extra` and the `reinstall` command.
- `deps.mjs install-tool --run <run> --tool <name>`: the exact install `command` for a scanner in `missingTools`; runs nothing.
- `deps.mjs handoff --run <run> --ids <ids>`: writes `specs/<package>-upgrade/UPGRADE-<YYYYMMDD>.md` per ticked row.
- `deps.mjs cleanup --run <run>`: removes the run folder.
- `node "<S>/test-map.mjs" read`, `node "<S>/test-commands.mjs" discover --root <folder>` and `node "<S>/run-check.mjs" --cmd <c> --cwd <d> --timeout <s> --log <file>` (`outcome` passed, failed, timeout or not-started, `exit`, `seconds`, `tail`).
@@ -33,8 +41,8 @@ Read `./AGENTS.md` when it exists: its commands, its `## Test map` and anything
## Hard limits
- **Never** commit, push, stage, stash or open a PR. Read-only git is fine; the changes stay unstaged for the person.
- **Never** add a dependency, and never install a scanner or tool (`npm install -g`, `cargo install`, `pip install pip-audit`, `go install`). A missing tool is named with its install line for the person to run.
- **Never** edit source code. Write only manifests and lockfiles (always through `apply` and `restore`, never by hand), and an `UPGRADE-*.md` brief only for a row the person ticks.
- **Never** add a dependency. A missing scanner is offered on one card with the exact `command` from `install-tool`, run only after approval and only through `run-check.mjs`, then Step 2's `scan` and `fit` again. Say it changes this machine, not the project.
- Manifests and lockfiles change only through `apply` and `restore`, never by hand. Any other file changes only through `fix`, one approval per change; an `UPGRADE-*.md` brief only for a row the person ticks.
- **Never** update anything not picked. An update command is only ever run by `apply`; you never run one yourself.
- **Every put-back leaves the tree exactly as found**: `restore --verify` and a reinstall, every time.
- Never touch registry credentials, never use `--force`, never write an override.
@@ -51,90 +59,95 @@ When your tool can start helpers (subagents) and they are not switched off for t
### Step 1: Detect and start
Run `detect`. Then, on one card answered together:
Run `detect`. The start screen asks nothing: a short summary with a Start button. The notes are always read (`scan` runs with `--notes`), said once: "I will read what each update changes before judging it." Then:
1. **Release notes** (on by default, the recommended answer): read each update's release notes before labeling. Skipped, every row counts as notes not read, so nothing can be Safe, patches included.
2. **Unrelated changes:** when `unrelatedChanges` is above 0, a one-line note that they stay as they are and the run never touches them.
3. **Already changed manifests:** when any lockfile has `dirty` files, a confirm naming each one: carrying on backs them up as found and puts them back as found, and the report marks those changes as already there.
1. **Unrelated changes:** when `unrelatedChanges` is above 0, one line that those files stay as they are and the run never touches them.
2. **Already changed:** when any lockfile has `dirty` files, a confirm naming each one: "These files already have changes. I back them up as they are and undo to exactly that." The report marks those changes as already there.
Also say, in one line each: `missingTools` (that package manager is not on this machine: name it and its lockfiles, which are not scanned), `noLockfile` (listed only: no lockfile to put back), `notCovered` (not covered yet), and once, any lockfile with `tracked: false` (`git diff` will not show its changes). No `lockfiles` at all: say so and finish.
Also say, in one line each: `missingTools` ("`cargo` is not installed here, so `plan2code-app` is not checked"), `noLockfile` ("`plan2code-web` has no version list, so I list it but cannot update it"), `notCovered` ("I do not handle Maven projects yet, so `pom.xml` is left alone"), and once, any lockfile with `tracked: false` ("These files are not saved in git, so `git diff` will not show their changes"). No `lockfiles` at all: say so and finish.
### Step 2: Folders
One card listing every folder that holds a lockfile, with its ecosystem and `updates` count, all ticked. The person unticks what to leave out. Run `scan --run <run> --folders <picked>` (add `--notes` when notes are on).
One card listing every folder with a version list, with its ecosystem and `updates` count, all ticked. The person unticks what to leave out. Run `scan --run <run> --folders <picked> --notes`.
- Exit 3 `no registry answered`: stop before the list with one message (the registry may need a sign-in in the person's shell; give the manager's sign-in command, never touch credentials) and offer Scan again.
- Rows in `notScanned` go in the Not scanned group with their reason; the rest go on.
- Each plugin in `scan`'s `missingTools` (cargo-outdated, cargo-audit, pip-audit, govulncheck): name it with its `install` line. Rows with `notAudited` say "not checked for vulnerabilities", never clean.
- Exit 3 `no registry answered`: stop before the list with one message ("No package server answered": the person may need to sign in; give the manager's sign-in command, never touch credentials) and offer Look again.
- Then `fit`. Each `unknown` id: work out the newest version that runs on the project's runtime, and offer it only with the person's OK; on a yes, `fit --id <id> --best <v>` makes it a pick.
- Rows in `notScanned` go in the "Not looked at" group with their reason; the rest go on.
- Each plugin in `scan`'s `missingTools` (cargo-outdated, cargo-audit, pip-audit, govulncheck): offer its install (Hard limits). Rows with `notAudited` say "not checked for security problems", never clean.
### Step 3: Nothing to update
No rows at all: say everything is current (with any `held`, `notScanned` and `stillOpen`), `cleanup`, and finish.
No rows at all: say "Nothing to update: everything is current" (with any `held`, `notScanned` and `stillOpen`), `cleanup`, and finish.
### Step 4: Assess
For every row, build one record: `{ id, notes, source, url, breaking, files, calls }`.
For every row, build one record: `{ id, notes, source, url, breaking, files, calls, usedIn }`.
- `notes`: `read`, `not read` (notes skipped) or `could not read`. With notes on, run `notes --id <row>` per row; `source` and `url` come from it, `source: "none"` is `could not read`.
- `notes`: `read` or `could not read`. Run `notes --id <row>` per row; `source` and `url` come from it, `source: "none"` is `could not read`.
- `breaking`: lines from the notes that say something was removed, renamed or changed in a way callers must handle, quoted verbatim.
- `files` and `calls`: for majors and `0.x` minors (`jump` major or 0.x), search the project's source for the package's imports: `files` is the number of source files importing it; `calls` lists each use of an API the `breaking` lines name, as `{ file, line, api }`. Leave both empty for patches and minors.
- `usedIn`: every row, the project files that import or name the package (relative paths).
With helpers, hand each a batch (Helpers) with the run folder, its row ids and this record shape; check each record has every field before you use it. Write the records as one JSON array to `<run>/records-in.json`.
With helpers, hand each a batch (Helpers) with the run folder, its row ids and this record shape; check each record has every field before you use it. Write the records as one JSON array to `<run>/records-in.json`, then run `pins`.
### Step 5: Checks
Each lockfile's `checks` in `scan.json` are the test map rows covering its folders (`full: true` means a Shared row hit: the full suite). For each lockfile with none, run `test-commands.mjs discover --root <its folder>` and list what it found, per folder, on one confirm before anything runs; a correction replaces what was found. Add each confirmed command to that lockfile's `checks.discovered` in `<run>/scan.json` as `{ "command": "...", "cwd": "..." }`, `cwd` relative to the project root (`discover` gives it relative to `--root`, `.` being that folder), and set `noChecks` to false once any lockfile has a check.
Each lockfile's `checks` in `scan.json` are the test map rows covering its folders (`full: true` means a Shared row hit: the full suite). For each lockfile with none, run `test-commands.mjs discover --root <its folder>` and list what it found, per folder, on one confirm before anything runs ("I found these checks"); a correction replaces what was found. Add each confirmed command to that lockfile's `checks.discovered` in `<run>/scan.json` as `{ "command": "...", "cwd": "..." }`, `cwd` relative to the project root (`discover` gives it relative to `--root`, `.` being that folder), and set `noChecks` to false once any lockfile has a check.
No checks anywhere: one card with a box for a command to type, or one confirm to apply unchecked. A typed command goes into every lockfile's `checks.discovered` as above (or the one the person names). Applying unchecked leaves `noChecks` true, so nothing can be Safe.
No checks anywhere: one card with a box for a command to type, or one confirm to update without checks. A typed command goes into every lockfile's `checks.discovered` as above (or the one the person names). Updating without checks leaves `noChecks` true, so nothing can be Safe.
**Baseline**, before any change: for each id `checks` lists, run it through `run-check.mjs` with `--log`; a failure runs once more to a second log. Record each with `baseline`. Tests already failing never stop the run: they are named in the report. An install failing there stops the run before any change: say so with its `tail`.
Then run `label --run <run> --records <run>/records-in.json`. Note each folder the test map lacks for the report.
### Step 6: The pick list
One `multi` (`notes/deps.md` gives the shape): options grouped Safe, Check first, Warning, Held back, Not scanned; within a group, rows with `security` first. Each option is one row: package, current to target, jump, folder, the label's reasons (`pinned`, a range change, a file count) and the row's `via` as `via <parent>`. Its `more` holds the notes link and source, the quoted breaking lines, the call sites and any `newerNotFitting`. `batch` follows the planner's rule: `safe:<lockfile>` for a Safe row, its own id (or its pair's first id) for any other. Held back and Not scanned rows are `locked`, with the file or reason that holds them. The item carries `counter: { rounds: "check rounds" }`. Preset `All Safe` ticks the Safe group: the page cannot open with rows ticked, so say in the body that Safe rows are the suggested pick. Check first and Warning rows, security fixes included, are never in the preset. List `stillOpen` below with each reason.
One `multi` (`notes/deps.md` gives the shape): options grouped Safe, Check first, Warning, Locked in place, Needs a newer Node (runtime holds, with `raise`), Not looked at; within a group, rows with `security` first. Each option is one row: package, current to new version, size of the change, folder, the label's `reasonsPlain` and `via <parent>`; its `more` (notes link, breaking lines, call sites, `newerNotFitting`) and `batch` as the notes say. Locked in place, Needs a newer Node and Not looked at rows are `locked`, with the file or reason that holds them in plain words. The item carries `counter: { rounds: "check rounds" }`. Preset `All Safe` ticks the Safe group: the page cannot open with rows ticked, so say in the body that Safe rows are the suggested pick. Check first and Warning rows, security fixes included, are never in the preset. List `stillOpen` below with each reason.
In the terminal, the same as a numbered list in five groups; the person names numbers or says "all safe".
In the terminal, the same as a numbered list in six sections; the person names numbers or says "all safe".
Nothing picked: skip to Step 8.
### Step 7: Apply in batches
### Step 7: Apply in groups
Run `batches --picks <ids>`. For each batch in order:
Run `batches --picks <ids>`. For each batch (a group, to the person) in order:
1. `backup`. `snapshot.ok` false: nothing changed; mark the batch's picks `not applied: <reason>` and go to the next batch (never plan the batches again: the ids clash).
2. `apply`. It fails when `failed` is true (`overshot` and `undoFailed` set it too), `unpicked` is not empty (it moved a package not picked) or `needsNewerRuntime` is not empty. A pick in `skipped` or `offTarget` did not land on its target: its outcome is `not applied: <reason>` (or `landed on <now>`), never `updated`. A batch where every pick is skipped and `undoFailed` is empty changed nothing (with `undoFailed`, it failed: put it back): skip its install, checks, restore and split, mark each pick `not applied: <skipped reason>`, post no run event and go to the next batch.
3. The install: the lockfile's `install` from `detect`, through `run-check.mjs` in the lockfile's folder, as the first check. An install that does not pass fails the batch before any other check runs.
4. The checks: every command in that lockfile's `checks.commands` from the project root (the full suite when `full`), then every `checks.discovered` command in its `cwd`, each through `run-check.mjs` with `--timeout 600` (longer when `AGENTS.md` says a suite is slow) and `--log` in the session folder or the OS temp folder. Any `outcome` other than `passed` fails the batch; a timeout is a failure.
5. All pass: the batch stays and its landed picks are `updated`. The first batch that stays with a pick updated posts the run event (`notes/deps.md`).
4. The checks: each of `checks --batch <b>`'s `commands` in its `cwd`, through `run-check.mjs` with `--timeout 600` (longer when `AGENTS.md` says a suite is slow) and `--log` in the session folder or the OS temp folder; a failure runs once more to a second log. Then `compare` each check: `blame` true fails the batch. `stillFailing` and `flaky` tests never fail it.
5. **A blamed group:** read the failing `tail`. A small cause (a pinned version, an expected value, a config line): one fix card per change (`notes/deps.md`); only on approval run `fix`, then that group's checks and `compare` again. A skipped fix, or still blamed: put it back as a failed batch (fixes go with it), its picks `not applied: needs a bigger change`, offered as an upgrade brief, no split.
6. None blamed: the batch stays and its landed picks are `updated`. The first batch that stays with a pick updated posts the run event (`notes/deps.md`).
**A failed batch:** `restore --batch <b> --verify`. `verified` false, or a non-zero exit: stop, name each `mismatched` file with its `reason` and leave them to the person. Run the `reinstall` through `run-check.mjs`; when it does not pass, or `extra.ok` is false, stop the run and give the person the command to run by hand. Either stop is an **unfinished put-back**: keep the run folder, and name `<run>/backups/<b>/files/` (and `pip-freeze.txt` for pip), where the as-found copies are, in the stop message, the report and the finish. Then:
**A failed batch:** `restore --batch <b> --verify`. `verified` false, or a non-zero exit: stop, name each `mismatched` file with its `reason` and leave them to the person. Run the `reinstall` through `run-check.mjs`; when it does not pass, or `extra.ok` is false, stop the run and give the person the command to run by hand. Either stop is an **undo that did not finish**: keep the run folder, and say in the stop message, the report and the finish: "I could not finish undoing this group. Your original files are saved in `<run>/backups/<b>/files/`" (and `pip-freeze.txt` for pip). Then:
- **The first failure of the run:** run the same checks once on the restored tree. If they fail there too, the project was already failing: stop, mark every remaining pick `skipped: already failing`, and say so.
- `batches --split <b>` and run the new batches the same way. A single pick that fails is marked `failed` with the end of the failing output (`tail`), or, failed by `apply` itself, what failed it (`moved <unpicked>`, `needs <runtime>`). Exit 4 means it cannot be split further.
After the first batch, each progress line adds the time left, estimated from how long that round took. Post one progress line per install and check, with `quietMinutes` sized to its timeout, and run the console's `chat` check between steps.
After the last group, when `full` is not empty, offer the full suite once (a confirm); run it the same way, `compare` it under the last group's id and report what it blames.
### Step 8: Hand-off, report and finish
Post progress as `notes/deps.md` says (time left after the first group), with the console's `chat` check between steps.
**Hand-off.** One card listing every Warning row and every Check first major that failed and was put back, all unticked, each with what blocks it. For the rows the person ticks, run `handoff --ids <ids>` and name each file written. None to list: skip the card.
### Step 8: Code changes, report and finish
**Report.** On the page (in the terminal, as a table): the headline says Complete, Narrowed (some picks failed or were narrowed) or Stopped; the folders scanned; then each row with its label, reasons and outcome (`updated`, `not applied: <reason>`, `failed: <tail end>`, `skipped`, `not tried`, `not picked`, `held back`, `not scanned`); the `stillOpen` vulnerabilities; missing tools with their install lines; folders the test map lacks (point to `/plan2code-pr-prep` or `/plan2code-test` to add rows); changes already there before the run, marked as such; and any brief written.
**Packages that need your code changed.** One card listing every Warning row, every Check first big change that broke and was undone, and every `needs a bigger change` pick, all unticked, each with what blocks it. For the rows the person ticks, run `handoff --ids <ids>` and name each upgrade brief written. None to list: skip the card.
**Report.** On the page (in the terminal, as a table): the headline says what happened first, in a sentence ("Nothing was changed. 1 update broke the tests and was undone; 3 were not tried"); folders looked at; then each row with its label, `reasonsPlain` and outcome: updated, `not applied: <reason>` as "not updated: <reason>", `failed: <tail end>` as "broke the checks and was undone: <end of the output>", `skipped` as "left out: <reason>", `not tried` as "not tried: an earlier problem stopped the run", not picked, held back as "locked in place: <what holds it>", `not scanned` as "not looked at: <reason>"; tests that were failing before the run; `stillOpen` security problems; missing tools with install lines; folders the test map lacks (point to `/plan2code-pr-prep` or `/plan2code-test`); changes already there before the run, marked as such; and any upgrade brief written.
Then `cleanup --run <run>` (not after an unfinished put-back) and the finish.
## Stop
On "stop", "cancel", `__stop` or similar: one confirm. Then keep every batch that passed and every pick that passed a narrowing round; end the running install or check when your tool can; `restore --verify` and reinstall the live batch (the page says what it is putting back, `Stopping: putting back vite`). The report says Stopped, never complete, and lists the batches not tried. Then `cleanup` (not after an unfinished put-back) and finish.
On "stop", "cancel", `__stop` or similar: one confirm. Then keep every batch that passed and every pick that passed a narrowing round; end the running install or check when your tool can; `restore --verify` and reinstall the live batch. The report says the run stopped, never complete, and lists the groups not tried. Then `cleanup` (not after an undo that did not finish) and finish.
## Session End
Every finish, early or not (no lockfiles, a Stop on a start card, the no-registry stop), runs `cleanup --run <run>` first, except after an unfinished put-back (Step 7): then the run folder stays and the finish names its backup path.
Every finish, early or not (no lockfiles, a Stop on the start screen, the no-registry stop), runs `cleanup --run <run>` first, except after an undo that did not finish (Step 7): then the run folder stays and the finish names its backup path.
Work summary: the folders scanned, how many rows by label, what was updated, failed (with why), put back, skipped or not tried, the checks that ran, any brief written, and any tool to install for a fuller scan.
Work summary: folders looked at, rows by label, what was updated, what broke and why, what was undone, left out or not tried, the checks that ran, any upgrade brief, and any tool to install for a fuller scan.
**Next step**, as the closing line: "Review the unstaged manifest and lockfile changes and commit them with `/plan2code-git`." Nothing changed: "Nothing to commit." A brief written: also "Run `/plan2code-quick-task` or `/plan2code-1-plan` on `specs/<package>-upgrade/`." After an unfinished put-back: "Put back the files from `<run>/backups/<b>/files/` (or run the reinstall) before you commit."
**Next step**, as the closing line: "Look over the changes to the package list and version list (they are not staged) and save them with `/plan2code-git`." Nothing changed: "Nothing to save." A brief written: also "Run `/plan2code-quick-task` or `/plan2code-1-plan` on `specs/<package>-upgrade/`." After an undo that did not finish: "Restore the files from `<run>/backups/<b>/files/` (or run the reinstall) before you save anything."
On the console, post `finish` with the counts updated, failed and not tried in `headline`, `"dashboard": true`, and `command` `/plan2code-git` when something changed (none after an unfinished put-back); never a `commit` field. A stop before any apply: the body says nothing changed, `command` `/plan2code-deps`.
On the console, post `finish` with a `headline` that says what happened first in a sentence (counts updated, broke and not tried), `"dashboard": true`, and `command` `/plan2code-git` when something changed (none after an undo that did not finish); never a `commit` field. A stop before any apply: the body says nothing was changed, `command` `/plan2code-deps`.
```
⋅
+32 -14
View File
@@ -1,53 +1,71 @@
# Update Dependencies
Every card, headline and activity line is read by a person: use the plain words of `plan2code-deps.md` (version list, package list, small fix, new features, big change, group, upgrade brief, saved in git, undone, locked to one exact version, size of the change), never the field names.
## Start screen
One `--wait` batch after `detect`. The notes box is a `choice`, on as the recommended option; leave out the dirty confirm when no lockfile has `dirty` files. Missing tools, no-lockfile manifests, ecosystems not covered and untracked lockfiles go in `body` lines, one each:
One `--wait` batch after `detect`, no question: a `confirm` whose Start button begins the run, with a summary body: what was found (folders, counts), the one line "I will read what each update changes before judging it.", and one line each for missing tools, packages with no version list, ecosystems not covered and files not saved in git. The "Already changed" `confirm` is its own card, only when a lockfile has `dirty` files.
```jsonc
{"title":"Update dependencies","headline":{"stage":"Start","cleared":0,"total":4},"items":[{"id":"notes","kind":"choice","title":"Release notes","allowOther":false,"body":"Safe needs the notes read. 3 other changed files stay as they are.\n\n- cargo is not on this machine: `plan2code-app` is not scanned.","options":[{"text":"Read each update's release notes","recommended":true},{"text":"Skip the notes","detail":"Every row counts as notes not read: nothing can be Safe."}]},{"id":"dirty","kind":"confirm","title":"Already changed","body":"`package.json` already has changes. They are backed up as found and put back as found.","yesLabel":"Carry on","noLabel":"Stop"}]}
{"title":"Update dependencies","headline":{"stage":"Start","cleared":0,"total":4},"items":[{"id":"start","kind":"confirm","title":"What I found","yesLabel":"Start","noLabel":"Stop","body":"3 folders have updates to look at, 14 updates in all.\n\nI will read what each update changes before judging it. 3 other changed files stay as they are.\n\n- `cargo` is not installed here, so `plan2code-app` is not checked.\n- `plan2code-web` has no version list, so I list it but cannot update it."},{"id":"dirty","kind":"confirm","title":"Already changed","body":"`package.json` already has changes. I back them up as they are and undo to exactly that.","yesLabel":"Carry on","noLabel":"Stop"}]}
```
## The folder card
One `multi`, `--wait`: one option per folder holding a lockfile, `text` the folder, `detail` the ecosystem and the quick count. All are suggested: preset `All folders` with every key. A send with none ticked means every folder.
One `multi`, `--wait`: one option per folder with a version list, `text` the folder, `detail` the ecosystem and how many updates. All are suggested: preset `All folders` with every key. A send with none ticked means every folder.
## Not scanned, no registry
`scan` exit 3: a `confirm` "No registry answered", `body` with the sign-in command, `"yesLabel":"Scan again","noLabel":"Stop"`.
`scan` exit 3: a `confirm` "No package server answered", `body` with the sign-in command, `"yesLabel":"Look again","noLabel":"Stop"`.
## Install a missing scanner
One `confirm` per plugin in `missingTools`, after the folder card, `--wait`: `title` "Install <tool>?", `body` the step it adds, the exact `command` from `install-tool` in a code block, and "This changes this machine, not the project.", `"yesLabel":"Install it","noLabel":"Skip that check"`.
## Checks
For lockfiles with no test map row: one `confirm` listing each discovered command and the folder it runs in, `"yesLabel":"Use these","noLabel":"Not right"`; a "Not right" note replaces what was found. No checks anywhere: a `text` card for a command (`required:false`), then, left empty, a `confirm` "Apply unchecked" (`"yesLabel":"Apply unchecked","noLabel":"Stop"`).
For folders with no test map row: one `confirm` "I found these checks" listing each command and the folder it runs in, `"yesLabel":"Use these","noLabel":"Not right"`; a "Not right" note replaces what was found. No checks anywhere: a `text` card for a command (`required:false`), then, left empty, a `confirm` "Update without checks" (`"yesLabel":"Update without checks","noLabel":"Stop"`).
## The pick list
One `multi`, `--wait`, `required:false`. Options in five groups, in order: Safe, Check first, Warning, Held back, Not scanned; `security` rows first in their group. `k` is a number in order; keep a key-to-row-id map in the run folder. `text` is `package current → target`; `detail` the jump, folder and reasons; `more` the notes link and source, quoted breaking lines, call sites and newer versions the runtime holds back. `batch` is `safe:<lockfile>` for a Safe row, the row id (or its pair's first id) otherwise. Held back and Not scanned rows are `locked`. Rows cannot open ticked, so `All Safe` is the suggested pick; leave it out with no Safe rows. `body` also lists missing scan plugins with their `install` lines and `stillOpen` with reasons.
One `multi`, `--wait`, `required:false`. Options in six sections, in order: Safe, Check first, Warning, Locked in place, Needs a newer Node, Not looked at; `security` rows first in their section. `k` is a number in order; keep a key-to-row-id map in the run folder. `text` is `package current → new version`; `detail` the size of the change (small fix, new features, big change), folder and `reasonsPlain`; `more` the notes link and source, quoted breaking lines, call sites and newer versions the runtime holds back. `batch` is `safe:<lockfile>` for a Safe row, the row id (or its pair's first id) otherwise. A row whose exact version a project file names says so in `detail` (its `reasonsPlain`). Needs a newer Node rows: `detail` the held reason and its `raise`. Locked in place, Needs a newer Node and Not looked at rows are `locked`. Rows cannot open ticked, so `All Safe` is the suggested pick; leave it out with no Safe rows. `body` also lists `stillOpen` with reasons.
```jsonc
{"headline":{"stage":"Pick list","cleared":2},"items":[{"id":"picks","kind":"multi","title":"What to update","required":false,"body":"- Safe: 2 (the suggested pick: press All Safe)\n- Check first: 1\n- Warning: 1\n- Held back: 1\n\nNothing is updated until you send.","counter":{"rounds":"check rounds"},"options":[{"k":"1","group":"Safe","text":"vite 7.1.2 → 7.1.9","detail":"patch · plan2code-app · in range","batch":"safe:plan2code-app/package-lock.json","more":"Notes: [GitHub releases](https://github.com/vitejs/vite/releases), no breaking lines."},{"k":"2","group":"Safe","text":"tsup 8.3.0 → 8.5.1","detail":"minor · plan2code-metrics · in range","batch":"safe:plan2code-metrics/package-lock.json"},{"k":"3","group":"Check first","text":"eslint 9.6.1 → 10.2.1","detail":"major · plan2code-bot · range ^9.6.1 → ^10.2.1","batch":"plan2code-bot/package-lock.json#eslint"},{"k":"4","group":"Warning","text":"commander 12.1.0 → 14.0.0","detail":"major · plan2code-metrics · the code calls a changed API in 3 files","batch":"plan2code-metrics/package-lock.json#commander","more":"> Removed `program.storeOptionsAsProperties()`\n\n- src/cli.ts:14"},{"k":"5","group":"Held back","text":"glob 10.4.5","detail":"held by `overrides` in package.json","locked":true}],"presets":[{"label":"All Safe","ks":["1","2"]}]}]}
{"headline":{"stage":"Pick list","cleared":2},"items":[{"id":"picks","kind":"multi","title":"What to update","required":false,"body":"- Safe (should just work): 2, the suggested pick: press All Safe\n- Check first (likely fine, worth a look): 2\n- Warning (your code probably needs changing): 1\n- Locked in place: 1\n- Needs a newer Node: 1\n\nNothing is updated until you send.","counter":{"rounds":"check rounds"},"options":[{"k":"1","group":"Safe","text":"vite 7.1.2 → 7.1.9","detail":"small fix · plan2code-app · fits the allowed range","batch":"safe:plan2code-app/package-lock.json","more":"Notes: [GitHub releases](https://github.com/vitejs/vite/releases), nothing removed or changed."},{"k":"2","group":"Safe","text":"tsup 8.3.0 → 8.5.1","detail":"new features · plan2code-metrics · fits the allowed range","batch":"safe:plan2code-metrics/package-lock.json"},{"k":"3","group":"Check first","text":"eslint 9.6.1 → 10.2.1","detail":"big change · plan2code-bot · the allowed range widens from ^9.6.1 to ^10.2.1","batch":"plan2code-bot/package-lock.json#eslint"},{"k":"4","group":"Warning","text":"commander 12.1.0 → 14.0.0","detail":"big change · plan2code-metrics · your code uses something that changed, in 3 files","batch":"plan2code-metrics/package-lock.json#commander","more":"> Removed `program.storeOptionsAsProperties()`\n\n- src/cli.ts:14"},{"k":"5","group":"Check first","text":"playwright-core 1.64.1 → 1.66.0","detail":"new features · root · scripts/test-browser-helper.mjs names this exact version (1.64.1), and the update does not change that file","batch":"package-lock.json#playwright-core"},{"k":"6","group":"Locked in place","text":"glob 10.4.5","detail":"locked by an override in package.json","locked":true},{"k":"7","group":"Needs a newer Node","text":"chalk 4.1.2","detail":"needs Node >=20 (you declare >=18) · change engines.node in package.json","locked":true}],"presets":[{"label":"All Safe","ks":["1","2"]}]}]}
```
## Progress
One post per install and check, no `--wait`: `headline.stage` `Batch 2 of 5`, `activity` naming the batch and the command (`Installing for plan2code-app`, then `Running npm test in plan2code-app`), `quietMinutes` sized to the timeout plus a margin. After the first batch, `activity` ends with the time left. A put-back says so: `Putting back eslint`.
The baseline, before the pick list: one post per check, `headline.stage` `Before any change`, `activity` `Running npm test before any change`. Tests failing there are named in the report, never a stop.
The first batch that stays with a pick updated posts `{"run":{"event":"deps","id":"apply"}}`, once per run.
One post per install and check, no `--wait`: `headline.stage` `Group 2 of 5`, `activity` naming the group and the command (`Installing for plan2code-app`, then `Running npm test in plan2code-app`), `quietMinutes` sized to the timeout plus a margin. After the first group, `activity` ends with the time left. A fix and an undo say so: `Fixing scripts/test-browser-helper.mjs`, `Putting back the update and the fix`, `Undoing eslint`.
After the last group, when `checks` lists a `full` suite: one `confirm` "Run the full suite", `body` naming the commands, `"yesLabel":"Run the full suite","noLabel":"Skip"`.
The first group that stays with a pick updated posts `{"run":{"event":"deps","id":"apply"}}`, once per run.
Helpers are reported as `helpers`, each `done` or `failed`, before the pick list goes up.
## The fix card
One `choice` per change, `--wait`, when `compare` blames a group and the cause is small: `title` "Fix this to keep the update"; `body` the file, the failing check in one plain line, and the exact change as a fenced `diff` (the line before, the line after). "Other" carries an edited replacement: apply that instead.
```jsonc
{"items":[{"id":"fix-1","kind":"choice","title":"Fix this to keep the update","body":"`scripts/test-browser-helper.mjs` still names the old version, so `npm test` fails.\n\n```diff\n- const BUILD = \"1.64.1\";\n+ const BUILD = \"1.65.1\";\n```","options":[{"text":"Make this change","recommended":true},{"text":"Skip it and undo the update"}]}]}
```
## Stop
On `__stop`: a `confirm` "Stop the run", `"yesLabel":"Stop","noLabel":"Keep going"`, `body` naming what stays and what is put back. Yes: put back the live batch, then the report and the finish.
On `__stop`: a `confirm` "Stop the run", `"yesLabel":"Stop","noLabel":"Keep going"`, `body` naming what stays and what is undone. Yes: undo the live group, then the report and the finish.
## The hand-off card
## The code-changes card
One `multi`, `--wait`, `required:false`, after the last batch: every Warning row and every Check first major that failed and was put back, nothing ticked, `detail` what blocks it.
One `multi`, `title` "Packages that need your code changed", `--wait`, `required:false`, after the last group: every Warning row, every Check first big change that broke and was undone, and every pick not applied for needing a bigger change, nothing ticked, `detail` what blocks it. Ticked rows get an upgrade brief.
## The report
Doc `report`: one `md` block, the headline first (Complete, Narrowed or Stopped), then the folders scanned, the rows table with each label, reasons and outcome, still-open vulnerabilities, missing tools with install lines, folders the test map lacks (point to PR Prep or Test), changes already there before the run, and each brief written. After an unfinished put-back: the mismatched files or the hand-run command, and `<run>/backups/<b>/files/`.
Doc `report`: one `md` block, a headline sentence first that says what happened ("Nothing was changed. 1 update broke the tests and was undone; 3 were not tried"), then folders looked at, the rows table with each label, reason and outcome in plain words, still-open security problems, missing tools with install lines, folders the test map lacks (point to PR Prep or Test), changes already there before the run, and each upgrade brief written. After an undo that did not finish: the files that differ or the command to run by hand, and `<run>/backups/<b>/files/`.
## The finish
`headline` the counts updated, failed and not tried; `body` the summary and any brief written; `"dashboard":true`; `command` `/plan2code-git` when something changed; never `commit`. A stop before any apply: `body` says nothing changed, `"command":"/plan2code-deps"`. An unfinished put-back: no `command`; `body` names what the report does.
`headline` a sentence saying what happened first (counts updated, broke and not tried); `body` the summary and any upgrade brief written; `"dashboard":true`; `command` `/plan2code-git` when something changed; never `commit`. A stop before any apply: `body` says nothing was changed, `"command":"/plan2code-deps"`. An undo that did not finish: no `command`; `body` names what the report does.