@bakit-org/ai-sdlc-cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-sdlc contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @bakit-org/ai-sdlc-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line installer for the ai-sdlc Claude Code harness. It puts the BA / Dev / Test agents, skills and hooks into a project repository of your choice, keeps them up to date without overwriting your edits, and removes them cleanly.
+
+## Quick start
+
+```sh
+npm install -g @bakit-org/ai-sdlc-cli       # installs the `ai-sdlc` command
+gh auth login                               # or export GH_TOKEN=... (needs read access to the kit repository)
+cd ~/projects && ai-sdlc init               # guided install: pick a project, review, apply
+ai-sdlc doctor --project <path>             # confirm the install is intact
+```
+
+Scripted, or without network access:
+
+```sh
+ai-sdlc install --project <path> --yes                                  # latest kit release from GitHub
+ai-sdlc install --project <path> --from-bundle ./ai-sdlc-0.1.0.bundle.json --yes
+```
+
+Add `--dry-run` first to see exactly what a run would do; a real run performs the same list.
+
+## Requirements and access
+
+- Prerequisites: Node 18 or newer, and read access to the GitHub repository that publishes the kit (`bakit-org/ai-sdlc-kit`; ask its owner if you do not have it). No runtime dependencies.
+- GitHub credentials come from what you already use, first match wins: the `AI_SDLC_GITHUB_TOKEN`, `GH_TOKEN` or `GITHUB_TOKEN` environment variable, then `gh auth login` (the GitHub CLI), then your git credential helper for `github.com`. The token is only sent to GitHub's API and is never printed or stored. Tokens found automatically (`GH_TOKEN`, `GITHUB_TOKEN`, `gh`, git credential helper) are only used for the public API at `https://api.github.com`; if `AI_SDLC_GITHUB_API` points anywhere else (for example GitHub Enterprise) only an explicit `AI_SDLC_GITHUB_TOKEN` is used. The token needs read access to the kit repository's contents (for example a fine-grained token with `Contents: read` on it, or a classic token with the `repo` scope). For a repository behind SAML SSO, authorize the token for the organization.
+- Downloads use Node's built-in `fetch`, which does not honour `HTTPS_PROXY` / `HTTP_PROXY`. Behind a proxy that GitHub is only reachable through, download the release bundle by other means and use `--from-bundle <file>`.
+- Everything is scoped to the project you pick. Nothing is written to `~/.claude`.
+- Works for both the Claude Code CLI and the VS Code extension (they share `.claude/`, `CLAUDE.md` and `.claude/settings.json`).
+
+## Commands
+
+```
+ai-sdlc init      [--project <path>] [--root <dir>] [--from-bundle <file> | --version <tag>] [--force] [--no-tui]
+ai-sdlc install   [--project <path>] [--root <dir>] [--from-bundle <file> | --version <tag>] [--dry-run] [--force] [--yes] [--json]
+ai-sdlc update    [--project <path>] [--root <dir>] [--from-bundle <file> | --version <tag>] [--dry-run] [--force] [--yes] [--json]
+ai-sdlc doctor    [--project <path>] [--from-bundle <file>] [--json]
+ai-sdlc uninstall [--project <path>] [--dry-run] [--yes] [--json]
+ai-sdlc version   [--check] [--project <path>] [--json]
+ai-sdlc                  # in a terminal: menu (Install / Update / Doctor / Uninstall / Quit)
+```
+
+Exit codes: `0` success, `1` the operation failed or you cancelled (Esc / Ctrl-C), `2` wrong usage. If the process is stopped from outside, the terminal is restored first and the exit code is `130` (SIGINT) or `143` (SIGTERM).
+
+Without `--from-bundle`, `install` and `update` download the latest release of the payload repository (or the one named by `--version <tag>`, for example `--version 1.2.0`), check its `.sha256` and the per-file hashes, and install it. With `--from-bundle <file>` they use a local release bundle instead (the `<file>.sha256` beside it is verified when present) and never touch the network. `ai-sdlc version --check` shows the latest release and, for the current or `--project` directory, whether the installed payload is behind it.
+
+Failures are plain messages: an invalid or expired token, a repository you cannot read (the message names `https://github.com/<owner>/<repo>` and says to ask the repo owner to grant read access), a GitHub rate limit (with the reset time), or no network (use `--from-bundle`).
+
+## Choosing the project
+
+Without `--project` the CLI lists the git repositories directly under the current directory (and its parent), or under `--root`, plus an "enter a path" option. It shows the full plan and asks before writing. In scripts and CI pass `--project <path> --yes`; without a terminal the CLI refuses to guess and exits with `2`.
+
+## Interactive mode
+
+In a terminal, `ai-sdlc init` is a guided install: a gradient banner, an environment check, a filterable project list (git repositories next to you plus recent projects, with `installed` / `not installed` / `no .git` badges), a review of what will change, a progress bar and a result panel with next steps. Running `ai-sdlc` with no command opens a menu, and `update`, `doctor` and `uninstall` print coloured result views. Esc or Ctrl-C at any step writes nothing and restores the terminal.
+
+It switches itself off for `--json`, `--yes`, `--no-tui`, `TERM=dumb` and whenever stdin or stdout is not a terminal; then the plain output and exit codes apply. Colours follow `NO_COLOR` and the terminal's capability, with an ASCII fallback. Details and key bindings: [docs/tui.md](docs/tui.md).
+
+## What gets installed
+
+| Path | Behaviour |
+|---|---|
+| `.claude/agents`, `.claude/skills`, `.claude/hooks`, ... | Managed: replaced on `update` only while still identical to what was installed. A file you edited is kept and the new version is written next to it as `<file>.new`. |
+| `CLAUDE.md` | Only the block between `<!-- ai-sdlc:begin -->` and `<!-- ai-sdlc:end -->` is managed. The rest of the file is never touched. |
+| `.claude/settings.json` | Only the hook entries the CLI added are managed. Invalid JSON aborts the run untouched. |
+| Starter files (project notes, design folder, ...) | Created if absent, never overwritten, never removed. |
+| `.claude/ai-sdlc.manifest.json` | Records what was installed; written last. |
+
+`uninstall` removes unmodified managed files, the block and the hooks it added, and gives `CLAUDE.md` and `settings.json` back byte-for-byte as they were before install. Files you modified and all starter files stay.
+
+Note: `.claude/ai-sdlc.manifest.json` may hold a copy of your original `.claude/settings.json` text so uninstall can restore it exactly. Do not publish it.
+
+See [docs/cli.md](docs/cli.md) for the details (update rules, doctor checks, bundle format, safety guarantees).
+
+## Update, uninstall and offline use
+
+- `ai-sdlc update` compares the installed files with the new release and your disk. Unmodified managed files are replaced; a file you edited is kept and the new version is written next to it as `<file>.new`; starter files are never touched. `--dry-run` lists the result first.
+- `ai-sdlc uninstall` removes what the CLI installed and nothing else (see above for what stays).
+- `--from-bundle <file>` installs or updates from a local `ai-sdlc-<version>.bundle.json` with no network access. The `<file>.sha256` beside it is verified when present. Use it behind a proxy, offline, or to try a release before publishing it.
+- `ai-sdlc doctor` is read-only: Node version, a leftover run journal, manifest, managed files (edited = warning, missing = failure), hook registration and scripts, the `CLAUDE.md` block, starter files, installed version, and a note when optional Python 3 is missing. It exits `1` if a check fails. `--json` for machine output.
+
+## Known limits
+
+- Node's `fetch` ignores `HTTPS_PROXY` / `HTTP_PROXY` (use `--from-bundle`).
+- Windows consoles have not been verified; the interactive screens fall back to ASCII on terminals without UTF-8.
+- The bundle checksum comes from the same release as the bundle: it detects corruption, not tampering by someone who can edit the release.
+- A symlinked `CLAUDE.md` or `settings.json` is refused.
+
+## License
+
+This installer is MIT licensed (see `LICENSE`). The kit it installs (`bakit-org/ai-sdlc-kit`) is a separate, commercially licensed product; access is granted by its owner.
+
+## Development
+
+```sh
+npm test            # node:test, no dependencies
+npm pack --dry-run  # shows the published file list
+```

package/bin/ai-sdlc.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+const { run } = require('../lib/commands');
+
+run(process.argv.slice(2)).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (err) => {
+    process.stderr.write(`ai-sdlc: unexpected error: ${err && err.stack ? err.stack : err}\n`);
+    process.exitCode = 1;
+  },
+);

package/docs/cli.md

@@ -0,0 +1,115 @@
+# CLI reference
+
+## Global behaviour
+
+- Options: `--project <path>`, `--root <dir>`, `--from-bundle <file>`, `--version <tag>` (install/update), `--check` (version), `--dry-run`, `--force`, `--yes` (`-y`), `--json`, `--no-tui`.
+- Exit codes: `0` ok, `1` failure or a cancelled interactive screen, `2` usage error (unknown option, missing value, invalid target, missing `--project` / `--yes` without a terminal, `--version` that is not a release version or is combined with `--from-bundle`). Access and network failures of a download (no credentials, rejected token, no read access, rate limit, offline) exit `1`.
+- `--json` prints one JSON document on stdout and never prompts; it therefore needs `--project`, and `--yes` for runs that write.
+- Target rules: the directory must exist, must not be your home directory or a filesystem root. A directory without `.git` is accepted with a warning.
+
+- `init` is `install` with a guided wizard when stdin and stdout are terminals and none of `--yes`, `--json`, `--no-tui`, `--dry-run` or `TERM=dumb` applies; in every other case it behaves exactly like `install`. Without a command, a terminal gets a menu (usage text and exit `2` otherwise). `update`, `doctor` and `uninstall` print coloured result views on a terminal. `--no-tui` always gives the plain text. See [tui.md](tui.md).
+- Cancelling an interactive screen with Esc or Ctrl-C changes nothing and exits `1`. A `SIGINT` or `SIGTERM` that arrives from outside restores the terminal and exits `130` or `143`.
+
+## Choosing the project
+
+1. `--project <path>` wins.
+2. Otherwise, in a terminal: a numbered list of directories that contain `.git`, found one level under `--root` (default: the current directory, then its parent; the scanned directory itself is listed when it is a repository), plus `p` to type a path and `q` to cancel.
+3. The plan is printed, then `Apply these changes? [y/N]` unless `--yes` or `--dry-run`.
+
+## Where the bundle comes from
+
+- `--from-bundle <file>`: a local bundle, no network.
+- Otherwise `install` and `update` (and the `init` wizard) download it from the payload repository's GitHub release: `bakit-org/ai-sdlc-kit` by default; `AI_SDLC_PAYLOAD_REPO=<owner>/<repo>` points at another repository.
+- `--version <tag>` pins a release (`1.2.0` and `v1.2.0` both work); without it the latest published release is used.
+
+Steps: find credentials, check read access to the repository, look up the release, download `ai-sdlc-<version>.bundle.json` and its `.sha256` through the API (`Accept: application/octet-stream`) into a private temporary directory (mode `0600`), verify the checksum and the per-file hashes with the same checks as a local bundle, install, and delete the temporary files. A release without a checksum asset is refused.
+
+Credentials, first match wins: environment `AI_SDLC_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`; the GitHub CLI (`gh auth token`, when `gh` is on the PATH); `git credential fill` for `github.com` (run with `core.askPass` and `credential.interactive` off and `GIT_ASKPASS`, `SSH_ASKPASS`, `GIT_TERMINAL_PROMPT` disabled, so no prompt or askpass dialog can appear; times out after 8 s). Only the name of the source is ever shown.
+
+**Custom API base.** Tokens found on the machine (`GH_TOKEN`, `GITHUB_TOKEN`, `gh`, the git credential helper) belong to github.com and are used only when the API base is exactly `https://api.github.com`. With `AI_SDLC_GITHUB_API` set to anything else (GitHub Enterprise, a mirror, a local test server) only an explicit `AI_SDLC_GITHUB_TOKEN` is used, and neither `gh` nor `git` is started. The wizard shows the non-default base next to the kit source. The token is sent only to the API origin: when an asset download redirects to another host (GitHub's storage), the `Authorization` header is not forwarded. Only `https` is used (plain `http` only for a `localhost` API override). Requests time out after 20 s and are retried twice with backoff on network errors and 5xx.
+
+| Situation | Message / exit |
+|---|---|
+| no credentials | lists the env vars, `gh auth login` and the git credential helper; exit `1` |
+| 403 with an SSO header | the organization uses SAML SSO: authorize the token for it; exit `1` |
+| 401 | token invalid or expired (names the source, not the value); exit `1` |
+| 403 / 404 on the repository | `no read access to <owner>/<repo> — ask the repo owner to grant read access: https://github.com/<owner>/<repo>`, also pointing at `--from-bundle <file>`; exit `1` |
+| rate limit (403/429) | shows the reset time (or the retry delay); exit `1` |
+| offline, DNS, timeout | suggests `--from-bundle <file>`; exit `1` |
+| release without bundle or checksum asset | names what is missing; exit `1` |
+
+`ai-sdlc version --check` runs the access check and the release lookup (no download) and prints the latest payload version; with `--project <path>` (or an installed project in the current directory) it also compares the installed version. `--json` gives `{ version, repo, latest, installed, status }`.
+
+Integrity: the `.sha256` asset comes from the same release as the bundle, so the check detects corruption or a partial download, not tampering by someone who can edit the release. The CLI also refuses a bundle whose payload version differs from its release tag. Redirect targets that carry a user name or password, or that are not https, are refused.
+
+Proxies: Node's built-in `fetch` ignores `HTTPS_PROXY` / `HTTP_PROXY`. Where GitHub is reachable only through a proxy, get the bundle another way and use `--from-bundle <file>`.
+
+Cancelling: in the guided install, Ctrl-C or Esc during the environment check or the download stops the in-flight request, removes the temporary files and ends with exit `1` (nothing written). In plain runs, `SIGINT` / `SIGTERM` during a download delete the temporary directory first and exit `130` / `143`.
+
+Flag checks happen first, before any network access: `--version` only applies to `install`, `update` and `init`, cannot be combined with `--from-bundle` and must look like `1.2.0` or `v1.2.0`; `--check` only applies to `version`. Violations exit `2`.
+
+Environment overrides meant for tests: `AI_SDLC_GITHUB_API` (API base URL).
+
+## install
+
+Verifies the bundle, then plans and applies. Refuses when a manifest already exists (use `update`, or `--force` to reinstall). A file already present at a managed path with different content is kept and the bundle's version is written beside it as `<file>.new`; `--force` overwrites instead.
+
+## update
+
+Three-way comparison per managed file: hash recorded at install, file on disk, file in the new bundle.
+
+| Disk vs recorded | Bundle | Result |
+|---|---|---|
+| unchanged | changed | replaced |
+| unchanged | same | nothing |
+| edited | changed | kept, `<file>.new` written |
+| edited | same | kept |
+| missing | present | restored |
+| unchanged | no longer shipped | deleted |
+| edited | no longer shipped | kept, no longer tracked |
+| not tracked | new in bundle | added (kept + `.new` if a different file is in the way) |
+
+A renamed or moved folder (for example a skill folder that gains a prefix) is the last two "no longer shipped" rows plus the "new in bundle" row: the old files that you did not edit are deleted (empty folders are removed too), an old file you edited stays where it is and is no longer tracked, and the new files are added. A project that already has a different file at a new path keeps it and gets `<file>.new` beside it.
+
+Starter files (`user-once`) are created only when they are new in the bundle. A starter file the previous install tracked and you have since deleted is not re-created by `update` (it is listed as `skip-deleted`; `doctor` still warns that it is missing). `install --force` does create it again. Existing starter files are never overwritten.
+
+The `CLAUDE.md` block and the recorded hooks are re-rendered. A hook that is already registered identically stays where it is, so `settings.json` is not rewritten or reordered for it.
+
+## doctor
+
+Read-only. Reports Node version, a leftover run journal (even when the manifest is missing), manifest validity, managed files (modified = warning, missing = failure), registered hooks and hook scripts, the `CLAUDE.md` block, starter files, installed version (compared with `--from-bundle` when given), and a note about optional Python 3 only when installed scripts need it. A check that cannot run (symlink, permissions, bad encoding) is reported as a failed check rather than aborting the report, in `--json` too. Exit `1` if any check fails.
+
+## uninstall
+
+Deletes managed files that still match the manifest (never starter files), removes the exact hook entries and the block the CLI added, deletes files the CLI itself created if they are empty again (`CLAUDE.md`, `settings.json`), removes directories it emptied, and finally removes the manifest. Edited managed files, `<file>.new` leftovers and starter files stay.
+
+## Bundle format
+
+One JSON file: `{ manifest, contents }`.
+
+- `manifest`: `version`, `payload_schema` (must be `1`), `min_cli_version`, `files[]` (`path`, `sha256`, `class`, `encoding`), optional `hooks[]` (`event`, optional `matcher`, `command`).
+- `contents[path]`: file text (`utf8`) or base64 string; `sha256` is over the raw bytes.
+- Classes: `managed` (under `.claude/`), `block` (`CLAUDE.md`, body without markers), `user-once`.
+- Hook commands may contain `$CLAUDE_PROJECT_DIR`; it is written as is, not expanded.
+- Optional `<bundle>.sha256` sidecar (`<hex>  <name>`): verified when present; when absent a warning is printed and listed under `warnings` in `--json` output.
+
+Rejected before any write: a block body that contains the begin/end markers, checksum mismatch, per-file hash mismatch, `payload_schema` other than `1`, `min_cli_version` above the CLI version, unsafe paths (absolute, `..`, backslash, empty segment), managed files outside `.claude/`, a `CLAUDE.md` that is not a block, entries in `contents` the manifest does not list.
+
+## Safety guarantees
+
+- Every write is a temporary file plus rename, and an existing file keeps its permission bits. The manifest is written last.
+- Each real (non `--dry-run`) run takes a per-project lock by creating `.claude/ai-sdlc.journal.json` exclusively, before planning. A second run fails with "another ai-sdlc run is in progress". Just before applying, the journal records the previous content of every path the run will touch. A failure inside the process rolls all of them back.
+- If the process is killed, the journal stays. `doctor` reports it, and the next `install` / `update` / `uninstall` refuses until you pass `--force`, which first rolls the interrupted run back from the journal (CLAUDE.md, settings.json, payload files and manifest return to their earlier state) and then proceeds. A journal owned by a still-running process is never recovered, not even with `--force`.
+- Paths are resolved against the real project path; a symlink that leads outside it is refused. A symlinked `CLAUDE.md` or `settings.json` is refused too (replace it with a regular file, or run against the directory holding the real file). A `.claude` directory that is a symlink inside the project works and is never removed.
+- The same path rules apply to the bundle and to the installed manifest before anything is deleted: no absolute paths, `..`, backslashes, nothing under `.git/`, managed files only under `.claude/`, and `.claude/settings.json`, `.claude/settings.local.json`, the manifest and the journal are reserved.
+- `CLAUDE.md` and `settings.json` must be valid UTF-8; otherwise the run stops before changing anything.
+- `settings.json` is parsed strictly; invalid JSON or an unexpected shape aborts before any file changes. Existing indentation and line endings are kept. The original text is recorded in the manifest so uninstall can restore it exactly (see the note below).
+- `CLAUDE.md` insertion records the exact separator it added, so removal restores the original bytes (including a missing final newline or CRLF endings).
+
+## Code map for the download
+
+`lib/release-source.js` exports `resolveBundle(opts, { fetchLatestBundle })` (resolving to `{ bundlePath }` or `{ bundleObject }`, plus an optional `cleanup()`) and `loadReleaseBundle`, which loads, verifies and then cleans up. `lib/github-release.js` is the default `fetchLatestBundle`; `github-auth.js` finds the token, `github-http.js` does timeouts, retries and redirects, `github-errors.js` maps responses to messages, `config.js` holds the repository and API settings.
+
+## Note on the manifest
+
+`.claude/ai-sdlc.manifest.json` may contain a copy of the original `.claude/settings.json` text (base64) taken before hooks were merged in. Treat the manifest as local state: do not publish it or commit it to a public repository if your settings contain anything private.

package/docs/tui.md

@@ -0,0 +1,87 @@
+# Interactive mode
+
+When you run the CLI in a terminal it can guide you with interactive screens that redraw in place (no alternate screen): a gradient banner, a status line, a filterable project list, a review step, a progress bar and a result panel. There are no extra dependencies; everything is built on Node's raw terminal mode and ANSI sequences.
+
+## When it starts
+
+| You run | In a terminal | Otherwise |
+|---|---|---|
+| `ai-sdlc init` | guided install (below) | same as `install` |
+| `ai-sdlc` (no command) | menu: Install, Update, Doctor, Uninstall, Quit | usage text, exit `2` |
+| `ai-sdlc update`, `doctor`, `uninstall` | coloured result views (checklist, panels); prompts as before | plain text |
+| `ai-sdlc install` | unchanged (numbered picker, `[y/N]`) | unchanged |
+
+"In a terminal" means stdin and stdout are both terminals. Interactive mode is never used when any of these is true, and the plain behaviour (output, prompts, exit codes `0`/`1`/`2`) is unchanged:
+
+- `--json`, `--yes`/`-y` or `--no-tui` is given
+- `TERM=dumb`
+- `init --dry-run` (it prints the plan and exits, like `install --dry-run`)
+
+`--project <path>` together with `init` skips the project list; the review step is still shown.
+
+## The guided install (`ai-sdlc init`)
+
+1. **Banner and checks.** A banner, a dim status line (`Using: node 24 | git ✔ | kit source: bundle file`) and one line per check: Node version, git, and the kit source. With `--from-bundle <file>` the source is that file. Without it the source is the GitHub release of the payload repository and two more checks run (with the spinner): `GitHub token` (shows only where it was found, for example `found via GH_TOKEN`) and `Access to <owner>/<repo>`. If either fails, the failure line explains it (owner contact for missing read access) and offers `--from-bundle <file>`; the run ends with exit `1` before the project list and nothing is written. The release is then downloaded behind a spinner, verified and read. Ctrl-C or Esc during either spinner cancels it immediately (the request and any helper process are stopped, temporary files removed; exit `1`, nothing written). Further checks plug in through the `extraChecks` list of `runPreflight` in `lib/tui/flows/preflight.js`.
+2. **Project.** A list of git repositories found one level under `--root` (default: the current directory and its parent) plus recently used projects, newest first. Each row has a badge: `not installed`, `installed vX → update`, or `no .git ⚠`. Type to filter; `Enter a path…` opens a path field with Tab / Shift-Tab completion. `~`, files, missing paths and filesystem roots are refused with an inline message.
+3. **Review.** What will happen by class (managed files, starter files, the `CLAUDE.md` block, hooks) with a note that only the marked block of `CLAUDE.md` is managed. `d` toggles the full file list. Nothing has been written at this point.
+4. **Install.** The project lock is taken, the plan is computed again under the lock, and the changes are applied with a progress bar showing the current file.
+5. **Result.** What was written and the next steps: open the folder in Claude Code, fill in `ai-sdlc/project.md`, run `ai-sdlc doctor`.
+
+### Keys
+
+| Key | Action |
+|---|---|
+| Enter | choose / confirm / install |
+| Esc | back one step; at the first step, cancel. In a filter or candidate list it first clears that |
+| Ctrl-C | cancel immediately |
+| Up / Down, Home / End, PgUp / PgDn | move in lists (lists wrap) |
+| Tab / Shift-Tab | next / previous path completion |
+| Left / Right, Home / End | move in text fields |
+| Backspace, Delete | edit |
+| Ctrl-A / Ctrl-E | start / end of line |
+| Ctrl-U / Ctrl-W | delete to line start / previous word |
+| `d` (review) | show or hide the full list |
+| `1`-`5` (menu) | pick an entry |
+
+Pasting works (bracketed paste); line breaks in pasted text are dropped. Enter sent as CRLF (Windows terminals) counts once. Resizing the window redraws the current screen.
+
+## What the screens guard against
+
+- **Typed-ahead keys.** Keys pressed before a screen is on display (for example Enter during the environment check) are dropped. The review ignores Enter and `y` for the first 150 ms after it appears. Only Ctrl-C survives typing ahead.
+- **Closed input.** If stdin ends (pipe closed, terminal gone) between screens, the next screen cancels: exit `1`, nothing written.
+- **Hostile text.** Folder names, versions, paths and messages come from disk, so control characters in them are shown as visible escapes (`^[`, `\n`, `\u009b`) and never sent to the terminal. Text typed or pasted into a field loses escape sequences and control characters. A manifest whose version is not a plain semantic version is treated as untrustworthy (a warning in the menu and the list).
+- **Stale review.** The plan is computed again after the project lock is taken. If it differs from what was reviewed, the review is shown again with a note instead of installing something else.
+- **Limits.** Fields hold at most 4096 characters; bracketed pastes are capped at 1 MB and abandoned after 2 s without an end marker; the project list shows at most 200 projects. A window smaller than 20x8 shows a single line asking for more room.
+
+## Cancelling
+
+Esc or Ctrl-C at any step writes nothing: the apply layer is only called after the final confirmation, and the project lock is not even taken before it. The command ends with `ai-sdlc: cancelled; nothing was changed` (or `interrupted; ...` for Ctrl-C) and exit code `1`, the same as declining the prompt in the plain flow. An external `SIGINT`/`SIGTERM` (for example `kill`) restores the terminal and exits `130`/`143`.
+
+The terminal is always put back by one cleanup path (cursor shown, bracketed paste off, raw mode off), registered for normal exit, `SIGINT`, `SIGTERM` and uncaught exceptions, and run again from a `finally` when a screen ends or throws.
+
+## Looks
+
+- **Colour:** truecolor when `COLORTERM` says so (also iTerm, Windows Terminal); 16 colours otherwise on a colour terminal; none for `NO_COLOR`, `FORCE_COLOR=0`, `TERM=dumb` or when output is not a terminal. `FORCE_COLOR=1` forces colour on.
+- **Banner** (chosen by terminal width): 120+ columns thick 2-pixel letters, 100+ the 1-pixel letters, 50+ a compact half-block version, below 50 columns, without colour, or without unicode a single line `> AI-SDLC`. `node lib/tui/logo.js` previews the banner for the current terminal.
+- **Unicode:** box drawing, `❯ ✔ ⚠ ✖ →` need a UTF-8 locale. With `TERM=linux`, `TERM=dumb` or a `LANG`/`LC_ALL` that is not UTF-8 the screens use ASCII (`+--+`, `|`, `>`, `+ ! x`).
+- Long lines are cut with an ellipsis, never wrapped; long paths keep their start and end.
+
+## Recent projects
+
+Project paths (nothing else) are remembered in `recent.json` under `$XDG_CONFIG_HOME/ai-sdlc/`, `%APPDATA%\ai-sdlc\` on Windows, or `~/.config/ai-sdlc/`. The file is replaced atomically, only paths of existing folders are shown, and any problem reading or writing it is ignored. Delete the file to forget everything.
+
+## Layout of the code
+
+```
+lib/tui/
+  keys.js          raw input -> key events (arrows, Home/End, Enter/CRLF, Esc, Tab, Ctrl-keys, paste)
+  terminal.js      session: raw mode, live frame redraw, resize, single cleanup path
+  theme.js         colour level, attribute support, unicode/ASCII symbols, gradient
+  text-width.js    ANSI-aware width, truncation (end and middle)
+  logo.js          banner variants; logo-fonts.js has the bitmap fonts
+  launch.js        decides whether interactive mode may start
+  widgets/         input-box select-list path-input confirm spinner progress-bar panel
+  flows/           init-flow menu-flow result-views plus their helpers
+```
+
+Frames are pure functions of `(state, theme, width)` returning lines; the session draws them by moving the cursor up over the previous frame and clearing it (no alternate screen). Tests drive widgets and flows with scripted key bytes over in-memory streams (`tests/tui-*.test.js`).

package/lib/apply-plan.js

@@ -0,0 +1,61 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { resolveInside, writeAtomic, pruneEmptyDirs } = require('./fs-safe');
+const { MANIFEST_REL } = require('./path-rules');
+const { rollbackEntries } = require('./journal');
+const { CliError } = require('./errors');
+
+// Disk changes in execution order, the manifest always last.
+function orderedChanges(plan) {
+  const changes = plan.actions.filter((a) => a.write || a.remove);
+  return [...changes.filter((a) => a.path !== MANIFEST_REL), ...changes.filter((a) => a.path === MANIFEST_REL)];
+}
+
+// Previous content of every path about to change (base64, or null when absent).
+function beforeImages(project, changes) {
+  return changes.map((a) => {
+    const abs = resolveInside(project, a.path);
+    return { path: a.path, before: fs.existsSync(abs) ? fs.readFileSync(abs).toString('base64') : null };
+  });
+}
+
+// Executes the planned writes/removals while holding `lock`. The before-images
+// go into the journal first, so a failure here (or a crash, recovered later with
+// --force) can put every path back exactly as it was.
+// `onProgress({ done, total, path })` (optional) is called before the first
+// change and after each one; it has no influence on what is written.
+function applyPlan(project, plan, op, lock, { onProgress } = {}) {
+  const changes = orderedChanges(plan);
+  const entries = beforeImages(project, changes);
+  const report = (done, rel) => {
+    if (!onProgress) return;
+    try {
+      onProgress({ done, total: changes.length, path: rel });
+    } catch (_) {
+      /* a display problem must not undo or abort the install */
+    }
+  };
+  try {
+    lock.record(entries);
+    report(0, null);
+    changes.forEach((a, i) => {
+      const abs = resolveInside(project, a.path);
+      if (a.write) writeAtomic(abs, a.write);
+      else {
+        fs.rmSync(abs, { force: true });
+        pruneEmptyDirs(project, path.dirname(abs));
+      }
+      report(i + 1, a.path);
+    });
+  } catch (err) {
+    const problems = rollbackEntries(project, entries);
+    if (problems.length) {
+      lock.keep();
+      throw new CliError(`${op} failed: ${err.message} (rollback also failed: ${problems.join('; ')}; re-run with --force to retry the rollback)`);
+    }
+    throw new CliError(`${op} failed: ${err.message} (rolled back)`);
+  }
+}
+
+module.exports = { applyPlan, orderedChanges, beforeImages };

package/lib/bundle.js

@@ -0,0 +1,120 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('./errors');
+const { sha256, assertRelPath } = require('./fs-safe');
+const semver = require('./semver');
+const { installPathProblem } = require('./path-rules');
+const { BEGIN, END } = require('./merge-claude-md');
+
+const SUPPORTED_SCHEMA = 1;
+const CLASSES = new Set(['managed', 'block', 'user-once']);
+const ENCODINGS = new Set(['utf8', 'base64']);
+
+function fail(msg) {
+  throw new CliError(`invalid bundle: ${msg}`);
+}
+
+// Compares the bundle file against the "<hex>  <name>" sidecar next to it.
+function verifySidecar(file, bytes, warnings) {
+  const sidecar = `${file}.sha256`;
+  if (!fs.existsSync(sidecar)) {
+    warnings.push(`no checksum file beside the bundle (${path.basename(sidecar)}); integrity not verified`);
+    return;
+  }
+  const expected = fs.readFileSync(sidecar, 'utf8').trim().split(/\s+/)[0] || '';
+  if (!/^[0-9a-f]{64}$/i.test(expected)) fail(`checksum file ${path.basename(sidecar)} is malformed`);
+  if (expected.toLowerCase() !== sha256(bytes)) {
+    throw new CliError(`bundle checksum mismatch for ${path.basename(file)}: the file or its .sha256 was altered`);
+  }
+}
+
+function readSource(source, warnings) {
+  if (source.bundleObject) return source.bundleObject;
+  let bytes;
+  try {
+    bytes = fs.readFileSync(source.bundlePath);
+  } catch (err) {
+    throw new CliError(`cannot read bundle ${source.bundlePath}: ${err.code || err.message}`);
+  }
+  verifySidecar(source.bundlePath, bytes, warnings);
+  try {
+    return JSON.parse(bytes.toString('utf8'));
+  } catch (err) {
+    return fail(`not valid JSON (${err.message})`);
+  }
+}
+
+function checkHeader(manifest, cliVersion) {
+  if (!manifest || typeof manifest !== 'object') fail('missing manifest');
+  if (manifest.payload_schema !== SUPPORTED_SCHEMA) {
+    fail(`payload_schema ${manifest.payload_schema} is not supported (this CLI reads ${SUPPORTED_SCHEMA})`);
+  }
+  if (!semver.isStrict(manifest.version)) fail('manifest.version is not a version');
+  const cmp = semver.compare(cliVersion, manifest.min_cli_version);
+  if (cmp === null) fail('manifest.min_cli_version is not a version');
+  if (cmp < 0) {
+    throw new CliError(`this payload needs ai-sdlc-cli >= ${manifest.min_cli_version}, but this is ${cliVersion}; upgrade the CLI first`);
+  }
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) fail('manifest.files is empty');
+}
+
+function decodeFiles(manifest, contents) {
+  const seen = new Set();
+  const files = manifest.files.map((f) => {
+    if (!f || typeof f !== 'object') fail('manifest.files has a non-object entry');
+    assertRelPath(f.path, 'bundle path');
+    if (seen.has(f.path)) fail(`duplicate path ${f.path}`);
+    seen.add(f.path);
+    if (!CLASSES.has(f.class)) fail(`${f.path}: unknown class "${f.class}"`);
+    if (!ENCODINGS.has(f.encoding)) fail(`${f.path}: unknown encoding "${f.encoding}"`);
+    if (typeof f.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(f.sha256)) fail(`${f.path}: bad sha256`);
+    if (typeof contents[f.path] !== 'string') fail(`${f.path}: no content in bundle`);
+    const why = installPathProblem(f.path, f.class);
+    if (why) fail(`${f.path}: ${why}`);
+    const bytes = Buffer.from(contents[f.path], f.encoding);
+    if (sha256(bytes) !== f.sha256) throw new CliError(`bundle file hash mismatch: ${f.path}`);
+    if (f.class === 'block' && f.encoding !== 'utf8') fail('the CLAUDE.md block must be utf8');
+    return { path: f.path, class: f.class, sha256: f.sha256, encoding: f.encoding, bytes };
+  });
+  const extra = Object.keys(contents).filter((p) => !seen.has(p));
+  if (extra.length) fail(`contents has files not listed in the manifest: ${extra[0]}`);
+  return files;
+}
+
+function checkHooks(hooks) {
+  if (hooks === undefined) return [];
+  if (!Array.isArray(hooks)) fail('manifest.hooks must be an array');
+  return hooks.map((h) => {
+    if (!h || typeof h.event !== 'string' || !h.event || typeof h.command !== 'string' || !h.command) {
+      fail('each hook needs a non-empty event and command');
+    }
+    if (h.matcher !== undefined && typeof h.matcher !== 'string') fail('hook matcher must be a string');
+    return h.matcher === undefined ? { event: h.event, command: h.command } : { event: h.event, matcher: h.matcher, command: h.command };
+  });
+}
+
+// source: { bundlePath } or { bundleObject }. Returns a verified, decoded bundle.
+function loadBundle(source, { cliVersion }) {
+  const warnings = [];
+  const raw = readSource(source, warnings);
+  if (!raw || typeof raw !== 'object' || !raw.manifest || !raw.contents || typeof raw.contents !== 'object') {
+    fail('expected { manifest, contents }');
+  }
+  checkHeader(raw.manifest, cliVersion);
+  const files = decodeFiles(raw.manifest, raw.contents);
+  const hooks = checkHooks(raw.manifest.hooks);
+  const blockFile = files.find((f) => f.class === 'block');
+  const body = blockFile ? blockFile.bytes.toString('utf8') : '';
+  if (body.includes(BEGIN) || body.includes(END)) fail('the CLAUDE.md block body must not contain the ai-sdlc begin/end markers');
+  return {
+    version: raw.manifest.version,
+    payloadSchema: raw.manifest.payload_schema,
+    files: files.filter((f) => f.class !== 'block'),
+    block: blockFile ? { sha256: blockFile.sha256, body } : null,
+    hooks,
+    warnings,
+  };
+}
+
+module.exports = { loadBundle, SUPPORTED_SCHEMA };

package/lib/cli-args.js

@@ -0,0 +1,89 @@
+'use strict';
+const { UsageError } = require('./errors');
+const semver = require('./semver');
+
+const COMMANDS = ['init', 'install', 'update', 'doctor', 'uninstall', 'version', 'help'];
+const VALUE_FLAGS = { '--project': 'project', '--root': 'root', '--from-bundle': 'fromBundle' };
+const BOOL_FLAGS = { '--dry-run': 'dryRun', '--check': 'check', '--force': 'force', '--yes': 'yes', '-y': 'yes', '--json': 'json', '--no-tui': 'noTui', '--help': 'help', '-h': 'help' };
+
+// Returns { command, flags }. Anything unrecognised is a usage error (exit 2).
+function parseArgs(argv) {
+  const flags = {};
+  let command = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const name = eq === -1 ? arg : arg.slice(0, eq);
+    if (VALUE_FLAGS[name]) {
+      const value = eq === -1 ? argv[(i += 1)] : arg.slice(eq + 1);
+      if (value === undefined || value === '' || (eq === -1 && value.startsWith('--'))) throw new UsageError(`${name} needs a value`);
+      flags[VALUE_FLAGS[name]] = value;
+    } else if (BOOL_FLAGS[name] && eq === -1) {
+      flags[BOOL_FLAGS[name]] = true;
+    } else if (name === '--version' && eq !== -1) {
+      flags.version = arg.slice(eq + 1);
+      if (!flags.version) throw new UsageError('--version needs a value');
+    } else if (arg === '--version' && command && command !== 'version') {
+      // After a command, --version <tag> pins the release to install.
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('-')) throw new UsageError('--version needs a value');
+      flags.version = next;
+      i += 1;
+    } else if (arg === '--version' || arg === '-v') {
+      command = command || 'version';
+    } else if (arg.startsWith('-')) {
+      throw new UsageError(`unknown option ${arg}`);
+    } else if (command === null) {
+      if (!COMMANDS.includes(arg)) throw new UsageError(`unknown command "${arg}"`);
+      // init is install with a guided wizard when a terminal is available.
+      command = arg === 'init' ? 'install' : arg;
+      if (arg === 'init') flags.init = true;
+    } else {
+      throw new UsageError(`unexpected argument "${arg}"`);
+    }
+  }
+  if (flags.help) command = 'help';
+  return { command, flags };
+}
+
+// Rejects flag combinations that make no sense, before anything touches the network or the disk.
+function validateFlags(command, flags) {
+  if (command === 'help') return;
+  if (flags.check && command !== 'version') throw new UsageError('--check only applies to the version command');
+  if (flags.version === undefined) return;
+  if (command !== 'install' && command !== 'update') throw new UsageError('--version only applies to install, update and init');
+  if (flags.fromBundle) throw new UsageError('--version cannot be combined with --from-bundle');
+  if (!semver.isReleaseTag(flags.version)) throw new UsageError('--version must be a release version such as 1.2.0 or v1.2.0');
+}
+
+const HELP = `ai-sdlc - install the ai-sdlc Claude Code harness into a project
+
+Usage: ai-sdlc <command> [options]
+
+Commands:
+  init         guided install in a terminal; otherwise the same as install
+  install      install into a project (refuses if already installed; see --force)
+  update       bring an installed project up to the given bundle
+  doctor       read-only health check of an installed project
+  uninstall    remove what install added, keep anything you changed
+  version      print the CLI version (--check: compare with the latest release)
+
+Options:
+  --project <path>      target project directory (skips the picker)
+  --root <dir>          where the picker looks for git repositories
+  --from-bundle <file>  use a local release bundle (<file>.sha256 is verified when present)
+                        without it, install/update download the latest release from GitHub
+  --version <tag>       with install/update: download this release instead of the latest
+  --check               with version: also show the latest release and the installed version
+  --dry-run             show exactly what would change, write nothing
+  --force               reinstall over an existing install / overwrite modified managed files
+  --yes, -y             do not ask for confirmation
+  --json                machine-readable output (needs --project; mutating runs also need --yes)
+  --no-tui              plain text output and prompts, no interactive screens
+
+Run without a command in a terminal to open a menu.
+
+Exit codes: 0 ok, 1 failure, 2 usage error.
+`;
+
+module.exports = { parseArgs, validateFlags, HELP };