@freetesh/canon 0.0.0-stage → 0.16.0

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 "../check.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 "../lib/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 "../check.js";
+import { buildSite, quartzConfig } from "../ui.js";
+import { requireEstate } from "../lib/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;
+    });
+}

package/cli/dist/config/load.d.ts

@@ -0,0 +1,23 @@
+import { type Config, type Kind, type Module } from "./schema.ts";
+export interface ConfigSource {
+    layer: "estate" | "product" | "local";
+    path: string;
+}
+export interface LoadOptions {
+    /** The estate folder; found by walking up from the repo when not given. */
+    estateRoot?: string | null;
+}
+/** The nearest folder at or above `start` whose canon.yaml says `estate: true`, or null. */
+export declare function findEstate(start: string): string | null;
+export declare function inferKind(repo: string): Kind;
+export declare function inferModules(repo: string, kind: Kind): Module[];
+/**
+ * Reads the estate, product and local canon.yaml layers over defaults inferred
+ * from the repo. Scalars: the most specific layer wins. Lists of names add up
+ * (packs, standards); lists of records merge by their key (commands, tools,
+ * wiki types, context folders).
+ */
+export declare function loadConfig(repo: string, options?: LoadOptions): {
+    config: Config;
+    sources: ConfigSource[];
+};

package/cli/dist/config/load.js

@@ -0,0 +1,116 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { MODULES_BY_KIND, layerSchema } from "./schema.js";
+const EXPO_MARKERS = ["app.config.ts", "app.config.js", "app.json"];
+const WEB_MARKERS = ["next.config.ts", "next.config.js", "next.config.mjs", "vite.config.ts"];
+function configPath(folder) {
+    return join(folder, ".claude", "canon.yaml");
+}
+function readLayer(path) {
+    const parsed = layerSchema.safeParse(parse(readFileSync(path, "utf8")) ?? {});
+    if (!parsed.success) {
+        const problems = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        throw new Error(`${path} is invalid:\n  ${problems.join("\n  ")}`);
+    }
+    return parsed.data;
+}
+/** The nearest folder at or above `start` whose canon.yaml says `estate: true`, or null. */
+export function findEstate(start) {
+    let folder = resolve(start);
+    while (true) {
+        const path = configPath(folder);
+        if (existsSync(path) && readLayer(path).estate === true)
+            return folder;
+        const parent = dirname(folder);
+        if (parent === folder)
+            return null;
+        folder = parent;
+    }
+}
+/** The repo root plus each app in a monorepo's apps/ folder. */
+function appRoots(repo) {
+    const apps = join(repo, "apps");
+    if (!existsSync(apps))
+        return [repo];
+    const children = readdirSync(apps, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+    return [repo, ...children.map((entry) => join(apps, entry.name))];
+}
+/** A root package.json that ships a CLI or exports a library. */
+function isPackage(repo) {
+    const file = join(repo, "package.json");
+    if (!existsSync(file))
+        return false;
+    const pkg = JSON.parse(readFileSync(file, "utf8"));
+    return Boolean(pkg.bin || pkg.exports || pkg.main) && !pkg.private;
+}
+export function inferKind(repo) {
+    const roots = appRoots(repo);
+    const anyHas = (markers) => roots.some((root) => markers.some((file) => existsSync(join(root, file))));
+    const mobile = anyHas(EXPO_MARKERS);
+    const web = anyHas(WEB_MARKERS);
+    if (mobile && web)
+        return "mobile-and-web";
+    if (mobile)
+        return "mobile";
+    if (web)
+        return "web";
+    return isPackage(repo) ? "package" : "content";
+}
+export function inferModules(repo, kind) {
+    const modules = MODULES_BY_KIND[kind];
+    const hasDesigns = existsSync(join(repo, ".context", "designs"));
+    return hasDesigns && !modules.includes("design") ? [...modules, "design"] : modules;
+}
+function lastDefined(values) {
+    return values.filter((value) => value !== undefined).pop();
+}
+function mergeBy(lists, key) {
+    const merged = new Map();
+    for (const item of lists.flat())
+        merged.set(key(item), item);
+    return [...merged.values()];
+}
+/**
+ * Reads the estate, product and local canon.yaml layers over defaults inferred
+ * from the repo. Scalars: the most specific layer wins. Lists of names add up
+ * (packs, standards); lists of records merge by their key (commands, tools,
+ * wiki types, context folders).
+ */
+export function loadConfig(repo, options = {}) {
+    const estateRoot = options.estateRoot === undefined ? findEstate(dirname(resolve(repo))) : options.estateRoot;
+    const candidates = [
+        ...(estateRoot && resolve(estateRoot) !== resolve(repo) ? [{ layer: "estate", path: configPath(estateRoot) }] : []),
+        { layer: "product", path: configPath(repo) },
+        { layer: "local", path: join(repo, ".claude", "canon.local.yaml") },
+    ];
+    const sources = candidates.filter((source) => existsSync(source.path));
+    const layers = sources.map((source) => ({ data: readLayer(source.path), base: dirname(dirname(source.path)) }));
+    const pick = (key) => layers.map((layer) => layer.data[key]);
+    const kind = lastDefined(pick("kind")) ?? inferKind(repo);
+    const config = {
+        canon: lastDefined(pick("canon")),
+        kind,
+        modules: lastDefined(pick("modules")) ?? inferModules(repo, kind),
+        expo: Object.assign({}, ...pick("expo")),
+        packs: [...new Set(pick("packs").flatMap((packs) => packs ?? []))].sort(),
+        standards: [...new Set(layers.flatMap((layer) => (layer.data.standards ?? []).map((dir) => resolve(layer.base, dir))))],
+        commands: mergeBy(pick("commands").map((list) => list ?? []), (command) => command.id),
+        doctor: { tools: mergeBy(pick("doctor").map((doctor) => doctor?.tools ?? []), (tool) => tool.tool) },
+        weigh: { weights: Object.assign({}, ...pick("weigh").map((weigh) => weigh?.weights)) },
+        wiki: { types: mergeBy(pick("wiki").map((wiki) => wiki?.types ?? []), (entry) => entry.type) },
+        context: { folders: mergeBy(pick("context").map((context) => context?.folders ?? []), (entry) => entry.folder) },
+        pipeline: lastDefined(pick("pipeline")) ?? [],
+        name: lastDefined(pick("name")),
+        copies: {
+            source: lastDefined(layers.map((layer) => (layer.data.copies?.source ? resolve(layer.base, layer.data.copies.source) : undefined))),
+            sets: Object.assign({}, ...pick("copies").map((copies) => copies?.sets)),
+            use: [...new Set(pick("copies").flatMap((copies) => copies?.use ?? []))],
+        },
+    };
+    if (config.name === undefined)
+        delete config.name;
+    if (Object.keys(config.expo ?? {}).length === 0)
+        delete config.expo;
+    return { config, sources };
+}

package/cli/dist/config/schema.d.ts

@@ -0,0 +1,200 @@
+import { z } from "zod";
+/** What a repo ships: an app to the stores, a site to the web, both, a package to a registry, or no code at all. */
+export declare const KINDS: readonly ["mobile", "web", "mobile-and-web", "package", "content"];
+export declare const MODULES: readonly ["docs", "design", "knowledge", "metrics", "code", "architecture", "listing", "refs"];
+/**
+ * The wiki page types every repo has, and the folder each lives in. A repo adds more under `wiki.types`.
+ * No flow type: a journey worth keeping is a concept. A surface page is a screen's notes, only where it has real ones.
+ */
+export declare const WIKI_FOLDER_BY_TYPE: Record<string, string>;
+/** Wiki folders that no longer exist, and what to do with what was in them. */
+export declare const REMOVED_WIKI_FOLDERS: Record<string, string>;
+/** The `.context/` folders every repo may have. A repo adds more under `context.folders`. */
+export declare const CONTEXT_FOLDERS: string[];
+export type Kind = (typeof KINDS)[number];
+export type Module = (typeof MODULES)[number];
+declare const command: z.ZodObject<{
+    id: z.ZodString;
+    run: z.ZodString;
+    if: z.ZodOptional<z.ZodString>;
+    module: z.ZodOptional<z.ZodEnum<{
+        architecture: "architecture";
+        code: "code";
+        design: "design";
+        docs: "docs";
+        knowledge: "knowledge";
+        listing: "listing";
+        metrics: "metrics";
+        refs: "refs";
+    }>>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        content: "content";
+        mobile: "mobile";
+        "mobile-and-web": "mobile-and-web";
+        package: "package";
+        web: "web";
+    }>>>;
+}, z.core.$strict>;
+declare const wikiType: z.ZodObject<{
+    type: z.ZodString;
+    folder: z.ZodString;
+    reason: z.ZodString;
+    sections: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+declare const contextFolder: z.ZodObject<{
+    folder: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+/** A file copied from the source repo: the same path on both sides, or `from` one path `to` another. */
+declare const copyFile: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodOptional<z.ZodString>;
+    named: z.ZodOptional<z.ZodBoolean>;
+    until: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+declare const stage: z.ZodObject<{
+    id: z.ZodString;
+    done: z.ZodArray<z.ZodString>;
+    gate: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const tool: z.ZodObject<{
+    tool: z.ZodString;
+    why: z.ZodString;
+    hint: z.ZodString;
+}, z.core.$strict>;
+/** One layer of `.claude/canon.yaml` as written: every field optional. */
+export declare const layerSchema: z.ZodObject<{
+    estate: z.ZodOptional<z.ZodBoolean>;
+    canon: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        content: "content";
+        mobile: "mobile";
+        "mobile-and-web": "mobile-and-web";
+        package: "package";
+        web: "web";
+    }>>;
+    modules: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        architecture: "architecture";
+        code: "code";
+        design: "design";
+        docs: "docs";
+        knowledge: "knowledge";
+        listing: "listing";
+        metrics: "metrics";
+        refs: "refs";
+    }>>>;
+    expo: z.ZodOptional<z.ZodObject<{
+        sdk: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    packs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    standards: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        run: z.ZodString;
+        if: z.ZodOptional<z.ZodString>;
+        module: z.ZodOptional<z.ZodEnum<{
+            architecture: "architecture";
+            code: "code";
+            design: "design";
+            docs: "docs";
+            knowledge: "knowledge";
+            listing: "listing";
+            metrics: "metrics";
+            refs: "refs";
+        }>>;
+        kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            content: "content";
+            mobile: "mobile";
+            "mobile-and-web": "mobile-and-web";
+            package: "package";
+            web: "web";
+        }>>>;
+    }, z.core.$strict>>>;
+    doctor: z.ZodOptional<z.ZodObject<{
+        tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            tool: z.ZodString;
+            why: z.ZodString;
+            hint: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strip>>;
+    weigh: z.ZodOptional<z.ZodObject<{
+        weights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>>;
+    wiki: z.ZodOptional<z.ZodObject<{
+        types: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            folder: z.ZodString;
+            reason: z.ZodString;
+            sections: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodObject<{
+        folders: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            folder: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strip>>;
+    pipeline: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        done: z.ZodArray<z.ZodString>;
+        gate: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    name: z.ZodOptional<z.ZodString>;
+    copies: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        sets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodOptional<z.ZodString>;
+            named: z.ZodOptional<z.ZodBoolean>;
+            until: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>>>;
+        use: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Layer = z.infer<typeof layerSchema>;
+export type CommandSpec = z.infer<typeof command>;
+export type ToolSpec = z.infer<typeof tool>;
+export type WikiTypeSpec = z.infer<typeof wikiType>;
+export type ContextFolderSpec = z.infer<typeof contextFolder>;
+export type StageSpec = z.infer<typeof stage>;
+export type CopyFileSpec = z.infer<typeof copyFile>;
+export interface Config {
+    /** The canon version this repo was last synced to. */
+    canon?: string;
+    kind: Kind;
+    modules: Module[];
+    expo?: {
+        sdk?: number;
+    };
+    packs: string[];
+    /** Absolute standards folders, estate first; a later file of the same name wins. */
+    standards: string[];
+    commands: CommandSpec[];
+    doctor: {
+        tools: ToolSpec[];
+    };
+    weigh: {
+        weights: Record<string, number>;
+    };
+    /** Wiki page types added to the built-in six. */
+    wiki: {
+        types: WikiTypeSpec[];
+    };
+    /** `.context/` folders added to the built-in ten. */
+    context: {
+        folders: ContextFolderSpec[];
+    };
+    /** Ordered stages; empty when no layer declares one. */
+    pipeline: StageSpec[];
+    name?: string;
+    /** `source` is absolute, resolved from the layer that set it. `use` adds up across layers. */
+    copies: {
+        source?: string;
+        sets: Record<string, CopyFileSpec[]>;
+        use: string[];
+    };
+}
+export declare const MODULES_BY_KIND: Record<Kind, Module[]>;
+/** A repo that ships both counts as mobile and as web: it gets both kinds' packs. */
+export declare function kindCovers(kind: Kind, wanted: Kind): boolean;
+export {};

package/cli/dist/config/schema.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+/** What a repo ships: an app to the stores, a site to the web, both, a package to a registry, or no code at all. */
+export const KINDS = ["mobile", "web", "mobile-and-web", "package", "content"];
+export const MODULES = ["docs", "design", "knowledge", "metrics", "code", "architecture", "listing", "refs"];
+/**
+ * The wiki page types every repo has, and the folder each lives in. A repo adds more under `wiki.types`.
+ * No flow type: a journey worth keeping is a concept. A surface page is a screen's notes, only where it has real ones.
+ */
+export const WIKI_FOLDER_BY_TYPE = {
+    concept: "concepts",
+    entity: "entities",
+    surface: "surfaces",
+    decision: "decisions",
+    synthesis: "synthesis",
+};
+/** Wiki folders that no longer exist, and what to do with what was in them. */
+export const REMOVED_WIKI_FOLDERS = {
+    flows: "fold a journey worth keeping into a concept page",
+};
+/** The `.context/` folders every repo may have. A repo adds more under `context.folders`. */
+export const CONTEXT_FOLDERS = ["raw", "wiki", "features", "designs", "listing", "marketing", "metrics", "support", "legal", "ops"];
+const principleId = z.string().regex(/^C-\d{2}$/, "principle IDs look like C-07");
+const command = z
+    .object({
+    id: z.string().regex(/^[a-z0-9-]+$/),
+    /** Shell command run from the repo root; a non-zero exit is an error finding. */
+    run: z.string().min(1),
+    /** Only run when this path exists in the repo. */
+    if: z.string().optional(),
+    /** Only run in a repo that uses this module. */
+    module: z.enum(MODULES).optional(),
+    /** Only run in a repo of one of these kinds. */
+    kinds: z.array(z.enum(KINDS)).optional(),
+})
+    .strict();
+const kebab = z.string().regex(/^[a-z0-9-]+$/, "use lowercase-kebab");
+/** An addition to canon's layout says why, so products drifting apart is written down. */
+const reason = z.string().min(1);
+const wikiType = z
+    .object({
+    type: kebab,
+    folder: kebab,
+    reason,
+    /** The `## ` headings every page of this type must have, as the schema lists them for the built-in six. */
+    sections: z.array(z.string().min(1)).min(1, "list the `## ` sections every page of this type must have"),
+})
+    .strict()
+    .refine((entry) => !(entry.type in WIKI_FOLDER_BY_TYPE) && !Object.values(WIKI_FOLDER_BY_TYPE).includes(entry.folder), {
+    message: "a built-in wiki type or its folder cannot be redefined — add a new one",
+});
+const contextFolder = z.object({ folder: kebab, reason }).strict();
+/** A file copied from the source repo: the same path on both sides, or `from` one path `to` another. */
+const copyFile = z.union([
+    z.string().min(1),
+    z
+        .object({
+        from: z.string().min(1),
+        to: z.string().min(1).optional(),
+        /** Identical except that the source product's name reads as this product's. */
+        named: z.boolean().optional(),
+        /** Compared only above the first line containing this text; below it is the product's own. */
+        until: z.string().min(1).optional(),
+    })
+        .strict(),
+]);
+const stage = z
+    .object({
+    id: kebab,
+    /** Paths that exist once the stage has started; any one is enough. */
+    done: z.array(z.string().min(1)).min(1),
+    /** A person must approve this stage (`canon approve <id>`) before any later stage starts. */
+    gate: z.boolean().default(false),
+})
+    .strict();
+const tool = z.object({ tool: z.string(), why: z.string(), hint: z.string() }).strict();
+/** One layer of `.claude/canon.yaml` as written: every field optional. */
+export const layerSchema = z
+    .object({
+    /** Marks the folder holding this file as an estate: the parent of several products. */
+    estate: z.boolean(),
+    canon: z.string(),
+    kind: z.enum(KINDS),
+    modules: z.array(z.enum(MODULES)),
+    expo: z.object({ sdk: z.number().int().positive() }).partial(),
+    packs: z.array(z.string().regex(/^[a-z0-9-]+$/, "pack names are lowercase-kebab")),
+    /** Folders of extra standards, relative to the folder that holds `.claude/`. */
+    standards: z.array(z.string()),
+    commands: z.array(command),
+    doctor: z.object({ tools: z.array(tool) }).partial(),
+    weigh: z.object({ weights: z.record(principleId, z.number().nonnegative()) }).partial(),
+    wiki: z.object({ types: z.array(wikiType) }).partial(),
+    context: z.object({ folders: z.array(contextFolder) }).partial(),
+    /** The stages work goes through, in order. A more specific layer replaces the whole list. */
+    pipeline: z.array(stage),
+    /** How the product is written in prose, for files shared with only the name changed. */
+    name: z.string().min(1),
+    /**
+     * Files copied from one source repo. The estate names sets of them; a product lists the sets it
+     * uses, and only those are held equal to the source.
+     */
+    copies: z.object({ source: z.string().min(1), sets: z.record(kebab, z.array(copyFile).min(1)), use: z.array(kebab) }).partial().strict(),
+})
+    .partial()
+    .strict();
+export const MODULES_BY_KIND = {
+    mobile: ["docs", "knowledge", "code", "listing", "refs"],
+    web: ["docs", "knowledge", "code", "refs"],
+    "mobile-and-web": ["docs", "knowledge", "code", "listing", "refs"],
+    // A package's docs describe other repos' .context/ paths, so refs would flag them.
+    package: ["docs", "knowledge", "code"],
+    content: ["docs", "knowledge", "refs"],
+};
+/** A repo that ships both counts as mobile and as web: it gets both kinds' packs. */
+export function kindCovers(kind, wanted) {
+    return kind === wanted || (kind === "mobile-and-web" && (wanted === "mobile" || wanted === "web"));
+}

package/cli/dist/doctor.d.ts

@@ -0,0 +1,12 @@
+import type { ToolSpec } from "./config/schema.ts";
+/** Runs `<command> --version` and returns its first output line, or null if the command is missing. */
+export type Probe = (command: string) => string | null;
+export interface ToolStatus {
+    tool: string;
+    ok: boolean;
+    version?: string;
+    why: string;
+    hint?: string;
+}
+export declare const systemProbe: Probe;
+export declare function runDoctor(probe?: Probe, extra?: ToolSpec[]): ToolStatus[];

package/cli/dist/doctor.js

@@ -0,0 +1,31 @@
+import { spawnSync } from "node:child_process";
+// What canon itself needs. A repo or estate adds its own under `doctor.tools`.
+const CORE_TOOLS = [
+    { tool: "node", why: "runs the canon CLI and hooks", hint: "install Node 22+", minimum: [22, 0] },
+    { tool: "git", why: "canon works on git repos", hint: "install git" },
+    { tool: "qmd", why: "knowledge search for Claude", hint: "npm i -g @tobilu/qmd (see the canon README)" },
+];
+const VERSION = /(\d+)\.(\d+)(?:\.(\d+))?/;
+export const systemProbe = (command) => {
+    const result = spawnSync(command, ["--version"], { encoding: "utf8" });
+    if (result.error || result.status !== 0)
+        return null;
+    return `${result.stdout}${result.stderr}`.trim().split("\n")[0];
+};
+export function runDoctor(probe = systemProbe, extra = []) {
+    const tools = [...CORE_TOOLS, ...extra];
+    return tools.map(({ tool, why, hint, minimum }) => {
+        const output = probe(tool);
+        if (output === null)
+            return { tool, ok: false, why, hint };
+        const match = VERSION.exec(output);
+        const version = match?.[0];
+        if (minimum && match) {
+            const [major, minor] = [Number(match[1]), Number(match[2])];
+            const tooOld = major < minimum[0] || (major === minimum[0] && minor < minimum[1]);
+            if (tooOld)
+                return { tool, ok: false, version, why, hint };
+        }
+        return { tool, ok: true, version, why };
+    });
+}

package/cli/dist/format.d.ts

@@ -0,0 +1,6 @@
+import type { Report } from "./check.ts";
+/** Compact, rtk-style text: one header per product, one line per finding, one total line. */
+export declare function formatReports(reports: Report[], options?: {
+    quiet?: boolean;
+}): string;
+export declare function exitCode(reports: Report[]): number;

package/cli/dist/format.js

@@ -0,0 +1,35 @@
+const MARK = { error: "✗", warn: "!" };
+function plural(count, word) {
+    return `${count} ${word}${count === 1 ? "" : "s"}`;
+}
+function counts(report) {
+    return {
+        errors: report.findings.filter((f) => f.level === "error").length,
+        warnings: report.findings.filter((f) => f.level === "warn").length,
+    };
+}
+/** Compact, rtk-style text: one header per product, one line per finding, one total line. */
+export function formatReports(reports, options = {}) {
+    const lines = [];
+    let errors = 0;
+    let warnings = 0;
+    for (const report of reports) {
+        const count = counts(report);
+        errors += count.errors;
+        warnings += count.warnings;
+        const clean = report.findings.length === 0;
+        if (clean && options.quiet)
+            continue;
+        const summary = clean ? "ok" : `${plural(count.errors, "error")}, ${plural(count.warnings, "warning")}`;
+        lines.push(`${report.name}  ${summary}`);
+        for (const finding of report.findings) {
+            const message = finding.message.replace(/\n/g, "\n      ");
+            lines.push(`  ${MARK[finding.level]} ${finding.check}  ${finding.file ?? ""}  ${message}`.replace(/  +$/, ""));
+        }
+    }
+    lines.push(`${plural(reports.length, "product")} · ${plural(errors, "error")} · ${plural(warnings, "warning")}`);
+    return lines.join("\n");
+}
+export function exitCode(reports) {
+    return reports.some((report) => report.findings.some((f) => f.level === "error")) ? 1 : 0;
+}

package/cli/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};