unknown-knowledge 2.1.0

package/cli/commands/init.js

@@ -0,0 +1,386 @@
+/**
+ * `npx unknown-knowledge init` (KK-19, PRD §6 Phase 1) — the interactive,
+ * npx-facing wrapper over the deterministic seams KK-17/KK-18 landed:
+ * cli/lib/copy-payload.js (manifest-driven copy engine) and
+ * cli/lib/generate-wrappers.js (platform pointer files). This file owns the
+ * cold-run UX ONLY — prompts (node:readline, zero-dependency D-002), repo
+ * stack auto-detection, the git check-ignore sweep, and the exit messaging.
+ * The copy/collision semantics live (and are tested) in the seams; this CLI
+ * never reimplements them.
+ *
+ * EVERY prompt is flag-drivable for non-interactive use (--root,
+ * --platforms, --stacks, --yes accepting the detected defaults) — CI and
+ * the acceptance harness drive it headlessly.
+ *
+ * NO CI MUTATION, EVER (D-006): init never writes workflow files — nothing
+ * under .github/workflows/ (or any other CI config) is created or edited by
+ * this command. The only .github/ path init may touch is the Copilot
+ * wrapper (.github/copilot-instructions.md), and only when the user selects
+ * the copilot platform.
+ *
+ * npx-ability: package.json maps bin "unknown-knowledge" → this file. The
+ * is published through GitHub Actions with provenance (docs/publishing.md).
+ * For local development, run `node cli/init.js init`; release verification
+ * runs `npx unknown-knowledge@<version> init` from a fresh npm cache.
+ *
+ * Exit codes (same contract as cli/init-copy.js):
+ *   0 — seeded clean. Wrapper skips and gitignore WARNs are reported
+ *       results, not failures — the seed happened.
+ *   2 — refusal (existing/partial seed, dotted root), usage error, a target
+ *       that is not an existing directory, or any engine failure — including
+ *       an unexpected throw, which the entry point maps here rather than
+ *       letting it exit 1. A seed that did not happen is never a silent pass,
+ *       and never wears the FINDINGS code.
+ */
+import { createInterface } from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import { copyPayload, loadManifest, DEFAULT_ROOT, SeedRefusal } from '../lib/copy-payload.js';
+import { assertKnownPlatforms, generateWrappers } from '../lib/generate-wrappers.js';
+import { EXIT_CODES } from '../../payload/engine/lib/exit-codes.js';
+import { parseArgs as parseFlags, rethrowIfBug, UsageError } from '../../payload/engine/lib/cli.js';
+
+export const USAGE = 'usage: npx unknown-knowledge init [--root <name>] [--platforms <ids|none>] '
+  + '[--stacks <ids|none>] [--target <dir>] [--yes]';
+// The kit root, two levels up: cli/commands/<this>.js (UCS-950).
+const kitRoot = fileURLToPath(new URL('../..', import.meta.url));
+
+// The D-009 later-stacks warning — printed at the end of every init AND
+// carried by the seeded README (payload/docs/README.md, KK-24).
+const LATER_STACKS_WARNING = 'Extractor fixtures for your selected stacks are included. If you adopt '
+  + 'another stack later, you author your own pack from the included template '
+  + '(templates/new-kind/) — there is no update channel. (D-001, D-009)';
+
+// ----------------------------------------------------------------- flags
+
+/** Split a multi-select answer: comma/whitespace separated; "none" → []. */
+function parseSelection(value) {
+  const items = value.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+  return items.length === 1 && items[0].toLowerCase() === 'none' ? [] : items;
+}
+
+function parseArgs(argv) {
+  const { options, positionals } = parseFlags(argv, {
+    boolean: ['yes', 'help'],
+    value: ['target', 'root', 'stacks', 'platforms'],
+    positionals: true,
+  });
+  // `npx unknown-knowledge init` — the subcommand is optional and the only one.
+  if (positionals.length > 1 || (positionals.length === 1 && positionals[0] !== 'init')) {
+    throw new UsageError(`unknown command: ${positionals.join(' ')}`);
+  }
+  return {
+    target: options.target ?? '.',
+    root: options.root ?? null,
+    stacks: options.stacks === undefined ? null : parseSelection(options.stacks),
+    platforms: options.platforms === undefined ? null : parseSelection(options.platforms),
+    yes: !!options.yes,
+    help: !!options.help,
+  };
+}
+
+// ------------------------------------------------- stack auto-detection
+
+/** Repo file list for detection: git ls-files when a repo, fs walk otherwise. */
+function listRepoFiles(targetDir) {
+  const git = spawnSync('git', ['-C', targetDir, 'ls-files', '--cached', '--others', '--exclude-standard', '-z'],
+    { encoding: 'utf8' });
+  if (git.status === 0) return git.stdout.split('\0').filter(Boolean);
+  const out = [];
+  const walk = (dir, rel) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === '.git' || entry.name === 'node_modules') continue;
+      const path = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(dir, entry.name), path);
+      else out.push(path);
+    }
+  };
+  walk(resolve(targetDir), '');
+  return out;
+}
+
+/**
+ * Auto-detect the target repo's stacks (PRD §6: the multi-select's
+ * pre-selection). Heuristics, per file list:
+ *   ts    — tsconfig.json / package.json anywhere, or any *.ts / *.tsx
+ *   swift — Package.swift anywhere, any *.xcodeproj, or any *.swift
+ * Nothing detected = config-only: an empty default, not an error.
+ */
+export function detectStacks(targetDir) {
+  const files = listRepoFiles(targetDir);
+  const detected = [];
+  if (files.some((f) => /(^|\/)(Package\.swift)$/.test(f) || /\.xcodeproj(\/|$)/.test(f) || /\.swift$/.test(f))) {
+    detected.push('swift');
+  }
+  if (files.some((f) => /(^|\/)(tsconfig\.json|package\.json)$/.test(f) || /\.tsx?$/.test(f))) {
+    detected.push('ts');
+  }
+  return detected.sort();
+}
+
+// ------------------------------------------------------------- prompts
+
+/**
+ * readline ask: empty answer (or closed/exhausted stdin) accepts the
+ * default. Lines are BUFFERED into a queue — with piped stdin (the headless
+ * test path) all answers can arrive before the next question registers, and
+ * bare rl.question() would drop them.
+ */
+function makeAsker(rl, output) {
+  const queue = [];
+  const waiters = [];
+  let closed = false;
+  rl.on('line', (line) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter(line);
+    else queue.push(line);
+  });
+  rl.on('close', () => {
+    closed = true;
+    while (waiters.length) waiters.shift()(null);
+  });
+  return (prompt) => {
+    output.write(prompt);
+    if (queue.length) return Promise.resolve(queue.shift().trim());
+    if (closed) return Promise.resolve('');
+    return new Promise((resolveAnswer) => {
+      waiters.push((line) => resolveAnswer(line === null ? '' : line.trim()));
+    });
+  };
+}
+
+/** Multi-select prompt loop: empty accepts the default, invalid ids re-ask. */
+async function askSelection(ask, out, { label, known, defaults, validate }) {
+  for (;;) {
+    const answer = await ask(`${label} [${defaults.join(', ') || 'none'}]: `);
+    const selection = answer === '' ? [...defaults] : parseSelection(answer);
+    try {
+      validate(selection);
+      return selection;
+    } catch (error) {
+      out(`  ${error.message.split('\n')[0]}\n  available: ${known.join(', ') || '(none)'} — or "none"\n`);
+    }
+  }
+}
+
+// ------------------------------------------------ git check-ignore sweep
+
+/**
+ * PRD §6: run `git check-ignore` across all seeded paths (batched via
+ * --stdin) — a gitignored findings log kills the improvement loop silently.
+ * Not a git repo → { skipped: true }; the caller says so and moves on.
+ */
+export function sweepGitIgnore({ targetDir, paths }) {
+  const inside = spawnSync('git', ['-C', targetDir, 'rev-parse', '--is-inside-work-tree'], { encoding: 'utf8' });
+  if (inside.status !== 0 || inside.stdout.trim() !== 'true') return { skipped: true, ignored: [] };
+  const r = spawnSync('git', ['-C', targetDir, 'check-ignore', '--stdin'],
+    { input: `${paths.join('\n')}\n`, encoding: 'utf8' });
+  // check-ignore exit contract: 0 = some path ignored, 1 = none, other = error.
+  if (r.status === 1) return { skipped: false, ignored: [] };
+  if (r.status !== 0) return { skipped: false, ignored: [], error: (r.stderr || 'git check-ignore failed').trim() };
+  return { skipped: false, ignored: r.stdout.split('\n').filter(Boolean) };
+}
+
+/**
+ * The seeded engine's one runtime dependency (D-002: js-yaml, resolved from
+ * the client's repo like any other package). Resolution is checked from the
+ * seeded engine file itself, so this answers the question the engine will
+ * ask at import time — not an approximation of it.
+ *
+ * Unresolvable is a WARN, never a refusal: the seed is correct and the fix
+ * is one `npm install` away. It stays a LOUD warn because every engine command
+ * refuses to start until the dependency is there — the whole kit is inert.
+ *
+ * It used to be louder still: an unresolved import exited 1, which the §5
+ * contract reads as "findings present" rather than "engine failure", and an
+ * agent riding those codes would quarantine-and-continue past an engine that
+ * never ran. The entry shims closed that (UCS-956): a module-load failure now
+ * exits 2, so the codes mean what they say even before the install.
+ */
+export function checkRuntimeDependency(seededRoot, dependency = 'js-yaml') {
+  const anchor = join(seededRoot, 'engine', 'lib', 'load-stores.js');
+  try {
+    createRequire(anchor).resolve(dependency);
+    return { resolved: true, dependency };
+  } catch {
+    return { resolved: false, dependency };
+  }
+}
+
+/** Negation rules to offer: one `!<root>/<dir>/**` per affected seeded dir. */
+export function negationRules(ignored, rootName) {
+  const rules = new Set();
+  for (const path of ignored) {
+    if (path.startsWith(`${rootName}/`)) {
+      const segments = path.split('/');
+      rules.add(segments.length > 2 ? `!${rootName}/${segments[1]}/**` : `!${path}`);
+    } else {
+      rules.add(`!${path}`);
+    }
+  }
+  return [...rules].sort();
+}
+
+// ----------------------------------------------------------------- main
+
+export async function main(argv, { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const opts = parseArgs(argv); // a UsageError reaches the harness
+  if (opts.help) {
+    stdout.write(`${USAGE}\n`);
+    return EXIT_CODES.CLEAN;
+  }
+  const out = (text) => stdout.write(text);
+  const warn = (text) => stderr.write(text);
+
+  let manifest;
+  try {
+    manifest = loadManifest(kitRoot);
+  } catch (error) {
+    // The manifest is malformed or missing — an anticipated refusal, and the
+    // message says which. A bug inside loadManifest is not, and goes to the
+    // harness with its stack. Both exit 2; nothing was seeded either way.
+    stderr.write(`unknown-knowledge init: ${error.message}\n`);
+    rethrowIfBug(error);
+    return EXIT_CODES.FAILURE;
+  }
+  const knownStacks = Object.keys(manifest.sections.stacks).sort();
+  const knownPlatforms = Object.keys(manifest.platforms).sort();
+
+  // The target must exist before anything reads it: auto-detection walks it
+  // (below) long before the copy engine's own guard would fire, and a typo'd
+  // --target should say so, not surface an ENOENT stack trace.
+  const target = resolve(opts.target);
+  if (!statSync(target, { throwIfNoEntry: false })?.isDirectory()) {
+    stderr.write(`unknown-knowledge init: target ${JSON.stringify(target)} is not an existing directory — `
+      + 'create it (or fix --target) and re-run; a seed that did not happen is never a silent pass\n');
+    return EXIT_CODES.FAILURE;
+  }
+  const detected = detectStacks(opts.target).filter((s) => knownStacks.includes(s));
+
+  // Resolve the three answers: flags win; --yes accepts every default
+  // (root: unknown-knowledge, platforms: none, stacks: the detection);
+  // otherwise prompt interactively (node:readline, D-002).
+  let rootName = opts.root ?? DEFAULT_ROOT;
+  let platforms = opts.platforms ?? [];
+  let stacks = opts.stacks ?? detected;
+  out(`stack auto-detection: ${detected.join(', ') || 'none (config-only)'}\n`);
+
+  const needPrompts = !opts.yes && (opts.root === null || opts.platforms === null || opts.stacks === null);
+  if (needPrompts) {
+    const rl = createInterface({ input: stdin, terminal: false });
+    const ask = makeAsker(rl, stdout);
+    try {
+      if (opts.root === null) {
+        for (;;) {
+          const answer = await ask(`root dir name (always visible, never dotted) [${DEFAULT_ROOT}]: `);
+          rootName = answer === '' ? DEFAULT_ROOT : answer;
+          // The engine validates (copy-payload.js §6 rules); we present.
+          if (!rootName.startsWith('.') && !/[/\\]/.test(rootName)) break;
+          out('  root dir names are single, visible path segments — never dotted (PRD §6)\n');
+        }
+      }
+      if (opts.platforms === null) {
+        out('agent platforms (thin wrappers pointing at the protocol):\n');
+        for (const id of knownPlatforms) out(`  ${id.padEnd(12)} ${manifest.platforms[id].name}\n`);
+        platforms = await askSelection(ask, out, {
+          label: 'platforms (comma/space separated ids)',
+          known: knownPlatforms,
+          defaults: [],
+          validate: (sel) => assertKnownPlatforms(manifest, sel),
+        });
+      }
+      if (opts.stacks === null) {
+        out(`stacks (drives which extractor-fixture packs ship, D-009): ${knownStacks.join(', ')}\n`);
+        stacks = await askSelection(ask, out, {
+          label: 'stacks (pre-selected by auto-detection)',
+          known: knownStacks,
+          defaults: detected,
+          validate: (sel) => {
+            for (const s of sel) {
+              if (!knownStacks.includes(s)) throw new Error(`unknown stack ${JSON.stringify(s)}`);
+            }
+          },
+        });
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  // ---- scaffold: one call into each landed seam (KK-17 copy engine,
+  // KK-18 wrapper generator) — their refusal/collision semantics apply.
+  let result;
+  let wrappers;
+  try {
+    assertKnownPlatforms(manifest, platforms); // refuse BEFORE seeding
+    result = copyPayload({ kitRoot, targetDir: opts.target, rootName, stacks });
+    try {
+      wrappers = generateWrappers({ kitRoot, targetDir: opts.target, rootName, platforms });
+    } catch (error) {
+      // The seed already landed; shared files may carry sentinel appends, so
+      // a silent rollback could destroy user bytes — name the partial state
+      // instead (a retry refuses on the existing root by design, §6).
+      error.message = `${error.message}\n  the store seed was already created at ${result.root} — remove it `
+        + '(and any wrapper sentinel blocks) before retrying; init refuses on an existing root';
+      throw error;
+    }
+  } catch (error) {
+    // Name the partial state FIRST, whatever went wrong: the seed may already
+    // have landed, and a silent rollback could destroy user bytes. The message
+    // carries that note (annotated above), and a stack trace would bury it.
+    const kind = error instanceof SeedRefusal ? 'refused' : 'error';
+    stderr.write(`unknown-knowledge init: ${kind}: ${error.message}\n`);
+    // Then: a SeedRefusal and the copy engine's plain Errors are anticipated,
+    // and this catch speaks for them. A TypeError is a bug — the harness gets
+    // it, and prints the stack nobody could debug without. Both exit 2.
+    rethrowIfBug(error);
+    return EXIT_CODES.FAILURE;
+  }
+
+  out(`seeded ${result.rootName}/ (kit ${result.version}, stacks: ${result.stacks.join(', ') || 'none'}) `
+    + `— ${result.files.length} files at ${result.root}\n`);
+  for (const w of wrappers) {
+    out(w.action === 'skipped'
+      ? `wrapper ${w.platform}: skipped ${w.target} — ${w.reason}\n`
+      : `wrapper ${w.platform}: ${w.action} ${w.target}\n`);
+  }
+
+  // ---- git check-ignore sweep over every seeded path (PRD §6).
+  const seededPaths = [
+    ...result.files.map((f) => `${result.rootName}/${f}`),
+    ...wrappers.filter((w) => w.action !== 'skipped').map((w) => w.target),
+  ];
+  const sweep = sweepGitIgnore({ targetDir: opts.target, paths: seededPaths });
+  if (sweep.skipped) {
+    warn('WARN: not a git repo — skipping the git check-ignore sweep; once the repo exists, '
+      + `verify none of the seeded paths (especially ${result.rootName}/logs/) are gitignored\n`);
+  } else if (sweep.error) {
+    warn(`WARN: git check-ignore sweep failed (${sweep.error}) — verify the seeded paths are not gitignored\n`);
+  } else if (sweep.ignored.length > 0) {
+    warn(`WARN: ${sweep.ignored.length} seeded path(s) are gitignored — a gitignored findings log kills `
+      + 'the improvement loop silently. Ignored:\n');
+    for (const path of sweep.ignored) warn(`  ${path}\n`);
+    warn('add negation rule(s) to your .gitignore:\n');
+    for (const rule of negationRules(sweep.ignored, result.rootName)) warn(`  ${rule}\n`);
+  }
+
+  // ---- runtime-dependency preflight: the handoff below tells the human to
+  // run phase 2, and every engine command it reaches for imports js-yaml.
+  const dep = checkRuntimeDependency(result.root);
+  if (!dep.resolved) {
+    warn(`WARN: the seeded engine's one runtime dependency, ${dep.dependency}, does not resolve `
+      + `from ${result.rootName}/engine/ — every engine command will fail to start until it does.\n`);
+    warn(`  install it before phase 2:  npm install --save-dev ${dep.dependency}\n`);
+    warn('  (until then every engine command exits 2 — engine failure, never a silent pass)\n');
+  }
+
+  // ---- D-009 later-stacks warning (also carried by the seeded README) +
+  // the phase-2 handoff (D-019 skill name). PRD §6, verbatim intent.
+  out(`\nwarning: ${LATER_STACKS_WARNING}\n`);
+  out('\nnow run /knowledge-bootstrap in your agent — phase 2 surveys the repo and populates the stores.\n');
+  return EXIT_CODES.CLEAN;
+}

package/cli/init-copy.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * cli/init-copy.js — the entry shim (UCS-956/UCS-950).
+ *
+ * Statically imports NOTHING. Node exits 1 on an unhandled ES module load
+ * error, and exit 1 means FINDINGS (PRD §5) — so a SyntaxError or a missing
+ * dependency in the init path would tell an agent the seed ran and found
+ * problems. Init never emits findings at all: exit 1 must be unreachable.
+ *
+ * The command lives in commands/init-copy.js. The invocation path is unchanged —
+ * this file is what `npx unknown-knowledge` runs.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('../payload/engine/lib/boot.js'),
+    import('./commands/init-copy.js'),
+  ]);
+  process.exitCode = await boot('init-copy', command);
+} catch (error) {
+  // The CLI could not be loaded, so nothing was seeded. Exit 2 — never 1.
+  // Hardcoded: reading it from lib/exit-codes.js is what may have just failed.
+  process.stderr.write(`init-copy: internal failure — nothing was seeded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/cli/init.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * cli/init.js — the entry shim (UCS-956/UCS-950).
+ *
+ * Statically imports NOTHING. Node exits 1 on an unhandled ES module load
+ * error, and exit 1 means FINDINGS (PRD §5) — so a SyntaxError or a missing
+ * dependency in the init path would tell an agent the seed ran and found
+ * problems. Init never emits findings at all: exit 1 must be unreachable.
+ *
+ * The command lives in commands/init.js. The invocation path is unchanged —
+ * this file is what `npx unknown-knowledge` runs.
+ */
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('../payload/engine/lib/boot.js'),
+    import('./commands/init.js'),
+  ]);
+  process.exitCode = await boot('unknown-knowledge init', command);
+} catch (error) {
+  // The CLI could not be loaded, so nothing was seeded. Exit 2 — never 1.
+  // Hardcoded: reading it from lib/exit-codes.js is what may have just failed.
+  process.stderr.write(`unknown-knowledge init: internal failure — nothing was seeded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}