release: 0.29.0 — the install verbs read as plan, apply and done - #27

The 0.29.0 release: install, upgrade and uninstall now print a plan, the steps as they run, and a result. At a terminal they ask before anything is written.

The maintainer asked for this after upgrading both shells to 0.28.2. Each printed one undivided block, ending in applied 3 change(s).. The record is the story Install, upgrade and uninstall read as plan, apply and done, and a terminal asks before writing (PS-HARNESS). It changes contract 9 of the install spec and adds contract 18.

What changes for a user

• The output has a header, then PLAN, APPLY and DONE.
  • PLAN lists every item once. Beneath it are every file written and every host command, verbatim, with the files that command touches. This is the consent content, so it is never folded.
  • APPLY marks each step ✓ or ✗ with its duration. That includes a registration's staging write and each host command, and each step of the layout move.
  • DONE gives the count, the time, and the next steps from the manifests' new install.next.
  • --verbose restores the host-managed prose and each step's why.
• A terminal is asked Apply N changes? [Y/n] after the plan, even when the harness or shell is named.
  • Enter, y or yes applies.
  • Anything else, or Ctrl+D, writes nothing (exit 1). Ctrl+C is SIGINT (exit 130).
  • Without a terminal nothing changes: a named harness confirms and a bare run refuses. The same holds for agents, CI, --json, and runs inside a host session.
  • Unattended in a terminal: pass --json, set CI=1, or use </dev/null. There is no --yes.
• --help is new.
  • The top level groups the verbs.
  • <verb> --help shows the options, examples and exit codes. Through a shell, the examples use the shell's name.
  • A near miss is named: did you mean install?.
• Fixed along the way:
  • a bare interactive install asked before it showed the plan;
  • --json in a terminal asked into its own envelope;
  • Ctrl+D at a question left it pending.

Under the hood

• scripts/term.mjs (new, zero dependencies) handles:
  • colour, following NO_COLOR, FORCE_COLOR and TERM=dumb;
  • icons;
  • wrapping, on a live terminal only;
  • step lines, rewritten in place;
  • the one line reader both of the bin's gates use. It reads in line mode, so it writes no cursor escapes.
• plan --json and install --json keep their shape.
• The shell bins pass PROJECTSTORE_SHELL, which only --help reads.
• The Codex doctor and agents skills run their confirmed writes with --json.

Reviews

All three passes are recorded in the story:

• projectstore:critic returned revise. In response, the amendment is scoped to the install family, and it now covers the answer rules, the unattended path, the Codex measurement gap, and the superseded wording.
• projectstore:planner found a crash before release: the interactivity check called .some on a Map, so every real terminal run would have thrown. It also found readline's escapes and a key plan --json had gained.
• projectstore:reviewer ran a real pseudo-terminal and compared side by side with 0.28.2. It found uninstall's reasons folded, writes wearing the skip glyph, and a STOPPED line that blamed a host command for every failure. All are fixed.

Checks

• npm run release:check: 556 of 556, both inside a Claude Code session and with its markers stripped.
• The whole suite passes with FORCE_COLOR=1 too. The test runner sets that for its children in a colour terminal.
• node scripts/version-guard.mjs reports ok, and node packaging/shells.mjs --check reports ok.

Known limits

• Codex's session marker is unmeasured, and so is whether its exec tool gives a command a terminal. Both are a live criterion after the release.
• Windows is not verified.
• A piped stdout makes a run non-interactive, as before.

Merging this is the git marketplace's release. After the merge, v0.29.0 is tagged on main, and CI publishes all three packages under latest.

Maintainer: [email protected]