explico 0.13.1 → 0.15.0

package/src/compiler/cli-main.ts

@@ -0,0 +1,557 @@
+/**
+ * `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` and `verify` is read-only; `move`, `rename`,
+ * `fix` and `init-agent` print a diff and change nothing without `--write`.
+ * Each verb's row — usage, flags, what it writes, the type its `--json`
+ * prints — is in `./cli-verbs`; `content help <verb>` prints it.
+ */
+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,
+  planFixMany,
+  planInitAgent,
+  planMove,
+  planRename,
+  renderEditPlan,
+  scaffoldDeck,
+  scaffoldLesson,
+  scaffoldTerm,
+  summarizeDiagnostics,
+  type ContentCliCode,
+  type EditPlan,
+  type RulesReport,
+  type Scaffold,
+} from './cli';
+import { formatVerbHelp, loadCliReference, verbHelp, type HelpJson } from './cli-reference';
+import { CONTENT_USAGE } from './cli-verbs';
+import { planContentRelease } from './content-release';
+import { formatVerifyReport, formatVerifyStep, runVerify, type VerifyReport } from './cli-verify';
+import type { CourseConfig } from './course-config';
+import { compileManifest, type Manifest } from './manifest';
+
+export { CONTENT_USAGE };
+
+/** `--json` of `rules`: the report without its Markdown page. */
+export type RulesJson = Pick<RulesReport, 'filter' | 'count' | 'rules'>;
+
+/** `--json` of `move`, `rename`, `fix` and `init-agent`: the plan, and whether `--write` applied it. */
+export type EditPlanJson = EditPlan & {
+  /** True when `--write` applied the edits; false for a dry run. */
+  readonly written: boolean;
+};
+
+/** `--json` of `new lesson`, `new deck` and `new term`. */
+export interface NewJson {
+  readonly ok: true;
+  /** Course-relative paths of the files it created. */
+  readonly created: readonly string[];
+}
+
+/** `--json` of any verb whose run failed: a stable code and a message, never a stack. */
+export interface ErrorJson {
+  readonly ok: false;
+  readonly error: {
+    /** `internal` for an unexpected throw; every other code is stable. */
+    readonly code: ContentCliCode | 'internal';
+    readonly message: string;
+  };
+}
+
+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;
+  /** `--e2e`: `verify` runs the browser tests too. */
+  readonly e2e: boolean;
+  /** `--force`: `verify` runs even on a tree its last pass covered. */
+  readonly force: 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;
+  let e2e = false;
+  let force = 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 (arg === '--e2e') e2e = true;
+    else if (arg === '--force') force = 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,
+    e2e,
+    force,
+    ...values,
+  };
+}
+
+/**
+ * A lesson's diagnostics include the shared cards it shows (a fault in one is
+ * the page's too), so `context` says how many sit in the lesson's own file —
+ * the number `diagnostics --lesson` lists.
+ */
+function diagnosticsWhere(diagnostics: readonly { readonly file?: string }[], file: string): string {
+  const own = diagnostics.filter((diagnostic) => diagnostic.file === file).length;
+  return own === diagnostics.length ? '' : ` (${own} in ${file}, ${diagnostics.length - own} in the shared cards it shows)`;
+}
+
+/** 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: ContentCliCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function usage(code: ContentCliCode, 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,
+  /** A manifest already compiled for this course, reused instead of compiling one: a test running many verbs compiles once. */
+  compiled?: Manifest,
+): 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, compiled);
+  } 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 } } satisfies ErrorJson);
+    else io.err(`Error [${code}]: ${message}\n`);
+    return 1;
+  }
+}
+
+async function dispatch(
+  courseConfig: CourseConfig,
+  args: ContentArgs,
+  io: ContentIo,
+  json: (value: unknown) => void,
+  compiled: Manifest | undefined,
+): Promise<number> {
+  const out = io.out;
+  if (args.command === '' || args.command === '--help' || (args.command === 'help' && args.positionals.length === 0 && !args.json)) {
+    out(`${CONTENT_USAGE}\n`);
+    return 0;
+  }
+
+  // `help` reads the generated reference beside the engine: no manifest.
+  if (args.command === 'help') {
+    if (args.positionals.length > 1) usage('usage', `content help takes one verb; got ${args.positionals.join(' ')}.`);
+    const reference = loadCliReference();
+    const [word] = args.positionals;
+    if (word === undefined) {
+      json(reference satisfies HelpJson);
+      return 0;
+    }
+    const help = verbHelp(reference, word);
+    if (args.json) json(help satisfies HelpJson);
+    else out(formatVerbHelp(reference, help));
+    return 0;
+  }
+
+  // `verify` runs the course's own scripts, each in its own process: no manifest here.
+  if (args.command === 'verify') {
+    if (args.positionals.length > 0) usage('usage', `content verify takes no argument; got ${args.positionals.join(' ')}.`);
+    if (!args.json) out(`verify (${args.e2e ? 'with' : 'without'} e2e; whole output under node_modules/.cache/explico/verify/)\n`);
+    const report = runVerify({
+      e2e: args.e2e,
+      force: args.force,
+      ...(args.json ? {} : { onStep: (event) => event.phase === 'end' && out(formatVerifyStep(event.step)) }),
+    });
+    if (args.json) json(report satisfies VerifyReport);
+    else out(report.cached ? formatVerifyReport(report) : `\n${formatVerifyReport(report)}`);
+    return report.ok ? 0 : 1;
+  }
+
+  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 } satisfies NewJson);
+    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, `release`
+  // edits the changelog and the config: no manifest for either.
+  if (args.command === 'init-agent' || args.command === 'release') {
+    let plan;
+    if (args.command === 'init-agent') {
+      if (args.positionals.length > 0) usage('usage', `content init-agent takes no argument; got ${args.positionals.join(' ')}.`);
+      plan = planInitAgent();
+    } else {
+      if (args.positionals.length > 1) usage('usage', `content release takes one of major, minor, patch; got ${args.positionals.join(' ')}.`);
+      plan = planContentRelease(args.positionals[0]);
+    }
+    if (args.json) json({ ...plan, written: args.write } satisfies EditPlanJson);
+    else out(renderEditPlan(plan));
+    if (plan.edits.length === 0) return 0;
+    const next = plan.next.length > 0 ? plan.next.join(' · ') : '';
+    if (args.write) {
+      const touched = applyEditPlan(plan);
+      if (!args.json) out(`\nwritten: ${touched.join(', ')}${next === '' ? '' : `\nnext: ${next}`}\n`);
+    } else if (!args.json) out(`\ndry run: nothing written. Add --write to apply${next === '' ? '' : `; then ${next}`}.\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 = compiled ?? (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;
+      const UNRELEASED_SHOWN = 6;
+      const unreleasedList =
+        unreleased.length <= UNRELEASED_SHOWN
+          ? unreleased.join(', ')
+          : `${unreleased.slice(0, UNRELEASED_SHOWN).join(', ')}, … ${unreleased.length - UNRELEASED_SHOWN} more in --json`;
+      out(
+        `Knowledge version ${report.knowledgeVersion}\n` +
+          `Page versions: ${report.pageVersions.tracked} page(s) tracked, ` +
+          `${unreleased.length} with changes not yet released` +
+          `${unreleased.length > 0 ? ` (${unreleasedList})` : ''}\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 {
+        if (args.all === (args.positionals.length > 0)) usage('usage', 'content fix needs <lesson> ids, or --all for every lesson.');
+        plan = planFixMany(manifest, args.all ? manifest.lessons.map((lesson) => lesson.id) : args.positionals);
+      }
+      if (args.json) json({ ...plan, written: args.write } satisfies EditPlanJson);
+      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 } satisfies RulesJson);
+      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}${diagnosticsWhere(report.diagnostics, report.lesson.file)}\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`);
+          // Errors and warnings line by line; info, which never fails a check, counted by code.
+          const infos = new Map<string, number>();
+          for (const diagnostic of entry.diagnostics) {
+            if (diagnostic.severity === 'info') infos.set(diagnostic.code, (infos.get(diagnostic.code) ?? 0) + 1);
+            else out(`     [${diagnostic.severity}] ${diagnostic.code}${ownerTag(diagnostic)}: ${diagnostic.message}\n`);
+          }
+          if (infos.size > 0) {
+            const total = [...infos.values()].reduce((sum, n) => sum + n, 0);
+            const byCode = [...infos].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([code, n]) => `${code} ${n}`).join(', ');
+            out(`     + ${total} info (${byCode}); content diagnostics --lesson ${entry.lesson} lists them\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}`);
+  }
+}