@cairn-tool/cairn 2.0.0

package/dist/commands/structure.js

@@ -0,0 +1,130 @@
+import { visit } from "unist-util-visit";
+import { extractText } 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 collectStructure(tree, content) {
+    const entries = [];
+    visit(tree, "heading", (node) => {
+        const line = node.position?.start.line ?? 0;
+        const text = extractText(node);
+        entries.push({
+            type: "heading",
+            line,
+            endLine: line,
+            detail: `${"#".repeat(node.depth)} ${text}`,
+        });
+    });
+    visit(tree, "code", (node) => {
+        const line = node.position?.start.line ?? 0;
+        const endLine = node.position?.end.line ?? 0;
+        const lang = node.lang ?? "(none)";
+        const lineCount = endLine - line + 1;
+        entries.push({
+            type: "code",
+            line,
+            endLine,
+            detail: `\`\`\`${lang} (${lineCount} lines)`,
+        });
+    });
+    visit(tree, "list", (node) => {
+        const line = node.position?.start.line ?? 0;
+        const endLine = node.position?.end.line ?? 0;
+        const kind = node.ordered ? "ordered" : "unordered";
+        const itemCount = node.children.length;
+        entries.push({
+            type: "list",
+            line,
+            endLine,
+            detail: `${kind} list (${itemCount} items)`,
+        });
+    });
+    // Detect math blocks from raw content (not in AST without remark-math)
+    const lines = content.split("\n");
+    let inDisplayMath = false;
+    let mathStart = 0;
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        if (/^```/.test(l.trimStart())) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock)
+            continue;
+        if (inDisplayMath) {
+            if (l.includes("$$")) {
+                entries.push({
+                    type: "math",
+                    line: mathStart + 1,
+                    endLine: i + 1,
+                    detail: "$$ display math",
+                });
+                inDisplayMath = false;
+            }
+        }
+        else if (l.includes("$$")) {
+            const afterStart = l.substring(l.indexOf("$$") + 2);
+            if (afterStart.includes("$$")) {
+                entries.push({
+                    type: "math",
+                    line: i + 1,
+                    endLine: i + 1,
+                    detail: "$$ inline display math",
+                });
+            }
+            else {
+                inDisplayMath = true;
+                mathStart = i;
+            }
+        }
+    }
+    entries.sort((a, b) => a.line - b.line);
+    return entries;
+}
+export async function structureAction(file, opts) {
+    const format = resolveFormat(opts);
+    const filePath = requireFile(file, opts);
+    const shownPath = outputPath(filePath, opts);
+    const { content, tree } = runtime().workspace.document(filePath);
+    const entries = collectStructure(tree, content);
+    if (format === "json") {
+        process.stdout.write(jsonPayload("md structure", entries, opts));
+        return;
+    }
+    if (entries.length === 0) {
+        if (format === "human") {
+            process.stdout.write(`\x1b[33mNo structure found in ${shownPath}\x1b[0m\n`);
+        }
+        else {
+            process.stdout.write(`No structure found in ${shownPath}\n`);
+        }
+        return;
+    }
+    const lines = [];
+    const isHuman = format === "human";
+    for (const e of entries) {
+        const loc = e.line === e.endLine ? `L${e.line}` : `L${e.line}-${e.endLine}`;
+        if (isHuman) {
+            const typeColor = e.type === "heading"
+                ? "\x1b[33m"
+                : e.type === "code"
+                    ? "\x1b[32m"
+                    : e.type === "math"
+                        ? "\x1b[35m"
+                        : "\x1b[34m";
+            lines.push(`\x1b[36m${loc.padEnd(12)}\x1b[0m ${typeColor}${e.detail}\x1b[0m`);
+        }
+        else {
+            lines.push(`${loc.padEnd(12)} ${e.detail}`);
+        }
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+}
+//# sourceMappingURL=structure.js.map

package/dist/commands/structure.js.map

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

package/dist/commands/tables.d.ts

@@ -0,0 +1,8 @@
+interface TablesOptions {
+    envelope?: boolean;
+    format: string;
+    content: boolean;
+    index?: string;
+}
+export declare function tablesAction(file: string, opts: TablesOptions): Promise<void>;
+export {};

package/dist/commands/tables.js

@@ -0,0 +1,77 @@
+import { extractTables } from "../markdown-ast.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 tablesAction(file, opts) {
+    const format = resolveFormat(opts);
+    const filePath = requireFile(file, opts);
+    const shownPath = outputPath(filePath, opts);
+    let tables = extractTables(runtime().workspace.document(filePath).tree);
+    if (opts.index !== undefined) {
+        const idx = parseInt(opts.index, 10);
+        if (isNaN(idx) || idx < 1 || idx > tables.length) {
+            process.stderr.write(`Error: Table index out of range: ${opts.index} (file has ${tables.length} table(s))\n`);
+            terminate(1);
+        }
+        tables = [tables[idx - 1]];
+    }
+    if (format === "json") {
+        const result = tables.map((t) => ({
+            line: t.line,
+            endLine: t.endLine,
+            columns: t.columns,
+            rows: t.rows,
+            align: t.align,
+            headers: t.headers,
+            data: t.data,
+        }));
+        process.stdout.write(jsonPayload("md tables", result, opts));
+        return;
+    }
+    const isHuman = format === "human";
+    const bold = (s) => (isHuman ? `\x1b[1m${s}\x1b[0m` : s);
+    const cyan = (s) => (isHuman ? `\x1b[36m${s}\x1b[0m` : s);
+    if (tables.length === 0) {
+        if (isHuman) {
+            process.stdout.write(`\x1b[33mNo tables found in ${shownPath}\x1b[0m\n`);
+        }
+        else {
+            process.stdout.write(`No tables found in ${shownPath}\n`);
+        }
+        return;
+    }
+    const lines = [];
+    lines.push(bold(`${tables.length} table(s) in ${shownPath}:`));
+    for (const t of tables) {
+        lines.push(`  ${cyan(`L${t.line}-L${t.endLine}`)}   ${t.columns} columns x ${t.rows} rows`);
+        if (opts.content) {
+            const colWidths = t.headers.map((h, i) => {
+                let max = h.length;
+                for (const row of t.data) {
+                    if (row[i] && row[i].length > max)
+                        max = row[i].length;
+                }
+                return max;
+            });
+            const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+            const headerLine = "| " + t.headers.map((h, i) => pad(h, colWidths[i])).join(" | ") + " |";
+            const sepLine = "|" + colWidths.map((w) => "-".repeat(w + 2)).join("|") + "|";
+            lines.push(`    ${headerLine}`);
+            lines.push(`    ${sepLine}`);
+            for (const row of t.data) {
+                const rowLine = "| " + row.map((c, i) => pad(c, colWidths[i])).join(" | ") + " |";
+                lines.push(`    ${rowLine}`);
+            }
+            lines.push("");
+        }
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+}
+//# sourceMappingURL=tables.js.map

package/dist/commands/tables.js.map

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

package/dist/commands/tasks.d.ts

@@ -0,0 +1,8 @@
+interface TasksOptions {
+    envelope?: boolean;
+    format: string;
+    status?: string;
+    summary: boolean;
+}
+export declare function tasksAction(file: string, opts: TasksOptions): Promise<void>;
+export {};

package/dist/commands/tasks.js

@@ -0,0 +1,59 @@
+import { extractTasks } 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";
+}
+export async function tasksAction(file, opts) {
+    const format = resolveFormat(opts);
+    const filePath = requireFile(file, opts);
+    const shownPath = outputPath(filePath, opts);
+    let tasks = extractTasks(runtime().workspace.document(filePath).tree);
+    if (opts.status === "done") {
+        tasks = tasks.filter((t) => t.checked);
+    }
+    else if (opts.status === "pending") {
+        tasks = tasks.filter((t) => !t.checked);
+    }
+    const done = tasks.filter((t) => t.checked).length;
+    const pending = tasks.filter((t) => !t.checked).length;
+    const total = tasks.length;
+    if (format === "json") {
+        const result = { file: shownPath, total, done, pending };
+        if (!opts.summary) {
+            result.tasks = tasks.map((t) => ({ line: t.line, checked: t.checked, text: t.text }));
+        }
+        process.stdout.write(jsonPayload("md tasks", result, opts));
+        return;
+    }
+    const isHuman = format === "human";
+    const bold = (s) => (isHuman ? `\x1b[1m${s}\x1b[0m` : s);
+    const green = (s) => (isHuman ? `\x1b[32m${s}\x1b[0m` : s);
+    const yellow = (s) => (isHuman ? `\x1b[33m${s}\x1b[0m` : s);
+    if (opts.summary) {
+        const pct = total > 0 ? Math.round((done / total) * 100) : 0;
+        process.stdout.write(bold(`${total} task(s) in ${shownPath}:`) + ` ${done} done, ${pending} pending (${pct}%)\n`);
+        return;
+    }
+    if (total === 0) {
+        if (isHuman) {
+            process.stdout.write(`\x1b[33mNo tasks found in ${shownPath}\x1b[0m\n`);
+        }
+        else {
+            process.stdout.write(`No tasks found in ${shownPath}\n`);
+        }
+        return;
+    }
+    const lines = [];
+    lines.push(bold(`${total} task(s) in ${shownPath} (${done} done, ${pending} pending):`));
+    for (const t of tasks) {
+        const marker = t.checked ? green("[x]") : yellow("[ ]");
+        lines.push(`  L${t.line}  ${marker} ${t.text}`);
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+}
+//# sourceMappingURL=tasks.js.map

package/dist/commands/tasks.js.map

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

package/dist/commands/toc.d.ts

@@ -0,0 +1,18 @@
+export interface TocOptions {
+    envelope?: boolean;
+    format: string;
+    maxDepth: string;
+    minDepth: string;
+    ordered: boolean;
+    check?: boolean;
+    write?: boolean;
+    dryRun?: boolean;
+}
+export declare function tocSynchronizationIssue(filePath: string, opts: TocOptions): {
+    issue?: string;
+    malformed?: string;
+    replacement?: string;
+    block?: string;
+    current: boolean;
+};
+export declare function tocAction(file: string, opts: TocOptions): Promise<void>;

package/dist/commands/toc.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import { outputPath, runtime } from "../runtime.js";
+import { requireFile } from "../input.js";
+import { terminate } from "../command-result.js";
+import { renderToc, synchronizeToc } from "../toc.js";
+import { extractCodeBlocks } from "../markdown-ast.js";
+import { jsonPayload } from "../result.js";
+function resolveFormat(opts) {
+    return opts.format === "human" || opts.format === "json" ? opts.format : "llm";
+}
+export function tocSynchronizationIssue(filePath, opts) {
+    const document = runtime().workspace.document(filePath);
+    const maxDepth = Math.min(6, Math.max(1, parseInt(opts.maxDepth, 10) || 6));
+    const minDepth = Math.min(6, Math.max(1, parseInt(opts.minDepth, 10) || 1));
+    const headings = document.headings.filter((heading) => heading.depth >= minDepth && heading.depth <= maxDepth);
+    const sync = synchronizeToc(document.content, renderToc(headings, opts.ordered), extractCodeBlocks(document.tree));
+    if (sync.status === "missing")
+        return { issue: "TOC markers are missing", current: false };
+    if (sync.status === "malformed")
+        return { malformed: sync.message, current: false };
+    if (sync.status === "current")
+        return { block: sync.block, current: true };
+    return {
+        issue: "Generated TOC is stale",
+        replacement: sync.replacement,
+        block: sync.block,
+        current: false,
+    };
+}
+export async function tocAction(file, opts) {
+    const format = resolveFormat(opts);
+    const filePath = requireFile(file, opts);
+    const shownPath = outputPath(filePath, opts);
+    const explicitModes = [
+        process.argv.includes("--check") ? "check" : undefined,
+        process.argv.includes("--write") ? "write" : undefined,
+        process.argv.includes("--dry-run") ? "dryRun" : undefined,
+    ].filter((mode) => mode !== undefined);
+    if (explicitModes.length > 1) {
+        throw new Error("--check, --write, and --dry-run are mutually exclusive");
+    }
+    const selected = explicitModes[0];
+    const check = selected ? selected === "check" : opts.check;
+    const write = selected ? selected === "write" : opts.write;
+    const dryRun = selected ? selected === "dryRun" : opts.dryRun;
+    const modes = [check, write, dryRun].filter(Boolean).length;
+    if (modes > 1)
+        throw new Error("--check, --write, and --dry-run are mutually exclusive");
+    if (modes) {
+        const result = tocSynchronizationIssue(filePath, opts);
+        if (result.malformed)
+            throw new Error(`${shownPath}: ${result.malformed}`);
+        if ((write || dryRun) && !result.block)
+            throw new Error(`${shownPath}: TOC markers are missing`);
+        if (write) {
+            if (result.replacement !== undefined) {
+                fs.writeFileSync(filePath, result.replacement);
+                runtime().workspace.invalidate(filePath);
+            }
+            const payload = format === "json"
+                ? jsonPayload("md toc", { file: shownPath, changed: result.replacement !== undefined }, opts)
+                : `${result.replacement !== undefined ? "Updated" : "TOC already current in"} ${shownPath}\n`;
+            process.stdout.write(payload);
+            return;
+        }
+        if (dryRun) {
+            if (format === "json")
+                process.stdout.write(jsonPayload("md toc", { file: shownPath, changed: !result.current, block: result.block }, opts));
+            else
+                process.stdout.write(result.block + "\n");
+            return;
+        }
+        const payload = format === "json"
+            ? jsonPayload("md toc", { file: shownPath, current: result.current, issue: result.issue ?? null }, opts, { exitCode: result.current ? 0 : 2 }).trimEnd()
+            : result.current
+                ? `TOC is current in ${shownPath}`
+                : `${result.issue} in ${shownPath}`;
+        (result.current ? process.stdout : process.stderr).write(payload + "\n");
+        if (!result.current)
+            terminate(2);
+        return;
+    }
+    const maxDepth = Math.min(6, Math.max(1, parseInt(opts.maxDepth, 10) || 6));
+    const minDepth = Math.min(6, Math.max(1, parseInt(opts.minDepth, 10) || 1));
+    const headings = runtime()
+        .workspace.document(filePath)
+        .headings.filter((heading) => heading.depth >= minDepth && heading.depth <= maxDepth);
+    if (format === "json") {
+        process.stdout.write(jsonPayload("md toc", headings.map((heading) => ({
+            text: heading.text,
+            slug: heading.slug,
+            depth: heading.depth,
+            line: heading.line,
+        })), opts));
+        return;
+    }
+    if (!headings.length) {
+        process.stdout.write(format === "human"
+            ? `\x1b[33mNo headings found in ${shownPath}\x1b[0m\n`
+            : `No headings found in ${shownPath}\n`);
+        return;
+    }
+    process.stdout.write(renderToc(headings, opts.ordered) + "\n");
+}
+//# sourceMappingURL=toc.js.map

package/dist/commands/toc.js.map

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

package/dist/commands/update-check.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolves the latest published version via `npm view`.
+ *
+ * Shelling out to npm rather than querying the registry directly is deliberate.
+ * The package is public on registry.npmjs.org, but plenty of installs sit behind
+ * a mirror or a proxy, so the request needs npm's own resolution of
+ * `@scope:registry`, `registry`, and `_authToken` across the project and user
+ * .npmrc files plus environment overrides. Reimplementing that is a large
+ * surface to get wrong for no gain.
+ */
+export declare function fetchLatestVersion(packageName: string): Promise<string | null>;
+/**
+ * Refreshes the cached latest version. Run in a detached child process, so it
+ * must never throw and never write to stdout/stderr.
+ */
+export declare function refreshUpdateCacheAction(packageName: string): Promise<void>;
+interface CheckUpdateOptions {
+    format: string;
+    envelope?: boolean;
+}
+/** Seams for testing; every field defaults to the real implementation. */
+export interface CheckUpdateDeps {
+    fetchLatest?: (packageName: string) => Promise<string | null>;
+    cachePath?: string;
+    now?: () => number;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+    exit?: (code: number) => void;
+}
+/**
+ * User-facing `check-update`. Always queries the registry — an explicit request
+ * should never be answered from a cache that may be up to 24h old — but it does
+ * refresh that cache so the passive notifier stays consistent.
+ */
+export declare function checkUpdateAction(packageName: string, currentVersion: string, opts: CheckUpdateOptions, deps?: CheckUpdateDeps): Promise<void>;
+export {};

package/dist/commands/update-check.js

@@ -0,0 +1,119 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getCachePath, getLockPath, isNewerVersion, readCache, releaseRefreshLock, writeCache, } from "../update-notifier.js";
+import { jsonPayload } from "../result.js";
+const exec = promisify(execFile);
+const FETCH_TIMEOUT_MS = 20_000;
+/**
+ * Resolves the latest published version via `npm view`.
+ *
+ * Shelling out to npm rather than querying the registry directly is deliberate.
+ * The package is public on registry.npmjs.org, but plenty of installs sit behind
+ * a mirror or a proxy, so the request needs npm's own resolution of
+ * `@scope:registry`, `registry`, and `_authToken` across the project and user
+ * .npmrc files plus environment overrides. Reimplementing that is a large
+ * surface to get wrong for no gain.
+ */
+export async function fetchLatestVersion(packageName) {
+    try {
+        const { stdout } = await exec("npm", ["view", packageName, "version", "--json"], {
+            timeout: FETCH_TIMEOUT_MS,
+            windowsHide: true,
+        });
+        const parsed = JSON.parse(stdout.trim());
+        if (typeof parsed === "string")
+            return parsed;
+        // `npm view` returns an array when several versions match.
+        if (Array.isArray(parsed)) {
+            const last = parsed[parsed.length - 1];
+            return typeof last === "string" ? last : null;
+        }
+        return null;
+    }
+    catch {
+        // Offline, unauthenticated, npm missing, package unpublished — all the same
+        // to us. The caller still records the attempt so it backs off for 24h.
+        return null;
+    }
+}
+/**
+ * Refreshes the cached latest version. Run in a detached child process, so it
+ * must never throw and never write to stdout/stderr.
+ */
+export async function refreshUpdateCacheAction(packageName) {
+    const cachePath = getCachePath();
+    try {
+        const previous = readCache(cachePath);
+        const latest = await fetchLatestVersion(packageName);
+        writeCache(cachePath, {
+            lastCheckedAt: Date.now(),
+            // Keep the previous answer on failure rather than dropping a valid notice.
+            latestVersion: latest ?? previous?.latestVersion ?? null,
+        });
+    }
+    finally {
+        // The parent holds the lock on our behalf; release it however we exit.
+        releaseRefreshLock(getLockPath(cachePath));
+    }
+}
+function resolveFormat(opts) {
+    const fmt = opts.format;
+    if (fmt === "llm" || fmt === "human" || fmt === "json")
+        return fmt;
+    return "llm";
+}
+/**
+ * User-facing `check-update`. Always queries the registry — an explicit request
+ * should never be answered from a cache that may be up to 24h old — but it does
+ * refresh that cache so the passive notifier stays consistent.
+ */
+export async function checkUpdateAction(packageName, currentVersion, opts, deps = {}) {
+    const fetchLatest = deps.fetchLatest ?? fetchLatestVersion;
+    const cachePath = deps.cachePath ?? getCachePath();
+    const now = deps.now ?? Date.now;
+    const stdout = deps.stdout ?? ((t) => void process.stdout.write(t));
+    const stderr = deps.stderr ?? ((t) => void process.stderr.write(t));
+    const exit = deps.exit ?? ((c) => void (process.exitCode = c));
+    const format = resolveFormat(opts);
+    const latest = await fetchLatest(packageName);
+    if (latest === null) {
+        if (format === "json") {
+            stderr(jsonPayload("check-update", {
+                current: currentVersion,
+                latest: null,
+                updateAvailable: false,
+                error: "Could not resolve the latest version",
+            }, opts, { exitCode: 1 }));
+        }
+        else {
+            stderr(`Error: Could not resolve the latest published version of ${packageName}.\n` +
+                `Check your network connection and that ~/.npmrc grants read access to the registry.\n`);
+        }
+        exit(1);
+        return;
+    }
+    // Record the fresh answer so the background check does not immediately redo it.
+    writeCache(cachePath, { lastCheckedAt: now(), latestVersion: latest });
+    const updateAvailable = isNewerVersion(latest, currentVersion);
+    if (format === "json") {
+        stdout(jsonPayload("check-update", { current: currentVersion, latest, updateAvailable }, opts, {
+            exitCode: updateAvailable ? 2 : 0,
+        }));
+    }
+    else if (updateAvailable) {
+        stdout(format === "human"
+            ? `\x1b[33mUpdate available\x1b[0m \x1b[2m${currentVersion}\x1b[0m → \x1b[1m${latest}\x1b[0m\n` +
+                `\x1b[2mRun\x1b[0m npm install -g ${packageName} \x1b[2mto update.\x1b[0m\n`
+            : `Update available: ${currentVersion} -> ${latest}\n` +
+                `Run: npm install -g ${packageName}\n`);
+    }
+    else {
+        stdout(format === "human"
+            ? `\x1b[32m✔ ${packageName} ${currentVersion} is up to date\x1b[0m\n`
+            : `${packageName} ${currentVersion} is up to date\n`);
+    }
+    // Consistent with the rest of the CLI: 2 means "actionable finding".
+    if (updateAvailable)
+        exit(2);
+}
+//# sourceMappingURL=update-check.js.map

package/dist/commands/update-check.js.map

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