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

package/lib/cli-output.js

@@ -0,0 +1,36 @@
+'use strict';
+const { publicView, summarize } = require('./plan');
+
+// Actions that change nothing are folded into a count in human output.
+const QUIET = new Set(['unchanged', 'keep-existing', 'forget']);
+
+function planLines(plan) {
+  const lines = [];
+  const quiet = plan.actions.filter((a) => QUIET.has(a.action)).length;
+  for (const a of plan.actions.filter((x) => !QUIET.has(x.action))) {
+    lines.push(`  ${a.action.padEnd(13)} ${a.path}${a.detail ? `  (${a.detail})` : ''}`);
+  }
+  if (quiet) lines.push(`  (${quiet} already in place or user-owned, untouched)`);
+  const counts = Object.entries(summarize(plan.actions)).map(([k, v]) => `${v} ${k}`);
+  lines.push(`  summary: ${counts.join(', ')}`);
+  return lines;
+}
+
+function planResult(command, project, plan, extra) {
+  return {
+    ok: true,
+    command,
+    project,
+    payloadVersion: plan.payloadVersion,
+    actions: plan.actions.map(publicView),
+    summary: summarize(plan.actions),
+    ...extra,
+  };
+}
+
+function doctorLines(report) {
+  const tag = { ok: '[ok]  ', warn: '[warn]', fail: '[FAIL]', info: '[info]' };
+  return report.checks.map((c) => `${tag[c.status]} ${c.name}: ${c.detail}`);
+}
+
+module.exports = { planLines, planResult, doctorLines, QUIET };

package/lib/command-plan.js

@@ -0,0 +1,28 @@
+'use strict';
+const crypto = require('crypto');
+const { CliError } = require('./errors');
+const { readManifest } = require('./manifest');
+const { planSync, planRemove } = require('./plan');
+
+// Reads the installed manifest, applies the install/update/uninstall
+// preconditions and plans the run. Read-only: nothing is written.
+function buildCommandPlan({ command, flags, project, bundle, cliVersion }) {
+  const prior = readManifest(project);
+  if (command === 'install' && prior && !flags.force) {
+    throw new CliError(`already installed (payload ${prior.payload_version}); use "ai-sdlc update", or --force to reinstall`);
+  }
+  if (command !== 'install' && !prior) throw new CliError(`ai-sdlc is not installed in ${project}`);
+  const plan = command === 'uninstall'
+    ? planRemove({ project, prior })
+    : planSync({ project, bundle, prior, force: flags.force, cliVersion, op: command });
+  return { prior, plan };
+}
+
+// Stable fingerprint of what a plan would do (actions, paths and the bytes to write),
+// to tell whether a plan made earlier still matches the project.
+function planSignature(plan) {
+  const rows = plan.actions.map((a) => [a.kind, a.action, a.path, a.detail, a.write ? crypto.createHash('sha256').update(a.write).digest('hex') : null, Boolean(a.remove)]);
+  return crypto.createHash('sha256').update(JSON.stringify(rows)).digest('hex');
+}
+
+module.exports = { buildCommandPlan, planSignature };

package/lib/commands.js

@@ -0,0 +1,173 @@
+'use strict';
+const os = require('os');
+const pkg = require('../package.json');
+const { CliError, UsageError } = require('./errors');
+const { parseArgs, validateFlags, HELP } = require('./cli-args');
+const { loadReleaseBundle } = require('./release-source');
+const { createGithubClient, createReleaseFetcher } = require('./github-release');
+const { JOURNAL_REL } = require('./path-rules');
+const { acquireLock } = require('./journal');
+const { inspect } = require('./fs-safe');
+const { buildCommandPlan } = require('./command-plan');
+const { applyPlan } = require('./apply-plan');
+const { createPrompter, confirm, pickProject } = require('./project-picker');
+const { runDoctor } = require('./doctor');
+const { planLines, planResult, doctorLines } = require('./cli-output');
+const { shouldUseTui, shouldRunWizard } = require('./tui/launch');
+
+const MUTATING = new Set(['install', 'update', 'uninstall']);
+
+function makeIo(env) {
+  const github = env.github || createGithubClient({
+    env: env.env || process.env, runCommand: env.runCommand, fetchImpl: env.fetch, releaseOptions: env.releaseOptions, proc: env.proc,
+  });
+  const stdin = env.stdin || process.stdin;
+  const stdout = env.stdout || process.stdout;
+  return {
+    stdin,
+    stdout,
+    stderr: env.stderr || process.stderr,
+    cwd: env.cwd || process.cwd(),
+    home: env.home || os.homedir(),
+    isTTY: env.isTTY !== undefined ? env.isTTY : Boolean(stdin.isTTY && stdout.isTTY),
+    probePython: env.probePython,
+    github,
+    fetchLatestBundle: env.fetchLatestBundle || createReleaseFetcher({ client: github }),
+    env: env.env || process.env,
+    proc: env.proc || process,
+    tui: env.tui,
+    execFile: env.execFile,
+    extraChecks: env.extraChecks,
+    escapeMs: env.escapeMs,
+    confirmGuardMs: env.confirmGuardMs,
+  };
+}
+
+// Without a terminal nothing may be asked, so the answers must be on the command line.
+function requireNonInteractiveInputs(command, flags, io) {
+  const interactive = io.isTTY && !flags.json;
+  if (interactive) return true;
+  if (!flags.project) throw new UsageError('--project <path> is required when not running in an interactive terminal');
+  if (MUTATING.has(command) && !flags.dryRun && !flags.yes) {
+    throw new UsageError('--yes is required to apply changes when not running in an interactive terminal (or use --dry-run)');
+  }
+  return false;
+}
+
+async function runProjectCommand(command, flags, io, say) {
+  const interactive = requireNonInteractiveInputs(command, flags, io);
+  const log = (line = '') => (flags.json ? undefined : say.stdout.write(`${line}\n`));
+  // On a terminal, update/doctor/uninstall print coloured result views instead of plain lines.
+  const view = command !== 'install' && shouldUseTui(flags, io) ? require('./tui/flows/terminal-views').createViews(io) : null;
+  const emit = (lines) => say.stdout.write(`${lines.join('\n')}\n`);
+  const prompter = interactive ? createPrompter({ input: io.stdin, output: io.stdout }) : null;
+  let lock = null;
+  try {
+    let bundle = null;
+    if (command === 'install' || command === 'update' || (command === 'doctor' && flags.fromBundle)) {
+      bundle = await loadReleaseBundle({ fromBundle: flags.fromBundle, version: flags.version, cwd: io.cwd }, { fetchLatestBundle: io.fetchLatestBundle }, { cliVersion: pkg.version });
+    }
+    const bundleWarnings = bundle ? [...bundle.warnings] : [];
+    const target = await pickProject({
+      project: flags.project, root: flags.root, cwd: io.cwd, home: io.home, prompter,
+      output: flags.json ? { write() {} } : say.stdout,
+    });
+    const project = target.dir;
+    const warnings = target.hasGit ? bundleWarnings : [...bundleWarnings, `${project} has no .git directory`];
+    if (!flags.json) for (const w of bundleWarnings) say.stderr.write(`warning: ${w}\n`);
+
+    if (command === 'doctor') {
+      const report = runDoctor({ project, nodeVersion: process.version, bundleVersion: bundle && bundle.version, probePython: io.probePython });
+      if (flags.json) say.stdout.write(`${JSON.stringify({ ...report, command, project, warnings }, null, 2)}\n`);
+      else if (view) emit(view.doctor({ project, report, warnings: warnings.filter((w) => !bundleWarnings.includes(w)) }));
+      else {
+        log(`ai-sdlc doctor: ${project}`);
+        doctorLines(report).forEach((l) => log(l));
+      }
+      return report.ok ? 0 : 1;
+    }
+
+    // Real runs hold the project lock (and the recovery journal) from here on.
+    if (!flags.dryRun) lock = acquireLock(project, command, { force: Boolean(flags.force) });
+    else if (inspect(project, JOURNAL_REL).exists) warnings.push(`${JOURNAL_REL} exists: an earlier run was interrupted or another run is active`);
+
+    const { plan } = buildCommandPlan({ command, flags, project, bundle, cliVersion: pkg.version });
+
+    if (view && !flags.json) emit(view.plan({ command, project, plan, dryRun: Boolean(flags.dryRun) }));
+    else {
+      log(`ai-sdlc ${command}${flags.dryRun ? ' (dry run, nothing will be written)' : ''}`);
+      log(`  project: ${project}`);
+      log(`  payload: ${plan.payloadVersion}`);
+      planLines(plan).forEach((l) => log(l));
+    }
+
+    const result = planResult(command, project, plan, { dryRun: Boolean(flags.dryRun), warnings });
+    if (flags.dryRun) return emitJson(flags, say, result, 0);
+
+    if (!flags.yes) {
+      if (!(await confirm(prompter, 'Apply these changes?'))) throw new CliError('not confirmed; nothing was changed');
+    }
+    applyPlan(project, plan, command, lock);
+    if (view && !flags.json) emit(view.done({ command, plan }));
+    else {
+      log('done.');
+      if (plan.actions.some((a) => a.action === 'write-new')) log('Review the *.new files next to the files you modified and merge by hand.');
+    }
+    return emitJson(flags, say, result, 0);
+  } finally {
+    if (lock) lock.release();
+    if (prompter) prompter.close();
+  }
+}
+
+function emitJson(flags, say, result, code) {
+  if (flags.json) say.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return code;
+}
+
+// Messages can embed repo-controlled paths: on a terminal show control characters as text (line breaks kept).
+const forTerminal = (text, stream) => (stream && stream.isTTY ? String(text).split('\n').map((l) => require('./tui/sanitize').sanitize(l)).join('\n') : text);
+const runWizard = (flags, io) => require('./tui/flows/init-flow').runInitFlow({ flags, io, cliVersion: pkg.version });
+
+// Bare `ai-sdlc` in a terminal: pick an action, then run it like the typed command.
+async function runMenu(flags, io, say) {
+  const { command, installedHere } = await require('./tui/flows/menu-flow').chooseAction({ io });
+  if (command === 'quit') return 0;
+  if (command === 'install' && shouldRunWizard(flags, io)) return runWizard(flags, io);
+  const target = installedHere && !flags.project && command !== 'install' ? { ...flags, project: io.cwd } : flags;
+  return runProjectCommand(command, target, io, say);
+}
+
+async function run(argv, env = {}) {
+  const io = makeIo(env);
+  const say = { stdout: io.stdout, stderr: io.stderr };
+  let flags = { json: argv.includes('--json') };
+  try {
+    const parsed = parseArgs(argv);
+    flags = parsed.flags;
+    validateFlags(parsed.command, flags);
+    switch (parsed.command) {
+      case 'version':
+        if (flags.check) return await require('./version-check').runVersionCheck(flags, io, say);
+        say.stdout.write(flags.json ? `${JSON.stringify({ version: pkg.version })}\n` : `ai-sdlc-cli ${pkg.version}\n`);
+        return 0;
+      case 'help':
+        say.stdout.write(HELP);
+        return 0;
+      case null:
+        if (shouldUseTui(flags, io)) return await runMenu(flags, io, say);
+        say.stderr.write(HELP);
+        return 2;
+      default:
+        if (flags.init && shouldRunWizard(flags, io)) return await runWizard(flags, io);
+        return await runProjectCommand(parsed.command, flags, io, say);
+    }
+  } catch (err) {
+    const code = err instanceof CliError ? err.exitCode : 1;
+    if (flags.json) say.stdout.write(`${JSON.stringify({ ok: false, error: err.message, exitCode: code })}\n`);
+    else say.stderr.write(`ai-sdlc: ${forTerminal(err instanceof CliError || err.code ? err.message : err.stack, say.stderr)}\n`);
+    return code;
+  }
+}
+
+module.exports = { run };

package/lib/config.js

@@ -0,0 +1,42 @@
+'use strict';
+const { UsageError } = require('./errors');
+
+// Where the release bundles live. Overridable per process for tests and mirrors.
+const DEFAULT_PAYLOAD_REPO = 'bakit-org/ai-sdlc-kit';
+const DEFAULT_API_BASE = 'https://api.github.com';
+
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+function payloadRepo(env = process.env) {
+  const repo = (env.AI_SDLC_PAYLOAD_REPO || '').trim() || DEFAULT_PAYLOAD_REPO;
+  if (!REPO_RE.test(repo) || repo.includes('..')) throw new UsageError('AI_SDLC_PAYLOAD_REPO must look like <owner>/<repo>');
+  return repo;
+}
+
+// The API base must be https; plain http is allowed only for a loopback host (local test servers).
+function apiBase(env = process.env) {
+  const raw = (env.AI_SDLC_GITHUB_API || '').trim() || DEFAULT_API_BASE;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new UsageError('AI_SDLC_GITHUB_API is not a valid URL');
+  }
+  const secure = url.protocol === 'https:' || (url.protocol === 'http:' && LOOPBACK.has(url.hostname));
+  if (!secure || url.username || url.password) throw new UsageError('AI_SDLC_GITHUB_API must be an https URL (http only for localhost)');
+  return `${url.origin}${url.pathname.replace(/\/+$/, '')}`;
+}
+
+// Whether a URL may be fetched given the configured API base (https, or loopback http when the base itself is loopback).
+function isAllowedUrl(url, base) {
+  if (url.username || url.password) return false;
+  if (url.protocol === 'https:') return true;
+  return url.protocol === 'http:' && LOOPBACK.has(url.hostname) && new URL(base).protocol === 'http:';
+}
+
+// Tokens found on the machine (gh, git credential helper, GH_TOKEN, GITHUB_TOKEN) belong to github.com
+// and are only used against the public API; any other base needs an explicit AI_SDLC_GITHUB_TOKEN.
+const isDefaultApiBase = (base) => base === DEFAULT_API_BASE;
+
+module.exports = { DEFAULT_PAYLOAD_REPO, DEFAULT_API_BASE, payloadRepo, apiBase, isAllowedUrl, isDefaultApiBase };

package/lib/doctor.js

@@ -0,0 +1,123 @@
+'use strict';
+const { spawnSync } = require('child_process');
+const { inspect, utf8Text } = require('./fs-safe');
+const { readManifest } = require('./manifest');
+const { JOURNAL_REL, MANIFEST_REL } = require('./path-rules');
+const { SETTINGS_REL, parseSettings, hasHook } = require('./merge-settings');
+const { hasBlock } = require('./merge-claude-md');
+const semver = require('./semver');
+
+const MIN_NODE_MAJOR = 18;
+// $CLAUDE_PROJECT_DIR/x, "$CLAUDE_PROJECT_DIR"/x and ${CLAUDE_PROJECT_DIR}/x, quoted or not.
+const HOOK_SCRIPT = /(?:\$\{CLAUDE_PROJECT_DIR\}|\$CLAUDE_PROJECT_DIR)"?\/([^\s"'`;|&)]+)/g;
+
+function defaultProbePython() {
+  for (const bin of ['python3', 'python']) {
+    const r = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+    if (!r.error && r.status === 0) return (r.stdout || r.stderr).trim();
+  }
+  return null;
+}
+
+// Read-only health report. Never writes; checks are { name, status, detail }
+// with status ok | warn | fail | info. A check that throws (symlink, permissions,
+// bad encoding) becomes a fail entry instead of aborting the report.
+function runDoctor({ project, nodeVersion, bundleVersion, probePython = defaultProbePython }) {
+  const checks = [];
+  const add = (name, status, detail) => checks.push({ name, status, detail });
+  const guard = (name, fn) => {
+    try {
+      fn();
+    } catch (err) {
+      add(name, 'fail', err.message);
+    }
+  };
+
+  const major = Number(String(nodeVersion).replace(/^v/, '').split('.')[0]);
+  add('node', major >= MIN_NODE_MAJOR ? 'ok' : 'fail', `${nodeVersion} (needs >= ${MIN_NODE_MAJOR})`);
+
+  guard('journal', () => {
+    if (inspect(project, JOURNAL_REL).exists) {
+      add('journal', 'fail', `${JOURNAL_REL} exists: a run is active or was interrupted; if no run is active, retry the command with --force to roll it back`);
+    }
+  });
+
+  let manifest = null;
+  guard('manifest', () => {
+    manifest = readManifest(project);
+    if (!manifest) add('manifest', 'fail', `${MANIFEST_REL} not found: ai-sdlc is not installed in ${project}`);
+    else add('manifest', 'ok', `payload ${manifest.payload_version}, ${manifest.files.length} tracked file(s)`);
+  });
+  if (!manifest) return finish(checks);
+
+  const managed = manifest.files.filter((f) => f.class === 'managed');
+  let intact = 0;
+  for (const f of managed) {
+    guard('managed file', () => {
+      const disk = inspect(project, f.path);
+      if (!disk.exists) add('managed file', 'fail', `missing: ${f.path}`);
+      else if (disk.hash !== f.sha256) add('managed file', 'warn', `modified locally: ${f.path}`);
+      else intact += 1;
+    });
+  }
+  add('managed files', intact === managed.length ? 'ok' : 'warn', `${intact}/${managed.length} intact`);
+
+  guard('hooks', () => checkHooks(project, manifest, add));
+
+  if (manifest.block) {
+    guard('CLAUDE.md block', () => {
+      const text = utf8Text(inspect(project, 'CLAUDE.md'), 'CLAUDE.md');
+      const present = text !== null && hasBlock(text);
+      add('CLAUDE.md block', present ? 'ok' : 'fail', present ? 'router block present' : 'router block missing from CLAUDE.md');
+    });
+  }
+
+  const scaffolds = manifest.files.filter((f) => f.class === 'user-once');
+  const lost = [];
+  for (const f of scaffolds) {
+    guard('scaffold', () => {
+      if (!inspect(project, f.path).exists) lost.push(f.path);
+    });
+  }
+  add('scaffolds', lost.length ? 'warn' : 'ok', lost.length ? `missing: ${lost.join(', ')}` : `${scaffolds.length} present`);
+
+  if (bundleVersion) {
+    const cmp = semver.compare(manifest.payload_version, bundleVersion);
+    add('version', cmp === 0 ? 'ok' : 'warn', cmp === 0 ? `up to date (${bundleVersion})` : `installed ${manifest.payload_version}, bundle ${bundleVersion}: run update`);
+  } else {
+    add('version', 'info', `installed ${manifest.payload_version}; pass --from-bundle to compare with a bundle`);
+  }
+
+  if (managed.some((f) => f.path.endsWith('.py'))) {
+    guard('python', () => {
+      const found = probePython();
+      add('python', found ? 'info' : 'warn', found ? `${found} (optional helper scripts)` : 'optional: some helper scripts need Python 3, which was not found');
+    });
+  }
+  return finish(checks);
+}
+
+function checkHooks(project, manifest, add) {
+  if (!manifest.hooks.length) return;
+  const file = inspect(project, SETTINGS_REL);
+  const settings = parseSettings(utf8Text(file, SETTINGS_REL));
+  for (const h of manifest.hooks) {
+    const registered = hasHook(settings, h);
+    add('hook', registered ? 'ok' : 'fail', `${h.event}: ${registered ? 'registered' : 'not registered'} (${h.command})`);
+    for (const m of h.command.matchAll(HOOK_SCRIPT)) {
+      let present = false;
+      try {
+        present = inspect(project, m[1]).exists;
+      } catch (_) {
+        /* unsafe or unreadable path counts as missing */
+      }
+      if (!present) add('hook script', 'fail', `missing or unusable: ${m[1]}`);
+    }
+  }
+}
+
+function finish(checks) {
+  return { checks, ok: !checks.some((c) => c.status === 'fail') };
+}
+
+module.exports = { runDoctor };

package/lib/errors.js

@@ -0,0 +1,19 @@
+'use strict';
+
+// exitCode: 1 = the operation failed, 2 = the command line was wrong.
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+  }
+}
+
+class UsageError extends CliError {
+  constructor(message) {
+    super(message, 2);
+    this.name = 'UsageError';
+  }
+}
+
+module.exports = { CliError, UsageError };

package/lib/fs-safe.js

@@ -0,0 +1,133 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { CliError } = require('./errors');
+
+const sha256 = (data) => crypto.createHash('sha256').update(data).digest('hex');
+
+// Install paths arrive from a downloaded bundle or a manifest, so they are
+// treated as hostile: relative, forward-slash, no dot segments.
+function assertRelPath(rel, what = 'path') {
+  const bad = (why) => {
+    throw new CliError(`unsafe ${what} "${String(rel)}": ${why}`);
+  };
+  if (typeof rel !== 'string' || rel === '') bad('empty');
+  if (rel.includes('\0')) bad('contains a NUL byte');
+  if (rel.includes('\\')) bad('contains a backslash');
+  if (rel.startsWith('/') || /^[A-Za-z]:/.test(rel)) bad('is absolute');
+  for (const seg of rel.split('/')) {
+    if (seg === '' || seg === '.' || seg === '..') bad('has an empty, "." or ".." segment');
+  }
+  return rel;
+}
+
+function isInside(root, target) {
+  const r = path.relative(root, target);
+  return r !== '' && r !== '..' && !r.startsWith(`..${path.sep}`) && !path.isAbsolute(r);
+}
+
+// Resolves rel under root and proves, through symlinks, that the result stays
+// inside root. `root` must already be a real path.
+function resolveInside(root, rel) {
+  assertRelPath(rel);
+  const abs = path.join(root, ...rel.split('/'));
+  if (!isInside(root, abs)) throw new CliError(`"${rel}" resolves outside the project`);
+  let probe = abs;
+  for (;;) {
+    try {
+      fs.lstatSync(probe);
+      break;
+    } catch (err) {
+      if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err;
+      const up = path.dirname(probe);
+      if (up === probe) break;
+      probe = up;
+    }
+  }
+  let real;
+  try {
+    real = fs.realpathSync(probe);
+  } catch (err) {
+    throw new CliError(`cannot resolve "${rel}": ${err.code || err.message}`);
+  }
+  if (real !== root && !isInside(root, real)) {
+    throw new CliError(`"${rel}" resolves outside the project through a symlink`);
+  }
+  return abs;
+}
+
+// Reads one project file without following symlinks.
+function inspect(root, rel) {
+  const abs = resolveInside(root, rel);
+  let st;
+  try {
+    st = fs.lstatSync(abs);
+  } catch (err) {
+    if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return { abs, exists: false, bytes: null, hash: null };
+    throw err;
+  }
+  if (st.isSymbolicLink()) {
+    throw new CliError(
+      `${rel} is a symlink and ai-sdlc will not write through it. Replace it with a regular file holding the same content, or run against the directory that contains the real file.`,
+    );
+  }
+  if (!st.isFile()) throw new CliError(`expected a regular file at ${rel}`);
+  const bytes = fs.readFileSync(abs);
+  return { abs, exists: true, bytes, hash: sha256(bytes) };
+}
+
+// Text of an inspected file, or null when absent. Files that do not survive a
+// UTF-8 round trip are refused so that rewriting them can never corrupt bytes.
+function utf8Text(file, rel) {
+  if (!file.exists) return null;
+  const text = file.bytes.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(file.bytes)) {
+    throw new CliError(`${rel} is not valid UTF-8; ai-sdlc will not rewrite it. Nothing was changed.`);
+  }
+  return text;
+}
+
+// Replaces abs through a temporary file; an existing file keeps its permission bits.
+function writeAtomic(abs, data) {
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  const tmp = `${abs}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try {
+    let mode = null;
+    try {
+      mode = fs.statSync(abs).mode & 0o7777;
+    } catch (_) {
+      /* new file: default mode */
+    }
+    fs.writeFileSync(tmp, data);
+    if (mode !== null) fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, abs);
+  } catch (err) {
+    fs.rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+// Removes now-empty directories above `start`, never the project root itself
+// and never a symlink (a linked .claude is the user's to keep).
+function pruneEmptyDirs(root, start) {
+  let dir = start;
+  while (isInside(root, dir)) {
+    let entries;
+    try {
+      if (!fs.lstatSync(dir).isDirectory()) return;
+      entries = fs.readdirSync(dir);
+    } catch (_) {
+      return;
+    }
+    if (entries.length) return;
+    fs.rmdirSync(dir);
+    dir = path.dirname(dir);
+  }
+}
+
+function realProject(dir) {
+  return fs.realpathSync(dir);
+}
+
+module.exports = { sha256, assertRelPath, isInside, resolveInside, inspect, utf8Text, writeAtomic, pruneEmptyDirs, realProject };

package/lib/github-auth.js

@@ -0,0 +1,115 @@
+'use strict';
+// Finds a GitHub token from the user's existing credentials. The token value is
+// only ever held in memory and sent as a request header: it is never printed,
+// logged or stored, and `redact` scrubs it from any text that might carry it.
+const { spawn } = require('child_process');
+
+const ENV_SOURCES = ['AI_SDLC_GITHUB_TOKEN', 'GH_TOKEN', 'GITHUB_TOKEN'];
+const COMMAND_TIMEOUT_MS = 8000;
+const MAX_OUTPUT = 16 * 1024;
+const MAX_TOKEN = 1024;
+
+// A header-safe token: printable ASCII without spaces (rules out header injection).
+const plausible = (t) => typeof t === 'string' && t.length > 0 && t.length <= MAX_TOKEN && /^[\x21-\x7e]+$/.test(t);
+
+// Runs a command without a shell. Never rejects: failure, timeout, abort and a
+// missing program all resolve with code null. { input, env, timeoutMs, signal } are optional.
+function runCommand(cmd, args, { input, env, timeoutMs = COMMAND_TIMEOUT_MS, signal } = {}) {
+  return new Promise((resolve) => {
+    let out = '';
+    let settled = false;
+    let child;
+    const stop = () => {
+      if (child) child.kill();
+      done(null);
+    };
+    const done = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', stop);
+      resolve({ code, stdout: out });
+    };
+    const timer = setTimeout(stop, timeoutMs);
+    if (signal) {
+      if (signal.aborted) return done(null);
+      signal.addEventListener('abort', stop, { once: true });
+    }
+    try {
+      child = spawn(cmd, args, { env, stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
+    } catch {
+      return done(null);
+    }
+    child.on('error', () => done(null));
+    child.on('close', (code) => done(code));
+    child.stdout.on('data', (c) => {
+      if (out.length < MAX_OUTPUT) out += c;
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input || '');
+    return undefined;
+  });
+}
+
+const fromEnv = (env) => {
+  for (const name of ENV_SOURCES) {
+    const value = (env[name] || '').trim();
+    if (plausible(value)) return { token: value, source: name };
+  }
+  return null;
+};
+
+async function fromGh(env, run, signal) {
+  const r = await run('gh', ['auth', 'token', '--hostname', 'github.com'], { env: { ...env, GH_PROMPT_DISABLED: '1', NO_COLOR: '1' }, signal });
+  const token = r && r.code === 0 ? String(r.stdout || '').trim() : '';
+  return plausible(token) ? { token, source: 'gh auth login' } : null;
+}
+
+// Neither the terminal nor any askpass program (GIT_ASKPASS, core.askPass, SSH_ASKPASS) may be
+// started: the lookup has to stay silent.
+const GIT_ARGS = ['-c', 'core.askPass=', '-c', 'credential.interactive=false', 'credential', 'fill'];
+
+async function fromGitCredential(env, run, signal) {
+  const r = await run('git', GIT_ARGS, {
+    input: 'protocol=https\nhost=github.com\n\n',
+    env: { ...env, GIT_ASKPASS: '', SSH_ASKPASS: '', GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' },
+    signal,
+  });
+  if (!r || r.code !== 0) return null;
+  const line = String(r.stdout || '').split(/\r?\n/).find((l) => l.startsWith('password='));
+  const token = line ? line.slice('password='.length).trim() : '';
+  return plausible(token) ? { token, source: 'git credential helper' } : null;
+}
+
+// Order: env vars, `gh auth token`, `git credential fill`. Resolves { token, source } or null.
+// With `explicitOnly` (a non-default API base) only AI_SDLC_GITHUB_TOKEN counts, so credentials
+// that belong to github.com are never offered to another host. An aborted signal rejects with its reason.
+async function resolveToken({ env = process.env, runCommand: run = runCommand, signal, explicitOnly = false } = {}) {
+  const stopIfAborted = () => {
+    if (signal && signal.aborted) throw signal.reason;
+  };
+  if (explicitOnly) {
+    const value = (env.AI_SDLC_GITHUB_TOKEN || '').trim();
+    return plausible(value) ? { token: value, source: 'AI_SDLC_GITHUB_TOKEN' } : null;
+  }
+  const found = fromEnv(env) || (await fromGh(env, run, signal)) || (stopIfAborted(), await fromGitCredential(env, run, signal));
+  stopIfAborted();
+  return found;
+}
+
+const NO_TOKEN_MESSAGE = 'no GitHub credentials found: set AI_SDLC_GITHUB_TOKEN, GH_TOKEN or GITHUB_TOKEN, run `gh auth login`, '
+  + 'or configure a git credential helper for github.com (or install from a local file with --from-bundle <file>)';
+
+const customBaseMessage = (base) => `no credentials for the API at ${base}: set AI_SDLC_GITHUB_TOKEN `
+  + '(tokens from GH_TOKEN, GITHUB_TOKEN, `gh` or git credential helpers are only used for https://api.github.com), or use --from-bundle <file>';
+
+// Removes every occurrence of the token from text (and its URL-encoded form).
+function redact(text, token) {
+  let s = String(text);
+  if (token) {
+    for (const form of [token, encodeURIComponent(token)]) s = s.split(form).join('[redacted]');
+  }
+  return s;
+}
+
+module.exports = { resolveToken, redact, runCommand, NO_TOKEN_MESSAGE, customBaseMessage, ENV_SOURCES };