@freetesh/canon 0.0.0-stage → 0.15.0

package/cli/dist/checks/wiki-frontmatter.js

@@ -0,0 +1,84 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { listFiles } from "../lib/files.js";
+import { parseFrontmatter } from "../lib/frontmatter.js";
+import { REMOVED_WIKI_FOLDERS, WIKI_FOLDER_BY_TYPE } from "../config/schema.js";
+const REQUIRED_FIELDS = ["last-verified"];
+// Filler an agent would read as fact: a section with nothing to say is deleted, not stubbed.
+const PLACEHOLDER = /\bTBD\b|\bnone yet\b|\bpopulate when\b/i;
+const CODE_BLOCK = /```[\s\S]*?```/g;
+const STALE_AFTER_DAYS = 90;
+const DAY_MS = 86_400_000;
+const NOT_PAGES = ["index.md", "CLAUDE.md"];
+const OLDEST_SHOWN = 3;
+export function wikiPages(repo) {
+    return listFiles(repo, ".context/wiki", (name) => name.endsWith(".md") && !NOT_PAGES.includes(name));
+}
+function asDate(value) {
+    const date = value instanceof Date ? value : new Date(String(value));
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+export const wikiFrontmatter = {
+    id: "wiki-frontmatter",
+    module: "docs",
+    description: "every wiki page has last-verified and no placeholder text; a type, if set, matches its folder; ids are unique; nothing stale",
+    run({ repo, config, today }) {
+        const folderByType = { ...WIKI_FOLDER_BY_TYPE, ...Object.fromEntries(config.wiki.types.map((entry) => [entry.type, entry.folder])) };
+        // Built-in types' sections are linted by the wiki-lint skill; added types carry theirs in config.
+        const sectionsByType = new Map(config.wiki.types.map((entry) => [entry.type, entry.sections]));
+        const findings = [];
+        const add = (level, file, message) => findings.push({ check: "wiki-frontmatter", level, file, message });
+        const filesById = new Map();
+        const stale = [];
+        for (const file of wikiPages(repo)) {
+            const folder = file.split("/")[2];
+            if (folder in REMOVED_WIKI_FOLDERS)
+                continue; // context-size reports the folder once
+            const { data, body } = parseFrontmatter(readFileSync(join(repo, file), "utf8"));
+            if (!data) {
+                add("error", file, "no frontmatter");
+                continue;
+            }
+            const missing = REQUIRED_FIELDS.filter((field) => data[field] === undefined || data[field] === null);
+            if (missing.length > 0)
+                add("error", file, `missing ${missing.join(", ")}`);
+            const expected = folderByType[String(data.type)];
+            if (data.type && expected !== folder)
+                add("error", file, `type ${data.type} does not belong in ${folder}/`);
+            if (!data.type && !Object.values(folderByType).includes(folder))
+                add("error", file, `${folder}/ is not a wiki folder`);
+            const sections = sectionsByType.get(String(data.type));
+            if (sections) {
+                const headings = new Set(body.split("\n").flatMap((line) => (line.startsWith("## ") ? [line.slice(3).trim()] : [])));
+                const absent = sections.filter((section) => !headings.has(section));
+                if (absent.length > 0)
+                    add("error", file, `missing sections: ${absent.join(", ")}`);
+            }
+            const placeholder = body.replace(CODE_BLOCK, "").match(PLACEHOLDER);
+            if (placeholder)
+                add("warn", file, `placeholder "${placeholder[0]}" — write the fact or delete the section`);
+            const verified = asDate(data["last-verified"]);
+            const age = verified ? Math.floor((today.getTime() - verified.getTime()) / DAY_MS) : 0;
+            if (verified && age > STALE_AFTER_DAYS)
+                stale.push({ file, age });
+            if (verified && age < 0)
+                add("error", file, `last-verified ${data["last-verified"]} is in the future`);
+            if (data.id)
+                filesById.set(String(data.id), [...(filesById.get(String(data.id)) ?? []), file]);
+        }
+        // One line per product: hundreds of "page X is stale" lines bury every other finding.
+        if (stale.length > 0) {
+            const oldest = stale
+                .sort((a, b) => b.age - a.age)
+                .slice(0, OLDEST_SHOWN)
+                .map(({ file, age }) => `${file.replace(".context/wiki/", "")} (${age}d)`);
+            const pages = stale.length === 1 ? "1 page" : `${stale.length} pages`;
+            add("warn", ".context/wiki", `${pages} last verified over ${STALE_AFTER_DAYS} days ago — oldest: ${oldest.join(", ")}`);
+        }
+        for (const [id, files] of filesById) {
+            if (files.length > 1)
+                add("error", files[1], `duplicate id ${id} (also ${files[0]})`);
+        }
+        return findings;
+    },
+};

package/cli/dist/commands/add.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Env } from "./env.ts";
+export declare function registerAdd(program: Command, env: Env): void;

package/cli/dist/commands/add.js

@@ -0,0 +1,24 @@
+import { resolve } from "node:path";
+import { CACHE_DIR, fetchText, runCommand } from "../lib/system.js";
+import { addPack, fetchPackDocs, findPack, listPacks } from "../packs.js";
+import { requireEstate } from "./env.js";
+export function registerAdd(program, env) {
+    program
+        .command("add")
+        .description("add a knowledge pack (rules + vendor docs in search), e.g. canon add expo")
+        .argument("[pack]", "pack name; omit to list packs")
+        .option("-g, --global", "add for every product (estate canon.yaml)")
+        .option("--repo <repo>", "product repo", ".")
+        .action(async (name, options) => {
+        if (!name) {
+            for (const pack of listPacks(env.canonRoot))
+                console.log(`${pack.name.padEnd(11)} ${pack.description}`);
+            return;
+        }
+        const estateRoot = options.global ? requireEstate(env) : undefined;
+        const { file, added } = addPack(resolve(options.repo), name, { canonRoot: env.canonRoot, global: options.global, estateRoot });
+        console.log(added ? `added ${name} to ${file}` : `${name} already in ${file}`);
+        const dir = await fetchPackDocs(findPack(env.canonRoot, name), { cacheDir: CACHE_DIR, fetchText, run: runCommand });
+        console.log(`indexed ${dir} as qmd://pack-${name}`);
+    });
+}

package/cli/dist/commands/approve.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerApprove(program: Command): void;

package/cli/dist/commands/approve.js

@@ -0,0 +1,20 @@
+import { resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+import { recordApproval } from "../pipeline.js";
+export function registerApprove(program) {
+    program
+        .command("approve")
+        .description("record that a person reviewed and approved a pipeline gate, dated now (a person runs this, not an agent)")
+        .argument("<stage>", "the gated stage's id in canon.yaml `pipeline:`")
+        .argument("[repo]", "product repo", ".")
+        .option("--note <text>", "what was reviewed", "")
+        .action((stageId, repo, options) => {
+        const root = resolve(repo);
+        const gates = loadConfig(root).config.pipeline.filter((stage) => stage.gate).map((stage) => stage.id);
+        if (!gates.includes(stageId)) {
+            throw new Error(`"${stageId}" is not a gated stage here — gates: ${gates.join(", ") || "none (no pipeline: in canon.yaml)"}`);
+        }
+        const approval = recordApproval(root, stageId, options.note);
+        console.log(`approved ${stageId} at ${approval.at}`);
+    });
+}

package/cli/dist/commands/check.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Env } from "./env.ts";
+export declare function registerCheck(program: Command, env: Env): void;

package/cli/dist/commands/check.js

@@ -0,0 +1,19 @@
+import { resolve } from "node:path";
+import { exitCode, formatReports } from "../format.js";
+import { findProducts, runChecks } from "../run.js";
+import { requireEstate } from "./env.js";
+export function registerCheck(program, env) {
+    program
+        .command("check")
+        .description("check that a product follows the standards (read-only)")
+        .argument("[repo]", "product repo", ".")
+        .option("--all", "check every product in the estate")
+        .option("--json", "print machine-readable JSON")
+        .option("-q, --quiet", "hide products with no findings")
+        .action((repo, options) => {
+        const repos = options.all ? findProducts(requireEstate(env)) : [resolve(repo)];
+        const reports = repos.map((path) => runChecks(path, { canonRoot: env.canonRoot, estateRoot: options.all ? env.estateRoot : undefined }));
+        console.log(options.json ? JSON.stringify(reports, null, 2) : formatReports(reports, { quiet: options.quiet }));
+        process.exitCode = exitCode(reports);
+    });
+}

package/cli/dist/commands/copies.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { Env } from "./env.ts";
+export declare function registerCopies(program: Command, env: Env): void;

package/cli/dist/commands/copies.js

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { compareCopies, syncCopies } from "../checks/shared-files.js";
+import { loadConfig } from "../config/load.js";
+export function registerCopies(program, env) {
+    program
+        .command("copies")
+        .description("compare a product's shared files with copies.source; --sync overwrites the drifted ones")
+        .argument("[repo]", "product repo", ".")
+        .option("--sync", "overwrite drifted copies from the source (never adds a missing file)")
+        .action((repo, options) => {
+        const path = resolve(repo);
+        const { config } = loadConfig(path, { estateRoot: env.estateRoot });
+        if (options.sync) {
+            const written = syncCopies(path, config);
+            console.log(written.length ? written.map((file) => `  synced: ${file}`).join("\n") : "  nothing to sync");
+            return;
+        }
+        const off = compareCopies(path, config).filter((entry) => entry.state !== "same");
+        console.log(off.length ? off.map(({ pair, state }) => `  ${state}: ${pair.to}`).join("\n") : "  ok");
+        if (off.length)
+            process.exitCode = 1;
+    });
+}

package/cli/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerDoctor(program: Command): void;

package/cli/dist/commands/doctor.js

@@ -0,0 +1,16 @@
+import { loadConfig } from "../config/load.js";
+import { runDoctor, systemProbe } from "../doctor.js";
+export function registerDoctor(program) {
+    program
+        .command("doctor")
+        .description("check that canon's tools, and any this repo declares, are installed")
+        .action(() => {
+        const results = runDoctor(systemProbe, loadConfig(process.cwd()).config.doctor.tools);
+        for (const result of results) {
+            const mark = result.ok ? "✓" : "✗";
+            const detail = result.ok ? (result.version ?? "") : `${result.version ?? "missing"} — ${result.hint}`;
+            console.log(`${mark} ${result.tool.padEnd(8)} ${detail}  (${result.why})`);
+        }
+        process.exitCode = results.every((result) => result.ok) ? 0 : 1;
+    });
+}

package/cli/dist/commands/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/commands/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/commands/hooks.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import { type Env } from "./env.ts";
+export declare const HOOK = "#!/bin/sh\n# installed by `canon hooks install` \u2014 run it again rather than editing this file.\n# A machine without canon pushes unchecked, as it would without any hook.\ncommand -v canon >/dev/null 2>&1 || exit 0\n# The product is the folder that owns .git, not the folder being pushed from: a worktree shares these hooks.\nroot=$(cd \"$(git rev-parse --git-common-dir)/..\" && pwd) || exit 0\nexec canon check \"$root\"\n";
+/** Writes the pre-push hook into one repo. Returns a one-line outcome. */
+export declare function installHook(repo: string): string;
+export declare function registerHooks(program: Command, env: Env): void;

package/cli/dist/commands/hooks.js

@@ -0,0 +1,55 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, lstatSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { findProducts } from "../run.js";
+import { requireEstate } from "./env.js";
+const MARK = "installed by `canon hooks install`";
+// Hooks written by the tools this command replaced (the estate script, then zeno); they are ours to overwrite.
+const OLD_MARKS = [MARK, "installed by ~/git/bin/install-hooks", "installed by `zeno hooks install`"];
+export const HOOK = `#!/bin/sh
+# ${MARK} — run it again rather than editing this file.
+# A machine without canon pushes unchecked, as it would without any hook.
+command -v canon >/dev/null 2>&1 || exit 0
+# The product is the folder that owns .git, not the folder being pushed from: a worktree shares these hooks.
+root=$(cd "$(git rev-parse --git-common-dir)/.." && pwd) || exit 0
+exec canon check "$root"
+`;
+const ours = (path) => OLD_MARKS.some((mark) => readFileSync(path, "utf8").includes(mark));
+/** Writes the pre-push hook into one repo. Returns a one-line outcome. */
+export function installHook(repo) {
+    if (!existsSync(join(repo, ".git")))
+        return `skipped: ${repo} is not a git repo`;
+    if (!existsSync(join(repo, ".context", "tasks.md"))) {
+        const old = join(repo, ".git", "hooks", "pre-push");
+        if (existsSync(old) && ours(old)) {
+            renameSync(old, `${old}.disabled`);
+            return `disabled: ${repo} has no .context/tasks.md, so it would never pass`;
+        }
+        return `skipped: ${repo} has no .context/tasks.md`;
+    }
+    const hooksPath = spawnSync("git", ["-C", repo, "config", "core.hooksPath"], { encoding: "utf8" }).stdout.trim();
+    // husky points core.hooksPath at .husky/_, whose stubs run .husky/<name>.
+    const target = hooksPath === "" ? join(repo, ".git", "hooks", "pre-push") : hooksPath === ".husky/_" ? join(repo, ".husky", "pre-push") : null;
+    if (!target)
+        return `SKIPPED: ${repo} sets core.hooksPath=${hooksPath} — add the hook there by hand`;
+    if (existsSync(target) && (lstatSync(target).isSymbolicLink() || !ours(target)))
+        return `SKIPPED: ${target} exists and is not canon's`;
+    writeFileSync(target, HOOK);
+    chmodSync(target, 0o755);
+    return target.includes("/.husky/") ? `installed: ${target} — a tracked file, commit it` : `installed: ${target}`;
+}
+export function registerHooks(program, env) {
+    program
+        .command("hooks")
+        .description("install a pre-push hook that runs `canon check`")
+        .argument("<action>", "install")
+        .argument("[repo]", "product repo", ".")
+        .option("--all", "every product in the estate")
+        .action((action, repo, options) => {
+        if (action !== "install")
+            throw new Error(`unknown action ${action} — use: canon hooks install`);
+        const repos = options.all ? findProducts(requireEstate(env)) : [resolve(repo)];
+        for (const path of repos)
+            console.log(`  ${installHook(path)}`);
+    });
+}

package/cli/dist/commands/init.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from "commander";
+import type { Env } from "./env.ts";
+export declare function registerInit(program: Command, env: Env): void;

package/cli/dist/commands/init.js

@@ -0,0 +1,78 @@
+import { basename, resolve } from "node:path";
+import * as prompts from "@clack/prompts";
+import { Option } from "commander";
+import { KINDS, MODULES } from "../config/schema.js";
+import { RULES_FILES } from "../checks/architecture.js";
+import { applyInit, parseChoices, planInit } from "../init.js";
+import { listPacks } from "../packs.js";
+import { runCommand } from "../lib/system.js";
+import { canonVersion } from "../status.js";
+function cancelled(value) {
+    if (!prompts.isCancel(value))
+        return false;
+    prompts.cancel("Nothing written.");
+    return true;
+}
+async function askAnswers(inferred, packs) {
+    const kind = await prompts.select({
+        message: "What kind of product is this?",
+        initialValue: inferred.config.kind,
+        options: KINDS.map((value) => ({ value, label: value })),
+    });
+    if (cancelled(kind))
+        return null;
+    const modules = await prompts.multiselect({
+        message: "Which modules? All optional. (docs = wiki, design = HTML designs, knowledge = search, metrics = definitions.yml, code = LSP, architecture, listing)",
+        initialValues: inferred.config.modules,
+        options: MODULES.map((value) => ({ value, label: value })),
+        required: false,
+    });
+    if (cancelled(modules))
+        return null;
+    const forKind = packs.filter((pack) => pack.kinds.includes(kind));
+    if (forKind.length === 0)
+        return { kind, modules, packs: [] };
+    const chosen = await prompts.multiselect({
+        message: "Which vendor doc packs? (indexed for search on `canon sync`)",
+        initialValues: inferred.config.packs ?? [],
+        options: forKind.map((pack) => ({ value: pack.name, label: pack.name, hint: pack.description })),
+        required: false,
+    });
+    if (cancelled(chosen))
+        return null;
+    return { kind, modules, packs: chosen };
+}
+export function registerInit(program, env) {
+    program
+        .command("init")
+        .description("set canon up for a product: write .claude/canon.yaml and the missing .context files")
+        .argument("[repo]", "product repo", ".")
+        .option("-y, --yes", "accept what canon infers (and any flags below), no questions")
+        .addOption(new Option("--kind <kind>", "product kind").choices(KINDS))
+        .option("--modules <list>", `comma list, empty for none: ${MODULES.join(", ")}`)
+        .option("--packs <list>", "comma list of vendor doc packs (see `canon add`)")
+        .option("--force", "redo a repo that already has canon.yaml")
+        .action(async (repo, options) => {
+        const path = resolve(repo);
+        const packs = listPacks(env.canonRoot);
+        const flags = {
+            canonVersion: canonVersion(env.canonRoot),
+            force: options.force,
+            kind: options.kind,
+            modules: options.modules === undefined ? undefined : parseChoices(options.modules, MODULES, "module"),
+            packs: options.packs === undefined ? undefined : parseChoices(options.packs, packs.map((p) => p.name), "pack"),
+        };
+        const inferred = planInit(path, flags);
+        const answers = options.yes ? null : await askAnswers(inferred, packs);
+        if (!options.yes && answers === null)
+            return;
+        const plan = answers ? planInit(path, { ...flags, ...answers }) : inferred;
+        applyInit(path, plan, { name: basename(path), canonRoot: env.canonRoot, run: (command, args) => void runCommand(command, args) });
+        console.log(`wrote .claude/canon.yaml (${plan.config.kind}: ${plan.config.modules.join(", ")})`);
+        for (const file of plan.create)
+            console.log(`created ${file}`);
+        if (plan.create.some((file) => file.endsWith(RULES_FILES[0])))
+            console.log("architecture: add the checker with `pnpm add -D dependency-cruiser`, then edit the .dependency-cruiser.cjs files to this repo's layers");
+        console.log(plan.config.packs ? "next: canon sync (fetches the packs), then canon check" : "next: canon check");
+    });
+}

package/cli/dist/commands/learn.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Env } from "./env.ts";
+export declare function registerLearn(program: Command, env: Env): void;

package/cli/dist/commands/learn.js

@@ -0,0 +1,36 @@
+import { proposals, readDecisions, readVerdicts, recordDecision, summarise } from "../learn.js";
+import { findProducts } from "../run.js";
+import { requireEstate } from "./env.js";
+const DEFAULT_THRESHOLD = 3;
+export function registerLearn(program, env) {
+    program
+        .command("learn")
+        .description("show how often the gate stops work, and turn overrides across products into proposals to change the rules")
+        .option("--threshold <n>", "overrides of one principle before it is proposed", String(DEFAULT_THRESHOLD))
+        .option("--approve <id>", "mark a proposal approved (then edit the standard)")
+        .option("--reject <id>", "mark a proposal rejected; it returns only with new evidence")
+        .option("--note <text>", "why, for --approve / --reject", "")
+        .action((options) => {
+        const estateRoot = requireEstate(env);
+        const entries = readVerdicts(findProducts(estateRoot));
+        const found = proposals(entries, { threshold: Number(options.threshold), decisions: readDecisions(estateRoot) });
+        const target = options.approve ?? options.reject;
+        if (target) {
+            const proposal = found.find((p) => p.id === target);
+            if (!proposal)
+                throw new Error(`no open proposal "${target}" — run \`canon learn\` to list them`);
+            recordDecision(estateRoot, { id: target, decision: options.approve ? "approved" : "rejected", count: proposal.count, note: options.note });
+            console.log(`${options.approve ? "approved" : "rejected"} ${target}`);
+            return;
+        }
+        const s = summarise(entries);
+        console.log(`${s.total} verdict(s) logged: ${s.proceeded} went ahead, ${s.stopped} stopped, ${s.overridden} overridden, ${s.dropped} dropped`);
+        if (found.length === 0)
+            console.log("no proposals");
+        for (const proposal of found) {
+            console.log(`\n${proposal.id}\n  ${proposal.summary}\n  products: ${proposal.products.join(", ")}`);
+            for (const reason of proposal.reasons)
+                console.log(`  - "${reason}"`);
+        }
+    });
+}

package/cli/dist/commands/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { Env } from "./env.ts";
+export declare function registerPipeline(program: Command, env: Env): void;

package/cli/dist/commands/pipeline.js

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+import { stagesOf } from "../pipeline.js";
+export function registerPipeline(program, env) {
+    program
+        .command("pipeline")
+        .description("the repo's stages in order — the estate's list unless the product declares its own — and where each stands")
+        .argument("[repo]", "product repo", ".")
+        .option("--json", "print JSON, for scripts")
+        .action((repo, options) => {
+        const root = resolve(repo);
+        const stages = stagesOf(root, loadConfig(root, { estateRoot: env.estateRoot }).config.pipeline);
+        if (options.json) {
+            console.log(JSON.stringify(stages, null, 2));
+            return;
+        }
+        if (stages.length === 0) {
+            console.log("no pipeline: in canon.yaml");
+            return;
+        }
+        for (const s of stages) {
+            const gate = s.gate ? (s.approved ? "  gate approved" : "  gate open") : "";
+            console.log(`${s.startedAt ? "●" : "○"} ${s.id.padEnd(14)}${s.startedAt ? ` started (${s.startedAt})` : " not started"}${gate}`);
+        }
+    });
+}

package/cli/dist/commands/standards.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { Env } from "./env.ts";
+export declare function registerStandards(program: Command, env: Env): void;

package/cli/dist/commands/standards.js

@@ -0,0 +1,26 @@
+import { resolve } from "node:path";
+import { loadConfig } from "../config/load.js";
+import { constitutionTitles, resolveStandards } from "../standards.js";
+export function registerStandards(program, env) {
+    program
+        .command("standards")
+        .description("list the standards that apply to a repo: canon's defaults, then the estate's and the repo's")
+        .argument("[repo]", "product repo", ".")
+        .option("--json", "print machine-readable JSON")
+        .option("--constitution", "print only the principle titles, canon's then any added ones")
+        .action((repo, options) => {
+        const { config } = loadConfig(resolve(repo));
+        if (options.constitution) {
+            const titles = constitutionTitles(env.canonRoot, config.standards);
+            console.log(options.json ? JSON.stringify(titles) : titles.map((title) => `- ${title}`).join("\n"));
+            return;
+        }
+        const standards = resolveStandards(env.canonRoot, config.standards);
+        if (options.json) {
+            console.log(JSON.stringify(standards, null, 2));
+            return;
+        }
+        for (const standard of standards)
+            console.log(`${standard.name.padEnd(18)} ${standard.path}`);
+    });
+}

package/cli/dist/commands/status.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { Env } from "./env.ts";
+export declare function registerStatus(program: Command, env: Env): void;

package/cli/dist/commands/status.js

@@ -0,0 +1,11 @@
+import { resolve } from "node:path";
+import { buildStatus } from "../status.js";
+export function registerStatus(program, env) {
+    program
+        .command("status")
+        .description("one screen: canon version, config, check summary")
+        .argument("[repo]", "product repo", ".")
+        .action((repo) => {
+        console.log(buildStatus(resolve(repo), { canonRoot: env.canonRoot }));
+    });
+}

package/cli/dist/commands/sync.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { Env } from "./env.ts";
+export declare function registerSync(program: Command, env: Env): void;

package/cli/dist/commands/sync.js

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { exitCode, formatReports } from "../format.js";
+import { CACHE_DIR, fetchText, runCommand } from "../lib/system.js";
+import { runChecks } from "../run.js";
+import { syncRepo } from "../sync.js";
+export function registerSync(program, env) {
+    program
+        .command("sync")
+        .description("refresh pack docs and the search index, move the pinned canon version, then check")
+        .argument("[repo]", "product repo", ".")
+        .action(async (repo) => {
+        const path = resolve(repo);
+        const result = await syncRepo(path, { canonRoot: env.canonRoot, estateRoot: env.estateRoot ?? undefined, cacheDir: CACHE_DIR, fetchText, run: runCommand });
+        console.log(`packs refreshed: ${result.packs.join(", ") || "none"}`);
+        if (result.base)
+            console.log("architecture base updated from canon's template");
+        if (result.version)
+            console.log(`canon ${result.version.from ?? "unpinned"} → ${result.version.to}`);
+        const report = runChecks(path, { canonRoot: env.canonRoot });
+        console.log(formatReports([report]));
+        process.exitCode = exitCode([report]);
+    });
+}

package/cli/dist/commands/ui.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Env } from "./env.ts";
+export declare function registerUi(program: Command, env: Env): void;

package/cli/dist/commands/ui.js

@@ -0,0 +1,64 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { architectureGraph } from "../checks/architecture.js";
+import { formatReports } from "../format.js";
+import { CACHE_DIR } from "../lib/system.js";
+import { findProducts, runChecks } from "../run.js";
+import { buildSite, quartzConfig } from "../ui.js";
+import { requireEstate } from "./env.js";
+// Quartz v5 has no tagged release yet, so pin the exact commit: an unpinned
+// clone could change the site under us on the next fresh install.
+const QUARTZ_REPO = "https://github.com/jackyzha0/quartz";
+const QUARTZ_COMMIT = "97a2d05f80c4c50534959b1d0d41cc4b3895625e";
+const QUARTZ_DIR = join(CACHE_DIR, "quartz");
+function must(command, args, cwd) {
+    const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+    if (result.status !== 0)
+        throw new Error(`${command} ${args.join(" ")} failed`);
+}
+function ensureQuartz() {
+    if (!existsSync(join(QUARTZ_DIR, "node_modules"))) {
+        if (!existsSync(QUARTZ_DIR))
+            must("git", ["clone", "--quiet", "--filter=blob:none", QUARTZ_REPO, QUARTZ_DIR]);
+        must("git", ["checkout", "--quiet", QUARTZ_COMMIT], QUARTZ_DIR);
+        must("npm", ["ci", "--silent"], QUARTZ_DIR);
+    }
+    const defaults = readFileSync(join(QUARTZ_DIR, "quartz.config.default.yaml"), "utf8");
+    writeFileSync(join(QUARTZ_DIR, "quartz.config.yaml"), quartzConfig(defaults));
+}
+export function registerUi(program, env) {
+    program
+        .command("ui")
+        .description("serve every product wiki (search, backlinks, graph) and the design galleries on localhost")
+        // Uncommon defaults: 8080 and 3001 are usually taken by Docker or a dev server.
+        .option("--port <port>", "wiki site port", "4610")
+        .option("--designs-port <port>", "design gallery port", "4611")
+        .option("--ws-port <port>", "live-reload socket port", "4612")
+        .action((options) => {
+        ensureQuartz();
+        const products = findProducts(requireEstate(env));
+        const siteDir = join(CACHE_DIR, "site");
+        const designsDir = join(CACHE_DIR, "designs");
+        const designsUrl = `http://127.0.0.1:${options.designsPort}`;
+        const report = formatReports(products.map((repo) => runChecks(repo, { canonRoot: env.canonRoot, estateRoot: env.estateRoot })));
+        buildSite(products, { siteDir, designsDir, designsUrl, report, graph: architectureGraph });
+        const designs = spawn("python3", ["-m", "http.server", options.designsPort, "--bind", "127.0.0.1", "--directory", designsDir], {
+            stdio: "ignore",
+        });
+        const site = spawn("npx", ["quartz", "build", "-d", siteDir, "-o", join(CACHE_DIR, "public"), "--serve", "--port", options.port, "--wsPort", options.wsPort], {
+            cwd: QUARTZ_DIR,
+            stdio: "inherit",
+        });
+        console.log(`wiki    http://localhost:${options.port}\ndesigns ${designsUrl}`);
+        const stop = () => {
+            designs.kill();
+            site.kill();
+        };
+        process.on("SIGINT", stop);
+        site.on("exit", (code) => {
+            designs.kill();
+            process.exitCode = code ?? 0;
+        });
+    });
+}

package/cli/dist/commands/weigh.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerWeigh(program: Command): void;

package/cli/dist/commands/weigh.js

@@ -0,0 +1,16 @@
+import { spawnSync } from "node:child_process";
+export function registerWeigh(program) {
+    program
+        .command("weigh")
+        .description("run the decision gate on a request without doing it (calls Claude)")
+        .argument("<request...>", "what you want to do")
+        .action((words) => {
+        const request = words.join(" ");
+        const result = spawnSync("claude", ["-p", `/canon:weigh ${request}\n\nWeigh only. Do not start the work.`], {
+            stdio: "inherit",
+        });
+        if (result.error)
+            throw new Error(`could not run claude: ${result.error.message}`);
+        process.exitCode = result.status ?? 1;
+    });
+}