@cairn-tool/cairn 2.0.0

package/dist/scripts/execute.js

@@ -0,0 +1,235 @@
+import os from "node:os";
+import { spawn } from "node:child_process";
+/**
+ * Runs a resolved script.
+ *
+ * This is the only module in the tool that executes anything, and the shape of
+ * both forms is chosen to keep argument content out of anything that gets
+ * re-parsed. `exec:` hands an argv array straight to `execve`. `run:` passes the
+ * body to `sh -c` and the forwarded arguments as *separate* argv entries, which
+ * the shell binds to `$1…$n` without ever lexing them as source — so an argument
+ * containing `; rm -rf ~` is one inert positional parameter. Building a command
+ * line by interpolating arguments into the body, or reaching for
+ * `spawn(cmd, { shell: true })`, would give that guarantee away.
+ */
+/** POSIX default. Not `$SHELL`: a login shell may be fish or csh, neither of
+ * which binds positional parameters for `-c`, which would make a registry
+ * behave differently on different machines — the exact problem this feature
+ * exists to solve. */
+const DEFAULT_SHELL = "/bin/sh";
+/** Captured output past this is dropped, but still drained. */
+const MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
+/** Deep enough for real composition, shallow enough to stop a runaway. */
+export const MAX_SCRIPT_DEPTH = 8;
+const DEPTH_VARIABLE = "CAIRN_SCRIPT_DEPTH";
+const STACK_VARIABLE = "CAIRN_SCRIPT_STACK";
+const LEGACY_DEPTH_VARIABLE = "CLAUDE_CLI_SCRIPT_DEPTH";
+const LEGACY_STACK_VARIABLE = "CLAUDE_CLI_SCRIPT_STACK";
+/** `$1`, `${1}`, `$@`, `$*` — any reference to a positional parameter. */
+const POSITIONAL_PARAMETER = /\$\{?[0-9@*]/;
+// Both spellings are read as well as written. A script from before the rename
+// may re-export only the legacy variable, and reading just the current one there
+// would reset the counter to zero and defeat the recursion guard entirely.
+function currentDepth(env = process.env) {
+    const parsed = Number.parseInt(env[DEPTH_VARIABLE] ?? env[LEGACY_DEPTH_VARIABLE] ?? "0", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+function currentStack(env = process.env) {
+    const raw = env[STACK_VARIABLE] ?? env[LEGACY_STACK_VARIABLE];
+    return raw ? raw.split("\n").filter(Boolean) : [];
+}
+function frameFor(execution) {
+    return `${execution.registry.file}#${execution.definition.name}`;
+}
+/**
+ * The child's environment.
+ *
+ * Every variable is exported under both the current and the pre-rename spelling.
+ * A script is user code this tool does not get to edit, so one already reading
+ * `CLAUDE_CLI_SCRIPT_ROOT` has to keep working; duplicating six variables is the
+ * cheap half of that bargain.
+ */
+export function scriptEnvironment(execution) {
+    const depth = String(currentDepth() + 1);
+    const stack = [...currentStack(), frameFor(execution)].join("\n");
+    return {
+        ...process.env,
+        CAIRN_SCRIPT_NAME: execution.definition.name,
+        CAIRN_SCRIPT_ROOT: execution.registry.directory,
+        CAIRN_SCRIPT_REGISTRY: execution.registry.file,
+        CAIRN_INVOKED_FROM: execution.invokedFrom,
+        [DEPTH_VARIABLE]: depth,
+        [STACK_VARIABLE]: stack,
+        CLAUDE_CLI_SCRIPT_NAME: execution.definition.name,
+        CLAUDE_CLI_SCRIPT_ROOT: execution.registry.directory,
+        CLAUDE_CLI_SCRIPT_REGISTRY: execution.registry.file,
+        CLAUDE_CLI_INVOKED_FROM: execution.invokedFrom,
+        [LEGACY_DEPTH_VARIABLE]: depth,
+        [LEGACY_STACK_VARIABLE]: stack,
+        // A nested `cairn` must not write an update notice into a stream the outer
+        // hook is capturing. The argv gate in src/update-notifier.ts covers this
+        // invocation; this covers every one the script makes.
+        CAIRN_NO_UPDATE_NOTIFIER: "1",
+        CLAUDE_CLI_NO_UPDATE_NOTIFIER: "1",
+    };
+}
+/**
+ * Refuses a script that is already running.
+ *
+ * This is a footgun guard, not a security control — a script can clear either
+ * variable. It exists so a self-referential definition fails immediately instead
+ * of forking until something else gives out.
+ */
+export function checkRecursionDepth(execution) {
+    if (currentStack().includes(frameFor(execution))) {
+        throw new Error(`Script recursion detected: '${execution.definition.name}' is already running from ${execution.registry.file}`);
+    }
+    if (currentDepth() >= MAX_SCRIPT_DEPTH) {
+        throw new Error(`Script recursion limit exceeded (${MAX_SCRIPT_DEPTH}): '${execution.definition.name}'`);
+    }
+}
+/**
+ * The program and argv for one script.
+ *
+ * Exported for the unit tests, which assert the exact argv rather than
+ * inspecting behavior through a child process.
+ */
+export function spawnPlan(execution) {
+    const { definition, args } = execution;
+    if (definition.exec) {
+        return { command: definition.exec[0], argv: [...definition.exec.slice(1), ...args] };
+    }
+    const body = definition.run;
+    if (process.platform === "win32") {
+        // cmd.exe has no positional-parameter mechanism, and emulating one means
+        // splicing caller-supplied text into a command line.
+        if (args.length > 0) {
+            throw new Error(`Script '${definition.name}' uses run: and cannot forward arguments on Windows; use exec:`);
+        }
+        const shell = definition.shell ?? process.env.ComSpec ?? "cmd.exe";
+        return { command: shell, argv: ["/d", "/s", "/c", body] };
+    }
+    if (args.length > 0 && !POSITIONAL_PARAMETER.test(body)) {
+        throw new Error(`scripts.${definition.name}.run takes no positional parameters; add "$@" to forward arguments`);
+    }
+    // `$0` is the script name rather than `sh`, so `set -u` and syntax errors name
+    // the script a reader can find.
+    return {
+        command: definition.shell ?? DEFAULT_SHELL,
+        argv: ["-c", body, definition.name, ...args],
+    };
+}
+function collect(stream, onDone) {
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    stream.on("data", (chunk) => {
+        // Past the cap the data is dropped but the stream keeps flowing: pausing it
+        // fills the OS pipe buffer and deadlocks the child.
+        if (size < MAX_CAPTURE_BYTES) {
+            chunks.push(chunk);
+            size += chunk.length;
+        }
+        else {
+            truncated = true;
+        }
+    });
+    stream.on("end", () => onDone(Buffer.concat(chunks).toString("utf-8"), truncated));
+}
+export async function executeScript(execution) {
+    checkRecursionDepth(execution);
+    const plan = spawnPlan(execution);
+    const capture = execution.mode === "capture";
+    const started = Date.now();
+    return await new Promise((resolve) => {
+        // stdin is inherited in both modes: a hook piping a payload into a script is
+        // ordinary, and stdin is never part of the captured output.
+        const child = spawn(plan.command, plan.argv, {
+            cwd: execution.workingDirectory,
+            env: scriptEnvironment(execution),
+            stdio: capture ? ["inherit", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
+            shell: false,
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncatedOut = false;
+        let truncatedErr = false;
+        let pending = 0;
+        let closed;
+        let settled = false;
+        // Forwarded without exiting, so the parent survives long enough to write its
+        // payload. `once` means a second interrupt reaches Node's default handler,
+        // so a child that ignores SIGINT cannot make this process unkillable.
+        const forward = (signal) => () => child.kill(signal);
+        const onInterrupt = forward("SIGINT");
+        const onTerminate = forward("SIGTERM");
+        process.once("SIGINT", onInterrupt);
+        process.once("SIGTERM", onTerminate);
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            process.removeListener("SIGINT", onInterrupt);
+            process.removeListener("SIGTERM", onTerminate);
+            resolve({ ...outcome, durationMs: Date.now() - started });
+        };
+        const finish = () => {
+            if (!closed || pending > 0)
+                return;
+            settle({
+                code: closed.code,
+                signal: closed.signal,
+                ...(capture
+                    ? { stdout, stderr, truncated: { stdout: truncatedOut, stderr: truncatedErr } }
+                    : {}),
+            });
+        };
+        if (capture && child.stdout && child.stderr) {
+            pending = 2;
+            collect(child.stdout, (text, truncated) => {
+                stdout = text;
+                truncatedOut = truncated;
+                pending--;
+                finish();
+            });
+            collect(child.stderr, (text, truncated) => {
+                stderr = text;
+                truncatedErr = truncated;
+                pending--;
+                finish();
+            });
+        }
+        // ENOENT, EACCES, or a rejected argument. Both `error` and `close` can fire;
+        // `settled` keeps the first one authoritative.
+        child.on("error", (error) => {
+            settle({
+                code: null,
+                signal: null,
+                startupError: error.message,
+                ...(capture ? { stdout, stderr, truncated: { stdout: false, stderr: false } } : {}),
+            });
+        });
+        child.on("close", (code, signal) => {
+            closed = { code, signal };
+            finish();
+        });
+    });
+}
+/**
+ * The status this process exits with when it passes the child's through.
+ *
+ * A bare `code & 0xff` would map 256 to 0, reporting success for a child that
+ * failed, so an out-of-range code that truncates to zero becomes 1 instead.
+ */
+export function exitStatusFor(outcome) {
+    if (outcome.startupError)
+        return 1;
+    if (outcome.signal)
+        return 128 + (os.constants.signals[outcome.signal] ?? 0);
+    const code = outcome.code ?? 1;
+    if (code >= 0 && code <= 255)
+        return code;
+    return code & 0xff || 1;
+}
+//# sourceMappingURL=execute.js.map

package/dist/scripts/execute.js.map

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

package/dist/scripts/registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Parsing and validation for the `scripts:` block of a `.cairn.yml` file.
+ *
+ * This module is deliberately pure — no filesystem access, no child process, no
+ * knowledge of how a configuration file is discovered. That seam is what lets
+ * `loadConfig`, which reads only the nearest file, and the chain walk in
+ * `./resolve.ts`, which reads several, share one validator. It also keeps
+ * `node:child_process` off the import path of every command that merely loads
+ * configuration.
+ */
+/** Where the child process runs. `path` is registry-relative. */
+export type ScriptCwd = {
+    kind: "registry";
+} | {
+    kind: "invocation";
+} | {
+    kind: "path";
+    value: string;
+};
+export interface ScriptDefinition {
+    name: string;
+    description?: string;
+    /** Exactly one of `run` and `exec` is set; the parser guarantees the xor. */
+    run?: string;
+    exec?: readonly string[];
+    /** Shell for `run`, defaulting to `/bin/sh`. Ignored for `exec`. */
+    shell?: string;
+    cwd: ScriptCwd;
+}
+export interface ScriptRegistry {
+    /** Absolute path of the `.cairn.yml` that declared these scripts. */
+    file: string;
+    /** Directory of that file; the default working directory for its scripts. */
+    directory: string;
+    /** Declaration order preserved. */
+    scripts: ReadonlyMap<string, ScriptDefinition>;
+}
+/**
+ * Names are restricted to what reads unambiguously on a command line and in a
+ * hook definition: no path separators, no `..`, no shell metacharacters, no
+ * leading or trailing punctuation.
+ */
+export declare const SCRIPT_NAME: RegExp;
+export declare const MAX_SCRIPT_NAME_LENGTH = 64;
+export declare function emptyRegistry(file: string, directory: string): ScriptRegistry;
+/**
+ * Validates an already-parsed `scripts:` value.
+ *
+ * An absent block yields an empty registry rather than throwing, so a
+ * configuration file with no scripts is not a special case at either call site.
+ */
+export declare function parseScriptsBlock(value: unknown, context: {
+    file: string;
+    directory: string;
+}): ScriptRegistry;

package/dist/scripts/registry.js

@@ -0,0 +1,103 @@
+import { knownKeys, object, optionalString } from "../config-schema.js";
+/**
+ * Names are restricted to what reads unambiguously on a command line and in a
+ * hook definition: no path separators, no `..`, no shell metacharacters, no
+ * leading or trailing punctuation.
+ */
+export const SCRIPT_NAME = /^[a-z0-9](?:[a-z0-9._:-]*[a-z0-9])?$/;
+export const MAX_SCRIPT_NAME_LENGTH = 64;
+const SCRIPT_KEYS = new Set(["run", "exec", "shell", "cwd", "description"]);
+/** Reserved `cwd:` values; anything else is a registry-relative path. */
+const CWD_REGISTRY = "registry";
+const CWD_INVOCATION = "invocation";
+export function emptyRegistry(file, directory) {
+    return { file, directory, scripts: new Map() };
+}
+function execArgv(value, name) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`${name} must be a list of strings`);
+    }
+    const argv = [...value];
+    if (argv.length === 0)
+        throw new Error(`${name} must be a non-empty list of strings`);
+    if (argv[0].length === 0)
+        throw new Error(`${name}[0] must be a non-empty program name`);
+    // A NUL byte makes `spawn` throw a TypeError from deep inside libuv rather
+    // than reporting which script is at fault.
+    if (argv.some((item) => item.includes("\0"))) {
+        throw new Error(`${name} must not contain NUL bytes`);
+    }
+    return argv;
+}
+function scriptCwd(value, name) {
+    const raw = optionalString(value, name);
+    if (raw === undefined || raw === CWD_REGISTRY)
+        return { kind: "registry" };
+    if (raw === CWD_INVOCATION)
+        return { kind: "invocation" };
+    if (raw.length === 0)
+        throw new Error(`${name} must be a non-empty string`);
+    // Containment of the resolved directory is enforced in `./resolve.ts`; this
+    // only rejects the spelling that could never be meant relatively.
+    if (raw.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(raw)) {
+        throw new Error(`${name} must be relative to the registry`);
+    }
+    return { kind: "path", value: raw };
+}
+function scriptDefinition(name, value) {
+    const label = `scripts.${name}`;
+    const entry = object(value, label);
+    knownKeys(entry, SCRIPT_KEYS, label);
+    const hasRun = entry.run !== undefined;
+    const hasExec = entry.exec !== undefined;
+    if (hasRun === hasExec) {
+        throw new Error(`${label} must set exactly one of run or exec`);
+    }
+    const definition = {
+        name,
+        cwd: scriptCwd(entry.cwd, `${label}.cwd`),
+    };
+    const description = optionalString(entry.description, `${label}.description`);
+    if (description !== undefined)
+        definition.description = description;
+    if (hasRun) {
+        const run = optionalString(entry.run, `${label}.run`);
+        if (!run || run.trim().length === 0) {
+            throw new Error(`${label}.run must be a non-empty string`);
+        }
+        definition.run = run;
+        const shell = optionalString(entry.shell, `${label}.shell`);
+        if (shell !== undefined) {
+            if (shell.length === 0)
+                throw new Error(`${label}.shell must be a non-empty string`);
+            definition.shell = shell;
+        }
+    }
+    else {
+        if (entry.shell !== undefined) {
+            throw new Error(`${label}.shell applies to run, not exec`);
+        }
+        definition.exec = execArgv(entry.exec, `${label}.exec`);
+    }
+    return definition;
+}
+/**
+ * Validates an already-parsed `scripts:` value.
+ *
+ * An absent block yields an empty registry rather than throwing, so a
+ * configuration file with no scripts is not a special case at either call site.
+ */
+export function parseScriptsBlock(value, context) {
+    if (value === undefined)
+        return emptyRegistry(context.file, context.directory);
+    const block = object(value, "scripts");
+    const scripts = new Map();
+    for (const [name, entry] of Object.entries(block)) {
+        if (name.length > MAX_SCRIPT_NAME_LENGTH || !SCRIPT_NAME.test(name)) {
+            throw new Error(`Invalid script name: ${name}`);
+        }
+        scripts.set(name, scriptDefinition(name, entry));
+    }
+    return { file: context.file, directory: context.directory, scripts };
+}
+//# sourceMappingURL=registry.js.map

package/dist/scripts/registry.js.map

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

package/dist/scripts/resolve.d.ts

@@ -0,0 +1,90 @@
+import type { ConfigSelection } from "../config.js";
+import type { ScriptDefinition, ScriptRegistry } from "./registry.js";
+export type ScriptBoundaryKind = "explicit-root" | "git-root" | "nearest-config" | "single-config" | "disabled";
+export interface ScriptBoundary {
+    /** Absolute and symlink-resolved. The walk never reads above this directory. */
+    directory: string;
+    kind: ScriptBoundaryKind;
+}
+export interface ScriptsWalkOptions {
+    /** Invocation directory; defaults to the process working directory. */
+    cwd?: string;
+    /** `--root <dir>`, resolved against `cwd` by the caller. */
+    root?: string;
+    /** `--config` / `--no-config`, as parsed by `selectConfig`. */
+    selection?: ConfigSelection;
+}
+export type ConsultedStatus = 
+/** Declares the requested name — the winner, or a shadowed definition. */
+"defines"
+/** Parsed and has a `scripts:` block, but not the requested name. */
+ | "declares"
+/** Parsed, with no `scripts:` block at all. */
+ | "no-scripts"
+/** Unreadable YAML, or a `scripts:` block that failed validation. */
+ | "invalid"
+/** Failed a read guard, or sits under `node_modules`. */
+ | "skipped";
+export interface ConsultedFile {
+    file: string;
+    directory: string;
+    /** Directory levels above the invocation directory; 0 is the directory itself. */
+    distance: number;
+    status: ConsultedStatus;
+    /** Set for `invalid` and `skipped`. */
+    reason?: string;
+    /** Script names the file declares, sorted. Empty unless it parsed. */
+    names: string[];
+}
+export interface ScriptWinner {
+    definition: ScriptDefinition;
+    registry: ScriptRegistry;
+    /** Absolute, resolved, and already checked against the boundary. */
+    workingDirectory: string;
+}
+export interface ShadowedDefinition {
+    file: string;
+    directory: string;
+    description?: string;
+}
+export interface ScriptResolution {
+    name: string;
+    boundary: ScriptBoundary;
+    invokedFrom: string;
+    /** Nearest first — exactly the files the walk opened. */
+    consulted: ConsultedFile[];
+    winner?: ScriptWinner;
+    /** Files that also define the name but lost, nearest first. */
+    shadowed: ShadowedDefinition[];
+}
+export interface ScriptListingEntry {
+    name: string;
+    description?: string;
+    form: "run" | "exec";
+    run?: string;
+    exec?: readonly string[];
+    shell?: string;
+    file: string;
+    directory: string;
+    workingDirectory: string;
+    /** Files whose same-named definition this one shadows. */
+    shadows: string[];
+}
+export interface ScriptListing {
+    boundary: ScriptBoundary;
+    invokedFrom: string;
+    consulted: ConsultedFile[];
+    scripts: ScriptListingEntry[];
+}
+export declare function resolveBoundary(options?: ScriptsWalkOptions): ScriptBoundary;
+export declare function resolveScript(name: string, options?: ScriptsWalkOptions): ScriptResolution;
+/**
+ * The first invalid file that could have changed the answer, if any.
+ *
+ * A file farther from the invocation directory than the winner cannot have won,
+ * so it must not break the run. A nearer one might have defined the name, and
+ * running the wrong script is precisely the failure this design exists to
+ * prevent.
+ */
+export declare function shadowingFailure(resolution: ScriptResolution): ConsultedFile | undefined;
+export declare function listScripts(options?: ScriptsWalkOptions): ScriptListing;