explico 0.13.0 → 0.14.0

package/src/compiler/cli-main.ts

@@ -0,0 +1,469 @@
+/**
+ * `pnpm content <command>` — the AI-authoring surface, whole.
+ *
+ * The engine owns the dispatch, the usage text, the flag parsing, the text
+ * rendering and the exit codes; a course's `scripts/content.ts` is three
+ * lines that hand it the course config:
+ *
+ *   import { runContentCli } from 'explico/compiler/cli-main';
+ *   import { courseConfig } from '../content/course.config';
+ *   process.exitCode = await runContentCli(courseConfig);
+ *
+ * so every verb reaches every course with the package and no course forks
+ * the router. Each verb's logic lives in `./cli`; this module only parses
+ * argv, prints (`--json` = data only, no stack traces), and returns the exit
+ * code. Everything except `new` is read-only; `move`, `rename` and `fix`
+ * print a diff and change nothing without `--write`.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import {
+  ContentCliError,
+  applyEditPlan,
+  changedLessonIds,
+  contentBindings,
+  contentCheck,
+  contentContext,
+  contentDiagnostics,
+  contentEquation,
+  contentMigrate,
+  contentRule,
+  contentRules,
+  contentStatus,
+  contentSymbol,
+  contentWarnings,
+  filterDiagnostics,
+  findLesson,
+  formatBindingsReport,
+  formatCliDiagnostic,
+  formatDiagnosticsSummary,
+  formatEquationReport,
+  formatMigrateReport,
+  formatRuleReport,
+  formatSymbolReport,
+  ownerTag,
+  parseRulesFilter,
+  planFix,
+  planInitAgent,
+  planMove,
+  planRename,
+  renderEditPlan,
+  scaffoldDeck,
+  scaffoldLesson,
+  scaffoldTerm,
+  summarizeDiagnostics,
+  type Scaffold,
+} from './cli';
+import type { CourseConfig } from './course-config';
+import { compileManifest } from './manifest';
+
+/** The usage text `content help` prints; `scripts/agent/gen-map.mjs` lists the verbs from it. */
+export const CONTENT_USAGE = `Usage:
+  pnpm content status
+  pnpm content diagnostics [info|warning|error] [--all | --code <c> | --lesson <id> | --changed] [--json]
+  pnpm content warnings [--json]
+  pnpm content context <lesson> [--json]
+  pnpm content equation "<latex>" [--lesson <id>] [--json]
+  pnpm content bindings <lesson> [--json]
+  pnpm content symbol <latex | key> [--json]
+  pnpm content check <lesson | deck>… [--changed] [--json]
+  pnpm content rule <ID> [--json]
+  pnpm content migrate [--from <version>] [--to <version>] [--json]
+  pnpm content rules [--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck] [--json]
+  pnpm content move <lesson>:<key> [--to <key>] [--write]
+  pnpm content rename <old> <new> [--write]
+  pnpm content fix <lesson> [--write]
+  pnpm content new lesson <id>
+  pnpm content new deck <lesson | part>
+  pnpm content new term <key>
+  pnpm content init-agent [--write]`;
+
+export interface ContentArgs {
+  readonly command: string;
+  readonly positionals: readonly string[];
+  readonly json: boolean;
+  readonly changed: boolean;
+  /** `--element a,b` — a value-taking flag; also `--element=a,b`. */
+  readonly element?: string;
+  /** `--enforcement script` — a value-taking flag; also `--enforcement=script`. */
+  readonly enforcement?: string;
+  /** `--edition deck` — a value-taking flag; also `--edition=deck`. */
+  readonly edition?: string;
+  /** `--all`: list every diagnostic instead of the counts. */
+  readonly all: boolean;
+  /** `--code <code>`: only that diagnostic code. */
+  readonly code?: string;
+  /** `--lesson <id>`: only that lesson's diagnostics; the scope for `equation`. */
+  readonly lesson?: string;
+  /** `--from <version>` / `--to <version>` for `migrate`; `--to <key>` for `move`. */
+  readonly from?: string;
+  readonly to?: string;
+  /** `--write`: apply a planned edit instead of only showing its diff. */
+  readonly write: boolean;
+}
+
+const VALUED_FLAGS = ['element', 'enforcement', 'edition', 'code', 'lesson', 'from', 'to'] as const;
+
+export function parseContentArgs(argv: readonly string[]): ContentArgs {
+  const positionals: string[] = [];
+  const values: Partial<Record<(typeof VALUED_FLAGS)[number], string>> = {};
+  let json = false;
+  let changed = false;
+  let all = false;
+  let write = false;
+  const valued = new RegExp(`^--(${VALUED_FLAGS.join('|')})(?:=(.*))?$`);
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    const match = valued.exec(arg);
+    if (arg === '--json') json = true;
+    else if (arg === '--changed') changed = true;
+    else if (arg === '--all') all = true;
+    else if (arg === '--write') write = true;
+    else if (match) values[match[1] as (typeof VALUED_FLAGS)[number]] = match[2] ?? argv[(i += 1)] ?? '';
+    else positionals.push(arg);
+  }
+  return {
+    command: positionals[0] ?? '',
+    positionals: positionals.slice(1),
+    json,
+    changed,
+    all,
+    write,
+    ...values,
+  };
+}
+
+/** Where a run prints; the process streams by default, a buffer in a test. */
+export interface ContentIo {
+  readonly out: (text: string) => void;
+  readonly err: (text: string) => void;
+}
+
+const PROCESS_IO: ContentIo = {
+  out: (text) => process.stdout.write(text),
+  err: (text) => process.stderr.write(text),
+};
+
+/** A usage or input mistake, reported like a `ContentCliError` and ending the run with 1. */
+class Usage extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function usage(code: string, message: string): never {
+  throw new Usage(code, message);
+}
+
+function writeScaffold(scaffold: Scaffold): string[] {
+  const written: string[] = [];
+  for (const file of [{ path: scaffold.path, contents: scaffold.contents }, ...scaffold.companions]) {
+    const absolute = join(process.cwd(), file.path);
+    mkdirSync(dirname(absolute), { recursive: true });
+    writeFileSync(absolute, file.contents, { flag: 'wx' });
+    written.push(file.path);
+  }
+  return written;
+}
+
+/**
+ * Run one `content` command for this course and return its exit code: 0 on
+ * success, 1 on a usage error, a `ContentCliError`, a check that failed, or
+ * an unexpected throw (reported by message, never a stack).
+ */
+export async function runContentCli(
+  courseConfig: CourseConfig,
+  argv: readonly string[] = process.argv.slice(2),
+  io: ContentIo = PROCESS_IO,
+): Promise<number> {
+  const args = parseContentArgs(argv);
+  const json = (value: unknown) => io.out(`${JSON.stringify(value, null, 2)}\n`);
+  try {
+    return await dispatch(courseConfig, args, io, json);
+  } catch (error) {
+    const code =
+      error instanceof Usage || error instanceof ContentCliError ? error.code : 'internal';
+    const message = error instanceof Error ? error.message : String(error);
+    if (args.json) json({ ok: false, error: { code, message } });
+    else io.err(`Error [${code}]: ${message}\n`);
+    return 1;
+  }
+}
+
+async function dispatch(
+  courseConfig: CourseConfig,
+  args: ContentArgs,
+  io: ContentIo,
+  json: (value: unknown) => void,
+): Promise<number> {
+  const out = io.out;
+  if (args.command === '' || args.command === 'help' || args.command === '--help') {
+    out(`${CONTENT_USAGE}\n`);
+    return 0;
+  }
+
+  if (args.command === 'new') {
+    const [kind, id] = args.positionals;
+    if (kind !== 'lesson' && kind !== 'deck' && kind !== 'term') {
+      usage('unknown-kind', 'content new expects "lesson", "deck" or "term".');
+    }
+    if (!id) usage('usage', `content new ${kind} needs an id.`);
+    if (args.positionals.length > 2) {
+      usage('usage', `content new ${kind} takes one id; got also ${args.positionals.slice(2).join(' ')}.`);
+    }
+    const scaffold = kind === 'lesson' ? scaffoldLesson(id) : kind === 'deck' ? scaffoldDeck(id) : scaffoldTerm(id);
+    const written = writeScaffold(scaffold);
+    if (args.json) json({ ok: true, created: written });
+    else out(`Created:\n${written.map((p) => `  ${p}`).join('\n')}\n`);
+    return 0;
+  }
+
+  // An argument a command does not take is a mistake, never silently dropped:
+  // `content status extra` would otherwise look like it did something with it.
+  if (['status', 'rules', 'warnings'].includes(args.command) && args.positionals.length > 0) {
+    usage('usage', `content ${args.command} takes no <lesson>; got ${args.positionals.join(' ')}.`);
+  }
+
+  // `init-agent` copies the engine's procedures into the course: no manifest.
+  if (args.command === 'init-agent') {
+    if (args.positionals.length > 0) usage('usage', `content init-agent takes no argument; got ${args.positionals.join(' ')}.`);
+    const plan = planInitAgent();
+    if (args.json) json({ ...plan, written: args.write });
+    else out(renderEditPlan(plan));
+    if (plan.edits.length === 0) return 0;
+    if (args.write) {
+      const touched = applyEditPlan(plan);
+      if (!args.json) out(`\nwritten: ${touched.join(', ')}\n`);
+    } else if (!args.json) out('\ndry run: nothing written. Add --write to install.\n');
+    return 0;
+  }
+
+  // `migrate` reads the guide beside the engine, not the course: no manifest.
+  if (args.command === 'migrate') {
+    if (args.positionals.length > 0) {
+      usage('usage', `content migrate takes no positional argument; got ${args.positionals.join(' ')}. Use --from and --to.`);
+    }
+    const report = contentMigrate({
+      ...(args.from === undefined ? {} : { from: args.from }),
+      ...(args.to === undefined ? {} : { to: args.to }),
+    });
+    if (args.json) json(report);
+    else out(formatMigrateReport(report));
+    return 0;
+  }
+
+  const known = [
+    'status', 'move', 'rename', 'fix', 'rule', 'rules', 'warnings', 'diagnostics',
+    'context', 'equation', 'bindings', 'symbol', 'check',
+  ];
+  if (!known.includes(args.command)) {
+    usage('unknown-command', `Unknown command "${args.command}".\n${CONTENT_USAGE}`);
+  }
+
+  const manifest = await compileManifest(courseConfig);
+
+  switch (args.command) {
+    case 'status': {
+      const report = contentStatus(manifest);
+      if (args.json) {
+        json(report);
+        return 0;
+      }
+      const c = report.counts;
+      const unreleased = report.pageVersions.unreleased;
+      out(
+        `Knowledge version ${report.knowledgeVersion}\n` +
+          `Page versions: ${report.pageVersions.tracked} page(s) tracked, ` +
+          `${unreleased.length} with changes not yet released` +
+          `${unreleased.length > 0 ? ` (${unreleased.join(', ')})` : ''}\n` +
+          `Lessons ${c.lessons} · competencies ${c.competencies} · assessments ${c.assessments} · ` +
+          `sources ${c.sources} · tracks ${c.tracks} · notation ${c.notationDefinitions} · ` +
+          `keyed equations ${c.keyedEquations} · tables ${c.keyedTables} · ` +
+          `figures ${c.keyedFigures} · diagrams ${c.keyedDiagrams} · example sets ${c.keyedExamples}\n` +
+          `Diagnostics: ${report.diagnostics.errors} error(s), ${report.diagnostics.warnings} warning(s), ${report.diagnostics.infos} info\n` +
+          `Orphans: ${report.orphans.length}\n` +
+          `Agent surfaces (estimated tokens): ${report.agentSurfaces
+            .map((s) => `${s.name} ${(s.tokens / 1000).toFixed(1)}k`)
+            .join(' · ')}\n` +
+          `Agent guide: ${
+            report.agentGuide.agentsFile === null
+              ? 'no AGENTS.md — `pnpm content init-agent --write` installs the baseline'
+              : report.agentGuide.linksGuide
+                ? `${report.agentGuide.agentsFile} points at the engine's guide`
+                : `${report.agentGuide.agentsFile} does not point at node_modules/explico/docs/authoring/agents.md — add that line`
+          }; procedures ${report.agentGuide.skillsInstalled ? 'installed' : 'not installed (`pnpm content init-agent --write`)'}\n`,
+      );
+      return 0;
+    }
+
+    case 'move':
+    case 'rename':
+    case 'fix': {
+      let plan;
+      if (args.command === 'move') {
+        const [target, ...extra] = args.positionals;
+        const [lesson, key] = (target ?? '').split(':');
+        if (!lesson || !key || extra.length > 0) usage('usage', 'content move needs <lesson>:<key> and optionally --to <key>.');
+        plan = planMove(manifest, lesson, key, args.to === undefined ? {} : { to: args.to });
+      } else if (args.command === 'rename') {
+        const [oldKey, newKey, ...extra] = args.positionals;
+        if (!oldKey || !newKey || extra.length > 0) usage('usage', 'content rename needs <old> <new>.');
+        plan = planRename(manifest, oldKey, newKey);
+      } else {
+        const [lesson, ...extra] = args.positionals;
+        if (!lesson || extra.length > 0) usage('usage', 'content fix needs one <lesson> id.');
+        plan = planFix(manifest, lesson);
+      }
+      if (args.json) json({ ...plan, written: args.write });
+      else out(renderEditPlan(plan));
+      if (plan.edits.length === 0) return 0;
+      if (args.write) {
+        const touched = applyEditPlan(plan);
+        if (!args.json) out(`\nwritten: ${touched.join(', ')}\nnext: ${plan.next.join(' · ')}\n`);
+      } else if (!args.json) {
+        out(`\ndry run: nothing written. Add --write to apply; then ${plan.next.join(' · ')}.\n`);
+      }
+      return 0;
+    }
+
+    case 'rule': {
+      const [id, ...extra] = args.positionals;
+      if (!id) usage('usage', 'content rule needs a rule ID: N4, V8, X1, or an invariant such as keyed-floats.');
+      if (extra.length > 0) usage('usage', `content rule takes one ID; got also ${extra.join(' ')}.`);
+      const report = contentRule(manifest, id);
+      if (args.json) json(report);
+      else out(formatRuleReport(report));
+      return report.status === 'unknown' ? 1 : 0;
+    }
+
+    case 'rules': {
+      const filter = parseRulesFilter({
+        ...(args.element === undefined ? {} : { element: args.element }),
+        ...(args.enforcement === undefined ? {} : { enforcement: args.enforcement }),
+        ...(args.edition === undefined ? {} : { edition: args.edition }),
+      });
+      const report = contentRules(manifest, filter);
+      if (args.json) json({ filter: report.filter, count: report.count, rules: report.rules });
+      else out(report.markdown);
+      return 0;
+    }
+
+    case 'warnings': {
+      const report = contentWarnings(manifest);
+      if (args.json) json(report);
+      else {
+        for (const warning of report.warnings) out(`${formatCliDiagnostic(warning)}\n`);
+        out(`${report.count} warning(s)\n`);
+      }
+      return 0;
+    }
+
+    case 'diagnostics': {
+      const [requested = 'info', ...extra] = args.positionals;
+      if (extra.length > 0 || (requested !== 'info' && requested !== 'warning' && requested !== 'error')) {
+        usage('usage', 'content diagnostics expects one of: info, warning, error.');
+      }
+      // The counts are the default; a filter or --all lists the lines.
+      let report = contentDiagnostics(manifest, requested);
+      let narrowed = false;
+      if (args.code !== undefined) {
+        report = filterDiagnostics(report, { code: args.code });
+        narrowed = true;
+      }
+      if (args.lesson !== undefined) {
+        report = filterDiagnostics(report, { files: [findLesson(manifest, args.lesson).file] });
+        narrowed = true;
+      }
+      if (args.changed) {
+        const ids = new Set(changedLessonIds());
+        const files = manifest.lessons.filter((l) => ids.has(l.id)).map((l) => l.file);
+        report = filterDiagnostics(report, { files });
+        narrowed = true;
+      }
+      if (args.json) json(report);
+      else if (args.all || narrowed) {
+        for (const diagnostic of report.diagnostics) out(`${formatCliDiagnostic(diagnostic)}\n`);
+        out(`${report.count} diagnostic(s) at ${report.minimumSeverity} or higher\n`);
+      } else out(formatDiagnosticsSummary(summarizeDiagnostics(report)));
+      return 0;
+    }
+
+    case 'context': {
+      const [lesson, ...extra] = args.positionals;
+      if (!lesson) usage('usage', 'content context needs a <lesson> id.');
+      if (extra.length > 0) usage('usage', `content context takes one <lesson> id; got also ${extra.join(' ')}.`);
+      const report = contentContext(manifest, lesson);
+      if (args.json) {
+        json(report);
+        return 0;
+      }
+      const t = report.tokens;
+      out(
+        `${report.lesson.id} — ${report.lesson.title}\n` +
+          `teaches: ${report.lesson.teaches.join(', ') || '(none)'}\n` +
+          `requires: ${report.lesson.requires.join(', ') || '(none)'}\n` +
+          `notation: ${report.notation.map((n) => n.key).join(', ') || '(none)'}\n` +
+          `sources: ${report.sources.map((s) => s.id).join(', ') || '(none)'}\n` +
+          `diagnostics: ${report.diagnostics.length}\n` +
+          `tokens: context ${t.context} vs doc set ${t.docSet} + corpus ${t.corpus} ` +
+          `(${(t.ratio * 100).toFixed(2)}% of the baseline)\n`,
+      );
+      return 0;
+    }
+
+    case 'equation': {
+      const [latex, ...extra] = args.positionals;
+      if (!latex) usage('usage', "content equation needs one quoted LaTeX string: content equation 'v_0 \\sin(\\theta)' --lesson <id>.");
+      if (extra.length > 0) usage('usage', `content equation takes one string; got also ${extra.join(' ')}. Quote the whole expression.`);
+      const report = contentEquation(manifest, latex, args.lesson === undefined ? {} : { lesson: args.lesson });
+      if (args.json) json(report);
+      else out(formatEquationReport(report));
+      return report.ok ? 0 : 1;
+    }
+
+    case 'bindings': {
+      const [lesson, ...extra] = args.positionals;
+      if (!lesson) usage('usage', 'content bindings needs a <lesson> id.');
+      if (extra.length > 0) usage('usage', `content bindings takes one <lesson> id; got also ${extra.join(' ')}.`);
+      const report = contentBindings(manifest, lesson);
+      if (args.json) json(report);
+      else out(formatBindingsReport(report));
+      return 0;
+    }
+
+    case 'symbol': {
+      const [query, ...extra] = args.positionals;
+      if (!query) usage('usage', "content symbol needs a <latex | key>; quote a backslash: '\\theta'.");
+      if (extra.length > 0) {
+        usage('usage', `content symbol takes one <latex | key>; got also ${extra.join(' ')}. Quote a symbol with spaces: 'v(t)'.`);
+      }
+      const report = contentSymbol(manifest, query);
+      if (args.json) json(report);
+      else out(formatSymbolReport(report));
+      return 0;
+    }
+
+    case 'check': {
+      // Every lesson named is checked, not only the first.
+      const report = await contentCheck(manifest, { lessons: args.positionals, changed: args.changed });
+      if (args.json) json(report);
+      else {
+        for (const entry of report.lessons) {
+          out(`${entry.ok ? 'ok  ' : 'FAIL'} ${entry.lesson}${entry.rendered ? '' : ' (render failed)'}\n`);
+          for (const diagnostic of entry.diagnostics) {
+            out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}\n`);
+          }
+        }
+        if (report.lessons.length === 0) out('No changed lessons.\n');
+      }
+      return report.ok ? 0 : 1;
+    }
+
+    default:
+      return usage('unknown-command', `Unknown command "${args.command}".\n${CONTENT_USAGE}`);
+  }
+}