@cairn-tool/cairn 2.0.0

package/dist/commands/scripts.d.ts

@@ -0,0 +1,59 @@
+import type { ConsultedFile } from "../scripts/resolve.js";
+export interface ScriptsOptions {
+    format?: string;
+    envelope?: boolean;
+    root?: string;
+    config?: string | boolean;
+}
+export interface ScriptRunPayload {
+    name: string;
+    registry: string;
+    workingDirectory: string;
+    invokedFrom: string;
+    command: {
+        form: "run" | "exec";
+        run?: string;
+        exec?: readonly string[];
+        shell?: string;
+    };
+    args: string[];
+    exit: {
+        code: number | null;
+        signal: string | null;
+        status: number;
+    };
+    stdout: string;
+    stderr: string;
+    truncated: {
+        stdout: boolean;
+        stderr: boolean;
+    };
+    durationMs: number;
+    startupError?: string;
+}
+export declare function scriptsRunAction(name: string, args: string[], opts: ScriptsOptions): Promise<void>;
+export interface ScriptWhichPayload {
+    name: string;
+    found: boolean;
+    boundary: {
+        directory: string;
+        kind: string;
+    };
+    invokedFrom: string;
+    registry?: string;
+    workingDirectory?: string;
+    description?: string;
+    command?: {
+        form: "run" | "exec";
+        run?: string;
+        exec?: readonly string[];
+        shell?: string;
+    };
+    shadowed: Array<{
+        file: string;
+        description?: string;
+    }>;
+    consulted: ConsultedFile[];
+}
+export declare function scriptsWhichAction(name: string, opts: ScriptsOptions): Promise<void>;
+export declare function scriptsListAction(opts: ScriptsOptions): Promise<void>;

package/dist/commands/scripts.js

@@ -0,0 +1,222 @@
+import { CONFIG_FILENAME, selectConfig } from "../config.js";
+import { terminate } from "../command-result.js";
+import { BASE_FORMATS } from "../formats.js";
+import { jsonPayload } from "../result.js";
+import { executeScript, exitStatusFor } from "../scripts/execute.js";
+import { listScripts, resolveScript, shadowingFailure } from "../scripts/resolve.js";
+/**
+ * Formats are validated here rather than through `commandOptions`, which is keyed
+ * on bare `md` subcommand names and whose error text says `md <command>`. The
+ * `agent` subcommands validate inline for the same reason.
+ *
+ * `scripts` commands are also deliberately absent from `COMMAND_OPTIONS`: a
+ * checked-in configuration file must never be able to change what executes, the
+ * same rule that keeps `--write` out of the configurable set for `md fix`.
+ */
+function resolveFormat(opts) {
+    const format = (opts.format ?? "llm");
+    if (!BASE_FORMATS.includes(format)) {
+        throw new Error(`Invalid output format: ${String(opts.format)}`);
+    }
+    if (opts.envelope && format !== "json") {
+        throw new Error("--envelope requires --format json");
+    }
+    return format;
+}
+/**
+ * `--config` and `--no-config` are read from argv rather than from commander,
+ * exactly as `md` reads them, so the mutual-exclusion error is raised in one
+ * place.
+ */
+function selection() {
+    return selectConfig(process.argv.slice(2));
+}
+function walkOptions(opts) {
+    return { root: opts.root, selection: selection() };
+}
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+function style(text, code, human) {
+    return human ? `${code}${text}${RESET}` : text;
+}
+function commandOf(entry) {
+    return entry.run ?? (entry.exec ?? []).join(" ");
+}
+/**
+ * Fails when the resolution cannot safely produce a script to run.
+ *
+ * The boundary refusal is the load-bearing one: without a repository and without
+ * `--root` the walk would fall back to the nearest configuration file, which in a
+ * scratch directory can mean a world-writable one in a shared parent.
+ */
+function requireWinner(resolution, name) {
+    const shadowing = shadowingFailure(resolution);
+    if (shadowing) {
+        throw new Error(`Cannot resolve '${name}': ${shadowing.file} is unreadable (${shadowing.reason}) and may shadow a definition above it`);
+    }
+    if (!resolution.winner) {
+        const consulted = resolution.consulted.length;
+        throw new Error(consulted === 0
+            ? `No script named '${name}': no ${CONFIG_FILENAME} was found from ${resolution.invokedFrom}`
+            : `No script named '${name}' in ${consulted} configuration file${consulted === 1 ? "" : "s"} from ${resolution.invokedFrom}`);
+    }
+}
+export async function scriptsRunAction(name, args, opts) {
+    const format = resolveFormat(opts);
+    const resolution = resolveScript(name, walkOptions(opts));
+    if (resolution.boundary.kind === "nearest-config") {
+        throw new Error("Refusing to run a script outside a Git repository; pass --root <dir> to set the boundary explicitly");
+    }
+    requireWinner(resolution, name);
+    const winner = resolution.winner;
+    const outcome = await executeScript({
+        mode: format === "json" ? "capture" : "pass-through",
+        definition: winner.definition,
+        registry: winner.registry,
+        workingDirectory: winner.workingDirectory,
+        invokedFrom: resolution.invokedFrom,
+        args,
+    });
+    if (format !== "json") {
+        if (format === "human") {
+            process.stderr.write(`${DIM}${winner.definition.name} — ${winner.registry.file} (cwd ${winner.workingDirectory})${RESET}\n`);
+        }
+        // Assigned rather than thrown: the child's status is outside CommandExit's
+        // 1|2 type. Never process.exit() — a piped stdout write is asynchronous and
+        // would be truncated.
+        process.exitCode = exitStatusFor(outcome);
+        return;
+    }
+    const status = exitStatusFor(outcome);
+    const payload = {
+        name,
+        registry: winner.registry.file,
+        workingDirectory: winner.workingDirectory,
+        invokedFrom: resolution.invokedFrom,
+        command: {
+            form: winner.definition.run !== undefined ? "run" : "exec",
+            ...(winner.definition.run !== undefined ? { run: winner.definition.run } : {}),
+            ...(winner.definition.exec !== undefined ? { exec: winner.definition.exec } : {}),
+            ...(winner.definition.shell !== undefined ? { shell: winner.definition.shell } : {}),
+        },
+        args: [...args],
+        exit: { code: outcome.code, signal: outcome.signal, status },
+        stdout: outcome.stdout ?? "",
+        stderr: outcome.stderr ?? "",
+        truncated: outcome.truncated ?? { stdout: false, stderr: false },
+        durationMs: outcome.durationMs,
+        ...(outcome.startupError ? { startupError: outcome.startupError } : {}),
+    };
+    // A script that never started is an invocation error, not a failing script;
+    // collapsing the two would make a typo in exec[0] indistinguishable from a
+    // legitimately failing test suite.
+    const exitCode = outcome.startupError ? 1 : status === 0 ? 0 : 2;
+    process.stdout.write(jsonPayload("scripts run", payload, opts, {
+        exitCode,
+        summary: { status, durationMs: outcome.durationMs },
+    }));
+    if (exitCode !== 0)
+        terminate(exitCode);
+}
+export async function scriptsWhichAction(name, opts) {
+    const format = resolveFormat(opts);
+    const resolution = resolveScript(name, walkOptions(opts));
+    const shadowing = shadowingFailure(resolution);
+    if (shadowing) {
+        throw new Error(`Cannot resolve '${name}': ${shadowing.file} is unreadable (${shadowing.reason}) and may shadow a definition above it`);
+    }
+    const winner = resolution.winner;
+    const payload = {
+        name,
+        found: Boolean(winner),
+        boundary: { directory: resolution.boundary.directory, kind: resolution.boundary.kind },
+        invokedFrom: resolution.invokedFrom,
+        ...(winner
+            ? {
+                registry: winner.registry.file,
+                workingDirectory: winner.workingDirectory,
+                ...(winner.definition.description ? { description: winner.definition.description } : {}),
+                command: {
+                    form: winner.definition.run !== undefined ? "run" : "exec",
+                    ...(winner.definition.run !== undefined ? { run: winner.definition.run } : {}),
+                    ...(winner.definition.exec !== undefined ? { exec: winner.definition.exec } : {}),
+                    ...(winner.definition.shell !== undefined ? { shell: winner.definition.shell } : {}),
+                },
+            }
+            : {}),
+        shadowed: resolution.shadowed.map(({ file, description }) => ({
+            file,
+            ...(description ? { description } : {}),
+        })),
+        consulted: resolution.consulted,
+    };
+    if (format === "json") {
+        const output = jsonPayload("scripts which", payload, opts, { exitCode: winner ? 0 : 2 });
+        (winner ? process.stdout : process.stderr).write(output);
+        if (!winner)
+            terminate(2);
+        return;
+    }
+    const human = format === "human";
+    const lines = [];
+    if (!winner) {
+        lines.push(`No script named '${name}'`);
+        lines.push(`  consulted: ${resolution.consulted.length} file(s) up to ${payload.boundary.directory}`);
+        process.stderr.write(lines.join("\n") + "\n");
+        terminate(2);
+    }
+    lines.push(`${style(name, BOLD, human)}  ${commandOf(winner.definition)}`);
+    if (winner.definition.description)
+        lines.push(`  ${winner.definition.description}`);
+    lines.push(`  registry: ${style(winner.registry.file, CYAN, human)}`);
+    lines.push(`  cwd:      ${winner.workingDirectory}`);
+    for (const shadow of payload.shadowed)
+        lines.push(`  shadows:  ${shadow.file}`);
+    process.stdout.write(lines.join("\n") + "\n");
+}
+// ---------------------------------------------------------------------------
+// scripts list
+// ---------------------------------------------------------------------------
+export async function scriptsListAction(opts) {
+    const format = resolveFormat(opts);
+    const listing = listScripts(walkOptions(opts));
+    const invalid = listing.consulted.filter((file) => file.status === "invalid");
+    const payload = {
+        boundary: { directory: listing.boundary.directory, kind: listing.boundary.kind },
+        invokedFrom: listing.invokedFrom,
+        scripts: listing.scripts,
+        consulted: listing.consulted,
+        invalid: invalid.length,
+    };
+    if (format === "json") {
+        const output = jsonPayload("scripts list", payload, opts, {
+            exitCode: invalid.length > 0 ? 2 : 0,
+            summary: { scripts: listing.scripts.length, invalid: invalid.length },
+        });
+        (invalid.length > 0 ? process.stderr : process.stdout).write(output);
+        if (invalid.length > 0)
+            terminate(2);
+        return;
+    }
+    const human = format === "human";
+    const lines = [];
+    if (listing.scripts.length === 0) {
+        lines.push(`No scripts declared from ${listing.invokedFrom}`);
+    }
+    const width = Math.max(0, ...listing.scripts.map((entry) => entry.name.length));
+    for (const entry of listing.scripts) {
+        const name = style(entry.name.padEnd(width), BOLD, human);
+        lines.push(`${name}  ${entry.description ?? commandOf(entry)}`);
+        lines.push(`${" ".repeat(width)}  ${style(entry.file, DIM, human)}`);
+    }
+    for (const file of invalid) {
+        lines.push(`${style("invalid", BOLD, human)}  ${file.file}: ${file.reason}`);
+    }
+    const rendered = lines.join("\n") + "\n";
+    (invalid.length > 0 ? process.stderr : process.stdout).write(rendered);
+    if (invalid.length > 0)
+        terminate(2);
+}
+//# sourceMappingURL=scripts.js.map

package/dist/commands/scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.js","sourceRoot":"","sources":["../../src/commands/scripts.ts"],"names":[],"mappings":"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"}

package/dist/commands/section.d.ts

@@ -0,0 +1,9 @@
+interface SectionOptions {
+    envelope?: boolean;
+    format: string;
+    includeHeading: boolean;
+    children: boolean;
+    raw: boolean;
+}
+export declare function sectionAction(file: string, heading: string, opts: SectionOptions): Promise<void>;
+export {};

package/dist/commands/section.js

@@ -0,0 +1,49 @@
+import { findSection } from "../sections.js";
+import { outputPath, runtime } from "../runtime.js";
+import { terminate } from "../command-result.js";
+import { requireFile } from "../input.js";
+import { jsonPayload } from "../result.js";
+function resolveFormat(opts) {
+    const fmt = opts.format;
+    if (fmt === "llm" || fmt === "human" || fmt === "json")
+        return fmt;
+    return "llm";
+}
+export async function sectionAction(file, heading, opts) {
+    const format = resolveFormat(opts);
+    const filePath = requireFile(file, opts);
+    const shownPath = outputPath(filePath, opts);
+    const document = runtime().workspace.document(filePath);
+    const section = findSection(document, heading, {
+        children: opts.children,
+        includeHeading: opts.includeHeading,
+    });
+    if (!section) {
+        process.stderr.write(`Error: Heading not found: ${heading}\n`);
+        terminate(1);
+    }
+    const { heading: matched, startLine, endLine, content: sectionContent } = section;
+    if (opts.raw) {
+        process.stdout.write(sectionContent + "\n");
+        return;
+    }
+    if (format === "json") {
+        process.stdout.write(jsonPayload("md section", {
+            file: shownPath,
+            heading: matched.text,
+            slug: matched.slug,
+            depth: matched.depth,
+            startLine,
+            endLine,
+            content: sectionContent,
+        }, opts));
+        return;
+    }
+    const isHuman = format === "human";
+    const bold = (s) => (isHuman ? `\x1b[1m${s}\x1b[0m` : s);
+    process.stdout.write(bold(`Section "${matched.text}" (L${startLine}-L${endLine}) in ${shownPath}:`) +
+        "\n\n" +
+        sectionContent +
+        "\n");
+}
+//# sourceMappingURL=section.js.map

package/dist/commands/section.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.js","sourceRoot":"","sources":["../../src/commands/section.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAU3C,SAAS,aAAa,CAAC,IAAoB;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;IACxB,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,GAAG,CAAC;IACnE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAY,EACZ,OAAe,EACf,IAAoB;IAEpB,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAE7C,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE;QAC7C,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;KACpC,CAAC,CAAC;IAEH,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,OAAO,IAAI,CAAC,CAAC;QAC/D,SAAS,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAElF,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,WAAW,CACT,YAAY,EACZ;YACE,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,OAAO,CAAC,IAAI;YACrB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS;YACT,OAAO;YACP,OAAO,EAAE,cAAc;SACxB,EACD,IAAI,CACL,CACF,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,YAAY,OAAO,CAAC,IAAI,OAAO,SAAS,KAAK,OAAO,QAAQ,SAAS,GAAG,CAAC;QAC5E,MAAM;QACN,cAAc;QACd,IAAI,CACP,CAAC;AACJ,CAAC"}

package/dist/commands/serve.d.ts

@@ -0,0 +1,6 @@
+export interface ServeOptions {
+    root: string;
+    maxDocuments: string;
+    concurrency: string;
+}
+export declare function serveAction(protocol: string, opts: ServeOptions): Promise<void>;

package/dist/commands/serve.js

@@ -0,0 +1,48 @@
+import { initializeRuntime, runtime } from "../runtime.js";
+import { terminate } from "../command-result.js";
+import { defaultLintConcurrency } from "../config.js";
+import { resolveRoot } from "../serve/paths.js";
+import { serveStdio } from "../serve/server.js";
+const PROTOCOLS = ["mcp"];
+/**
+ * Upper bound on documents held in memory at once.
+ *
+ * Large enough that an ordinary workspace never evicts, small enough that a
+ * server pointed at a huge tree cannot grow without limit.
+ */
+const DEFAULT_MAX_DOCUMENTS = 2048;
+function bounded(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`--${name} must be a positive integer`);
+    }
+    return parsed;
+}
+export async function serveAction(protocol, opts) {
+    if (!PROTOCOLS.includes(protocol)) {
+        process.stderr.write(`Error: Unknown protocol: ${protocol}. Supported: ${PROTOCOLS.join(", ")}\n`);
+        terminate(1);
+    }
+    const root = resolveRoot(opts.root);
+    const config = runtime().config;
+    // Reinstalls the runtime with a workspace suited to a long-lived process: the
+    // document cache is bounded, and the shared on-disk index is left alone. That
+    // index accumulates every parse until a flush and latches its load once, so
+    // flushing at shutdown would rewrite a snapshot a concurrent `md index clear`
+    // had already deleted. It has to replace the runtime's own workspace rather
+    // than sit beside it, because library helpers reach for `runtime().workspace`.
+    const { workspace } = initializeRuntime(config, {
+        maxDocuments: bounded(opts.maxDocuments, "max-documents", DEFAULT_MAX_DOCUMENTS),
+        persistIndex: false,
+    });
+    const context = {
+        workspace,
+        config,
+        root,
+        concurrency: bounded(opts.concurrency, "concurrency", defaultLintConcurrency()),
+    };
+    await serveStdio(context);
+}
+//# sourceMappingURL=serve.js.map

package/dist/commands/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAShD,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC,SAAS,OAAO,CAAC,KAAa,EAAE,IAAY,EAAE,QAAgB;IAC5D,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,KAAK,IAAI,6BAA6B,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,IAAkB;IACpE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,4BAA4B,QAAQ,gBAAgB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC7E,CAAC;QACF,SAAS,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC;IAEhC,8EAA8E;IAC9E,8EAA8E;IAC9E,4EAA4E;IAC5E,8EAA8E;IAC9E,4EAA4E;IAC5E,+EAA+E;IAC/E,MAAM,EAAE,SAAS,EAAE,GAAG,iBAAiB,CAAC,MAAM,EAAE;QAC9C,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,eAAe,EAAE,qBAAqB,CAAC;QAChF,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IAEH,MAAM,OAAO,GAAiB;QAC5B,SAAS;QACT,MAAM;QACN,IAAI;QACJ,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,sBAAsB,EAAE,CAAC;KAChF,CAAC;IAEF,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC"}

package/dist/commands/stats.d.ts

@@ -0,0 +1,6 @@
+interface StatsOptions {
+    envelope?: boolean;
+    format: string;
+}
+export declare function statsAction(file: string, opts: StatsOptions): Promise<void>;
+export {};

package/dist/commands/stats.js

@@ -0,0 +1,109 @@
+import { visit } from "unist-util-visit";
+import { extractCodeBlocks } from "../markdown-ast.js";
+import { outputPath, runtime } from "../runtime.js";
+import { requireFile } from "../input.js";
+import { jsonPayload } from "../result.js";
+function resolveFormat(opts) {
+    const fmt = opts.format;
+    if (fmt === "llm" || fmt === "human" || fmt === "json")
+        return fmt;
+    return "llm";
+}
+function countWords(tree) {
+    let count = 0;
+    // Count words only in text nodes that are NOT inside code blocks
+    // (mdast code nodes contain their content in .value, not as text children)
+    visit(tree, "text", (node) => {
+        const words = node.value
+            .trim()
+            .split(/\s+/)
+            .filter((w) => w.length > 0);
+        count += words.length;
+    });
+    return count;
+}
+function countParagraphs(tree) {
+    let count = 0;
+    visit(tree, "paragraph", () => {
+        count++;
+    });
+    return count;
+}
+function countLists(tree) {
+    let ordered = 0;
+    let unordered = 0;
+    visit(tree, "list", (node) => {
+        if (node.ordered) {
+            ordered++;
+        }
+        else {
+            unordered++;
+        }
+    });
+    return { total: ordered + unordered, ordered, unordered };
+}
+export async function statsAction(file, opts) {
+    const format = resolveFormat(opts);
+    const filePath = requireFile(file, opts);
+    const shownPath = outputPath(filePath, opts);
+    const document = runtime().workspace.document(filePath);
+    const { tree } = document;
+    const headings = document.headings;
+    const links = document.references;
+    const codeBlocks = extractCodeBlocks(tree);
+    const byDepth = {};
+    for (const h of headings) {
+        byDepth[h.depth] = (byDepth[h.depth] ?? 0) + 1;
+    }
+    const byLang = {};
+    for (const b of codeBlocks) {
+        const lang = b.lang ?? "(none)";
+        byLang[lang] = (byLang[lang] ?? 0) + 1;
+    }
+    const internalLinks = links.filter((l) => !l.isExternal && !l.isImage);
+    const externalLinks = links.filter((l) => l.isExternal);
+    const images = links.filter((l) => l.isImage);
+    const stats = {
+        file: shownPath,
+        wordCount: countWords(tree),
+        headings: { total: headings.length, byDepth },
+        links: {
+            total: links.length,
+            internal: internalLinks.length,
+            external: externalLinks.length,
+            images: images.length,
+        },
+        codeBlocks: { total: codeBlocks.length, byLang },
+        paragraphs: countParagraphs(tree),
+        lists: countLists(tree),
+    };
+    if (format === "json") {
+        process.stdout.write(jsonPayload("md stats", stats, opts));
+        return;
+    }
+    const lines = [];
+    const isHuman = format === "human";
+    const bold = (s) => (isHuman ? `\x1b[1m${s}\x1b[0m` : s);
+    const cyan = (s) => (isHuman ? `\x1b[36m${s}\x1b[0m` : s);
+    lines.push(bold(`Statistics for ${shownPath}`));
+    lines.push("");
+    lines.push(`  ${cyan("Words:")} ${stats.wordCount}`);
+    lines.push(`  ${cyan("Paragraphs:")} ${stats.paragraphs}`);
+    lines.push(`  ${cyan("Headings:")} ${stats.headings.total}`);
+    for (const [depth, count] of Object.entries(stats.headings.byDepth).sort()) {
+        lines.push(`    ${"#".repeat(Number(depth))}: ${count}`);
+    }
+    lines.push(`  ${cyan("Links:")} ${stats.links.total}`);
+    lines.push(`    Internal: ${stats.links.internal}`);
+    lines.push(`    External: ${stats.links.external}`);
+    lines.push(`    Images: ${stats.links.images}`);
+    lines.push(`  ${cyan("Code blocks:")} ${stats.codeBlocks.total}`);
+    for (const [lang, count] of Object.entries(stats.codeBlocks.byLang).sort()) {
+        lines.push(`    ${lang}: ${count}`);
+    }
+    lines.push(`  ${cyan("Lists:")} ${stats.lists.total}`);
+    lines.push(`    Ordered: ${stats.lists.ordered}`);
+    lines.push(`    Unordered: ${stats.lists.unordered}`);
+    process.stdout.write(lines.join("\n") + "\n");
+}
+//# sourceMappingURL=stats.js.map

package/dist/commands/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/commands/stats.ts"],"names":[],"mappings":"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"}

package/dist/commands/structure.d.ts

@@ -0,0 +1,6 @@
+interface StructureOptions {
+    envelope?: boolean;
+    format: string;
+}
+export declare function structureAction(file: string, opts: StructureOptions): Promise<void>;
+export {};