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

package/lib/tui/flows/init-flow.js

@@ -0,0 +1,126 @@
+'use strict';
+// The guided install: banner, environment check, project, review, progress, result.
+// Nothing touches the project until the review is confirmed; the apply layer is
+// only called after that.
+const { CliError } = require('../../errors');
+const { loadReleaseBundle } = require('../../release-source');
+const { githubChecks } = require('../../github-checks');
+const { validateTarget } = require('../../project-picker');
+const { buildCommandPlan, planSignature } = require('../../command-plan');
+const { acquireLock } = require('../../journal');
+const { applyPlan } = require('../../apply-plan');
+const { inspect } = require('../../fs-safe');
+const { JOURNAL_REL } = require('../../path-rules');
+const { createTheme } = require('../theme');
+const { withSession, Cancelled, BACK } = require('../terminal');
+const { truncateMiddle } = require('../text-width');
+const { sanitize } = require('../sanitize');
+const { withSpinner } = require('../widgets/spinner');
+const { createConfirm } = require('../widgets/confirm');
+const { renderProgress } = require('../widgets/progress-bar');
+const { runPreflight, statusLine } = require('./preflight');
+const { bannerLines } = require('./intro');
+const { sessionOptions } = require('./session-options');
+const { pickProjectStep } = require('./pick-project-step');
+const { reviewBody } = require('./review-view');
+const { installedPanel } = require('./result-views');
+const { readRecent, rememberProject } = require('./recent-projects');
+const { shortPath } = require('./project-choices');
+
+const CHANGED_NOTE = 'The project changed after the plan was made; this is the updated plan.';
+
+function preflightLines(theme, items) {
+  return items.map((i) => {
+    const mark = theme.sym[{ ok: 'ok', warn: 'warn', fail: 'err' }[i.status]];
+    return `  ${theme.paint(theme.tone(i.status), mark)} ${sanitize(i.label)}  ${theme.paint('dim', sanitize(i.detail))}`;
+  });
+}
+
+async function wizard({ session, flags, io, cliVersion }) {
+  const { theme } = session;
+  const preflight = await withSpinner(session, 'Checking your environment...', (signal) => runPreflight({
+    flags, cwd: io.cwd, execFile: io.execFile, env: io.env, signal, extraChecks: io.extraChecks || (flags.fromBundle ? [] : githubChecks(io.github)),
+  }));
+  session.commit([...bannerLines(session), `  ${theme.paint('dim', statusLine(theme, preflight.items))}`, '', ...preflightLines(theme, preflight.items), '']);
+
+  // A failed token or access check ends the run here; the detail already names the way out (--from-bundle).
+  const blocked = preflight.items.find((i) => i.status === 'fail' && /^github-/.test(i.id));
+  if (blocked) throw new CliError(`${blocked.label}: ${blocked.detail}`);
+  const bundle = await withSpinner(session, flags.fromBundle ? 'Reading the bundle...' : 'Downloading the kit release...', (signal) => loadReleaseBundle(
+    { fromBundle: flags.fromBundle, version: flags.version, cwd: io.cwd, signal }, { fetchLatestBundle: io.fetchLatestBundle }, { cliVersion },
+  ));
+  for (const w of bundle.warnings) session.commit([`  ${theme.paint('warn', `${theme.sym.warn} ${sanitize(w)}`)}`]);
+
+  const recents = readRecent({ env: io.env, home: io.home });
+  let notice = '';
+  for (;;) {
+    const target = flags.project ? validateTarget(flags.project, { cwd: io.cwd, home: io.home }) : await pickProjectStep({ session, cwd: io.cwd, home: io.home, root: flags.root, recents, notice });
+    notice = '';
+    if (target === BACK) throw new Cancelled('escape');
+    let plan;
+    try {
+      ({ plan } = buildCommandPlan({ command: 'install', flags, project: target.dir, bundle, cliVersion }));
+    } catch (err) {
+      // For example "already installed": say so and let the user pick another project.
+      if (flags.project || !(err instanceof CliError)) throw err;
+      notice = err.message;
+      continue;
+    }
+    if ((await reviewAndInstall({ session, flags, io, cliVersion, bundle, target, plan })) === BACK) {
+      if (flags.project) throw new Cancelled('escape');
+      continue;
+    }
+    return 0;
+  }
+}
+
+// Review loop: if the project no longer matches the reviewed plan once the lock is held, review again.
+async function reviewAndInstall({ session, flags, io, cliVersion, bundle, target, plan: first }) {
+  let plan = first;
+  const warnings = inspect(target.dir, JOURNAL_REL).exists ? [`${JOURNAL_REL} exists: an earlier run was interrupted or another run is active`] : [];
+  for (;;) {
+    const current = plan;
+    const review = createConfirm({
+      title: 'Review', confirmLabel: 'Install', detailsToggle: true, guardMs: io.confirmGuardMs,
+      body: (state, ctx) => reviewBody({ theme: ctx.theme, project: truncateMiddle(sanitize(shortPath(target.dir, io.home)), ctx.width - 30), plan: current, bundle, hasGit: target.hasGit, warnings }, state),
+    });
+    if ((await session.run(review)) === BACK) return BACK;
+    const outcome = install({ session, flags, io, cliVersion, bundle, project: target.dir, reviewed: current });
+    if (!outcome.changed) return 0;
+    plan = outcome.plan;
+    if (!warnings.includes(CHANGED_NOTE)) warnings.push(CHANGED_NOTE);
+  }
+}
+
+// Lock, plan again under the lock, apply with a progress bar, release.
+// Returns { changed: true, plan } without writing when the fresh plan differs from the reviewed one.
+function install({ session, flags, io, cliVersion, bundle, project, reviewed }) {
+  const lock = acquireLock(project, 'install', { force: Boolean(flags.force) });
+  try {
+    const { plan } = buildCommandPlan({ command: 'install', flags, project, bundle, cliVersion });
+    if (planSignature(plan) !== planSignature(reviewed)) return { changed: true, plan };
+    const shown = truncateMiddle(sanitize(shortPath(project, io.home)), session.ctx().width - 14);
+    session.commit([`  ${session.theme.paint('ok', session.theme.sym.ok)} Project  ${session.theme.paint('dim', shown)}`]);
+    const show = ({ done, total, path: rel }) => session.draw((ctx) => [
+      '', `  Installing ai-sdlc ${sanitize(bundle.version)}`, renderProgress({ theme: ctx.theme, width: ctx.width, done, total, label: sanitize(rel || 'preparing') }),
+    ]);
+    applyPlan(project, plan, 'install', lock, { onProgress: show });
+    rememberProject(project, { env: io.env, home: io.home });
+    session.commit(installedPanel({ theme: session.theme, width: session.ctx().width, project: shortPath(project, io.home), plan, version: bundle.version }));
+    return { changed: false };
+  } finally {
+    lock.release();
+  }
+}
+
+async function runInitFlow({ flags, io, cliVersion }) {
+  const theme = createTheme({ env: io.env, stream: io.stdout });
+  try {
+    return await withSession(sessionOptions(io, theme), (session) => wizard({ session, flags, io, cliVersion }));
+  } catch (err) {
+    if (err instanceof Cancelled) throw new CliError(err.reason === 'interrupt' ? 'interrupted; nothing was changed' : 'cancelled; nothing was changed');
+    throw err;
+  }
+}
+
+module.exports = { runInitFlow };

package/lib/tui/flows/intro.js

@@ -0,0 +1,12 @@
+'use strict';
+// The header every interactive screen starts with: banner, then a dim status line.
+const { bannerFor } = require('../logo');
+
+const indent = (lines) => lines.map((l) => `  ${l}`);
+
+function bannerLines(session) {
+  const { theme } = session;
+  return ['', ...indent(bannerFor(session.columns, theme.level, { unicode: theme.unicode })), ''];
+}
+
+module.exports = { bannerLines, indent };

package/lib/tui/flows/menu-flow.js

@@ -0,0 +1,51 @@
+'use strict';
+// Bare `ai-sdlc` in a terminal: banner, what the current folder looks like,
+// and a short list of actions.
+const { CliError } = require('../../errors');
+const { createTheme } = require('../theme');
+const { withSession, Cancelled, BACK } = require('../terminal');
+const { createSelectList } = require('../widgets/select-list');
+const { bannerLines } = require('./intro');
+const { sessionOptions } = require('./session-options');
+const { truncateMiddle } = require('../text-width');
+const { sanitize } = require('../sanitize');
+const { projectState, shortPath } = require('./project-choices');
+
+const ACTIONS = [
+  { label: 'Install', hint: 'set up ai-sdlc in a project', value: 'install', hotkey: '1' },
+  { label: 'Update', hint: 'bring an installed project up to date', value: 'update', hotkey: '2' },
+  { label: 'Doctor', hint: 'check an installed project', value: 'doctor', hotkey: '3' },
+  { label: 'Uninstall', hint: 'remove what install added', value: 'uninstall', hotkey: '4' },
+  { label: 'Quit', hint: '', value: 'quit', hotkey: '5' },
+];
+
+function stateLines(theme, state, cwd, home, width) {
+  let status;
+  if (state.invalid) status = theme.paint('warn', `${theme.sym.warn} manifest cannot be trusted: ${truncateMiddle(state.invalid, Math.max(20, width - 40))}`);
+  else if (state.version) status = theme.paint('ok', `${theme.sym.ok} ai-sdlc ${sanitize(state.version)} installed`);
+  else {
+    status = theme.paint('dim', 'ai-sdlc not installed');
+    if (!state.hasGit) status += `  ${theme.paint('warn', `${theme.sym.warn} no .git`)}`;
+  }
+  return [`  ${theme.paint('dim', 'Folder')}  ${truncateMiddle(sanitize(shortPath(cwd, home)), width - 12)}`, `  ${theme.paint('dim', 'Status')}  ${status}`];
+}
+
+// Resolves to { command, installedHere }. Quit and Esc give command 'quit'.
+async function chooseAction({ io }) {
+  const theme = createTheme({ env: io.env, stream: io.stdout });
+  const state = projectState(io.cwd);
+  try {
+    const command = await withSession(sessionOptions(io, theme), async (session) => {
+      session.commit([...bannerLines(session), ...stateLines(theme, state, io.cwd, io.home, session.ctx().width), '']);
+      const picked = await session.run(createSelectList({ title: 'What would you like to do?', items: ACTIONS, filterable: false, maxVisible: ACTIONS.length }));
+      session.clear();
+      return picked === BACK ? 'quit' : picked.item.value;
+    });
+    return { command, installedHere: Boolean(state.version) && !state.invalid };
+  } catch (err) {
+    if (err instanceof Cancelled) throw new CliError(err.reason === 'interrupt' ? 'interrupted; nothing was changed' : 'cancelled; nothing was changed');
+    throw err;
+  }
+}
+
+module.exports = { chooseAction, ACTIONS };

package/lib/tui/flows/pick-project-step.js

@@ -0,0 +1,42 @@
+'use strict';
+// "Which project?" step: filterable list of repositories and recent projects,
+// with an "Enter a path..." entry that opens a path field with Tab completion.
+const { UsageError } = require('../../errors');
+const { validateTarget } = require('../../project-picker');
+const { BACK } = require('../terminal');
+const { createSelectList } = require('../widgets/select-list');
+const { createPathInput } = require('../widgets/path-input');
+const { buildProjectItems, PATH_CHOICE } = require('./project-choices');
+
+// Resolves to { dir, hasGit } or BACK.
+async function pickProjectStep({ session, cwd, home, root, recents, notice: initialNotice = '' }) {
+  const items = buildProjectItems({ cwd, root, home, recents, theme: session.theme });
+  const maxVisible = Math.max(3, Math.min(10, session.rows - 10));
+  const validate = (text) => validateTarget(text, { cwd, home });
+  let notice = initialNotice;
+  let mode = 'list';
+  for (;;) {
+    if (mode === 'list') {
+      const picked = await session.run(createSelectList({ title: 'Select the project to install into', items, maxVisible, notice, placeholder: 'Type to filter projects' }));
+      if (picked === BACK) return BACK;
+      if (picked.item.value === PATH_CHOICE) {
+        mode = 'path';
+        continue;
+      }
+      try {
+        return validate(picked.item.value);
+      } catch (err) {
+        if (!(err instanceof UsageError)) throw err;
+        notice = err.message;
+      }
+    } else {
+      const typed = await session.run(createPathInput({ cwd, home, validate }));
+      if (typed === BACK) {
+        mode = 'list';
+        notice = '';
+      } else return typed;
+    }
+  }
+}
+
+module.exports = { pickProjectStep };

package/lib/tui/flows/preflight.js

@@ -0,0 +1,80 @@
+'use strict';
+// Environment checks shown before the project picker. Items are
+// { id, status: 'ok' | 'warn' | 'fail', label, detail, segment? }.
+const fs = require('fs');
+const path = require('path');
+const { execFile: nodeExecFile } = require('child_process');
+const { sanitize } = require('../sanitize');
+const { payloadRepo, apiBase, isDefaultApiBase } = require('../../config');
+
+const MIN_NODE_MAJOR = 18;
+
+function probeGit(execFile, signal) {
+  return new Promise((resolve) => {
+    execFile('git', ['--version'], { timeout: 4000, windowsHide: true, signal }, (err, stdout) => {
+      resolve(err ? null : sanitize(String(stdout).trim().replace(/^git version\s*/i, '')).slice(0, 80));
+    });
+  });
+}
+
+// "owner/repo", plus the API base when it is not the public GitHub API (so it is never a surprise).
+function releaseSource(env) {
+  try {
+    const repo = payloadRepo(env);
+    const base = apiBase(env);
+    return { repo, custom: !isDefaultApiBase(base), text: isDefaultApiBase(base) ? repo : `${repo} via ${base}` };
+  } catch (err) {
+    return { custom: false, text: err.message };
+  }
+}
+
+function sourceItem(flags, cwd, env) {
+  if (flags.fromBundle) {
+    const file = path.resolve(cwd, flags.fromBundle);
+    const found = fs.existsSync(file);
+    return {
+      id: 'source', status: found ? 'ok' : 'fail', label: 'Kit source: bundle file',
+      detail: sanitize(found ? path.basename(file) : `not found: ${file}`), segment: found ? 'kit source: bundle file' : 'kit source: missing',
+    };
+  }
+  const src = releaseSource(env);
+  return {
+    id: 'source', status: 'ok', label: 'Kit source: GitHub release',
+    detail: sanitize(src.text), segment: src.custom ? 'kit source: GitHub release (custom API)' : 'kit source: GitHub release',
+  };
+}
+
+// `extraChecks` is the plug-in point for further checks (the wizard adds the GitHub
+// token and repository access checks when no local bundle is given). Each is an async (context) => item | null and runs after
+// the built-in ones; an exception becomes a warning item instead of aborting.
+async function runPreflight({ flags = {}, cwd = process.cwd(), nodeVersion = process.version, execFile = nodeExecFile, extraChecks = [], env = process.env, signal } = {}) {
+  const major = Number(String(nodeVersion).replace(/^v/, '').split('.')[0]);
+  const git = await probeGit(execFile, signal);
+  const items = [
+    { id: 'node', status: major >= MIN_NODE_MAJOR ? 'ok' : 'fail', label: 'Node.js', detail: `${nodeVersion} (needs >= ${MIN_NODE_MAJOR})`, segment: `node ${major}` },
+    { id: 'git', status: git ? 'ok' : 'warn', label: 'git', detail: git || 'not found; only used to recognise repositories', segment: 'git' },
+    sourceItem(flags, cwd, env),
+  ];
+  for (const check of extraChecks) {
+    try {
+      const item = await check({ flags, cwd, signal });
+      if (item) items.push(item);
+    } catch (err) {
+      if (signal && signal.aborted) throw signal.reason;
+      items.push({ id: 'extra', status: 'warn', label: 'Additional check', detail: sanitize(err.message) });
+    }
+  }
+  return { items };
+}
+
+// "Using: node 24 | git ✔ | kit source: bundle file"
+function statusLine(theme, items) {
+  const parts = items.filter((i) => i.segment).map((i) => {
+    if (i.id !== 'node' && i.id !== 'git' && i.id !== 'source') return sanitize(i.segment);
+    if (i.id === 'git') return `git ${i.status === 'ok' ? theme.sym.ok : theme.sym.warn}`;
+    return i.segment;
+  });
+  return `Using: ${parts.join(' | ')}`;
+}
+
+module.exports = { runPreflight, statusLine, MIN_NODE_MAJOR };

package/lib/tui/flows/project-choices.js

@@ -0,0 +1,64 @@
+'use strict';
+// Candidate projects for the picker: remembered ones first, then repositories
+// found next to the working directory (or under --root). Everything shown is
+// data from disk, so it is sanitized before it reaches a widget.
+const fs = require('fs');
+const path = require('path');
+const { findRepos } = require('../../project-picker');
+const { readManifest } = require('../../manifest');
+const { sanitize } = require('../sanitize');
+
+const PATH_CHOICE = Symbol('enter-a-path');
+const MAX_CANDIDATES = 200;
+
+// { hasGit, version, invalid }: version is the installed payload version or null;
+// invalid carries the reason when the manifest exists but cannot be trusted.
+function projectState(dir) {
+  const state = { hasGit: fs.existsSync(path.join(dir, '.git')), version: null, invalid: null };
+  try {
+    const m = readManifest(dir);
+    state.version = m ? m.payload_version : null;
+  } catch (err) {
+    state.invalid = sanitize(err.message);
+  }
+  return state;
+}
+
+const shortPath = (dir, home) => (home && (dir === home || dir.startsWith(home + path.sep)) ? `~${dir.slice(home.length)}` : dir);
+
+function badgeFor(state, theme) {
+  if (!state.hasGit) return { badge: `no .git ${theme.sym.warn}`, tone: 'warn' };
+  if (state.invalid) return { badge: `manifest invalid ${theme.sym.warn}`, tone: 'warn' };
+  if (state.version) return { badge: `installed v${sanitize(state.version)} ${theme.sym.arrow} update`, tone: 'ok' };
+  return { badge: 'not installed', tone: 'dim' };
+}
+
+function realOrSelf(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch (_) {
+    return p;
+  }
+}
+
+// Volumes on Windows and macOS are usually case-insensitive: the same folder spelled twice is one folder.
+const dedupeKey = (p) => (process.platform === 'win32' || process.platform === 'darwin' ? p.toLowerCase() : p);
+
+// Returns picker items ending with the sticky "Enter a path..." entry (at most MAX_CANDIDATES projects).
+function buildProjectItems({ cwd, root, home, recents = [], theme }) {
+  const bases = root ? [path.resolve(cwd, root)] : [cwd, path.dirname(cwd)];
+  const seen = new Set();
+  const items = [];
+  for (const dir of [...recents, ...findRepos(bases, MAX_CANDIDATES)]) {
+    if (items.length >= MAX_CANDIDATES) break;
+    const real = realOrSelf(dir);
+    const key = dedupeKey(real);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    items.push({ label: path.basename(real) || real, hint: shortPath(real, home), value: real, ...badgeFor(projectState(real), theme) });
+  }
+  items.push({ label: `Enter a path${theme.sym.ellipsis}`, hint: '', value: PATH_CHOICE, sticky: true });
+  return items;
+}
+
+module.exports = { buildProjectItems, projectState, shortPath, badgeFor, PATH_CHOICE, MAX_CANDIDATES };

package/lib/tui/flows/recent-projects.js

@@ -0,0 +1,76 @@
+'use strict';
+// Remembers project paths (and nothing else) between runs in a small JSON file
+// under the user's config directory. Every failure is ignored: this is a
+// convenience, never a reason for a run to fail.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const MAX_RECENT = 12;
+const MAX_EXAMINED = 40; // entries checked on disk per read, so a dead path cannot stall startup
+
+// XDG_CONFIG_HOME counts only when absolute, as the XDG specification says.
+function configDir(env = process.env, home = os.homedir(), platform = process.platform) {
+  if (env.XDG_CONFIG_HOME && path.isAbsolute(env.XDG_CONFIG_HOME)) return path.join(env.XDG_CONFIG_HOME, 'ai-sdlc');
+  if (platform === 'win32' && env.APPDATA) return path.join(env.APPDATA, 'ai-sdlc');
+  return path.join(home, '.config', 'ai-sdlc');
+}
+
+const recentFile = (opts = {}) => path.join(configDir(opts.env, opts.home, opts.platform), 'recent.json');
+
+function readList(opts) {
+  const parsed = JSON.parse(fs.readFileSync(recentFile(opts), 'utf8'));
+  return Array.isArray(parsed && parsed.projects) ? parsed.projects.filter((p) => typeof p === 'string' && path.isAbsolute(p)) : [];
+}
+
+// Absolute paths of remembered projects that still exist, newest first.
+function readRecent(opts = {}) {
+  try {
+    const out = [];
+    for (const p of readList(opts).slice(0, MAX_EXAMINED)) {
+      try {
+        if (fs.statSync(p).isDirectory()) out.push(p);
+      } catch (_) {
+        /* gone: skip */
+      }
+      if (out.length >= MAX_RECENT) break;
+    }
+    return out;
+  } catch (_) {
+    return [];
+  }
+}
+
+// Private to the user: the folder is created 0700 and the file 0600 (no effect on Windows).
+function writePrivate(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try {
+    fs.writeFileSync(tmp, text, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+// Puts `dir` first in the list. Returns true when the file was written.
+function rememberProject(dir, opts = {}) {
+  try {
+    if (typeof dir !== 'string' || !path.isAbsolute(dir)) return false;
+    let current = [];
+    try {
+      current = readList(opts);
+    } catch (_) {
+      /* no file yet, or unreadable: start a new list */
+    }
+    const projects = [dir, ...current.filter((p) => p !== dir)].slice(0, MAX_RECENT);
+    writePrivate(recentFile(opts), `${JSON.stringify({ projects }, null, 2)}\n`);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { configDir, recentFile, readRecent, rememberProject };

package/lib/tui/flows/result-views.js

@@ -0,0 +1,89 @@
+'use strict';
+// Static views (frames are plain string[]) for results: doctor checklist,
+// plan listing, and the closing panels. No input handling here.
+const { summarize } = require('../../plan');
+const { QUIET } = require('../../cli-output');
+const { padEnd, truncateMiddle } = require('../text-width');
+const { sanitize } = require('../sanitize');
+const { renderPanel } = require('../widgets/panel');
+
+const ACTION_TONE = {
+  create: 'ok', restore: 'ok', replace: 'accent', update: 'accent', 'write-new': 'warn', 'skip-deleted': 'warn',
+  'keep-modified': 'warn', delete: 'err', remove: 'err', 'keep-existing': 'dim', unchanged: 'dim', forget: 'dim',
+};
+const STATUS_SYMBOL = { ok: 'ok', warn: 'warn', fail: 'err', info: 'info' };
+
+const counts = (actions) => Object.entries(summarize(actions)).map(([k, v]) => `${v} ${sanitize(k)}`).join(', ');
+
+function checkRow(theme, check, nameWidth) {
+  const tone = theme.tone(check.status);
+  const mark = theme.sym[STATUS_SYMBOL[check.status] || 'info'];
+  return `  ${theme.paint(tone, mark)} ${padEnd(sanitize(check.name), nameWidth)}  ${theme.paint('dim', sanitize(check.detail))}`;
+}
+
+function doctorView({ theme, width, project, report, warnings = [] }) {
+  const nameWidth = Math.max(0, ...report.checks.map((c) => sanitize(c.name).length));
+  const by = (s) => report.checks.filter((c) => c.status === s).length;
+  const failed = by('fail');
+  const warned = by('warn');
+  const tone = failed ? 'err' : warned ? 'warn' : 'ok';
+  const verdict = failed ? 'Problems found' : warned ? 'Healthy, with warnings' : 'Healthy';
+  return [
+    '',
+    `  ${theme.paint('bold', 'ai-sdlc doctor')}  ${theme.paint('dim', truncateMiddle(sanitize(project), width - 20))}`,
+    '',
+    ...report.checks.map((c) => checkRow(theme, c, nameWidth)),
+    ...warnings.map((w) => `  ${theme.paint('warn', theme.sym.warn)} ${sanitize(w)}`),
+    '',
+    ...renderPanel({
+      theme, width, tone, title: verdict,
+      lines: [`${report.checks.length} checks: ${by('ok')} ok, ${warned} warning(s), ${failed} failed`],
+    }),
+  ];
+}
+
+// Action rows, quiet ones folded into one line. `limit` caps the rows (null = all).
+function planRows(theme, plan, limit = null) {
+  const loud = plan.actions.filter((a) => !QUIET.has(a.action));
+  const shown = limit === null ? loud : loud.slice(0, limit);
+  const rows = shown.map((a) => {
+    const tone = ACTION_TONE[a.action] || 'dim';
+    return `  ${theme.paint(tone, theme.sym.bullet)} ${theme.paint(tone, padEnd(sanitize(a.action), 13))} ${sanitize(a.path)}${a.detail ? theme.paint('dim', `  (${sanitize(a.detail)})`) : ''}`;
+  });
+  if (shown.length < loud.length) rows.push(theme.paint('dim', `  ${theme.sym.ellipsis} ${loud.length - shown.length} more`));
+  const quiet = plan.actions.length - loud.length;
+  if (quiet) rows.push(theme.paint('dim', `  (${quiet} already in place or user-owned, untouched)`));
+  return rows;
+}
+
+function planView({ theme, width, command, project, plan, dryRun }) {
+  return [
+    '',
+    `  ${theme.paint('bold', `ai-sdlc ${command}`)}${dryRun ? theme.paint('warn', '  dry run, nothing will be written') : ''}`,
+    `  ${theme.paint('dim', `project: ${truncateMiddle(sanitize(project), width - 14)}`)}`,
+    `  ${theme.paint('dim', `payload: ${sanitize(plan.payloadVersion)}`)}`,
+    '',
+    ...planRows(theme, plan),
+    '',
+    `  ${theme.paint('dim', `summary: ${counts(plan.actions)}`)}`,
+  ];
+}
+
+function doneView({ theme, width, command, plan }) {
+  const lines = [`${command} finished: ${counts(plan.actions)}`];
+  if (plan.actions.some((a) => a.action === 'write-new')) lines.push('Review the *.new files next to the files you modified and merge by hand.');
+  return ['', ...renderPanel({ theme, width, tone: 'ok', title: `${theme.sym.ok} Done`, lines })];
+}
+
+// The wizard's closing panel: what was written and what to do next.
+function installedPanel({ theme, width, project, plan, version }) {
+  const written = plan.actions.filter((a) => a.write).length;
+  const lines = [`ai-sdlc ${sanitize(version)} installed into ${truncateMiddle(sanitize(project), width - 30)}`, `${written} file(s) written (${counts(plan.actions)})`, '', 'Next steps:', '  1. Open this folder in Claude Code (terminal or the VS Code extension).'];
+  let n = 2;
+  if (plan.actions.some((a) => a.path === 'ai-sdlc/project.md')) lines.push(`  ${n++}. Fill in ai-sdlc/project.md with what your project is about.`);
+  lines.push(`  ${n++}. Run \`ai-sdlc doctor\` in the project to check the install.`);
+  if (plan.actions.some((a) => a.action === 'write-new')) lines.push('', 'Review the *.new files next to files you modified and merge by hand.');
+  return ['', ...renderPanel({ theme, width, tone: 'ok', title: `${theme.sym.ok} Installed`, lines })];
+}
+
+module.exports = { doctorView, planView, planRows, doneView, installedPanel, counts };

package/lib/tui/flows/review-view.js

@@ -0,0 +1,45 @@
+'use strict';
+// Body of the review screen: what the run will do, grouped by file class.
+const { padEnd } = require('../text-width');
+const { sanitize } = require('../sanitize');
+const { planRows } = require('./result-views');
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// Per-class tallies: { managed: { total, by: { create: 2 } }, 'user-once': {...} }.
+function tallyByClass(plan, bundle) {
+  const classOf = new Map(((bundle && bundle.files) || []).map((f) => [f.path, f.class]));
+  const out = { managed: { total: 0, by: {} }, 'user-once': { total: 0, by: {} } };
+  for (const a of plan.actions.filter((x) => x.kind === 'file')) {
+    const cls = classOf.get(a.action === 'write-new' ? a.path.replace(/\.new$/, '') : a.path) || 'managed';
+    if (a.action !== 'write-new') out[cls].total += 1;
+    out[cls].by[a.action] = (out[cls].by[a.action] || 0) + 1;
+  }
+  return out;
+}
+
+const breakdown = (by) => Object.entries(by).map(([k, v]) => `${sanitize(k)} ${v}`).join(', ');
+
+// ctx: { theme, project, plan, bundle, hasGit, warnings }
+function reviewBody({ theme, project, plan, bundle, hasGit, warnings = [] }, state) {
+  const dim = (s) => theme.paint('dim', s);
+  const tally = tallyByClass(plan, bundle);
+  const block = plan.actions.find((a) => a.kind === 'block');
+  const settings = plan.actions.find((a) => a.kind === 'settings');
+  const hookCount = bundle ? bundle.hooks.length : 0;
+  const row = (name, text, extra) => `  ${theme.paint('accent', padEnd(name, 10))} ${padEnd(text, 18)} ${dim(extra)}`;
+
+  const lines = [`${theme.paint('bold', `ai-sdlc ${sanitize(plan.payloadVersion)}`)} ${theme.sym.arrow} ${sanitize(project)}`, ''];
+  lines.push(row('managed', plural(tally.managed.total, 'file'), breakdown(tally.managed.by)));
+  lines.push(row('user-once', plural(tally['user-once'].total, 'starter file'), breakdown(tally['user-once'].by)));
+  lines.push(row('block', 'CLAUDE.md block', block ? sanitize(block.action) : 'unchanged'));
+  lines.push(row('hooks', plural(hookCount, 'hook'), `.claude/settings.json ${settings ? sanitize(settings.action) : 'unchanged'}`));
+  lines.push('', dim('  CLAUDE.md: only the marked ai-sdlc block is managed; the rest of the file is never touched.'));
+  lines.push(dim('  Starter files are created only if missing and never overwritten.'));
+  if (!hasGit) lines.push('', `  ${theme.paint('warn', `${theme.sym.warn} no .git directory here; this may not be a repository root`)}`);
+  for (const w of warnings) lines.push(`  ${theme.paint('warn', `${theme.sym.warn} ${sanitize(w)}`)}`);
+  if (state.expanded) lines.push('', theme.paint('bold', '  Full list'), ...planRows(theme, plan));
+  return lines;
+}
+
+module.exports = { reviewBody, tallyByClass };

package/lib/tui/flows/session-options.js

@@ -0,0 +1,7 @@
+'use strict';
+// Options for a terminal session built from the command's io.
+const sessionOptions = (io, theme) => ({
+  stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, theme, proc: io.proc, escapeMs: io.escapeMs,
+});
+
+module.exports = { sessionOptions };

package/lib/tui/flows/terminal-views.js

@@ -0,0 +1,17 @@
+'use strict';
+// Result views for update/doctor/uninstall when stdout is a terminal.
+// Each returns lines for the caller to print; nothing here reads input.
+const { createTheme } = require('../theme');
+const views = require('./result-views');
+
+function createViews(io) {
+  const theme = createTheme({ env: io.env, stream: io.stdout });
+  const width = Math.max(40, (io.stdout.columns || 80) - 1);
+  return {
+    doctor: (data) => views.doctorView({ theme, width, ...data }),
+    plan: (data) => views.planView({ theme, width, ...data }),
+    done: (data) => views.doneView({ theme, width, ...data }),
+  };
+}
+
+module.exports = { createViews };