@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/handlers/dev.js

@@ -0,0 +1,113 @@
+import { resolve } from "node:path";
+import { formatError, formatSuccess, formatWarning } from "../format.js";
+export async function runDevGenerate(ctx) {
+    for (const plugin of ctx.plugins) {
+        await plugin.generate({ verbose: ctx.args.verbose });
+        console.error(formatSuccess(`${plugin.name}: generate complete`));
+        await plugin.validate({ verbose: ctx.args.verbose });
+        console.error(formatSuccess(`${plugin.name}: validate complete`));
+        await plugin.coverage({ verbose: ctx.args.verbose });
+        console.error(formatSuccess(`${plugin.name}: coverage complete`));
+    }
+    return 0;
+}
+export async function runDevPublish(ctx) {
+    for (const plugin of ctx.plugins) {
+        await plugin.package({ verbose: ctx.args.verbose, force: ctx.args.force });
+        console.error(formatSuccess(`${plugin.name}: publish complete`));
+    }
+    return 0;
+}
+export async function runDevOnboard(ctx) {
+    const name = ctx.args.extraPositional;
+    if (!name) {
+        console.error(formatError({
+            message: "Missing lexicon name",
+            hint: "Usage: chant dev onboard <name>",
+        }));
+        return 1;
+    }
+    const { onboardCommand, printOnboardResult } = await import("../commands/onboard.js");
+    // chant#2578 — so a lexicon the project declares by path is recognised.
+    // chant#2591 — read without running chant.config.ts.
+    const { recordProjectLexicons, unknownPathLexiconsNotice } = await import("../plugins.js");
+    const notice = unknownPathLexiconsNotice(recordProjectLexicons(process.cwd()));
+    if (notice !== undefined)
+        console.error(formatWarning({ message: notice }));
+    const result = onboardCommand({ name, verbose: ctx.args.verbose });
+    await printOnboardResult(result, name);
+    return result.success ? 0 : 1;
+}
+export async function runDevCheckLexicon(ctx) {
+    const dir = ctx.args.extraPositional ?? ".";
+    const { checkLexicon, printCheckResult } = await import("../commands/check-lexicon.js");
+    const result = await checkLexicon(resolve(dir));
+    printCheckResult(result, ctx.args.format === "json");
+    return result.tier1Pass ? 0 : 1;
+}
+export async function runDevSurfaceDiff(ctx) {
+    const dir = ctx.args.extraPositional ?? ".";
+    const { runSurfaceDiff, printSurfaceDiffResult } = await import("../commands/lexicon-surface-diff.js");
+    const result = await runSurfaceDiff({
+        lexiconDir: resolve(dir),
+        force: ctx.args.force,
+        verbose: ctx.args.verbose,
+        runExamples: ctx.args.runExamples,
+        pinnedDigestPath: ctx.args.pinnedDigest,
+        // --check never writes; it verifies the committed baseline is in sync.
+        updateSnapshot: ctx.args.check ? false : ctx.args.updateSnapshot,
+        bump: ctx.args.bump,
+    });
+    printSurfaceDiffResult(result, ctx.args.format === "json");
+    // --check: fail if regen failed OR the fresh surface drifted from the
+    // committed baseline (stale/hand-edited baseline, or pin bumped without
+    // updating it). Meaningful for pinned lexicons — a fresh regen at the pinned
+    // version must equal the baseline. #545.
+    if (ctx.args.check) {
+        if (!result.ok)
+            return 1;
+        if (result.changed) {
+            console.error(`Baseline out of sync: ${dir}/surface.snapshot.json differs from a fresh regen. ` +
+                `Re-baseline with: chant dev surface-diff ${dir} --update-snapshot --bump`);
+            return 1;
+        }
+        return 0;
+    }
+    return result.ok ? 0 : 1;
+}
+export async function runDevPinnedUpgrade(ctx) {
+    const dir = ctx.args.extraPositional ?? ".";
+    const { runPinnedUpgrades, printPinnedUpgradeResults } = await import("../commands/pinned-upgrade.js");
+    // The optional second positional is a pin label, for a lexicon that declares several pins.
+    const results = await runPinnedUpgrades({
+        lexiconDir: resolve(dir),
+        pin: ctx.args.extraPositional2,
+        force: ctx.args.force,
+        verbose: ctx.args.verbose,
+    });
+    printPinnedUpgradeResults(results, ctx.args.format === "json");
+    // Exit non-zero when an upstream query failed or a regen validation broke.
+    if (results.some((r) => r.fetchError))
+        return 1;
+    if (results.some((r) => r.validation && !r.validation.ok))
+        return 1;
+    return 0;
+}
+export async function runDevRollingUpgrade(ctx) {
+    const dir = ctx.args.extraPositional ?? ".";
+    const { runRollingUpgrade, printRollingUpgradeResult } = await import("../commands/lexicon-rolling-upgrade.js");
+    const result = await runRollingUpgrade({
+        lexiconDir: resolve(dir),
+        force: ctx.args.force,
+        verbose: ctx.args.verbose,
+    });
+    printRollingUpgradeResult(result, ctx.args.format === "json");
+    return result.validationOk ? 0 : 1;
+}
+export async function runDevUnknown(ctx) {
+    console.error(formatError({
+        message: `Unknown dev subcommand: ${ctx.args.path}`,
+        hint: "Available: chant dev generate, chant dev publish, chant dev onboard, chant dev check-lexicon, chant dev surface-diff, chant dev pinned-upgrade, chant dev rolling-upgrade",
+    }));
+    return 1;
+}

package/dist/cli/handlers/emulator.js

@@ -0,0 +1,233 @@
+import { exec, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { emulatorLifecycle, emulatorsOf } from "../../op/index.js";
+import { formatError, formatWarning, formatSuccess } from "../format.js";
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+const ACTIONS = new Set(["up", "down", "status"]);
+/** Whether a container of this name is running, or why docker could not say. */
+async function containerState(name) {
+    try {
+        const { stdout } = await execAsync(`docker ps -q -f name=${name}`);
+        return { running: Boolean(stdout.trim()) };
+    }
+    catch (err) {
+        // The shell exits 127 when the command is not on PATH. Reporting that as
+        // "down" told a user with running containers that nothing was running.
+        const e = err;
+        if (e.code === 127 || e.code === "ENOENT")
+            return { error: "docker not found on PATH; cannot check the emulator" };
+        const why = (e.stderr || e.message || "").trim().split("\n")[0];
+        return { error: `docker could not list containers${why ? ` (${why})` : ""}; cannot check the emulator` };
+    }
+}
+/** The host port Docker publishes `containerPort` on, or undefined when it cannot tell. */
+async function publishedPort(name, containerPort) {
+    try {
+        const { stdout } = await execFileAsync("docker", ["port", name, `${containerPort}/tcp`]);
+        const match = /:(\d+)\s*$/m.exec(stdout.trim().split("\n")[0] ?? "");
+        return match ? Number(match[1]) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether `endpoint` reaches this container's server (#3673): the identity
+ * read inside the container against the one read through the endpoint.
+ * Returns the problem, or undefined when they agree or the check cannot run.
+ */
+export async function endpointConflict(lexicon, cap, endpoint, port) {
+    const identity = cap.spec.identity;
+    if (!identity)
+        return undefined;
+    let inside;
+    try {
+        inside = (await execFileAsync("docker", ["exec", cap.spec.name, ...identity.command])).stdout.trim();
+    }
+    catch {
+        return undefined; // the container cannot answer for itself; nothing to compare
+    }
+    const hint = `Run \`chant emulator down --lexicon ${lexicon}\`, then \`chant emulator up --lexicon ${lexicon} --port ${cap.spec.containerPort}=<free port>\`.`;
+    let answered;
+    try {
+        answered = await identity.probe(endpoint);
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message : String(err);
+        return `localhost:${port} does not answer as the emulator (${why}); another ${identity.server} may hold 127.0.0.1:${port}. ${hint}`;
+    }
+    if (answered.id.trim() === inside)
+        return undefined;
+    return `localhost:${port} answers as ${answered.label}, not the emulator; another ${identity.server} holds 127.0.0.1:${port}. ${hint}`;
+}
+/**
+ * `--port` values as container port to host port (#3673). A bare number
+ * applies when exactly one emulator is selected.
+ */
+export function parsePortMappings(values, targets) {
+    const ports = new Map();
+    for (const value of values) {
+        const pair = /^(\d+)=(\d+)$/.exec(value);
+        const bare = /^(\d+)$/.exec(value);
+        if (pair) {
+            const containerPort = Number(pair[1]);
+            if (!targets.some((t) => t.spec.containerPort === containerPort)) {
+                const known = targets.map((t) => `${t.spec.containerPort} (${t.spec.name})`).join(", ");
+                throw new Error(`--port ${value}: no selected emulator listens on ${containerPort}; the selected ones use ${known || "none"}`);
+            }
+            ports.set(containerPort, Number(pair[2]));
+        }
+        else if (bare) {
+            if (targets.length !== 1) {
+                throw new Error(`--port ${value} is ambiguous with ${targets.length} emulators selected; use --port <container-port>=<host-port>`);
+            }
+            ports.set(targets[0].spec.containerPort, Number(bare[1]));
+        }
+        else {
+            throw new Error(`--port ${value}: expected <container-port>=<host-port>, e.g. --port 5432=15432`);
+        }
+    }
+    return ports;
+}
+/**
+ * `chant emulator --help` (#3673): the subcommands and flags, and for each
+ * configured lexicon's emulator the port, endpoint and sign-in a client uses.
+ */
+export function formatEmulatorHelp(plugins) {
+    const lines = [
+        "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]",
+        "",
+        "Boot, stop or inspect the local emulators of the project's configured lexicons.",
+        "",
+        "Subcommands:",
+        "  up       Boot each emulator, or reuse a running one, and wait until it is ready.",
+        "           Refuses when another process already holds the host port on 127.0.0.1.",
+        "  down     Stop and remove the containers.",
+        "  status   Report whether each emulator runs, and check that its endpoint reaches it.",
+        "           Exits 1 when docker cannot be asked or an endpoint reaches another server.",
+        "",
+        "Flags:",
+        "  --lexicon <name>     Act on one lexicon's emulators only.",
+        "  --port <c>=<h>       up: publish container port <c> on host port <h>; repeatable.",
+        "                       A bare <h> works when one emulator is selected.",
+        "  --json               Print the machine-readable report on stdout.",
+        "",
+    ];
+    const caps = plugins.flatMap((p) => emulatorsOf(p.emulator).map((cap) => ({ lexicon: p.name, cap })));
+    if (caps.length === 0) {
+        lines.push("No lexicon configured for this project has a local emulator.");
+        return lines.join("\n");
+    }
+    lines.push("Emulators in this project (default ports):");
+    for (const { lexicon, cap } of caps) {
+        const endpoint = emulatorLifecycle(cap.spec).endpoint(cap.spec.containerPort);
+        lines.push(`  ${lexicon}: ${cap.spec.name}, port ${cap.spec.containerPort}, ${endpoint}`);
+        if (cap.spec.credentials)
+            lines.push(`      sign in: ${cap.spec.credentials}`);
+        const env = Object.entries(cap.env(endpoint)).map(([k, v]) => `${k}=${v}`);
+        if (env.length)
+            lines.push(`      env: ${env.join(" ")}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * chant emulator up|down|status [--lexicon <name>] [--json]  (#920)
+ *
+ * Boot / stop / inspect the local emulators of the project's configured lexicons
+ * (Floci for aws, floci-az/gcp, mudflaps/spritzer for fly). `up` leaves them
+ * running (persistent, unlike the in-Op boot/teardown) so a consumer can deploy to
+ * and observe them; `--json` reports each one's endpoint + the env that redirects
+ * tooling at it. Consumed by behold `serve --local`.
+ */
+export async function runEmulator(ctx) {
+    const { args, plugins } = ctx;
+    // Registered as compound `emulator <up|down|status>`, so the action word lands
+    // in args.path; the bare `emulator` fallback leaves it as the "." default.
+    const action = args.path;
+    if (!action || !ACTIONS.has(action)) {
+        console.error(formatError({ message: "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]; chant emulator --help lists the ports and sign-in" }));
+        return 1;
+    }
+    // One entry per emulator, not per lexicon (#1345): fly ships two — mudflaps
+    // for the Machines API and spritzer for Sprites — and reporting a lexicon
+    // would have to pick one of them.
+    const targets = plugins
+        .filter((p) => !args.lexicon || p.name === args.lexicon)
+        .flatMap((p) => emulatorsOf(p.emulator).map((cap) => ({ lexicon: p.name, cap })));
+    if (targets.length === 0) {
+        if (args.json) {
+            console.log(JSON.stringify({ emulators: [] }));
+            return 0;
+        }
+        console.error(formatWarning({
+            message: args.lexicon
+                ? `Lexicon "${args.lexicon}" has no local emulator, or isn't configured for this project`
+                : "No configured lexicon has a local emulator",
+        }));
+        return 0;
+    }
+    let ports;
+    try {
+        if (args.port?.length && action !== "up")
+            throw new Error("--port applies to `chant emulator up` only");
+        ports = parsePortMappings(args.port ?? [], targets.map((t) => t.cap));
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    const reports = [];
+    for (const { lexicon, cap } of targets) {
+        const lc = emulatorLifecycle(cap.spec);
+        if (action === "up") {
+            const port = ports.get(cap.spec.containerPort);
+            try {
+                const { endpoint } = await lc.up(port === undefined ? {} : { port });
+                reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
+            }
+            catch (err) {
+                console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+                return 1;
+            }
+        }
+        else if (action === "down") {
+            await lc.down();
+            reports.push({ lexicon, name: cap.spec.name, endpoint: "", env: {} });
+        }
+        else {
+            const state = await containerState(cap.spec.name);
+            if ("error" in state) {
+                console.error(formatError({ message: state.error }));
+                return 1;
+            }
+            if (!state.running) {
+                reports.push({ lexicon, name: cap.spec.name, endpoint: "", env: {} });
+                continue;
+            }
+            // The port `up` published, which `--port` may have moved off the default.
+            const port = (await publishedPort(cap.spec.name, cap.spec.containerPort)) ?? cap.spec.containerPort;
+            const endpoint = lc.endpoint(port);
+            const conflict = await endpointConflict(lexicon, cap, endpoint, port);
+            reports.push(conflict
+                ? { lexicon, name: cap.spec.name, endpoint: "", env: {}, conflict }
+                : { lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
+        }
+    }
+    const exit = reports.some((r) => r.conflict) ? 1 : 0;
+    if (args.json) {
+        console.log(JSON.stringify({ emulators: reports }));
+        return exit;
+    }
+    for (const r of reports) {
+        if (action === "up")
+            console.error(formatSuccess(`${r.lexicon}: ${r.name} up on ${r.endpoint}`));
+        else if (action === "down")
+            console.error(formatSuccess(`${r.lexicon}: ${r.name} down`));
+        else if (r.conflict)
+            console.error(formatError({ message: `${r.lexicon}: ${r.name} runs, but ${r.conflict}` }));
+        else
+            console.error(`${r.lexicon}: ${r.name} — ${r.endpoint ? `up on ${r.endpoint}` : "down"}`);
+    }
+    return exit;
+}

package/dist/cli/handlers/explain.js

@@ -0,0 +1,54 @@
+import { resolve, join, dirname } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { discover } from "../../discovery/index.js";
+import { buildOkfBundle, OKF_VERSION } from "../../okf.js";
+import { handleExplain } from "../mcp/tools/explain.js";
+import { formatError, formatSuccess } from "../format.js";
+const EXPLAIN_FORMATS = ["markdown", "json", "okf"];
+/**
+ * `chant explain [path] [--format markdown|json|okf] [-o <dir>]` — the CLI
+ * path of the MCP `explain` tool (#1058): a structured summary of every
+ * discovered entity. `--format okf` emits an OKF v0.2 knowledge bundle
+ * instead — one markdown concept per entity plus an `index.md` — written as a
+ * directory tree under `-o <dir>`, or printed as JSON (path → content) when
+ * no output directory is given.
+ */
+export async function runExplain(ctx) {
+    const { args } = ctx;
+    const format = (args.format || "markdown");
+    if (!EXPLAIN_FORMATS.includes(format)) {
+        console.error(formatError({
+            message: `Invalid --format: ${format}. Expected one of ${EXPLAIN_FORMATS.join(", ")}.`,
+        }));
+        return 1;
+    }
+    const projectPath = resolve(args.path === "." ? "." : args.path);
+    if (format === "okf") {
+        const result = await discover(projectPath);
+        for (const err of result.errors)
+            console.error(formatError({ message: err.message }));
+        const bundle = buildOkfBundle(result, projectPath);
+        if (args.output) {
+            await writeBundle(bundle, resolve(args.output));
+            console.log(formatSuccess(`Wrote OKF v${OKF_VERSION} bundle: ${bundle.length} file(s) under ${args.output}`));
+        }
+        else {
+            console.log(JSON.stringify({
+                okf_version: OKF_VERSION,
+                files: Object.fromEntries(bundle.map((f) => [f.path, f.content])),
+            }, null, 2));
+        }
+        return result.errors.length > 0 ? 1 : 0;
+    }
+    const summary = await handleExplain({ path: projectPath, format });
+    console.log(typeof summary === "string" ? summary : JSON.stringify(summary, null, 2));
+    return 0;
+}
+/** Write the bundle's files under `outDir`, creating subdirectories as needed. */
+async function writeBundle(bundle, outDir) {
+    for (const file of bundle) {
+        const target = join(outDir, file.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, file.content, "utf-8");
+    }
+}