instar 1.2.7 → 1.2.9

package/upgrades/1.2.8.md

@@ -0,0 +1,69 @@
+# Upgrade Guide — v1.2.8 (nuke --here for project-local installs)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**New: `instar nuke --here` removes a project-local install.**
+
+`instar nuke <name>` has always handled standalone agents (the ones
+at `~/.instar/agents/<name>/`). There was no equivalent for the
+project-bound install method — the result of `npx instar setup`
+inside a project directory. Removing one of those required a manual
+multi-path `rm -rf` of `.instar/`, `.claude/` (or `.codex/`),
+`.mcp.json`, and the identity-shadow files, plus the invisible parts:
+the tmux server, the launchd plist, the agent-registry entry, the
+secret backup.
+
+`instar nuke --here` collapses that into one command. Run it inside
+the project directory and it:
+
+1. Stops the `<projectName>-server` tmux session and any spawned
+   `<projectName>-*` sessions.
+2. Removes the launchd / systemd auto-start entry for that project.
+3. Backs up secrets (Telegram token, dashboard PIN, etc.) so a
+   subsequent `npx instar setup` in the same directory auto-restores
+   them, identical to the standalone reinstall flow.
+4. Unregisters the directory from the agent registry.
+5. Removes filesystem artifacts:
+   - Always: `.instar/`, `.claude/`, `.codex/`, `.mcp.json`,
+     `instar.config.json`.
+   - For `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`: git decides.
+     Tracked-clean → kept (pre-existing). Tracked-modified → restored
+     to `HEAD`. Untracked → deleted.
+
+Safety:
+- Refuses to run inside the instar source repo (checks `package.json`
+  name and `src/cli.ts` presence).
+- Refuses to run when `.instar/config.json` is absent.
+- Confirmation prompt by default; bypassed with `--yes`.
+
+Spec: `specs/dev-infrastructure/nuke-here.md`.
+ELI16: `specs/dev-infrastructure/nuke-here.eli16.md`.
+Side-effects review: `upgrades/side-effects/feat-nuke-here.md`.
+
+## What to Tell Your User
+
+If you want to test installing instar a few different ways in a
+project directory, there is now a built-in uninstall mode that runs
+inside the project. It tears down everything instar installed in one
+shot. Files you had committed before the install are kept (or
+restored from git HEAD), so it is safe to run on a repo that already
+had its own identity-shadow files.
+
+## Summary of New Capabilities
+
+- New CLI mode: `instar nuke --here` (project-local install teardown).
+- Standalone form `instar nuke <name>` unchanged.
+
+## Evidence
+
+14 new unit tests in `tests/unit/nuke-here.test.ts` cover the source-
+repo refusal check (four cases), the shadow-file classifier (four
+cases of pre-existing-vs-instar-added-vs-untracked-vs-modified), and
+the end-to-end filesystem teardown against tmpdirs (six cases
+including the missing-config refusal path). All pass locally and in CI.
+
+Manual end-to-end verification will run against the `instar-codey`
+test clone after publish.

package/upgrades/1.2.9.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — v1.2.9 (nuke --here leftover-artifact fixes)
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**Fix: `nuke --here` now leaves no leftovers.**
+
+End-to-end testing of the v1.2.8 nuke --here flow on a fresh project
+turned up two artifacts the teardown forgot:
+
+1. The `.gitignore` instar writes during install was orphaned after
+   nuke. Fixed by routing it through the existing identity-shadow
+   classifier (tracked-clean keep, tracked-modified restore,
+   untracked delete) — same rule we already apply to the identity
+   shadow files.
+
+2. The `.instar/` directory ghost-revived itself after delete. The
+   SafeFsExecutor and SafeGitExecutor audit log lives at
+   `.instar/audit/destructive-ops.jsonl`. When `.instar/` was deleted
+   early in teardown, every subsequent destructive op wrote an audit
+   entry into a freshly-recreated `.instar/audit/`. Fix: reorder
+   teardown so `.instar/` is last, and suppress audit logging for
+   that single delete via the existing `INSTAR_AUDIT_LOG_DISABLED`
+   env contract. The agent dir is going away in the same breath, so
+   the suppressed entry has no downstream consumer.
+
+Three new unit tests pin the corrected behavior end-to-end against
+tmpdirs: instar-created `.gitignore` is deleted, pre-existing
+tracked `.gitignore` is preserved, and `.instar/` is fully absent
+after nuke (no `audit/` carryover).
+
+Spec: `specs/dev-infrastructure/nuke-here-leftovers.md`.
+ELI16: `specs/dev-infrastructure/nuke-here-leftovers.eli16.md`.
+Side-effects review: `upgrades/side-effects/fix-nuke-here-leftovers.md`.
+
+## What to Tell Your User
+
+Uninstall now actually leaves the project the way it was before
+instar was installed. There is no orphaned per-machine ignores file
+and no ghost configuration directory left behind. If you run the
+install/uninstall/reinstall loop a dozen times in a row, each cycle
+starts from the same clean state as the first.
+
+## Summary of New Capabilities
+
+No new capabilities. Behavior fix on top of v1.2.8.
+
+## Evidence
+
+Reproduction prior: ran `npx instar@1.2.8 init <name> --framework
+codex-cli` followed by `npx instar@1.2.8 nuke --here --yes`. On-disk
+state after nuke: `.gitignore` present with instar's per-machine
+ignores; `.instar/` present containing
+`audit/destructive-ops.jsonl`. Three explicit unit tests now cover
+both observations and fail on v1.2.8, pass on v1.2.9.

package/upgrades/side-effects/feat-nuke-here.md

@@ -0,0 +1,123 @@
+# Side-effects review — `instar nuke --here`
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — project-bound installs had no uninstall command at all;
+operators had to manually `rm -rf` the install artifacts (and forget the
+tmux server / launchd plist / registry entry / secret backup).
+
+After: precisely targeted. The new mode requires explicit `--here`, runs
+only when `.instar/config.json` exists in the target dir, and refuses
+to run inside the instar source repo. No over-block: the standalone
+form is unchanged, and operators who never pass `--here` see no
+behavior change.
+
+## 2. Level-of-abstraction fit
+
+`nukeHere(options)` is a sibling function to the existing `nukeAgent`
+in the same file. Both share the same Step 1-4 shape (tmux teardown,
+auto-start removal, secret backup, registry unregister) and the same
+SafeFsExecutor / SafeGitExecutor helpers for the filesystem half. The
+new git-tracked-vs-untracked decision for identity-shadow files
+delegates to `git ls-files --error-unmatch` + `git status --porcelain`
+— the existing single source of truth for tracking state. No new
+abstraction layer.
+
+## 3. Signal vs Authority compliance
+
+- The `--here` flag is the operator-intent SIGNAL.
+- `.instar/config.json` presence is the AUTHORITY for "is there an
+  install here to remove."
+- `package.json` `name === "instar"` + `src/cli.ts` presence is the
+  AUTHORITY for "is this the instar source repo (refuse)."
+- For identity-shadow files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`):
+  - `git ls-files --error-unmatch <file>` is the AUTHORITY for
+    "tracked at HEAD."
+  - `git status --porcelain <file>` is the AUTHORITY for "has working-
+    tree diff."
+  No new heuristic is invented; existing git tooling is the single
+  source of truth.
+
+## 4. Interactions with adjacent systems
+
+- **Standalone `nuke <name>`** — unchanged. Same function, same flags,
+  same prompts. The CLI route was changed from `nuke <name>` (required)
+  to `nuke [name]` (optional) plus a `--here` flag — when `--here` is
+  set, the positional is ignored; when `--here` is not set and no name
+  is given, usage is printed and the command exits 1.
+
+- **`uninstallAutoStart(projectName)`** in `src/commands/setup.ts` —
+  reused as-is. The function is already idempotent and project-name-
+  scoped; the new mode hands it the same `projectName` the install
+  wrote into `.instar/config.json`.
+
+- **`SecretManager.backupFromConfig`** — reused exactly as
+  `nukeAgent` does, with the same field mapping (Telegram token, chat
+  id, authToken, dashboardPin, tunnel token). This means a subsequent
+  `npx instar setup` in the same directory will auto-restore secrets,
+  matching the standalone reinstall flow.
+
+- **`unregisterAgent(dir)`** — reused. Operates on the absolute
+  directory path, identical contract.
+
+- **`SafeFsExecutor.safeRmSync`** — used for every delete. The recent
+  source-tree-guard carve-out (PR #294) for `<root>/.instar/` runtime
+  artifacts means `.instar/` deletions inside an agent's project dir
+  do not trip the guard.
+
+- **`SafeGitExecutor`** — used for `ls-files`, `status`, and
+  `checkout HEAD --`. All three are already allow-listed git ops; the
+  audit trail records the new operations under
+  `src/commands/nuke.ts:nukeHere-*`.
+
+- **Tmux session naming** (`<projectName>-server`, `<projectName>-*`) —
+  identical to `nukeAgent`. The new function uses the same
+  `isTmuxSessionRunning` helper that already exists in the file.
+
+## 5. Rollback cost
+
+Trivial. One new exported function in `src/commands/nuke.ts`, one
+modified CLI registration in `src/cli.ts`, one unit test, one ELI16
++ spec + this artifact. `git revert` restores the prior CLI surface;
+no other surface depends on `--here`. Standalone nuke users see no
+change either way.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- `instar nuke <name>` still works (positional became optional, but
+  passing a name still routes to `nukeAgent`).
+- `instar nuke` with no arguments now prints usage and exits 1 —
+  before, commander would error out with a "missing required argument"
+  message. Same exit-1 outcome, slightly clearer error.
+- `instar nuke --here` is a new code path; no prior agent has it, so
+  there's nothing to drift against.
+- No config file changes, no template changes, no hook changes, no
+  built-in skill changes — therefore no `PostUpdateMigrator` work
+  needed (Migration Parity Standard not triggered: this is a CLI-only
+  surface change, not an agent-installed-files change).
+
+## 7. Authorization / Trust posture
+
+No new authority. The command only acts on:
+
+- The current working directory (or `--dir` override) — same scope as
+  every other instar CLI command that takes a `--dir` flag.
+- The launchd plist / agent registry entry / secret store keyed to
+  the **projectName the install itself wrote**. The command cannot
+  delete data belonging to a different project name; it reads
+  `projectName` from `.instar/config.json` in the target dir.
+
+The source-repo refusal check is an additional safety floor that
+exists only to protect the instar development checkout — a one-way
+guardrail with no positive authority.
+
+## Outcome
+
+Ship. Closes the project-local uninstall gap, matches the standalone
+flow's safety posture, no new authority, no migration work, and
+removes the manual-rm-rf trap operators hit today during install
+testing.

package/upgrades/side-effects/fix-nuke-here-leftovers.md

@@ -0,0 +1,98 @@
+# Side-effects review — Nuke --here leftover-artifact fixes
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER on two specific paths.
+- `.gitignore` survived nuke entirely (orphaned instar artifact).
+- `.instar/` resurrected itself via audit-log writes immediately after
+  delete, leaving an empty `.instar/audit/` directory behind.
+
+After: precisely targeted. `.gitignore` joins the existing identity-
+shadow classifier (same three-way disposition: keep / restore /
+delete). `.instar/` is now the last destructive op, with audit logging
+suppressed for that single call so it doesn't recreate itself. No
+over-block: the keep-pre-existing-`.gitignore` path means a project
+that had its own `.gitignore` before instar was installed gets that
+file preserved.
+
+## 2. Level-of-abstraction fit
+
+Fix 1 adds one string to an existing array
+(`PROJECT_LOCAL_IDENTITY_SHADOWS`); no new classifier, no new
+disposition. The existing `classifyShadowFile` already handles
+`.gitignore` correctly.
+
+Fix 2 partitions an existing array (`PROJECT_LOCAL_ALWAYS_REMOVE`)
+into "everything except `.instar`" and "`.instar`". The audit
+suppression uses an existing public env var
+(`INSTAR_AUDIT_LOG_DISABLED`) documented in
+`src/core/SafeGitExecutor.ts:auditLogPath`. No new authority, no new
+API surface.
+
+## 3. Signal vs Authority compliance
+
+- The git-tracked-vs-untracked decision for `.gitignore` delegates
+  exactly as it does for other shadow files: `git ls-files
+  --error-unmatch` + `git status --porcelain` are the AUTHORITY.
+- The audit-log suppression honors the existing
+  `INSTAR_AUDIT_LOG_DISABLED` env contract — the env var IS the
+  documented signal for "skip audit." No new signal invented.
+
+## 4. Interactions with adjacent systems
+
+- **`SafeFsExecutor.safeRmSync` / `SafeGitExecutor.execSync` audit
+  paths** — unchanged. They continue to write to
+  `<cwd>/.instar/audit/destructive-ops.jsonl` whenever
+  `INSTAR_AUDIT_LOG_DISABLED` is not set. The only suppression is
+  inside `nukeHere`, around the final `.instar` delete, and is
+  scoped to that single op.
+
+- **`classifyShadowFile` callers** — none other than `nukeHere`. The
+  function's signature is unchanged.
+
+- **Other CLI commands that touch `.gitignore`** — `instar init`
+  writes it, `instar setup` does not touch it. No reader of
+  `.gitignore` depends on it being absent. Removing it during nuke
+  has no cascading effect.
+
+- **Reinstall flow** — `instar init` regenerates `.gitignore` from
+  scratch. The fix re-aligns the install/uninstall contract:
+  whatever `init` writes, `nuke --here` removes.
+
+## 5. Rollback cost
+
+Trivial. One array-element addition and one reorder + env-var
+suppress block in `src/commands/nuke.ts`. Three new unit tests.
+`git revert` restores the prior leaky behavior.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backwards-compatible.
+
+- `nuke <name>` (standalone form) untouched.
+- `nuke --here` consumers see strictly more-correct behavior: no
+  orphaned `.gitignore`, no ghost `.instar/`.
+- A project that had `.gitignore` tracked in git before instar was
+  installed gets it preserved (the new identity-shadow rule) —
+  strictly better than the v1.2.8 behavior of leaving instar's
+  rewritten version behind. No legitimate caller depends on the
+  buggy v1.2.8 leftover state.
+- No config changes, no template changes, no hook changes, no
+  migration work needed (CLI-only surface).
+
+## 7. Authorization / Trust posture
+
+No new authority. The audit-log suppression is scoped to one syscall
+inside one function; the env var is restored in a `finally` block so
+the rest of the process retains the prior audit-log state. The
+shadow classifier already delegates the keep/restore/delete decision
+to git, not to instar.
+
+## Outcome
+
+Ship. Closes the two leftover-artifact failure modes uncovered by
+end-to-end testing on `instar-codey`. Three unit tests pin the
+corrected behavior. The fix exercises only existing primitives;
+zero new abstraction surface.