@freetesh/canon 0.0.0-stage → 0.16.0

package/cli/dist/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { registerAdd } from "./commands/add.js";
+import { registerApprove } from "./commands/approve.js";
+import { registerCheck } from "./commands/check.js";
+import { registerCopies } from "./commands/copies.js";
+import { registerDoctor } from "./commands/doctor.js";
+import { registerHooks } from "./commands/hooks.js";
+import { registerInit } from "./commands/init.js";
+import { registerLearn } from "./commands/learn.js";
+import { registerPipeline } from "./commands/pipeline.js";
+import { registerStandards } from "./commands/standards.js";
+import { registerStatus } from "./commands/status.js";
+import { registerSync } from "./commands/sync.js";
+import { registerUi } from "./commands/ui.js";
+import { registerWeigh } from "./commands/weigh.js";
+import { findEstate } from "./config/load.js";
+import { registerMcp } from "./commands/mcp.js";
+import { registerSearch } from "./commands/search.js";
+import { canonVersion } from "./status.js";
+const env = {
+    canonRoot: resolve(import.meta.dirname, "..", ".."),
+    estateRoot: process.env.CANON_ESTATE ?? findEstate(process.cwd()),
+};
+const program = new Command("canon")
+    .description("Shared standards, knowledge and decision checks for every product.")
+    .version(canonVersion(env.canonRoot));
+registerInit(program, env);
+registerAdd(program, env);
+registerCheck(program, env);
+registerCopies(program, env);
+registerSync(program, env);
+registerStatus(program, env);
+registerStandards(program, env);
+registerDoctor(program);
+registerHooks(program, env);
+registerUi(program, env);
+registerLearn(program, env);
+registerApprove(program);
+registerPipeline(program, env);
+registerWeigh(program);
+registerSearch(program);
+registerMcp(program);
+program.parseAsync().catch((error) => {
+    console.error(`canon: ${error.message}`);
+    process.exitCode = 1;
+});

package/cli/dist/init.d.ts

@@ -0,0 +1,46 @@
+import { type Kind, type Module } from "./config/schema.ts";
+export type Runner = (command: string, args: string[]) => void;
+export interface InitAnswers {
+    canonVersion: string;
+    kind?: Kind;
+    modules?: Module[];
+    packs?: string[];
+    force?: boolean;
+}
+export interface InitPlan {
+    config: {
+        canon: string;
+        kind: Kind;
+        modules: Module[];
+        expo?: {
+            sdk: number;
+        };
+        packs?: string[];
+    };
+    /** Files under the repo that will be created; existing files are never touched. */
+    create: string[];
+}
+export declare const ARCHITECTURE_BASE = ".dependency-cruiser.base.cjs";
+export interface Starter {
+    file: string;
+    template: "base.cjs" | "root.cjs" | "app.cjs" | "package.cjs";
+}
+/**
+ * The rules files the architecture module needs: canon's managed base, then a starter
+ * per workspace (a folder under apps/ or packages/ with a package.json), or one at the
+ * root when the repo has no workspaces.
+ */
+export declare function architectureStarters(repo: string): Starter[];
+/** Rewrites a repo's managed architecture base from canon's template; true when it changed. */
+export declare function refreshArchitectureBase(repo: string, canonRoot: string): boolean;
+/** Parses a `--modules`/`--packs` style comma list, rejecting anything not in `allowed`. */
+export declare function parseChoices<T extends string>(value: string, allowed: readonly T[], label: string): T[];
+export declare function detectExpoSdk(repo: string): number | undefined;
+export declare function planInit(repo: string, answers: InitAnswers): InitPlan;
+export declare function applyInit(repo: string, plan: InitPlan, options: {
+    run: Runner;
+    name: string;
+    canonRoot: string;
+}): void;
+/** Adds the repo's wiki and features to qmd. Safe to repeat: qmd refuses a name it already has. */
+export declare function indexKnowledge(repo: string, name: string, run: Runner): void;

package/cli/dist/init.js

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stringify } from "yaml";
+import { RULES_FILES } from "./checks/architecture.js";
+import { requiredContext } from "./checks/context-layout.js";
+import { inferKind, inferModules } from "./config/load.js";
+import { kindCovers, MODULES_BY_KIND } from "./config/schema.js";
+export const ARCHITECTURE_BASE = ".dependency-cruiser.base.cjs";
+const ARCHITECTURE_TEMPLATES = join("templates", "dependency-cruiser");
+const WORKSPACE_PARENTS = ["apps", "packages"];
+/**
+ * The rules files the architecture module needs: canon's managed base, then a starter
+ * per workspace (a folder under apps/ or packages/ with a package.json), or one at the
+ * root when the repo has no workspaces.
+ */
+export function architectureStarters(repo) {
+    const workspaces = WORKSPACE_PARENTS.flatMap((parent) => existsSync(join(repo, parent))
+        ? readdirSync(join(repo, parent), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && existsSync(join(repo, parent, entry.name, "package.json")))
+            .map((entry) => `${parent}/${entry.name}`)
+            .sort()
+        : []);
+    const starters = workspaces.length > 0
+        ? workspaces.map((dir) => ({ file: `${dir}/${RULES_FILES[0]}`, template: dir.startsWith("apps/") ? "app.cjs" : "package.cjs" }))
+        : [{ file: RULES_FILES[0], template: "root.cjs" }];
+    return [{ file: ARCHITECTURE_BASE, template: "base.cjs" }, ...starters];
+}
+/** Rewrites a repo's managed architecture base from canon's template; true when it changed. */
+export function refreshArchitectureBase(repo, canonRoot) {
+    const file = join(repo, ARCHITECTURE_BASE);
+    if (!existsSync(file))
+        return false;
+    const current = readFileSync(join(canonRoot, ARCHITECTURE_TEMPLATES, "base.cjs"), "utf8");
+    if (readFileSync(file, "utf8") === current)
+        return false;
+    writeFileSync(file, current);
+    return true;
+}
+/** Parses a `--modules`/`--packs` style comma list, rejecting anything not in `allowed`. */
+export function parseChoices(value, allowed, label) {
+    const chosen = value.split(",").map((item) => item.trim()).filter(Boolean);
+    const unknown = chosen.find((item) => !allowed.includes(item));
+    if (unknown)
+        throw new Error(`unknown ${label} "${unknown}" — choose from: ${allowed.join(", ")}`);
+    return chosen;
+}
+const PACKAGE_FILES = ["package.json", "apps/mobile/package.json"];
+export function detectExpoSdk(repo) {
+    for (const file of PACKAGE_FILES) {
+        const path = join(repo, file);
+        if (!existsSync(path))
+            continue;
+        const pkg = JSON.parse(readFileSync(path, "utf8"));
+        const range = pkg.dependencies?.expo ?? pkg.devDependencies?.expo;
+        const major = range?.match(/\d+/)?.[0];
+        if (major)
+            return Number(major);
+    }
+    return undefined;
+}
+// The first file each required .context entry gets, so no folder is created empty.
+const FIRST_FILE = {
+    "README.md": ".context/README.md",
+    "tasks.md": ".context/tasks.md",
+    raw: ".context/raw/.gitkeep",
+    wiki: ".context/wiki/index.md",
+    features: ".context/features/index.md",
+};
+function template(file) {
+    switch (file) {
+        case ".context/README.md":
+            return "# .context\n\nProduct material, in the canon context layout. Start at [`tasks.md`](tasks.md).\n";
+        case ".context/tasks.md":
+            return "# Tasks\n\n## Now\n\n## Blocked\n\n## Waiting\n";
+        case ".context/wiki/index.md":
+            return "# Wiki index\n\nPages by type. Schema: the canon plugin's wiki-schema standard.\n";
+        case ".context/features/index.md":
+            return "# Features\n\n| ID | Title | Status | Release |\n|---|---|---|---|\n";
+        default:
+            return "";
+    }
+}
+export function planInit(repo, answers) {
+    if (existsSync(join(repo, ".claude", "canon.yaml")) && !answers.force) {
+        throw new Error(`${repo} is already set up (.claude/canon.yaml exists) — use --force to redo it`);
+    }
+    const kind = answers.kind ?? inferKind(repo);
+    const modules = answers.modules ?? (answers.kind ? MODULES_BY_KIND[kind] : inferModules(repo, kind));
+    const sdk = kindCovers(kind, "mobile") ? detectExpoSdk(repo) : undefined;
+    const packs = answers.packs?.length ? { packs: answers.packs } : {};
+    const config = { canon: answers.canonVersion, kind, modules, ...(sdk ? { expo: { sdk } } : {}), ...packs };
+    const create = requiredContext(modules).filter((name) => !existsSync(join(repo, ".context", name))).map((name) => FIRST_FILE[name]);
+    if (modules.includes("architecture")) {
+        // A workspace that already has rules of its own (any name dependency-cruiser reads) keeps them.
+        const taken = (file) => file === ARCHITECTURE_BASE ? existsSync(join(repo, file)) : RULES_FILES.some((name) => existsSync(join(repo, dirname(file), name)));
+        create.push(...architectureStarters(repo).map((s) => s.file).filter((file) => !taken(file)));
+    }
+    return { config, create };
+}
+export function applyInit(repo, plan, options) {
+    const write = (file, content) => {
+        mkdirSync(dirname(join(repo, file)), { recursive: true });
+        writeFileSync(join(repo, file), content);
+    };
+    write(".claude/canon.yaml", stringify(plan.config));
+    const starters = new Map(architectureStarters(repo).map((s) => [s.file, s.template]));
+    for (const file of plan.create) {
+        const starter = starters.get(file);
+        write(file, starter ? readFileSync(join(options.canonRoot, ARCHITECTURE_TEMPLATES, starter), "utf8") : template(file));
+    }
+    if (plan.config.modules.includes("knowledge"))
+        indexKnowledge(repo, options.name, options.run);
+}
+/** Adds the repo's wiki and features to qmd. Safe to repeat: qmd refuses a name it already has. */
+export function indexKnowledge(repo, name, run) {
+    for (const kind of ["wiki", "features"]) {
+        run("qmd", ["collection", "add", join(repo, ".context", kind), "--name", `${name}-${kind}`]);
+    }
+}

package/cli/dist/learn.d.ts

@@ -0,0 +1,44 @@
+export interface VerdictEntry {
+    product: string;
+    at: string;
+    verdict: string;
+    principles: string[];
+    request: string;
+    reason: string;
+    /** What happened next. Lines written before every verdict was logged have none, and were all overrides. */
+    outcome?: Outcome;
+}
+export declare const OUTCOMES: readonly ["proceeded", "stopped", "overridden", "dropped"];
+export type Outcome = (typeof OUTCOMES)[number];
+export type Summary = {
+    total: number;
+} & Record<Outcome, number>;
+/** How often the gate let work through, stopped it, or was overridden. */
+export declare function summarise(entries: VerdictEntry[]): Summary;
+export interface Decision {
+    id: string;
+    decision: "approved" | "rejected";
+    /** How many overrides the proposal had when it was decided. */
+    count: number;
+    at: string;
+    note: string;
+}
+export interface Proposal {
+    id: string;
+    summary: string;
+    count: number;
+    products: string[];
+    reasons: string[];
+}
+export declare function readVerdicts(repos: string[]): VerdictEntry[];
+/**
+ * Turns override history into proposals: a principle overridden `threshold`+
+ * times, or one reason given in two or more products. A decided proposal comes
+ * back only when its count has grown past what it was when decided.
+ */
+export declare function proposals(all: VerdictEntry[], options: {
+    threshold: number;
+    decisions: Decision[];
+}): Proposal[];
+export declare function readDecisions(estateRoot: string): Decision[];
+export declare function recordDecision(estateRoot: string, decision: Omit<Decision, "at">): void;

package/cli/dist/learn.js

@@ -0,0 +1,80 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+export const OUTCOMES = ["proceeded", "stopped", "overridden", "dropped"];
+const outcomeOf = (entry) => entry.outcome ?? "overridden";
+/** How often the gate let work through, stopped it, or was overridden. */
+export function summarise(entries) {
+    const counts = Object.fromEntries(OUTCOMES.map((o) => [o, 0]));
+    for (const entry of entries)
+        counts[outcomeOf(entry)] += 1;
+    return { total: entries.length, ...counts };
+}
+const LOG = join(".context", "raw", "canon", "verdicts.jsonl");
+const MAX_REASONS = 5;
+function readJsonLines(path) {
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .flatMap((line) => {
+        try {
+            return line.trim() ? [JSON.parse(line)] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function readVerdicts(repos) {
+    return repos.flatMap((repo) => readJsonLines(join(repo, LOG)).map((entry) => ({ ...entry, product: basename(repo) })));
+}
+function group(entries, keyOf) {
+    const groups = new Map();
+    for (const entry of entries) {
+        for (const key of keyOf(entry))
+            groups.set(key, [...(groups.get(key) ?? []), entry]);
+    }
+    return groups;
+}
+function toProposal(id, summary, entries) {
+    return {
+        id,
+        summary,
+        count: entries.length,
+        products: [...new Set(entries.map((e) => e.product))].sort(),
+        reasons: [...new Set(entries.map((e) => e.reason))].slice(0, MAX_REASONS),
+    };
+}
+/**
+ * Turns override history into proposals: a principle overridden `threshold`+
+ * times, or one reason given in two or more products. A decided proposal comes
+ * back only when its count has grown past what it was when decided.
+ */
+export function proposals(all, options) {
+    // Only an override says a rule may be wrong; a verdict the user followed says nothing about it.
+    const entries = all.filter((entry) => outcomeOf(entry) === "overridden");
+    const found = [];
+    for (const [principle, group_] of group(entries, (e) => e.principles)) {
+        if (group_.length >= options.threshold) {
+            found.push(toProposal(`principle:${principle}`, `${principle} was overridden ${group_.length} times — revisit the rule or its wording`, group_));
+        }
+    }
+    for (const [reason, group_] of group(entries, (e) => [e.reason])) {
+        const products = new Set(group_.map((e) => e.product));
+        if (products.size >= 2) {
+            found.push(toProposal(`reason:${reason}`, `"${reason}" was given in ${products.size} products — a missing exception?`, group_));
+        }
+    }
+    const decidedAt = new Map(options.decisions.map((d) => [d.id, d.count]));
+    return found.filter((p) => !decidedAt.has(p.id) || p.count > (decidedAt.get(p.id) ?? 0));
+}
+// In the estate, not the canon install: a global npm install may be read-only and is replaced on upgrade.
+const DECISIONS_DIR = join(".claude", "canon");
+const DECISIONS = join(DECISIONS_DIR, "decisions.jsonl");
+export function readDecisions(estateRoot) {
+    return readJsonLines(join(estateRoot, DECISIONS));
+}
+export function recordDecision(estateRoot, decision) {
+    mkdirSync(join(estateRoot, DECISIONS_DIR), { recursive: true });
+    appendFileSync(join(estateRoot, DECISIONS), `${JSON.stringify({ ...decision, at: new Date().toISOString() })}\n`);
+}

package/cli/dist/lib/env.d.ts

@@ -0,0 +1,7 @@
+export interface Env {
+    canonRoot: string;
+    /** The estate folder (parent of several products), or null when there is none. */
+    estateRoot: string | null;
+}
+/** For commands that only make sense across products. */
+export declare function requireEstate(env: Env): string;

package/cli/dist/lib/env.js

@@ -0,0 +1,6 @@
+/** For commands that only make sense across products. */
+export function requireEstate(env) {
+    if (env.estateRoot)
+        return env.estateRoot;
+    throw new Error("no estate found — put `estate: true` in .claude/canon.yaml of the folder that holds your products, or set CANON_ESTATE");
+}

package/cli/dist/lib/files.d.ts

@@ -0,0 +1,3 @@
+/** Every file under `dir` whose name matches `test`, as paths relative to `root`. Missing dir → []. */
+export declare function listFiles(root: string, dir: string, test: (name: string) => boolean): string[];
+export declare function isDirectory(path: string): boolean;

package/cli/dist/lib/files.js

@@ -0,0 +1,23 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+/** Every file under `dir` whose name matches `test`, as paths relative to `root`. Missing dir → []. */
+export function listFiles(root, dir, test) {
+    const start = join(root, dir);
+    if (!existsSync(start))
+        return [];
+    const found = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (test(entry.name))
+                found.push(relative(root, full));
+        }
+    };
+    walk(start);
+    return found.sort();
+}
+export function isDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}

package/cli/dist/lib/frontmatter.d.ts

@@ -0,0 +1,6 @@
+export interface ParsedPage {
+    data: Record<string, unknown> | null;
+    body: string;
+}
+/** Splits YAML frontmatter from a Markdown body. Unparseable or absent frontmatter → data null. */
+export declare function parseFrontmatter(text: string): ParsedPage;

package/cli/dist/lib/frontmatter.js

@@ -0,0 +1,16 @@
+import { parse } from "yaml";
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/** Splits YAML frontmatter from a Markdown body. Unparseable or absent frontmatter → data null. */
+export function parseFrontmatter(text) {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return { data: null, body: text };
+    try {
+        const data = parse(match[1]);
+        const isObject = typeof data === "object" && data !== null && !Array.isArray(data);
+        return { data: isObject ? data : null, body: text.slice(match[0].length) };
+    }
+    catch {
+        return { data: null, body: text.slice(match[0].length) };
+    }
+}

package/cli/dist/lib/qmd.d.ts

@@ -0,0 +1,9 @@
+import { type SpawnSyncOptions } from "node:child_process";
+export interface QmdResult {
+    ok: boolean;
+    out: string;
+    err: string;
+}
+export declare function qmd(args: string[], options?: SpawnSyncOptions): QmdResult;
+export declare function qmdQuery(query: string, collections?: string[]): QmdResult;
+export declare function qmdRefresh(): void;

package/cli/dist/lib/qmd.js

@@ -0,0 +1,13 @@
+// qmd subprocess wrapper — the retrieval engine behind search and the site index.
+import { spawnSync } from "node:child_process";
+export function qmd(args, options = {}) {
+    const result = spawnSync("qmd", args, { encoding: "utf8", ...options });
+    return { ok: result.status === 0, out: String(result.stdout ?? ""), err: String(result.stderr ?? "") };
+}
+export function qmdQuery(query, collections = []) {
+    return qmd(["query", query, ...collections.flatMap((collection) => ["-c", collection])]);
+}
+export function qmdRefresh() {
+    qmd(["update"]);
+    qmd(["embed"]);
+}

package/cli/dist/lib/system.d.ts

@@ -0,0 +1,4 @@
+import type { RunResult } from "../packs.ts";
+export declare const CACHE_DIR: string;
+export declare function runCommand(command: string, args: string[]): RunResult;
+export declare function fetchText(url: string): Promise<string>;

package/cli/dist/lib/system.js

@@ -0,0 +1,19 @@
+import { spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const CACHE_DIR = process.env.CANON_CACHE ?? join(homedir(), ".cache", "canon");
+const FETCH_TIMEOUT_MS = 30_000;
+export function runCommand(command, args) {
+    const result = spawnSync(command, args, { encoding: "utf8" });
+    if (result.error) {
+        const missing = result.error.code === "ENOENT";
+        return { status: 1, output: missing ? `${command} is not installed — run \`canon doctor\`` : result.error.message };
+    }
+    return { status: result.status ?? 1, output: `${result.stdout}${result.stderr}` };
+}
+export async function fetchText(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}`);
+    return response.text();
+}

package/cli/dist/packs.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+declare const packSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    kinds: z.ZodArray<z.ZodEnum<{
+        content: "content";
+        mobile: "mobile";
+        "mobile-and-web": "mobile-and-web";
+        package: "package";
+        web: "web";
+    }>>;
+    skill: z.ZodOptional<z.ZodString>;
+    docs: z.ZodArray<z.ZodURL>;
+}, z.core.$strict>;
+export type Pack = z.infer<typeof packSchema>;
+export interface RunResult {
+    status: number;
+    output: string;
+}
+export type CommandRunner = (command: string, args: string[]) => RunResult;
+export declare function listPacks(canonRoot: string): Pack[];
+export declare function findPack(canonRoot: string, name: string): Pack;
+interface AddOptions {
+    canonRoot: string;
+    global?: boolean;
+    estateRoot?: string;
+}
+/** Records a pack in canon.yaml (product, or estate with --global), keeping the file's comments and other keys. */
+export declare function addPack(repo: string, name: string, options: AddOptions): {
+    file: string;
+    added: boolean;
+};
+interface FetchOptions {
+    cacheDir: string;
+    fetchText: (url: string) => Promise<string>;
+    run: CommandRunner;
+}
+/** Downloads a pack's vendor docs into the cache as Markdown and indexes them in QMD as `pack-<name>`. */
+export declare function fetchPackDocs(pack: Pack, options: FetchOptions): Promise<string>;
+export {};

package/cli/dist/packs.js

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse, parseDocument } from "yaml";
+import { z } from "zod";
+import { KINDS } from "./config/schema.js";
+const packSchema = z
+    .object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    description: z.string(),
+    kinds: z.array(z.enum(KINDS)),
+    skill: z.string().optional(),
+    docs: z.array(z.url()),
+})
+    .strict();
+export function listPacks(canonRoot) {
+    const root = join(canonRoot, "packs");
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(root, entry.name, "pack.yaml")))
+        .map((entry) => {
+        const pack = packSchema.parse(parse(readFileSync(join(root, entry.name, "pack.yaml"), "utf8")));
+        if (pack.name !== entry.name)
+            throw new Error(`packs/${entry.name}/pack.yaml is named "${pack.name}"`);
+        return pack;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findPack(canonRoot, name) {
+    const packs = listPacks(canonRoot);
+    const pack = packs.find((candidate) => candidate.name === name);
+    if (!pack)
+        throw new Error(`no pack "${name}" — available: ${packs.map((p) => p.name).join(", ")}`);
+    return pack;
+}
+/** Records a pack in canon.yaml (product, or estate with --global), keeping the file's comments and other keys. */
+export function addPack(repo, name, options) {
+    findPack(options.canonRoot, name);
+    if (options.global && !options.estateRoot)
+        throw new Error("--global needs an estate (a folder whose canon.yaml says estate: true)");
+    const base = options.global ? options.estateRoot : repo;
+    const file = join(base, ".claude", "canon.yaml");
+    if (!existsSync(file) && !options.global)
+        throw new Error(`${repo} has no .claude/canon.yaml — run \`canon init\` first`);
+    const document = parseDocument(existsSync(file) ? readFileSync(file, "utf8") : "");
+    const current = document.get("packs")?.toJSON() ?? [];
+    if (current.includes(name))
+        return { file, added: false };
+    document.set("packs", [...current, name]);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, document.toString());
+    return { file, added: true };
+}
+function docFileName(url) {
+    const { hostname, pathname } = new URL(url);
+    const stem = pathname.split("/").filter(Boolean).pop()?.replace(/\.[a-z]+$/, "") ?? "index";
+    return `${hostname}-${stem}.md`;
+}
+/** Downloads a pack's vendor docs into the cache as Markdown and indexes them in QMD as `pack-<name>`. */
+export async function fetchPackDocs(pack, options) {
+    const dir = join(options.cacheDir, "packs", pack.name);
+    mkdirSync(dir, { recursive: true });
+    for (const url of pack.docs) {
+        let text;
+        try {
+            text = await options.fetchText(url);
+        }
+        catch (error) {
+            throw new Error(`could not download ${url}: ${error.message}`);
+        }
+        writeFileSync(join(dir, docFileName(url)), text);
+    }
+    const collection = `pack-${pack.name}`;
+    const added = options.run("qmd", ["collection", "add", dir, "--name", collection]);
+    if (added.status === 0) {
+        options.run("qmd", ["context", "add", `qmd://${collection}`, `${pack.description.split(" — ")[0]} — vendor docs index (${pack.name} pack)`]);
+    }
+    else if (/already exists/i.test(added.output)) {
+        options.run("qmd", ["update"]);
+    }
+    else {
+        throw new Error(`qmd could not index ${dir}: ${added.output.trim()}`);
+    }
+    return dir;
+}

package/cli/dist/pipeline.d.ts

@@ -0,0 +1,20 @@
+import type { StageSpec } from "./config/schema.ts";
+export interface Approval {
+    stage: string;
+    /** When a person approved the gate. Approvals are never backdated. */
+    at: string;
+    note: string;
+}
+export declare const GATES_LOG: string;
+export declare function readApprovals(repo: string): Approval[];
+export declare function recordApproval(repo: string, stage: string, note: string): Approval;
+export interface StageState {
+    id: string;
+    gate: boolean;
+    /** The first `done` path that exists, or null when the stage has not started. */
+    startedAt: string | null;
+    /** Whether a person approved this gate; null for a stage with no gate. */
+    approved: boolean | null;
+}
+/** The repo's resolved stages, in order, with where each stands. */
+export declare function stagesOf(repo: string, stages: StageSpec[]): StageState[];

package/cli/dist/pipeline.js

@@ -0,0 +1,30 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+// In raw/, which is append-only: the dates are the record of how long each stage waited.
+export const GATES_LOG = join(".context", "raw", "canon", "gates.jsonl");
+export function readApprovals(repo) {
+    const path = join(repo, GATES_LOG);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line));
+}
+export function recordApproval(repo, stage, note) {
+    const approval = { stage, at: new Date().toISOString(), note };
+    const path = join(repo, GATES_LOG);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(approval)}\n`);
+    return approval;
+}
+/** The repo's resolved stages, in order, with where each stands. */
+export function stagesOf(repo, stages) {
+    const approved = new Set(readApprovals(repo).map((approval) => approval.stage));
+    return stages.map((stage) => ({
+        id: stage.id,
+        gate: stage.gate,
+        startedAt: stage.done.find((path) => existsSync(join(repo, path))) ?? null,
+        approved: stage.gate ? approved.has(stage.id) : null,
+    }));
+}

package/cli/dist/standards.d.ts

@@ -0,0 +1,14 @@
+export interface Standard {
+    name: string;
+    path: string;
+    /** "canon" for a built-in default, else the configured folder it came from. */
+    from: string;
+}
+/** canon's default standards, then each configured folder in order; a later file of the same name replaces an earlier one. */
+export declare function resolveStandards(canonRoot: string, folders: string[]): Standard[];
+/**
+ * Principle headings from canon's constitution and every configured one. A
+ * constitution in a folder extends rather than replaces: it adds principles,
+ * and restating an ID rewords it.
+ */
+export declare function constitutionTitles(canonRoot: string, folders: string[]): string[];