explico 0.13.1 → 0.15.0

package/dist/compiler/cli-reference.js

@@ -0,0 +1,213 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ContentCliError, authoringDocsDir } from "./cli.js";
+import { CONTENT_VERBS, usageLine } from "./cli-verbs.js";
+const CLI_REFERENCE_FILE = "cli-reference.json";
+function loadCliReference() {
+  const dir = authoringDocsDir();
+  const file = dir === void 0 ? void 0 : join(dir, CLI_REFERENCE_FILE);
+  if (file === void 0 || !existsSync(file)) {
+    throw new ContentCliError("unknown-command", `No ${CLI_REFERENCE_FILE} beside the engine (node_modules/explico/docs/authoring).`);
+  }
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+function verbsNamed(word) {
+  const hits = CONTENT_VERBS.filter((verb) => verb.verb === word || verb.verb.startsWith(`${word} `));
+  if (hits.length === 0) {
+    throw new ContentCliError(
+      "unknown-command",
+      `Unknown verb "${word}". The verbs: ${[...new Set(CONTENT_VERBS.map((verb) => verb.verb.split(" ")[0]))].join(", ")}.`
+    );
+  }
+  return hits;
+}
+function reachableDefs(name, defs, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(name) || defs[name] === void 0) return seen;
+  seen.add(name);
+  for (const match of JSON.stringify(defs[name]).matchAll(/"#\/\$defs\/([^"]+)"/g)) reachableDefs(match[1], defs, seen);
+  return seen;
+}
+function schemaOf(reference, name) {
+  const names = [...reachableDefs(name, reference.$defs)].sort();
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $ref: `#/$defs/${name}`,
+    $defs: Object.fromEntries(names.map((n) => [n, reference.$defs[n]]))
+  };
+}
+function verbHelp(reference, word) {
+  return {
+    verbs: verbsNamed(word).map((verb) => ({ ...verb, usage: usageLine(verb), schema: schemaOf(reference, verb.json) }))
+  };
+}
+function oneLine(text) {
+  return typeof text === "string" ? text.replace(/\s+/g, " ").trim() : "";
+}
+function refName(ref) {
+  return ref.replace("#/$defs/", "");
+}
+function isObjectShape(schema) {
+  return schema.type === "object" && schema.properties !== void 0;
+}
+function typeExpression(schema) {
+  if (typeof schema.$ref === "string") return refName(schema.$ref);
+  if ("const" in schema) return JSON.stringify(schema.const);
+  if (Array.isArray(schema.enum)) return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+  if (Array.isArray(schema.anyOf)) return schema.anyOf.map(typeExpression).join(" | ");
+  if (schema.type === "array") {
+    const items = typeExpression(schema.items ?? {});
+    return / \| /.test(items) ? `(${items})[]` : `${items}[]`;
+  }
+  if (schema.type === "object") {
+    if (schema.properties !== void 0) return "{\u2026}";
+    const value = schema.additionalProperties;
+    return `Record<string, ${typeof value === "object" && value !== null ? typeExpression(value) : "unknown"}>`;
+  }
+  if (schema.type === "integer") return "number";
+  if (typeof schema.type === "string") return schema.type;
+  return "unknown";
+}
+function expandable(schema) {
+  if (isObjectShape(schema)) return schema;
+  if (schema.type === "array") return expandable(schema.items ?? {});
+  if (Array.isArray(schema.anyOf)) {
+    const objects = schema.anyOf.map(expandable).filter((s) => s !== void 0);
+    return objects.length === 1 ? objects[0] : void 0;
+  }
+  return void 0;
+}
+function shapeLines(schema, indent = "  ") {
+  const lines = [];
+  const required = new Set(schema.required ?? []);
+  for (const [name, raw] of Object.entries(schema.properties ?? {})) {
+    const description = oneLine(raw.description);
+    lines.push(`${indent}${name}${required.has(name) ? "" : "?"}: ${typeExpression(raw)}${description === "" ? "" : `  \u2014 ${description}`}`);
+    const nested = expandable(raw);
+    if (nested !== void 0) lines.push(...shapeLines(nested, `${indent}  `));
+  }
+  return lines;
+}
+function defLines(name, schema) {
+  const description = oneLine(schema.description);
+  const head = `${name}${isObjectShape(schema) ? "" : ` = ${typeExpression(schema)}`}`;
+  return [description === "" ? head : `${head}  \u2014 ${description}`, ...isObjectShape(schema) ? shapeLines(schema) : []];
+}
+function verbFacts(verb) {
+  return [
+    ["For", verb.when],
+    ["Prints", verb.prints],
+    ["Writes", verb.writes],
+    ["Exits 1", `on a usage error${verb.exit === void 0 ? "" : `, and ${verb.exit}`}`]
+  ];
+}
+function typeOrder(verb) {
+  return [verb.json, ...Object.keys(verb.schema.$defs).filter((name) => name !== verb.json).sort()];
+}
+function formatVerbHelp(reference, help) {
+  const blocks = help.verbs.map((verb) => {
+    const lines = [verb.usage, "", ...verbFacts(verb).map(([label, text]) => `  ${`${label}:`.padEnd(9)}${text}`)];
+    if (verb.flags.length > 0) {
+      lines.push("", "Flags:");
+      const width = Math.max(...verb.flags.map((flag) => flag.flag.length));
+      for (const flag of verb.flags) lines.push(`  ${flag.flag.padEnd(width)}  ${flag.description}`);
+    }
+    lines.push("", `--json prints ${verb.json}:`);
+    for (const name of typeOrder(verb)) lines.push(...defLines(name, reference.$defs[name]).map((line) => `  ${line}`), "");
+    return lines.join("\n").trimEnd();
+  });
+  return `${blocks.join("\n\n")}
+
+On a failure --json prints ${reference.error}: { "ok": false, "error": { "code", "message" } }.
+`;
+}
+function anchor(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+}
+function cliReferenceMarkdown(reference) {
+  const out = [
+    "<!-- generated by scripts/agent/gen-cli.mjs from src/compiler/cli-verbs.ts and the report types \u2014 do not edit; `node scripts/agent/gen-cli.mjs` rewrites it, `--check` gates it -->",
+    "",
+    "# The `content` CLI",
+    "",
+    "Every verb of `pnpm content`, what it writes, when it exits 1, and the shape",
+    "of its `--json`. The same data, with a JSON Schema per type, is",
+    "[`cli-reference.json`](cli-reference.json); `pnpm content help <verb> [--json]`",
+    "prints one verb of it. Every verb takes `--json`: data only on stdout, and on",
+    `a failure \`{ "ok": false, "error": { "code", "message" } }\` ([\`${reference.error}\`](#${anchor(reference.error)})).`,
+    "",
+    "| Verb | You want to know or do | Writes |",
+    "| --- | --- | --- |",
+    ...reference.verbs.map((verb) => `| [\`${verb.verb}\`](#${anchor(`content ${verb.verb}`)}) | ${verb.when} | ${verb.writes} |`),
+    ""
+  ];
+  for (const verb of reference.verbs) {
+    out.push(`## content ${verb.verb}`, "", "```text", usageLine(verb), "```", "");
+    for (const [label, text] of verbFacts(verb)) out.push(`- **${label}:** ${text.replace(/\\explain/g, "`\\explain`")}`);
+    out.push("");
+    if (verb.flags.length > 0) {
+      out.push("| Flag | Effect |", "| --- | --- |");
+      for (const flag of verb.flags) out.push(`| \`${flag.flag}\` | ${flag.description} |`);
+      out.push("");
+    }
+    out.push(`\`--json\`: [\`${verb.json}\`](#${anchor(verb.json)})`, "");
+  }
+  out.push("## The `--json` types", "", "A `?` marks a property that may be absent.", "");
+  for (const name of Object.keys(reference.$defs).sort()) {
+    out.push(`### ${name}`, "", "```ts", ...defLines(name, reference.$defs[name]), "```", "");
+  }
+  return `${out.join("\n").trimEnd()}
+`;
+}
+function jsonShapeErrors(schema, value, defs = schema.$defs ?? {}, path = "$") {
+  if (typeof schema.$ref === "string") {
+    const target = defs[refName(schema.$ref)];
+    return target === void 0 ? [`${path}: unknown ${schema.$ref}`] : jsonShapeErrors(target, value, defs, path);
+  }
+  if ("const" in schema) return value === schema.const ? [] : [`${path}: expected ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`];
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.includes(value) ? [] : [`${path}: expected one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}, got ${JSON.stringify(value)}`];
+  }
+  if (Array.isArray(schema.anyOf)) {
+    const branches = schema.anyOf.map((branch) => jsonShapeErrors(branch, value, defs, path));
+    if (branches.some((errors2) => errors2.length === 0)) return [];
+    return [`${path}: matches none of ${typeExpression(schema)} (${branches.map((errors2) => errors2[0]).join("; ")})`];
+  }
+  const type = schema.type;
+  if (type === void 0) return [];
+  const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  const ok = type === "integer" ? Number.isInteger(value) : type === actual;
+  if (!ok) return [`${path}: expected ${type}, got ${actual}`];
+  if (type === "array") {
+    const items = schema.items ?? {};
+    return value.flatMap((item, index) => jsonShapeErrors(items, item, defs, `${path}[${index}]`));
+  }
+  if (type !== "object") return [];
+  const record = value;
+  const properties = schema.properties ?? {};
+  const errors = [];
+  for (const name of schema.required ?? []) {
+    if (!(name in record)) errors.push(`${path}.${name}: missing`);
+  }
+  for (const [name, item] of Object.entries(record)) {
+    if (item === void 0) continue;
+    const declared = properties[name];
+    if (declared !== void 0) errors.push(...jsonShapeErrors(declared, item, defs, `${path}.${name}`));
+    else if (schema.additionalProperties === false) errors.push(`${path}.${name}: not in the type`);
+    else if (typeof schema.additionalProperties === "object") {
+      errors.push(...jsonShapeErrors(schema.additionalProperties, item, defs, `${path}.${name}`));
+    }
+  }
+  return errors;
+}
+export {
+  CLI_REFERENCE_FILE,
+  cliReferenceMarkdown,
+  defLines,
+  formatVerbHelp,
+  jsonShapeErrors,
+  loadCliReference,
+  schemaOf,
+  shapeLines,
+  verbHelp,
+  verbsNamed
+};

package/dist/compiler/cli-verbs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Every `content` verb, as data: its arguments, what it is for, what it
+ * prints, what it writes, when it exits non-zero, and the exported type its
+ * `--json` prints. The one source for the usage text (`CONTENT_USAGE`),
+ * `content help <verb>`, `docs/authoring/cli.md` and
+ * `docs/authoring/cli-reference.json` — the last two generated by
+ * `scripts/agent/gen-cli.mjs`, which also turns each `json` type name into a
+ * JSON Schema from the TypeScript declaration (`--check` in verify and CI).
+ *
+ * A new verb is a row here, a `case` in `cli-main.ts`, and a regenerated
+ * reference; the `--json` contract test in the playground runs every
+ * read-only row against the course and validates its output.
+ */
+/** One flag a verb takes. */
+interface ContentVerbFlag {
+    /** As typed: `--lesson <id>`, `--write`. */
+    readonly flag: string;
+    readonly description: string;
+}
+/** One verb's row. */
+interface ContentVerb {
+    /** The command word(s): `symbol`, `new lesson`. */
+    readonly verb: string;
+    /** What follows the verb on the usage line, `--json` left out (every verb takes it). */
+    readonly args: string;
+    /** What you want to know or do when you reach for it. */
+    readonly when: string;
+    /** What it prints as text. */
+    readonly prints: string;
+    /** The flags, each once; a positional argument is described in `prints` or `when`. */
+    readonly flags: readonly ContentVerbFlag[];
+    /** What it changes on disk. */
+    readonly writes: string;
+    /** When it exits 1, beyond a usage error. */
+    readonly exit?: string;
+    /** The type its `--json` prints, by its exported name in `explico/compiler/cli`, `cli-main` or `cli-verify`. */
+    readonly json: string;
+}
+declare const CONTENT_VERBS: readonly ContentVerb[];
+/** One usage line: `pnpm content symbol <latex | key> [--json]`. */
+declare function usageLine(verb: ContentVerb): string;
+/** The usage text `content help` prints; `scripts/agent/gen-map.mjs` lists the verbs from the generated reference. */
+declare const CONTENT_USAGE: string;
+
+export { CONTENT_USAGE, CONTENT_VERBS, type ContentVerb, type ContentVerbFlag, usageLine };

package/dist/compiler/cli-verbs.js

@@ -0,0 +1,224 @@
+const WRITE = { flag: "--write", description: "apply the edits; without it the diff is printed and nothing changes" };
+const READ_ONLY = "nothing";
+const CONTENT_VERBS = [
+  {
+    verb: "status",
+    args: "",
+    when: "how the course stands",
+    prints: "counts, diagnostic totals, the knowledge and page versions, the agent surfaces' sizes, whether the course's AGENTS.md points at the engine's guide and the procedures are installed",
+    flags: [],
+    writes: READ_ONLY,
+    json: "StatusReport"
+  },
+  {
+    verb: "diagnostics",
+    args: "[info|warning|error] [--all | --code <c> | --lesson <id> | --changed]",
+    when: "what is wrong, where",
+    prints: "counts by code (with each code's rule) and by file, at the given severity or higher (info by default); a filter or --all lists the lines instead. --json always prints the lines",
+    flags: [
+      { flag: "--all", description: "list every diagnostic instead of the counts" },
+      { flag: "--code <c>", description: "only that diagnostic code" },
+      { flag: "--lesson <id>", description: "only that lesson's file" },
+      { flag: "--changed", description: "only lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not" }
+    ],
+    writes: READ_ONLY,
+    json: "DiagnosticsReport"
+  },
+  {
+    verb: "warnings",
+    args: "",
+    when: "the warnings alone",
+    prints: "every warning, one line each with its rule, then the count",
+    flags: [],
+    writes: READ_ONLY,
+    json: "WarningsReport"
+  },
+  {
+    verb: "context",
+    args: "<lesson>",
+    when: "what a lesson draws on",
+    prints: "its outcomes, notation, sources, diagnostics and token counts; --json adds the body, the floats it can reference, its sections and domain signatures",
+    flags: [],
+    writes: READ_ONLY,
+    json: "ContextReport"
+  },
+  {
+    verb: "equation",
+    args: '"<latex>" [--lesson <id>]',
+    when: "will this expression build",
+    prints: "each glyph's card, unresolved glyphs with where they are defined",
+    flags: [{ flag: "--lesson <id>", description: "resolve against that lesson's local notation as well as the shared cards" }],
+    writes: READ_ONLY,
+    exit: "when the build would refuse the expression",
+    json: "EquationReport"
+  },
+  {
+    verb: "bindings",
+    args: "<lesson>",
+    when: "what a lesson's math binds",
+    prints: "every math span: its bindings, unresolved glyphs, redundant \\explain wraps",
+    flags: [],
+    writes: READ_ONLY,
+    json: "BindingsReport"
+  },
+  {
+    verb: "symbol",
+    args: "<latex | key>",
+    when: "is this symbol defined already",
+    prints: "the shared card, each local entry with its lesson, each gloss with its card, near misses",
+    flags: [],
+    writes: READ_ONLY,
+    json: "SymbolReport"
+  },
+  {
+    verb: "check",
+    args: "<lesson | deck>\u2026 [--changed]",
+    when: "does it render",
+    prints: "ok or FAIL per lesson: schema, references, MDX \u2192 KaTeX; each error and warning with its rule, the info counted by code",
+    flags: [{ flag: "--changed", description: "the lessons whose .mdx or .checks.yml differs from git HEAD, tracked or not" }],
+    writes: READ_ONLY,
+    exit: "when a lesson has an error",
+    json: "CheckReport"
+  },
+  {
+    verb: "rule",
+    args: "<ID>",
+    when: "one rule, whole",
+    prints: "the entry as this course has it (enforcement, codes, settings in effect) and the rule page's section, example included",
+    flags: [],
+    writes: READ_ONLY,
+    exit: "for an ID the catalog and the course rules do not know",
+    json: "RuleReport"
+  },
+  {
+    verb: "migrate",
+    args: "[--from <version>] [--to <version>]",
+    when: "what an upgrade needs",
+    prints: "the migration guide's sections between the version package.json pins at git HEAD and the one installed, oldest first",
+    flags: [
+      { flag: "--from <version>", description: "start here instead of the version pinned at HEAD" },
+      { flag: "--to <version>", description: "stop here instead of the installed version" }
+    ],
+    writes: READ_ONLY,
+    exit: "when a section between the two versions is missing",
+    json: "MigrateReport"
+  },
+  {
+    verb: "rules",
+    args: "[--element <e>[,<e>]] [--enforcement script|partial|guide|locked] [--edition chapter|deck]",
+    when: "which rules apply",
+    prints: "the rules this course has on, by element, with enforcement, codes, settings in effect and a one-line summary",
+    flags: [
+      { flag: "--element <e>[,<e>]", description: "only rules about these elements (prose, table, notation, \u2026)" },
+      { flag: "--enforcement <kind>", description: "only script, partial, guide or locked rules" },
+      { flag: "--edition <edition>", description: "chapter (the default) or deck: the rules for that edition's pages" }
+    ],
+    writes: READ_ONLY,
+    json: "RulesJson"
+  },
+  {
+    verb: "move",
+    args: "<lesson>:<key> [--to <key>] [--write]",
+    when: "a local entry becomes shared",
+    prints: "the new card and every copy and reference that changes, as a diff",
+    flags: [{ flag: "--to <key>", description: "the shared card's key, when it differs from the local one" }, WRITE],
+    writes: "only with --write",
+    json: "EditPlanJson"
+  },
+  {
+    verb: "rename",
+    args: "<old> <new> [--write]",
+    when: "rename a shared card",
+    prints: "the card file and every reference, as a diff",
+    flags: [WRITE],
+    writes: "only with --write",
+    json: "EditPlanJson"
+  },
+  {
+    verb: "fix",
+    args: "<lesson>\u2026 | --all [--write]",
+    when: "the mechanical repairs",
+    prints: "redundant \\explain wraps unwrapped, as a diff",
+    flags: [{ flag: "--all", description: "every lesson; the ones with nothing to fix are counted" }, WRITE],
+    writes: "only with --write",
+    json: "EditPlanJson"
+  },
+  {
+    verb: "new lesson",
+    args: "<id>",
+    when: "a chapter to start from",
+    prints: "the files it created: the .mdx and its .checks.yml",
+    flags: [],
+    writes: "new files; never overwrites",
+    json: "NewJson"
+  },
+  {
+    verb: "new deck",
+    args: "<lesson | part>",
+    when: "slides to start from",
+    prints: "the deck it drafted from the chapter (or the part's chapters)",
+    flags: [],
+    writes: "new files; never overwrites",
+    json: "NewJson"
+  },
+  {
+    verb: "new term",
+    args: "<key>",
+    when: "a shared notation card to start from",
+    prints: "the card file it created",
+    flags: [],
+    writes: "new files; never overwrites",
+    json: "NewJson"
+  },
+  {
+    verb: "init-agent",
+    args: "[--write]",
+    when: "install the agent procedures",
+    prints: "the skills and the rules-reviewer agent it would copy into .claude/, and a baseline AGENTS.md when the course has none; rerun after an upgrade",
+    flags: [WRITE],
+    writes: "only with --write",
+    json: "EditPlanJson"
+  },
+  {
+    verb: "release",
+    args: "[major|minor|patch] [--write]",
+    when: "cut a content release (rule C3)",
+    prints: "## [Unreleased] in content/CHANGELOG.md becoming a dated ## [x.y.z] heading and about.version becoming x.y.z, as a diff; the bump defaults to what the section's headings imply (Breaking or Removed \u2192 major, Added \u2192 minor, else patch)",
+    flags: [WRITE],
+    writes: "only with --write",
+    json: "EditPlanJson"
+  },
+  {
+    verb: "verify",
+    args: "[--e2e] [--force]",
+    when: "is it ready to hand back",
+    prints: "one line per step \u2014 validate:content, check --changed, astro check, the course's tests, astro build, and with --e2e the browser tests \u2014 and the tail of each failed step's log; a rerun on an unchanged tree answers from the last pass",
+    flags: [
+      { flag: "--e2e", description: "also run the browser tests (the course's test:e2e script, or playwright test when it has a config)" },
+      { flag: "--force", description: "run even when nothing changed since the last pass" }
+    ],
+    writes: "what validate:content and astro build write; logs and the pass record under node_modules/.cache/explico/verify/",
+    exit: "when a step fails",
+    json: "VerifyReport"
+  },
+  {
+    verb: "help",
+    args: "[<verb>]",
+    when: "a verb's flags and its --json shape",
+    prints: "the usage; with a verb, its flags, what it writes, its exit code and the shape of its --json",
+    flags: [],
+    writes: READ_ONLY,
+    exit: "for an unknown verb",
+    json: "HelpJson"
+  }
+];
+function usageLine(verb) {
+  return `pnpm content ${verb.verb}${verb.args === "" ? "" : ` ${verb.args}`} [--json]`;
+}
+const CONTENT_USAGE = `Usage:
+${CONTENT_VERBS.map((verb) => `  ${usageLine(verb)}`).join("\n")}`;
+export {
+  CONTENT_USAGE,
+  CONTENT_VERBS,
+  usageLine
+};

package/dist/compiler/cli-verify.d.ts

@@ -0,0 +1,51 @@
+type VerifyStepName = 'validate:content' | 'check --changed' | 'astro check' | 'tests' | 'astro build' | 'e2e';
+interface VerifyStep {
+    readonly name: VerifyStepName;
+    readonly status: 'pass' | 'fail' | 'skipped';
+    /** The command it ran, as it would be typed; absent for a skipped step. */
+    readonly command?: string;
+    /** Why it was skipped, or why it could not start. */
+    readonly reason?: string;
+    readonly seconds?: number;
+    /** Course-relative path of its whole output. */
+    readonly log?: string;
+    /** The last lines of the output of a failed step. */
+    readonly tail?: readonly string[];
+}
+interface VerifyReport {
+    readonly ok: boolean;
+    /** True when the tree is unchanged since a pass that covered as much: nothing ran, `steps` are that pass's. */
+    readonly cached: boolean;
+    /** When the recorded pass ran, for a cached answer (ISO 8601). */
+    readonly since?: string;
+    /** The hash of the tree the run left, or `null` outside a git repository (then nothing is recorded). */
+    readonly tree: string | null;
+    /** Whether the browser tests were part of the run. */
+    readonly e2e: boolean;
+    readonly steps: readonly VerifyStep[];
+}
+interface VerifyOptions {
+    readonly e2e?: boolean;
+    readonly force?: boolean;
+    /** The course root; the working directory by default. */
+    readonly cwd?: string;
+    /** Called as each step starts and ends, for a progress line. */
+    readonly onStep?: (event: {
+        readonly phase: 'start';
+        readonly name: VerifyStepName;
+    } | {
+        readonly phase: 'end';
+        readonly step: VerifyStep;
+    }) => void;
+}
+declare const VERIFY_DIR: string;
+/** The working tree as the gate sees it, in one hash; `null` outside git. */
+declare function verifyTreeHash(cwd: string): string | null;
+/** Run every step, record a pass, and say what happened; never throws for a failing step. */
+declare function runVerify(options?: VerifyOptions): VerifyReport;
+/** The digest after a run: failed steps' tails, then one verdict line. */
+declare function formatVerifyReport(report: VerifyReport): string;
+/** One progress line per step: `  astro build        ok   41.2s`. */
+declare function formatVerifyStep(step: VerifyStep): string;
+
+export { VERIFY_DIR, type VerifyOptions, type VerifyReport, type VerifyStep, type VerifyStepName, formatVerifyReport, formatVerifyStep, runVerify, verifyTreeHash };