@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/commands/init.js

@@ -0,0 +1,381 @@
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync } from "fs";
+import { join, resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { createInterface } from "readline";
+import { formatSuccess, formatWarning } from "../format.js";
+import { loadPlugin, recordProjectLexicons, unknownPathLexiconsNotice } from "../plugins.js";
+import { lexiconModulePath, lexiconSourceLabel } from "../../lexicon-module.js";
+import { MCP_CONFIG_FILENAME, detectPackageManager, generateMcpConfig, mcpConfigPath } from "../mcp-config.js";
+/** Read the current chant package version from our own package.json. */
+export function getChantVersion() {
+    try {
+        const pkgDir = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))));
+        const pkg = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.13";
+    }
+    catch {
+        return "0.0.13";
+    }
+}
+/**
+ * The devDependencies a scaffolded project gets, from `chant init` and from
+ * `chant carve` (#3233). The project's TypeScript is for its editor and `tsc`
+ * only; chant parses with its own copy, so any 5.9+ or 7 release works (#3089).
+ */
+export const SCAFFOLD_DEV_DEPENDENCIES = {
+    "@types/node": "^24.0.0",
+    typescript: "^5.9.3 || ^7.0.0",
+};
+/**
+ * Generate package.json content
+ */
+function generatePackageJson(lexicon, extraScripts, lexiconIsPackage = true) {
+    const ver = getChantVersion();
+    const dependencies = {
+        "@intentius/chant": `^${ver}`,
+        // chant#2578 — a lexicon declared by path is not a package to depend on.
+        ...(lexiconIsPackage ? { [`@intentius/chant-lexicon-${lexicon}`]: `^${ver}` } : {}),
+    };
+    const pkg = {
+        name: "chant-project",
+        version: ver,
+        type: "module",
+        scripts: {
+            build: `chant build src --lexicon ${lexicon}`,
+            lint: "chant lint src",
+            dev: `chant build src --lexicon ${lexicon} --watch`,
+            ...extraScripts,
+        },
+        dependencies,
+        devDependencies: { ...SCAFFOLD_DEV_DEPENDENCIES },
+    };
+    return JSON.stringify(pkg, null, 2);
+}
+/**
+ * Generate tsconfig.json content.
+ *
+ * `bundler` resolution, because chant resolves a project's imports the way tsx
+ * and fold do: `./config` with no extension. NodeNext rejects that form
+ * (TS2835), and its suggested `./config.js` makes fold fall back to running the
+ * file (#3089). `types` names node because TypeScript 6 and later no longer load
+ * every `@types` package by default.
+ */
+export function generateTsConfig() {
+    const config = {
+        compilerOptions: {
+            target: "ES2022",
+            module: "esnext",
+            moduleResolution: "bundler",
+            types: ["node"],
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            declaration: true,
+            outDir: "./dist",
+            rootDir: "./src",
+        },
+        include: ["src"],
+        exclude: ["node_modules", "dist"],
+    };
+    return JSON.stringify(config, null, 2);
+}
+/**
+ * Generate chant.config.ts content
+ */
+function generateChantConfig(lexicon) {
+    return `import type { ChantConfig } from "@intentius/chant";
+
+export default {
+  lexicons: ["${lexicon}"],
+} satisfies ChantConfig;
+`;
+}
+/**
+ * Generate .gitignore content
+ */
+function generateGitignore() {
+    return `dist/
+node_modules/
+.chant/types/
+.chant/meta/
+.chant/rules/
+skills/
+`;
+}
+/**
+ * Generate embedded core type definitions for .chant/types/core/
+ */
+function generateCoreTypeDefs() {
+    return `// @intentius/chant — core type definitions
+// Run "chant update" to sync the latest types
+
+/** Wraps a value that may be a literal or an intrinsic expression */
+export type Value<T> = T | Intrinsic;
+
+/** Marker interface for intrinsic functions (Ref, Sub, etc.) */
+export interface Intrinsic {
+  toJSON(): unknown;
+}
+
+/** Serializer interface for chant specifications */
+export interface Serializer {
+  name: string;
+  rulePrefix: string;
+  serialize(entities: Map<string, Declarable>, outputs?: LexiconOutput[]): string;
+  serializeCrossRef?(output: LexiconOutput): unknown;
+}
+
+/** Base interface for all declarable entities */
+export interface Declarable {
+  readonly lexicon: string;
+  readonly entityType: string;
+  readonly kind?: "resource" | "property";
+}
+
+/** Cross-lexicon output reference */
+export interface LexiconOutput {
+  readonly outputName: string;
+  readonly sourceEntity: string;
+  readonly sourceAttribute: string;
+  readonly lexicon: string;
+}
+
+/** Top-level project configuration */
+export interface ChantConfig {
+  lexicons?: string[];
+  lint?: {
+    rules?: Record<string, string | [string, Record<string, unknown>]>;
+    extends?: string[];
+    plugins?: string[];
+  };
+}
+
+`;
+}
+/**
+ * Prompt user for install
+ */
+async function promptInstall() {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question("Install dependencies? (Y/n) ", (answer) => {
+            rl.close();
+            const trimmed = answer.trim().toLowerCase();
+            resolve(trimmed === "" || trimmed === "y" || trimmed === "yes");
+        });
+    });
+}
+/**
+ * Write a file if it doesn't exist, tracking created files and warnings
+ */
+function writeIfNotExists(filePath, content, relativePath, createdFiles, warnings) {
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, content);
+        createdFiles.push(relativePath);
+    }
+    else {
+        warnings.push(`${relativePath} already exists, skipping`);
+    }
+}
+/**
+ * Execute the init command
+ */
+export async function initCommand(options) {
+    const targetDir = resolve(options.path ?? ".");
+    const createdFiles = [];
+    const warnings = [];
+    // Check if directory is non-empty
+    if (existsSync(targetDir)) {
+        const contents = readdirSync(targetDir);
+        const nonHiddenFiles = contents.filter((f) => !f.startsWith("."));
+        if (nonHiddenFiles.length > 0 && !options.force) {
+            return {
+                success: false,
+                createdFiles: [],
+                warnings: [],
+                error: `Directory is not empty. Use --force to initialize anyway.`,
+            };
+        }
+        if (nonHiddenFiles.length > 0) {
+            warnings.push("Initializing in non-empty directory");
+        }
+    }
+    // Create target directory if it doesn't exist
+    if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+    }
+    // chant#2578 — `--force` into an existing project keeps its chant.config.
+    // When that config declares the lexicon by path, it loads from the module
+    // and there is no package to depend on or install. chant#2591 — the config
+    // is read without running it; when that fails, init says so and treats the
+    // lexicon as a package.
+    let lexiconModule;
+    if (existsSync(join(targetDir, "chant.config.ts")) || existsSync(join(targetDir, "chant.config.json"))) {
+        const notice = unknownPathLexiconsNotice(recordProjectLexicons(targetDir));
+        if (notice !== undefined)
+            warnings.push(notice);
+        if (lexiconModulePath(options.lexicon) !== undefined) {
+            lexiconModule = lexiconSourceLabel(options.lexicon, targetDir);
+        }
+    }
+    // Load plugin early to get template set (used for scripts + source files)
+    let templateSet;
+    try {
+        const plugin = await loadPlugin(options.lexicon);
+        if (plugin.initTemplates) {
+            templateSet = plugin.initTemplates(options.template);
+        }
+    }
+    catch {
+        // Plugin not yet installed — no source files to scaffold
+    }
+    // Create src directory
+    const srcDir = join(targetDir, "src");
+    if (!existsSync(srcDir)) {
+        mkdirSync(srcDir, { recursive: true });
+    }
+    // Generate package.json
+    writeIfNotExists(join(targetDir, "package.json"), generatePackageJson(options.lexicon, templateSet?.scripts, lexiconModule === undefined), "package.json", createdFiles, warnings);
+    // Generate tsconfig.json
+    writeIfNotExists(join(targetDir, "tsconfig.json"), generateTsConfig(), "tsconfig.json", createdFiles, warnings);
+    // Generate chant.config.ts. A template that ships its own wins: core's
+    // version knows only the lexicon name, while a template that declares a
+    // config namespace (fountain's steward scaffold and its `fountain.profiles`
+    // block, chant #2129) is scaffolding a project that needs it to run at all.
+    // The root-file loop below runs *after* this write, and `writeIfNotExists`
+    // keeps the first file, so a template's config would otherwise be discarded
+    // in silence — see lexicons/cedar/src/init-templates.ts, which documents
+    // having had to work around exactly that.
+    writeIfNotExists(join(targetDir, "chant.config.ts"), templateSet?.root?.["chant.config.ts"] ?? generateChantConfig(options.lexicon), "chant.config.ts", createdFiles, warnings);
+    // Generate .gitignore
+    writeIfNotExists(join(targetDir, ".gitignore"), generateGitignore(), ".gitignore", createdFiles, warnings);
+    // Write source files from plugin template set
+    if (templateSet) {
+        for (const [filename, content] of Object.entries(templateSet.src)) {
+            writeIfNotExists(join(srcDir, filename), content, `src/${filename}`, createdFiles, warnings);
+        }
+        // Write root scaffold files (e.g. index.js, test.js, Dockerfile).
+        // `chant.config.ts` is skipped: it was already written above, from this
+        // same template set, and re-offering it here would only produce an
+        // "already exists, skipping" warning about a file the template supplied.
+        if (templateSet.root) {
+            for (const [filename, content] of Object.entries(templateSet.root)) {
+                if (filename === "chant.config.ts")
+                    continue;
+                writeIfNotExists(join(targetDir, filename), content, filename, createdFiles, warnings);
+            }
+        }
+    }
+    // Scaffold .chant/types/core/ with embedded type definitions
+    const coreTypesDir = join(targetDir, ".chant", "types", "core");
+    mkdirSync(coreTypesDir, { recursive: true });
+    writeIfNotExists(join(coreTypesDir, "package.json"), JSON.stringify({ name: "@intentius/chant", version: "0.0.0", types: "./index.d.ts" }, null, 2), ".chant/types/core/package.json", createdFiles, warnings);
+    writeIfNotExists(join(coreTypesDir, "index.d.ts"), generateCoreTypeDefs(), ".chant/types/core/index.d.ts", createdFiles, warnings);
+    // Scaffold .chant/types/lexicon-{lexicon}/ stub. A lexicon declared by path
+    // is imported by its path, so it has no package name to stub (chant#2578).
+    if (lexiconModule === undefined) {
+        const lexiconTypesDir = join(targetDir, ".chant", "types", `lexicon-${options.lexicon}`);
+        mkdirSync(lexiconTypesDir, { recursive: true });
+        writeIfNotExists(join(lexiconTypesDir, "package.json"), JSON.stringify({ name: `@intentius/chant-lexicon-${options.lexicon}`, version: "0.0.0", types: "./index.d.ts" }, null, 2), `.chant/types/lexicon-${options.lexicon}/package.json`, createdFiles, warnings);
+        writeIfNotExists(join(lexiconTypesDir, "index.d.ts"), `// Lexicon type stubs — run "chant update" to sync full types\nexport {};\n`, `.chant/types/lexicon-${options.lexicon}/index.d.ts`, createdFiles, warnings);
+    }
+    // Generate the project's MCP config. It lands in the directory init was
+    // pointed at, like everything else init produces, and at the path
+    // `chant doctor` checks — see ../mcp-config.ts for why project scope, and
+    // chant #2383 for the three-way disagreement that came of writing it into
+    // the user's home directory instead.
+    if (!options.skipMcp) {
+        writeIfNotExists(mcpConfigPath(targetDir), generateMcpConfig(detectPackageManager(targetDir)), MCP_CONFIG_FILENAME, createdFiles, warnings);
+    }
+    // Install skills from the lexicon's plugin. With --skill, install only
+    // the matching skill; without, install all.
+    try {
+        const plugin = await loadPlugin(options.lexicon);
+        if (plugin.skills) {
+            const all = plugin.skills();
+            const skills = options.skill ? all.filter((s) => s.name === options.skill) : all;
+            if (options.skill && skills.length === 0) {
+                warnings.push(`No skill named "${options.skill}" in lexicon ${options.lexicon}; nothing installed`);
+            }
+            for (const skill of skills) {
+                const skillDir = join(targetDir, "skills", skill.name);
+                mkdirSync(skillDir, { recursive: true });
+                writeFileSync(join(skillDir, "SKILL.md"), skill.content);
+                createdFiles.push(`skills/${skill.name}/SKILL.md`);
+            }
+        }
+    }
+    catch {
+        // Skills are optional — don't fail init if plugin isn't installed yet
+    }
+    // `--template` records where the files came from (#2540, ws-047). Plain
+    // init writes no lock and never loads the lineage module.
+    if (options.template && templateSet) {
+        const { writeTemplateLock } = await import("../../workspace/lineage-init.js");
+        const lock = writeTemplateLock({
+            targetDir,
+            lexicon: options.lexicon,
+            template: options.template,
+            createdFiles,
+            chantVersion: getChantVersion(),
+            lexiconModule,
+        });
+        if (lock)
+            createdFiles.push(lock);
+        else
+            warnings.push(".chant/workspace.lock.json already exists, skipping");
+    }
+    return {
+        success: true,
+        createdFiles,
+        warnings,
+        ...(lexiconModule !== undefined ? { lexiconModule } : {}),
+    };
+}
+/**
+ * Print init result and prompt for install
+ */
+export async function printInitResult(result, options) {
+    if (!result.success) {
+        console.error(result.error);
+        return;
+    }
+    for (const warning of result.warnings) {
+        console.error(formatWarning({ message: warning }));
+    }
+    if (result.createdFiles.length > 0) {
+        console.log(formatSuccess("Created:"));
+        for (const file of result.createdFiles) {
+            console.log(`  ${file}`);
+        }
+    }
+    console.log("");
+    if (result.lexiconModule !== undefined) {
+        console.log(`The lexicon loads from ${result.lexiconModule}, as chant.config.ts declares. It has no package to install.`);
+        console.log("");
+    }
+    const pm = detectPackageManager(options?.cwd);
+    // Interactive install prompt
+    if (!options?.skipInstall) {
+        const shouldInstall = await promptInstall();
+        if (shouldInstall) {
+            const { execSync } = await import("child_process");
+            const cwd = options?.cwd ?? ".";
+            console.log("Installing dependencies...");
+            try {
+                execSync(`${pm} install`, { cwd, stdio: "inherit" });
+            }
+            catch {
+                console.error(formatWarning({ message: `Install failed. Run '${pm} install' manually.` }));
+            }
+        }
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Edit src/config.ts");
+    console.log("  2. Add resources in src/");
+    console.log(`  3. ${pm} run build`);
+}

package/dist/cli/commands/lexicon-rolling-upgrade.js

@@ -0,0 +1,145 @@
+/**
+ * `chant dev rolling-upgrade <lexicon-dir>` command implementation.
+ *
+ * Detects rolling-spec drift for the aws, azure, and github lexicons. These
+ * lexicons pin no version constant — "latest" is fetched on every regen. This
+ * command regenerates from current-latest, diffs the produced API surface
+ * against the committed baseline (surface.snapshot.json), and REPORTS the
+ * result. It is a dry run: it never opens a PR, updates a branch, or writes the
+ * baseline. PR automation and scheduling live in #527.
+ *
+ * The PR label an eventual automation would apply is derived from severity:
+ *   additive → `minor`, breaking → `major`. This command only prints it.
+ */
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { checkRollingUpgrade, } from "../../codegen/rolling-upgrade.js";
+// ── Main entry ────────────────────────────────────────────────────────
+/**
+ * Run the rolling-upgrade check and return the result.
+ * Returns a synthetic failed result when the directory is missing.
+ */
+export async function runRollingUpgrade(opts) {
+    const dir = resolve(opts.lexiconDir);
+    if (!existsSync(dir)) {
+        return {
+            lexicon: "aws",
+            hasUpgrade: false,
+            severity: "none",
+            delta: { added: [], changed: [], removed: [], renamed: [], severity: "none" },
+            deltaText: "",
+            validationOk: false,
+            failures: [{ step: "setup", output: `Lexicon directory not found: ${dir}` }],
+            apiVersionDelta: [],
+            freshSnapshot: null,
+        };
+    }
+    return checkRollingUpgrade({
+        lexiconDir: dir,
+        force: opts.force,
+        verbose: opts.verbose,
+    });
+}
+/**
+ * Map surface severity to the semver PR label an upgrade would carry.
+ * additive → minor, breaking → major, none → none.
+ */
+export function severityToLabel(severity) {
+    if (severity === "breaking")
+        return "major";
+    if (severity === "additive")
+        return "minor";
+    return "none";
+}
+// ── Human-readable output ─────────────────────────────────────────────
+const COLORS = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    gray: "\x1b[90m",
+    bold: "\x1b[1m",
+    reset: "\x1b[0m",
+};
+function useColors() {
+    return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+function c(text, code) {
+    return useColors() ? `${code}${text}${COLORS.reset}` : text;
+}
+/**
+ * Print the rolling-upgrade result to stdout.
+ */
+export function printRollingUpgradeResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            lexicon: result.lexicon,
+            hasUpgrade: result.hasUpgrade,
+            severity: result.severity,
+            label: severityToLabel(result.severity),
+            validationOk: result.validationOk,
+            delta: result.delta,
+            apiVersionDelta: result.apiVersionDelta,
+            failures: result.failures,
+        }, null, 2));
+        return;
+    }
+    console.log(c(`Rolling upgrade check: ${result.lexicon}`, COLORS.bold));
+    console.log("");
+    // Surface delta — the review payload
+    if (result.deltaText) {
+        console.log(result.deltaText);
+    }
+    else {
+        console.log(c("No surface changes.", COLORS.green));
+    }
+    // azure API-version delta
+    if (result.apiVersionDelta.length > 0) {
+        console.log("");
+        console.log(c(`API version changes (${result.apiVersionDelta.length}):`, COLORS.bold));
+        for (const v of result.apiVersionDelta) {
+            const arrow = v.kind === "added"
+                ? `+ ${v.provider} (${v.after})`
+                : v.kind === "removed"
+                    ? `- ${v.provider} (was ${v.before})`
+                    : `~ ${v.provider}: ${v.before} -> ${v.after}`;
+            console.log(`  ${arrow}`);
+        }
+    }
+    // Failures
+    if (result.failures.length > 0) {
+        console.log("");
+        console.log(c(`${result.failures.length} step(s) failed:`, COLORS.bold));
+        for (const f of result.failures) {
+            console.log(c(`  FAIL [${f.step}]${f.exitCode !== undefined ? ` (exit ${f.exitCode})` : ""}`, COLORS.red));
+            if (f.output) {
+                const indented = f.output
+                    .split("\n")
+                    .map((l) => `       ${l}`)
+                    .join("\n");
+                console.log(c(indented, COLORS.gray));
+            }
+        }
+    }
+    console.log("");
+    // Decision line
+    const severityColor = result.severity === "breaking"
+        ? COLORS.red
+        : result.severity === "additive"
+            ? COLORS.yellow
+            : COLORS.green;
+    const label = severityToLabel(result.severity);
+    const validationLabel = result.validationOk
+        ? c("ok", COLORS.green)
+        : c("FAILED", COLORS.red);
+    console.log(`Upgrade: ${result.hasUpgrade}  Severity: ${c(result.severity, severityColor)}  ` +
+        `Label: ${label}  Validation: ${validationLabel}`);
+    if (result.hasUpgrade && result.validationOk) {
+        console.log(c(`A PR would be opened: chore(${result.lexicon}): regen from latest spec [${label}]`, COLORS.gray));
+    }
+    else if (result.hasUpgrade && !result.validationOk) {
+        console.log(c("Surface moved but validation failed — no PR; surfaces as a report/issue (#527).", COLORS.yellow));
+    }
+    else {
+        console.log(c("No surface change — no PR.", COLORS.gray));
+    }
+}

package/dist/cli/commands/lexicon-surface-diff.js

@@ -0,0 +1,145 @@
+/**
+ * `chant dev surface-diff <lexicon-dir>` command implementation.
+ *
+ * Regenerates a lexicon from its spec, validates the result, extracts the
+ * public API surface, and diffs it against the committed baseline snapshot.
+ *
+ * Outputs a human-readable delta to stdout and optionally a machine-readable
+ * JSON result to a file. Never auto-fixes: failures are captured and reported.
+ *
+ * The snapshot file is written to `<lexicon-dir>/surface.snapshot.json`.
+ * Pass `--update-snapshot` to commit the fresh snapshot after a successful run.
+ *
+ * An update run is exempt from the `surface-matches-snapshot` validate check
+ * and from nothing else (#1825): that check fails on the stale baseline the
+ * run exists to replace, and with an `"always"` gate (#1475) the documented
+ * re-baseline flow would deadlock. Any other failing step still refuses the
+ * write, so a broken generate cannot be baselined.
+ */
+import { existsSync, readFileSync } from "fs";
+import { resolve, join } from "path";
+import { regenLexicon, writeSurfaceSnapshot, SNAPSHOT_FILENAME } from "../../codegen/lexicon-regen.js";
+import { bumpForSeverity, bumpPackageJsonVersion } from "../../codegen/version-bump.js";
+// ── Main entry ────────────────────────────────────────────────────────
+/**
+ * Run the surface-diff pipeline and return the result.
+ * Logs human-readable output to stderr; machine-readable JSON goes to the caller.
+ */
+export async function runSurfaceDiff(opts) {
+    const dir = resolve(opts.lexiconDir);
+    if (!existsSync(dir)) {
+        const failure = {
+            step: "setup",
+            output: `Lexicon directory not found: ${dir}`,
+        };
+        return {
+            ok: false,
+            changed: false,
+            severity: "none",
+            delta: { added: [], changed: [], removed: [], renamed: [], severity: "none" },
+            deltaText: "",
+            failures: [failure],
+            freshSnapshot: null,
+        };
+    }
+    const result = await regenLexicon({
+        lexiconDir: dir,
+        force: opts.force,
+        verbose: opts.verbose,
+        skipBundle: opts.skipBundle,
+        skipBuild: opts.skipBuild,
+        skipLint: opts.skipLint,
+        skipExamples: !opts.runExamples,
+        pinnedDigestPath: opts.pinnedDigestPath,
+        // The update run skips only the surface-matches-snapshot validate check —
+        // the staleness it is about to fix (#1825).
+        updatingSnapshot: opts.updateSnapshot,
+    });
+    // Update snapshot when requested and the run succeeded
+    if (opts.updateSnapshot && result.ok && result.freshSnapshot) {
+        writeSurfaceSnapshot(dir, result.freshSnapshot);
+        process.stderr.write(`Snapshot updated: ${dir}/${SNAPSHOT_FILENAME}\n`);
+        // #616: accepting drift on a rolling lexicon changes the surface but nothing
+        // bumps the version — so skip-if-unchanged would strand the new surface at
+        // publish time. `--bump` raises the version by the drift severity (0.x-aware)
+        // so the accepted drift actually ships.
+        if (opts.bump && result.changed && result.severity !== "none") {
+            const pkgPath = join(dir, "package.json");
+            if (existsSync(pkgPath)) {
+                const current = JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "0.0.0";
+                const bumped = bumpForSeverity(current, result.severity);
+                if (bumped) {
+                    bumpPackageJsonVersion(pkgPath, bumped);
+                    process.stderr.write(`Version bumped: ${current} -> ${bumped} (${result.severity})\n`);
+                }
+                else {
+                    process.stderr.write(`Version unchanged: could not bump ${current} for severity ${result.severity}\n`);
+                }
+            }
+        }
+    }
+    return result;
+}
+// ── Human-readable output ─────────────────────────────────────────────
+const COLORS = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    gray: "\x1b[90m",
+    bold: "\x1b[1m",
+    reset: "\x1b[0m",
+};
+function useColors() {
+    return !process.env.NO_COLOR && process.stdout.isTTY !== false;
+}
+function c(text, code) {
+    return useColors() ? `${code}${text}${COLORS.reset}` : text;
+}
+/**
+ * Print the surface-diff result as human-readable text to stdout.
+ */
+export function printSurfaceDiffResult(result, json) {
+    if (json) {
+        console.log(JSON.stringify({
+            ok: result.ok,
+            changed: result.changed,
+            severity: result.severity,
+            delta: result.delta,
+            failures: result.failures,
+        }, null, 2));
+        return;
+    }
+    // Surface delta
+    if (result.deltaText) {
+        console.log(result.deltaText);
+    }
+    else if (result.changed) {
+        console.log("Surface changed (no baseline to diff against).");
+    }
+    else {
+        console.log(c("No surface changes.", COLORS.green));
+    }
+    // Failures
+    if (result.failures.length > 0) {
+        console.log("");
+        console.log(c(`${result.failures.length} step(s) failed:`, COLORS.bold));
+        for (const f of result.failures) {
+            console.log(c(`  FAIL [${f.step}]${f.exitCode !== undefined ? ` (exit ${f.exitCode})` : ""}`, COLORS.red));
+            if (f.output) {
+                const indented = f.output
+                    .split("\n")
+                    .map((l) => `       ${l}`)
+                    .join("\n");
+                console.log(c(indented, COLORS.gray));
+            }
+        }
+    }
+    console.log("");
+    // Summary line
+    const severityColor = result.severity === "breaking" ? COLORS.red :
+        result.severity === "additive" ? COLORS.yellow :
+            COLORS.green;
+    const statusLabel = result.ok ? c("ok", COLORS.green) : c("FAILED", COLORS.red);
+    const severityLabel = c(result.severity, severityColor);
+    console.log(`Status: ${statusLabel}  Severity: ${severityLabel}  Changed: ${result.changed}`);
+}