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

package/lib/merge-settings.js

@@ -0,0 +1,125 @@
+'use strict';
+const { isDeepStrictEqual } = require('util');
+const { CliError } = require('./errors');
+
+const SETTINGS_REL = '.claude/settings.json';
+
+function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+// Strict parse: anything unexpected aborts before a single byte is written.
+function parseSettings(text) {
+  if (text === null) return {};
+  let value;
+  try {
+    value = JSON.parse(stripBom(text));
+  } catch (err) {
+    throw new CliError(`${SETTINGS_REL} is not valid JSON (${err.message}); fix it and re-run. Nothing was changed.`);
+  }
+  const wrong = (why) => {
+    throw new CliError(`${SETTINGS_REL}: ${why}; fix it and re-run. Nothing was changed.`);
+  };
+  if (!value || typeof value !== 'object' || Array.isArray(value)) wrong('top level must be an object');
+  if (value.hooks !== undefined) {
+    if (!value.hooks || typeof value.hooks !== 'object' || Array.isArray(value.hooks)) wrong('"hooks" must be an object');
+    for (const [event, list] of Object.entries(value.hooks)) {
+      if (!Array.isArray(list)) wrong(`hooks.${event} must be an array`);
+    }
+  }
+  return value;
+}
+
+function detectFormat(text) {
+  if (text === null) return { eol: '\n', indent: '  ', trailing: true, bom: false };
+  const body = stripBom(text);
+  const indentMatch = /\n([ \t]+)\S/.exec(body);
+  let indent = '  ';
+  if (indentMatch) indent = indentMatch[1];
+  else if (!body.trim().includes('\n')) indent = '';
+  return { eol: body.includes('\r\n') ? '\r\n' : '\n', indent, trailing: /\n$/.test(body), bom: body !== text };
+}
+
+function serialize(obj, fmt) {
+  let out = JSON.stringify(obj, null, fmt.indent);
+  if (fmt.eol === '\r\n') out = out.replace(/\n/g, '\r\n');
+  if (fmt.trailing) out += fmt.eol;
+  return (fmt.bom ? '' : '') + out;
+}
+
+const entryMatcher = (h) => (h.matcher === undefined ? '' : h.matcher);
+const sameCommand = (x, h) => x && x.type === 'command' && x.command === h.command;
+
+function matchingEntries(obj, h) {
+  const list = (obj.hooks && obj.hooks[h.event]) || [];
+  return list.filter((e) => e && Array.isArray(e.hooks) && (e.matcher === undefined ? '' : e.matcher) === entryMatcher(h));
+}
+
+const hasHook = (obj, h) => matchingEntries(obj, h).some((e) => e.hooks.some((x) => sameCommand(x, h)));
+
+function addHook(obj, h) {
+  if (hasHook(obj, h)) return false;
+  obj.hooks = obj.hooks || {};
+  obj.hooks[h.event] = obj.hooks[h.event] || [];
+  const entry = h.matcher === undefined ? {} : { matcher: h.matcher };
+  entry.hooks = [{ type: 'command', command: h.command }];
+  obj.hooks[h.event].push(entry);
+  return true;
+}
+
+// Removes the first occurrence of exactly this hook; other entries stay.
+function removeHook(obj, h) {
+  for (const entry of matchingEntries(obj, h)) {
+    const i = entry.hooks.findIndex((x) => sameCommand(x, h));
+    if (i === -1) continue;
+    entry.hooks.splice(i, 1);
+    if (!entry.hooks.length) obj.hooks[h.event].splice(obj.hooks[h.event].indexOf(entry), 1);
+    return true;
+  }
+  return false;
+}
+
+// Drops event arrays (and then "hooks") that an edit left empty.
+function pruneEmpty(obj, events) {
+  if (!obj.hooks) return;
+  for (const ev of events) if (Array.isArray(obj.hooks[ev]) && !obj.hooks[ev].length) delete obj.hooks[ev];
+  if (!Object.keys(obj.hooks).length) delete obj.hooks;
+}
+
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64');
+const unb64 = (s) => Buffer.from(s, 'base64').toString('utf8');
+
+// currentText: file text or null when absent. info: manifest.settings or null.
+// Returns { text, info, added }; text === null means "delete the file".
+function renderSettings(currentText, info, removeList, addList) {
+  if (!removeList.length && !addList.length) return { text: currentText, info, added: [] };
+  const fmt = detectFormat(currentText);
+  const obj = parseSettings(currentText);
+  // A hook that is both installed and shipped again stays where it is.
+  const sameHook = (a, b) => a.event === b.event && entryMatcher(a) === entryMatcher(b) && a.command === b.command;
+  const kept = removeList.filter((r) => addList.some((a) => sameHook(a, r)) && hasHook(obj, r));
+  const dropped = removeList.filter((r) => !kept.includes(r));
+  for (const h of dropped) removeHook(obj, h);
+  const added = addList.filter((h) => kept.some((k) => sameHook(k, h)) || addHook(obj, h));
+  const touched = [...new Set(dropped.map((h) => h.event))];
+  pruneEmpty(obj, touched);
+
+  if (isDeepStrictEqual(obj, parseSettings(currentText))) {
+    return { text: currentText, info: added.length ? info : null, added };
+  }
+  if (added.length) {
+    const nextInfo = info || { created: currentText === null, original: currentText === null ? null : b64(currentText) };
+    return { text: serialize(obj, fmt), info: nextInfo, added };
+  }
+  // No hooks of ours remain: give the file back the way it was before the install.
+  if (info && info.original !== null) {
+    const original = unb64(info.original);
+    const origObj = parseSettings(original);
+    pruneEmpty(origObj, touched);
+    if (isDeepStrictEqual(obj, origObj)) return { text: original, info: null, added };
+  }
+  if (info && info.created && !Object.keys(obj).length) return { text: null, info: null, added };
+  return { text: serialize(obj, fmt), info: null, added };
+}
+
+module.exports = { SETTINGS_REL, parseSettings, hasHook, renderSettings };

package/lib/path-rules.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const MANIFEST_REL = '.claude/ai-sdlc.manifest.json';
+const JOURNAL_REL = '.claude/ai-sdlc.journal.json';
+
+// Paths the installer owns or that belong to the user's own tooling.
+const RESERVED = new Set([MANIFEST_REL, JOURNAL_REL, '.claude/settings.json', '.claude/settings.local.json']);
+
+// Class/location rules shared by freshly downloaded bundles and by the manifest
+// of an earlier install (which is just as untrusted before something is deleted
+// on its say-so). Returns a reason string, or null when the path is acceptable.
+// Syntax checks (absolute, "..", backslash) live in fs-safe.assertRelPath.
+function installPathProblem(rel, cls) {
+  const lower = rel.toLowerCase();
+  if (lower.split('/').includes('.git')) return 'paths inside .git are not allowed';
+  if (RESERVED.has(lower)) return 'reserved for the installer or the user';
+  if (cls === 'block') return lower === 'claude.md' ? null : 'only CLAUDE.md may use class "block"';
+  if (lower === 'claude.md') return 'CLAUDE.md must use class "block"';
+  if (cls === 'managed' && !rel.startsWith('.claude/')) return 'managed files must live under .claude/';
+  return null;
+}
+
+module.exports = { MANIFEST_REL, JOURNAL_REL, RESERVED, installPathProblem };

package/lib/plan-files.js

@@ -0,0 +1,86 @@
+'use strict';
+const { inspect } = require('./fs-safe');
+
+// An action is a plain record. `write` (Buffer) / `remove` make it a disk
+// change; everything else is information only. Apply never decides anything.
+function act(kind, action, rel, detail, extra) {
+  return { kind, action, path: rel, detail: detail || '', ...extra };
+}
+
+// Three-way comparison for payload files:
+//   old = hash recorded at last install, disk = what is there now, new = bundle.
+// `reinstall` is true for install (even over a manifest) and false for update.
+// Returns { actions, tracked } where tracked is the file list for the next manifest.
+function planFiles({ project, bundle, prior, force, reinstall }) {
+  const actions = [];
+  const tracked = [];
+  const priorByPath = new Map((prior ? prior.files : []).map((f) => [f.path, f]));
+  const shipped = new Set(bundle.files.map((f) => f.path));
+
+  for (const f of bundle.files) {
+    const disk = inspect(project, f.path);
+    const old = priorByPath.get(f.path);
+
+    if (f.class === 'user-once') {
+      tracked.push({ path: f.path, sha256: f.sha256, class: 'user-once' });
+      if (disk.exists) actions.push(act('file', 'keep-existing', f.path, 'user-owned, never overwritten'));
+      else if (old && old.class === 'user-once' && !reinstall) {
+        // Tracked before and gone now: the user removed it, so an update must not bring it back.
+        actions.push(act('file', 'skip-deleted', f.path, 'you deleted this starter file; not re-created'));
+      } else actions.push(act('file', 'create', f.path, 'starter file', { write: f.bytes }));
+      continue;
+    }
+
+    const recorded = old && old.class === 'managed' ? old.sha256 : null;
+    const own = { path: f.path, sha256: f.sha256, class: 'managed' };
+    if (!disk.exists) {
+      tracked.push(own);
+      actions.push(act('file', recorded ? 'restore' : 'create', f.path, '', { write: f.bytes }));
+    } else if (disk.hash === f.sha256) {
+      tracked.push(own);
+      actions.push(act('file', 'unchanged', f.path));
+    } else if (recorded && disk.hash === recorded) {
+      tracked.push(own);
+      actions.push(act('file', 'replace', f.path, 'new payload version', { write: f.bytes }));
+    } else if (force) {
+      tracked.push(own);
+      actions.push(act('file', 'replace', f.path, 'overwritten (--force)', { write: f.bytes }));
+    } else {
+      // Locally modified (or a foreign file sits here): keep it, offer the new copy beside it.
+      if (recorded) tracked.push({ path: f.path, sha256: recorded, class: 'managed' });
+      actions.push(act('file', 'keep-modified', f.path, recorded ? 'locally modified' : 'a different file already exists'));
+      if (f.sha256 !== recorded) {
+        const newRel = `${f.path}.new`;
+        inspect(project, newRel);
+        actions.push(act('file', 'write-new', newRel, 'incoming version for manual merge', { write: f.bytes }));
+      }
+    }
+  }
+
+  for (const old of priorByPath.values()) {
+    if (old.class !== 'managed' || shipped.has(old.path)) continue;
+    const disk = inspect(project, old.path);
+    if (!disk.exists) actions.push(act('file', 'forget', old.path, 'no longer shipped, already gone'));
+    else if (disk.hash === old.sha256) actions.push(act('file', 'delete', old.path, 'no longer shipped', { remove: true }));
+    else actions.push(act('file', 'keep-modified', old.path, 'no longer shipped but locally modified; now yours'));
+  }
+  return { actions, tracked };
+}
+
+// Uninstall counterpart: only unmodified managed files are deleted.
+function planRemoveFiles({ project, prior }) {
+  const actions = [];
+  for (const f of prior.files) {
+    if (f.class === 'user-once') {
+      actions.push(act('file', 'keep-existing', f.path, 'user-owned, left in place'));
+      continue;
+    }
+    const disk = inspect(project, f.path);
+    if (!disk.exists) actions.push(act('file', 'forget', f.path, 'already gone'));
+    else if (disk.hash === f.sha256) actions.push(act('file', 'delete', f.path, '', { remove: true }));
+    else actions.push(act('file', 'keep-modified', f.path, 'locally modified, left in place'));
+  }
+  return actions;
+}
+
+module.exports = { act, planFiles, planRemoveFiles };

package/lib/plan.js

@@ -0,0 +1,78 @@
+'use strict';
+const { inspect, utf8Text } = require('./fs-safe');
+const { act, planFiles, planRemoveFiles } = require('./plan-files');
+const { SETTINGS_REL, renderSettings } = require('./merge-settings');
+const { upsertBlock, removeBlock } = require('./merge-claude-md');
+const { MANIFEST_REL, buildManifest, serializeManifest } = require('./manifest');
+
+const CLAUDE_MD = 'CLAUDE.md';
+// Turns "what the file should contain" into an action (or nothing if unchanged).
+function textAction(kind, rel, file, next, detail) {
+  const current = utf8Text(file, rel);
+  if (next === current) return null;
+  if (next === null) return act(kind, 'remove', rel, detail, { remove: true });
+  return act(kind, file.exists ? 'update' : 'create', rel, detail, { write: Buffer.from(next, 'utf8') });
+}
+
+function settingsStep(project, prior, removeList, addList) {
+  const file = inspect(project, SETTINGS_REL);
+  const out = renderSettings(utf8Text(file, SETTINGS_REL), prior ? prior.settings : null, removeList, addList);
+  const action = textAction('settings', SETTINGS_REL, file, out.text, `${out.added.length} hook(s) tracked`);
+  return { action, info: out.info, hooks: out.added };
+}
+
+// install and update are the same plan; `prior` (the installed manifest) selects the behaviour.
+function planSync({ project, bundle, prior, force, cliVersion, op }) {
+  const { actions, tracked } = planFiles({ project, bundle, prior, force, reinstall: op === 'install' });
+  const settings = settingsStep(project, prior, prior ? prior.hooks : [], bundle.hooks);
+  if (settings.action) actions.push(settings.action);
+
+  let blockInfo = null;
+  const md = inspect(project, CLAUDE_MD);
+  if (bundle.block) {
+    const out = upsertBlock(utf8Text(md, CLAUDE_MD), bundle.block.body, prior ? prior.block : null);
+    blockInfo = out.info;
+    const a = textAction('block', CLAUDE_MD, md, out.text, 'ai-sdlc router block');
+    if (a) actions.push(a);
+  } else if (prior && prior.block) {
+    const out = removeBlock(utf8Text(md, CLAUDE_MD), prior.block);
+    const a = textAction('block', CLAUDE_MD, md, out.text, 'block no longer shipped');
+    if (a) actions.push(a);
+  }
+
+  const manifest = buildManifest({
+    cliVersion,
+    payloadVersion: bundle.version,
+    payloadSchema: bundle.payloadSchema,
+    files: tracked,
+    block: blockInfo,
+    hooks: settings.hooks,
+    settings: settings.info,
+  });
+  actions.push(act('manifest', prior ? 'update' : 'create', MANIFEST_REL, `payload ${bundle.version}`, { write: serializeManifest(manifest) }));
+  return { actions, payloadVersion: bundle.version };
+}
+
+function planRemove({ project, prior }) {
+  const actions = planRemoveFiles({ project, prior });
+  const settings = settingsStep(project, prior, prior.hooks, []);
+  if (settings.action) actions.push(settings.action);
+  if (prior.block) {
+    const md = inspect(project, CLAUDE_MD);
+    const a = textAction('block', CLAUDE_MD, md, removeBlock(utf8Text(md, CLAUDE_MD), prior.block).text, 'ai-sdlc router block');
+    if (a) actions.push(a);
+  }
+  actions.push(act('manifest', 'remove', MANIFEST_REL, '', { remove: true }));
+  return { actions, payloadVersion: prior.payload_version };
+}
+
+// Counts per action name, for the summary line.
+function summarize(actions) {
+  const out = {};
+  for (const a of actions) out[a.action] = (out[a.action] || 0) + 1;
+  return out;
+}
+
+const publicView = (a) => ({ kind: a.kind, action: a.action, path: a.path, ...(a.detail ? { detail: a.detail } : {}) });
+
+module.exports = { planSync, planRemove, summarize, publicView };

package/lib/project-picker.js

@@ -0,0 +1,117 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { UsageError, CliError } = require('./errors');
+
+// Line-oriented prompter over any readable stream (a TTY or scripted input).
+function createPrompter({ input, output }) {
+  const rl = readline.createInterface({ input, crlfDelay: Infinity });
+  const lines = rl[Symbol.asyncIterator]();
+  return {
+    // Resolves to the trimmed answer, or null once input has ended.
+    async ask(question) {
+      output.write(question);
+      const next = await lines.next();
+      return next.done ? null : String(next.value).trim();
+    },
+    close() {
+      rl.close();
+    },
+  };
+}
+
+async function confirm(prompter, question) {
+  const answer = await prompter.ask(`${question} [y/N] `);
+  return answer !== null && /^y(es)?$/i.test(answer);
+}
+
+const hasGit = (dir) => fs.existsSync(path.join(dir, '.git'));
+
+function expandHome(p, home) {
+  if (p === '~') return home;
+  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(home, p.slice(2));
+  return p;
+}
+
+// Accepts a path only if it is an existing directory that is not the home
+// directory or a filesystem root. Returns { dir (real path), hasGit }.
+function validateTarget(input, { cwd, home }) {
+  if (typeof input !== 'string' || !input.trim()) throw new UsageError('project path is empty');
+  const abs = path.resolve(cwd, expandHome(input.trim(), home));
+  let real;
+  try {
+    real = fs.realpathSync(abs);
+  } catch (_) {
+    throw new UsageError(`project path does not exist: ${abs}`);
+  }
+  if (!fs.statSync(real).isDirectory()) throw new UsageError(`project path is not a directory: ${abs}`);
+  if (path.parse(real).root === real) throw new UsageError('refusing to use a filesystem root as the project');
+  let realHome = null;
+  try {
+    realHome = fs.realpathSync(home);
+  } catch (_) {
+    /* no usable home: nothing to compare with */
+  }
+  if (realHome && realHome === real) throw new UsageError('refusing to install into the home directory; pick a project repository');
+  return { dir: real, hasGit: hasGit(real) };
+}
+
+// Repositories (directories with .git) directly under each base, plus the base itself.
+// `limit` stops the scan once that many have been found.
+function findRepos(bases, limit = Infinity) {
+  const found = new Map();
+  const add = (dir) => {
+    if (found.size < limit && hasGit(dir) && !found.has(dir)) found.set(dir, true);
+  };
+  for (const base of bases) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch (_) {
+      continue;
+    }
+    add(base);
+    for (const e of entries.filter((x) => x.isDirectory() && !x.name.startsWith('.') && x.name !== 'node_modules')) {
+      if (found.size >= limit) break;
+      add(path.join(base, e.name));
+    }
+  }
+  return [...found.keys()];
+}
+
+async function chooseInteractively({ root, cwd, home, prompter, output }) {
+  const bases = root ? [path.resolve(cwd, root)] : [cwd, path.dirname(cwd)];
+  const repos = findRepos(bases);
+  output.write('Select the project to install into:\n');
+  repos.forEach((dir, i) => output.write(`  ${i + 1}) ${dir}\n`));
+  output.write(`  p) enter a path\n  q) cancel\n`);
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const answer = await prompter.ask('> ');
+    if (answer === null || /^q/i.test(answer)) throw new CliError('cancelled; nothing was changed');
+    let candidate = null;
+    if (/^\d+$/.test(answer) && repos[Number(answer) - 1]) candidate = repos[Number(answer) - 1];
+    else if (/^p$/i.test(answer)) {
+      const typed = await prompter.ask('Project path: ');
+      if (typed === null) throw new CliError('cancelled; nothing was changed');
+      candidate = typed;
+    } else output.write('Not a valid choice.\n');
+    if (candidate === null) continue;
+    try {
+      return validateTarget(candidate, { cwd, home });
+    } catch (err) {
+      if (!(err instanceof UsageError)) throw err;
+      output.write(`${err.message}\n`);
+    }
+  }
+  throw new UsageError('no valid project selected');
+}
+
+// --project wins; otherwise an interactive choice. Warns when the target is not a git repository.
+async function pickProject({ project, root, cwd, home, prompter, output }) {
+  const target = project ? validateTarget(project, { cwd, home }) : await chooseInteractively({ root, cwd, home, prompter, output });
+  if (!target.hasGit) output.write(`warning: ${target.dir} has no .git directory; it may not be a repository root\n`);
+  return target;
+}
+
+module.exports = { createPrompter, confirm, pickProject, validateTarget, findRepos, expandHome };

package/lib/release-source.js

@@ -0,0 +1,30 @@
+'use strict';
+const path = require('path');
+const { CliError, UsageError } = require('./errors');
+const { loadBundle } = require('./bundle');
+
+// Decides where the bundle comes from. Returns { bundlePath } or { bundleObject },
+// optionally with `cleanup()` for temporary files and `version` (the release's version).
+// `fetchLatestBundle(opts)` downloads a release; `opts.version` pins a tag, `opts.signal` cancels it.
+async function resolveBundle(opts, { fetchLatestBundle } = {}) {
+  if (opts.fromBundle) return { bundlePath: path.resolve(opts.cwd || process.cwd(), opts.fromBundle) };
+  if (typeof fetchLatestBundle === 'function') return fetchLatestBundle(opts);
+  throw new UsageError('no release source is configured; use --from-bundle <file>');
+}
+
+// Resolve + load + verify, then remove any downloaded temporary file.
+async function loadReleaseBundle(opts, deps, { cliVersion }) {
+  const source = await resolveBundle(opts, deps);
+  try {
+    const bundle = loadBundle(source, { cliVersion });
+    // A downloaded release must carry the payload version its tag announces.
+    if (source.version && bundle.version !== source.version) {
+      throw new CliError(`the release is tagged ${source.version} but its bundle contains payload ${bundle.version}; refusing to install (ask the repo owner to republish the release)`);
+    }
+    return bundle;
+  } finally {
+    if (typeof source.cleanup === 'function') source.cleanup();
+  }
+}
+
+module.exports = { resolveBundle, loadReleaseBundle };

package/lib/semver.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Only plain major.minor.patch ordering is needed; pre-release tags are ignored.
+function parse(version) {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(String(version).trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// Returns -1, 0 or 1; null when either side is not a version.
+function compare(a, b) {
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+// Strict semantic version text (no stray characters), used for versions that are shown to the user.
+const STRICT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const isStrict = (v) => typeof v === 'string' && v.length <= 64 && STRICT.test(v);
+
+// A release version as typed by a user: 1.2.0 or v1.2.0 (optionally with a pre-release / build suffix).
+const isReleaseTag = (v) => typeof v === 'string' && v.length <= 64 && /^v?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/.test(v);
+
+module.exports = { parse, compare, isStrict, isReleaseTag };

package/lib/termination-cleanup.js

@@ -0,0 +1,22 @@
+'use strict';
+// Runs `fn` (synchronous cleanup) when the process is told to stop with SIGINT or SIGTERM,
+// then exits with the conventional 130 / 143. Returns a function that removes the handlers.
+function onTermination(proc, fn) {
+  const handler = (code) => () => {
+    try {
+      fn();
+    } finally {
+      proc.exit(code);
+    }
+  };
+  const onInt = handler(130);
+  const onTerm = handler(143);
+  proc.on('SIGINT', onInt);
+  proc.on('SIGTERM', onTerm);
+  return () => {
+    proc.removeListener('SIGINT', onInt);
+    proc.removeListener('SIGTERM', onTerm);
+  };
+}
+
+module.exports = { onTermination };

package/lib/tui/cancelled.js

@@ -0,0 +1,16 @@
+'use strict';
+// Returned by a screen when the user pressed Esc (or declined) at that step.
+const BACK = Object.freeze({ back: true });
+
+// reason: 'interrupt' (Ctrl-C), 'eof' (input closed) or 'escape' (backed out of the first step).
+class Cancelled extends Error {
+  constructor(reason) {
+    super(reason === 'interrupt' ? 'interrupted' : 'cancelled');
+    this.name = 'Cancelled';
+    this.reason = reason;
+  }
+}
+
+const isCancelKey = (k) => k.ctrl && k.name === 'c';
+
+module.exports = { BACK, Cancelled, isCancelKey };

package/lib/tui/colors.js

@@ -0,0 +1,33 @@
+'use strict';
+// Terminal colour capability + helpers. Honors NO_COLOR and non-TTY output.
+
+// 0 = none, 1 = basic 16 colours, 3 = truecolor
+function colorLevel(env = process.env, stream = process.stdout) {
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return 0;
+  if (env.FORCE_COLOR === '0') return 0;
+  if (!stream.isTTY && !env.FORCE_COLOR) return 0;
+  if (env.TERM === 'dumb') return 0;
+  const ct = String(env.COLORTERM || '').toLowerCase();
+  if (ct === 'truecolor' || ct === '24bit' || env.TERM_PROGRAM === 'iTerm.app' || env.WT_SESSION) return 3;
+  return 1;
+}
+
+const lerp = (a, b, t) => Math.round(a + (b - a) * t);
+
+// Colour at position t (0..1) along a list of [r,g,b] stops.
+function gradientAt(stops, t) {
+  if (stops.length === 1) return stops[0];
+  const scaled = Math.min(Math.max(t, 0), 1) * (stops.length - 1);
+  const i = Math.min(Math.floor(scaled), stops.length - 2);
+  const f = scaled - i;
+  return stops[i].map((c, k) => lerp(c, stops[i + 1][k], f));
+}
+
+// Darken a colour toward a backdrop (used for drop shadows).
+const shade = (rgb, amount = 0.3, backdrop = [36, 36, 56]) => rgb.map((c, k) => lerp(backdrop[k], c, amount));
+
+const fg = (rgb) => `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+const bg = (rgb) => `\x1b[48;2;${rgb[0]};${rgb[1]};${rgb[2]}m`;
+const RESET = '\x1b[0m';
+
+module.exports = { colorLevel, gradientAt, shade, fg, bg, RESET };