sandstream-kit 1.0.0

package/dist/triage-sandbox.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Triage sandbox — behavioral analysis for npm packages without executing them.
+ *
+ * Complements the bumblebee catalog (known compromises) and the existing
+ * triage script (registry metadata). This module pulls the tarball, inspects
+ * it offline, and flags risk signals that frequently appear in supply-chain
+ * attacks but are absent from npm-registry metadata.
+ *
+ * Risk signals:
+ *   - install scripts (preinstall / install / postinstall) — execution surface
+ *   - postinstall content that resembles obfuscation, base64 blobs,
+ *     network calls, or filesystem reads outside the package root
+ *   - tarball entries that escape the package directory (path traversal)
+ *   - tarball entries marked executable that shouldn't be
+ *
+ * No code from the package is ever executed. All work is read-only on the
+ * downloaded tarball.
+ */
+export interface SandboxFinding {
+    severity: "info" | "warn" | "critical";
+    signal: string;
+    detail: string;
+}
+export interface SandboxResult {
+    package: string;
+    version: string | null;
+    findings: SandboxFinding[];
+    hasInstallScripts: boolean;
+    tarballSize: number;
+}
+/** Inspect an npm package without executing any of its code. */
+export declare function triageNpmSandbox(packageName: string, version?: string): Promise<SandboxResult>;
+/** Cleanup helper if caller wants to drop the extraction tmpdir. */
+export declare function cleanupSandbox(workDir: string): Promise<void>;

package/dist/triage-sandbox.js

@@ -0,0 +1,167 @@
+/**
+ * Triage sandbox — behavioral analysis for npm packages without executing them.
+ *
+ * Complements the bumblebee catalog (known compromises) and the existing
+ * triage script (registry metadata). This module pulls the tarball, inspects
+ * it offline, and flags risk signals that frequently appear in supply-chain
+ * attacks but are absent from npm-registry metadata.
+ *
+ * Risk signals:
+ *   - install scripts (preinstall / install / postinstall) — execution surface
+ *   - postinstall content that resembles obfuscation, base64 blobs,
+ *     network calls, or filesystem reads outside the package root
+ *   - tarball entries that escape the package directory (path traversal)
+ *   - tarball entries marked executable that shouldn't be
+ *
+ * No code from the package is ever executed. All work is read-only on the
+ * downloaded tarball.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile, mkdtemp, readdir, stat, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+const exec = promisify(execFile);
+/** Patterns that frequently appear in malicious lifecycle scripts. */
+const SUSPICIOUS_SCRIPT_PATTERNS = [
+    [/curl|wget|https?:\/\//i, "network call in install script"],
+    [/eval\s*\(/, "eval() in install script"],
+    [/Buffer\.from\([^,)]+,\s*['"]base64/, "base64 blob in install script"],
+    [/\\x[0-9a-f]{2}|\\u[0-9a-f]{4}/, "hex/unicode-escaped string in install script"],
+    [/\.ssh|\.aws|\.env|\.npmrc/, "reads sensitive file in install script"],
+    [/child_process|spawn|exec/, "spawns subprocess in install script"],
+    [/process\.env\.[A-Z]+_TOKEN|process\.env\.[A-Z]+_KEY/, "reads env credential in install script"],
+];
+/** Inspect an npm package without executing any of its code. */
+export async function triageNpmSandbox(packageName, version) {
+    const findings = [];
+    const spec = version ? `${packageName}@${version}` : packageName;
+    // 1. Pull the tarball offline. npm pack writes to cwd; use a tmpdir so we
+    //    can clean up cleanly.
+    const work = await mkdtemp(join(tmpdir(), "kit-triage-"));
+    let tarballPath = "";
+    let tarballSize = 0;
+    try {
+        const { stdout } = await exec("npm", ["pack", spec, "--json", "--silent"], {
+            cwd: work,
+            timeout: 60_000,
+        });
+        const meta = JSON.parse(stdout)[0];
+        tarballPath = join(work, meta.filename);
+        tarballSize = meta.size;
+        if (meta.version)
+            version = meta.version;
+    }
+    catch (err) {
+        return {
+            package: packageName,
+            version: version ?? null,
+            findings: [
+                {
+                    severity: "warn",
+                    signal: "pack failed",
+                    detail: `npm pack ${spec}: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            hasInstallScripts: false,
+            tarballSize: 0,
+        };
+    }
+    // 2. Extract into the same tmpdir for inspection.
+    await exec("tar", ["xzf", tarballPath, "-C", work], { timeout: 30_000 });
+    const pkgRoot = join(work, "package");
+    // 3. Path traversal check — npm packs everything under "package/", anything
+    //    above is malicious.
+    const entries = (await exec("tar", ["tzf", tarballPath], { timeout: 10_000 })).stdout
+        .split("\n")
+        .filter(Boolean);
+    for (const entry of entries) {
+        if (entry.includes("..") || entry.startsWith("/")) {
+            findings.push({
+                severity: "critical",
+                signal: "path traversal",
+                detail: `tarball entry escapes package root: ${entry}`,
+            });
+        }
+    }
+    // 4. Parse package.json for install scripts.
+    let hasInstallScripts = false;
+    let pkgJson = {};
+    try {
+        pkgJson = JSON.parse(await readFile(join(pkgRoot, "package.json"), "utf-8"));
+    }
+    catch {
+        findings.push({
+            severity: "warn",
+            signal: "package.json unreadable",
+            detail: "couldn't parse extracted package.json",
+        });
+    }
+    const lifecycleHooks = ["preinstall", "install", "postinstall"];
+    for (const hook of lifecycleHooks) {
+        const script = pkgJson.scripts?.[hook];
+        if (!script)
+            continue;
+        hasInstallScripts = true;
+        findings.push({
+            severity: "warn",
+            signal: `lifecycle: ${hook}`,
+            detail: `${hook}: ${script}`,
+        });
+        // 5. Scan the actual script file the hook invokes — `node foo.js` etc.
+        for (const [pattern, label] of SUSPICIOUS_SCRIPT_PATTERNS) {
+            if (pattern.test(script)) {
+                findings.push({
+                    severity: "critical",
+                    signal: label,
+                    detail: `${hook} script matches: ${pattern}`,
+                });
+            }
+        }
+    }
+    // 6. World-readable, executable, oddly large files.
+    await walkAndCheck(pkgRoot, findings);
+    return {
+        package: packageName,
+        version: version ?? null,
+        findings,
+        hasInstallScripts,
+        tarballSize,
+    };
+}
+async function walkAndCheck(dir, findings) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules")
+                continue;
+            await walkAndCheck(full, findings);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const st = await stat(full);
+        // Bash/python/Perl scripts dropped at the package root are unusual for
+        // libraries — flag them.
+        if (/\.(sh|py|pl|rb)$/i.test(entry.name)) {
+            findings.push({
+                severity: "warn",
+                signal: "script in package",
+                detail: `${entry.name} (${st.size} bytes)`,
+            });
+        }
+        // 5MB+ single file in a tarball is unusual for JS libs.
+        if (st.size > 5 * 1024 * 1024) {
+            findings.push({
+                severity: "info",
+                signal: "large file",
+                detail: `${entry.name}: ${(st.size / 1024 / 1024).toFixed(1)} MB`,
+            });
+        }
+    }
+}
+/** Cleanup helper if caller wants to drop the extraction tmpdir. */
+export async function cleanupSandbox(workDir) {
+    await rm(workDir, { recursive: true, force: true }).catch(() => { });
+}
+//# sourceMappingURL=triage-sandbox.js.map

package/dist/triage-sandbox.js.map

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

package/dist/triage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Triage — Security evaluation for open source packages, Docker images, skills, and repos.
+ * Wraps the Python triage script and integrates with kit's check-security system.
+ */
+import { triageNpmSandbox, type SandboxResult } from "./triage-sandbox.js";
+export type TriageType = "docker" | "npm" | "pip" | "repo" | "skill" | "all" | "tools";
+export { triageNpmSandbox, type SandboxResult };
+export interface TriageResult {
+    target: string;
+    type: TriageType;
+    passed: boolean;
+    output: string;
+}
+/**
+ * Run triage on a target
+ */
+export declare function runTriage(type: TriageType, target: string): Promise<TriageResult>;
+/**
+ * List available security tools
+ */
+export declare function listTriageTools(): Promise<TriageResult>;
+/**
+ * Parse the triage output for structured data
+ */
+export declare function parseTriageOutput(output: string): {
+    healthScore?: string;
+    criticalIssues: number;
+    warnings: number;
+    sections: string[];
+};

package/dist/triage.js

@@ -0,0 +1,79 @@
+/**
+ * Triage — Security evaluation for open source packages, Docker images, skills, and repos.
+ * Wraps the Python triage script and integrates with kit's check-security system.
+ */
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { triageNpmSandbox } from "./triage-sandbox.js";
+import { exec } from "./utils/exec.js";
+const TRIAGE_SCRIPT = resolve(process.env.HOME || "~", ".claude/skills/triage/scripts/triage.py");
+export { triageNpmSandbox };
+/**
+ * Check if the triage script exists
+ */
+async function ensureTriageScript() {
+    try {
+        await access(TRIAGE_SCRIPT);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run triage on a target
+ */
+export async function runTriage(type, target) {
+    const scriptExists = await ensureTriageScript();
+    if (!scriptExists) {
+        return {
+            target,
+            type,
+            passed: false,
+            output: `Triage script not found at ${TRIAGE_SCRIPT}\nInstall: copy triage skill to ~/.claude/skills/triage/`,
+        };
+    }
+    try {
+        const { stdout, stderr } = await exec("python3", [TRIAGE_SCRIPT, type, target], { timeout: 300_000 } // 5 min for Docker pulls
+        );
+        const output = stdout + (stderr ? `\n${stderr}` : "");
+        const passed = output.includes("TRIAGE PASSED");
+        return { target, type, passed, output };
+    }
+    catch (error) {
+        const err = error;
+        const output = (err.stdout || "") + (err.stderr || "") + (err.message || "");
+        return {
+            target,
+            type,
+            passed: false,
+            output: output || "Triage script execution failed",
+        };
+    }
+}
+/**
+ * List available security tools
+ */
+export async function listTriageTools() {
+    return runTriage("tools", "");
+}
+/**
+ * Parse the triage output for structured data
+ */
+export function parseTriageOutput(output) {
+    const healthMatch = output.match(/Health score: (\d+\/\d+)/);
+    const criticalMatch = output.match(/Critical issues: (\d+)/);
+    const warningsMatch = output.match(/Warnings: (\d+)/);
+    const sections = output
+        .split("──────")
+        .filter((s) => s.trim())
+        .map((s) => s.trim().split("\n")[0]?.trim())
+        .filter(Boolean);
+    return {
+        healthScore: healthMatch?.[1],
+        criticalIssues: criticalMatch ? parseInt(criticalMatch[1]) : 0,
+        warnings: warningsMatch ? parseInt(warningsMatch[1]) : 0,
+        sections,
+    };
+}
+//# sourceMappingURL=triage.js.map

package/dist/triage.js.map

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

package/dist/update-check.d.ts

@@ -0,0 +1,13 @@
+export interface UpdateInfo {
+    available: boolean;
+    latest: string;
+    current: string;
+}
+/**
+ * Check npm registry for a newer version of kit.
+ * Returns null if already on latest, check fails, or check is suppressed.
+ * Never throws — all errors are caught silently.
+ */
+export declare function checkForUpdate(currentVersion: string): Promise<UpdateInfo | null>;
+/** Format and print the update notice after command output. */
+export declare function printUpdateNotice(info: UpdateInfo): void;

package/dist/update-check.js

@@ -0,0 +1,91 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const PACKAGE_NAME = "sandstream-kit";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const CACHE_DIR = join(homedir(), ".kit");
+const CACHE_FILE = join(CACHE_DIR, "last-update-check.json");
+/**
+ * Check npm registry for a newer version of kit.
+ * Returns null if already on latest, check fails, or check is suppressed.
+ * Never throws — all errors are caught silently.
+ */
+export async function checkForUpdate(currentVersion) {
+    try {
+        // Suppression conditions
+        if (process.env.KIT_NO_UPDATE_CHECK === "1" ||
+            process.env.CI === "true" ||
+            process.env.GITHUB_ACTIONS === "true" ||
+            process.env.GITLAB_CI === "true") {
+            return null;
+        }
+        // Read cache
+        let cache = null;
+        try {
+            const raw = await readFile(CACHE_FILE, "utf8");
+            cache = JSON.parse(raw);
+        }
+        catch {
+            // No cache yet
+        }
+        const now = Date.now();
+        // Use cached result if fresh
+        if (cache && now - cache.checkedAt < CHECK_INTERVAL_MS) {
+            const latest = cache.latestVersion;
+            if (isNewer(latest, currentVersion)) {
+                return { available: true, latest, current: currentVersion };
+            }
+            return null;
+        }
+        // Fetch latest from npm registry
+        const resp = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+            signal: AbortSignal.timeout(3_000),
+            headers: { Accept: "application/json" },
+        });
+        if (!resp.ok)
+            return null;
+        const data = (await resp.json());
+        const latest = data.version;
+        // Write cache
+        try {
+            await mkdir(CACHE_DIR, { recursive: true });
+            await writeFile(CACHE_FILE, JSON.stringify({ checkedAt: now, latestVersion: latest }), "utf8");
+        }
+        catch {
+            // Cache write failure is non-fatal
+        }
+        if (isNewer(latest, currentVersion)) {
+            return { available: true, latest, current: currentVersion };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true if `latest` is strictly newer than `current` (semver comparison). */
+function isNewer(latest, current) {
+    try {
+        const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+        const [lMaj, lMin, lPatch] = parse(latest);
+        const [cMaj, cMin, cPatch] = parse(current);
+        if (lMaj !== cMaj)
+            return lMaj > cMaj;
+        if (lMin !== cMin)
+            return lMin > cMin;
+        return lPatch > cPatch;
+    }
+    catch {
+        return false;
+    }
+}
+/** Format and print the update notice after command output. */
+export function printUpdateNotice(info) {
+    const dim = "\x1b[2m";
+    const reset = "\x1b[0m";
+    const yellow = "\x1b[33m";
+    const cyan = "\x1b[36m";
+    console.log(`\n  ${dim}╰─${reset} ${yellow}Update available${reset}: ${dim}${info.current}${reset} → ${cyan}${info.latest}${reset}  ` +
+        `${dim}npm install -g ${PACKAGE_NAME}${reset}`);
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

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

package/dist/utils/colors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared ANSI color codes. Single source of truth — cli.ts and output.ts
+ * previously each declared an identical private copy; extracted command
+ * modules import this one.
+ */
+export declare const c: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly green: "\u001B[32m";
+    readonly red: "\u001B[31m";
+    readonly yellow: "\u001B[33m";
+    readonly cyan: "\u001B[36m";
+};

package/dist/utils/colors.js

@@ -0,0 +1,15 @@
+/**
+ * Shared ANSI color codes. Single source of truth — cli.ts and output.ts
+ * previously each declared an identical private copy; extracted command
+ * modules import this one.
+ */
+export const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    red: "\x1b[31m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+};
+//# sourceMappingURL=colors.js.map

package/dist/utils/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../../src/utils/colors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,CAAC,GAAG;IACf,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,SAAS;IACd,KAAK,EAAE,UAAU;IACjB,GAAG,EAAE,UAAU;IACf,MAAM,EAAE,UAAU;IAClB,IAAI,EAAE,UAAU;CACR,CAAC"}

package/dist/utils/didYouMean.d.ts

@@ -0,0 +1,15 @@
+/**
+ * "Did you mean …?" suggestion for mistyped CLI subcommands.
+ *
+ * Plain Levenshtein with early-out on length difference. Suggestion
+ * threshold: distance <= 2 for short names, <= 3 for names longer than
+ * 8 chars — tight enough that unrelated commands never surface, loose
+ * enough to catch transpositions ("chekc"), drops ("screts") and fat
+ * fingers ("securty").
+ */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Return the closest candidates to `input`, best first. Empty array when
+ * nothing is within the distance threshold.
+ */
+export declare function didYouMean(input: string, candidates: string[]): string[];

package/dist/utils/didYouMean.js

@@ -0,0 +1,47 @@
+/**
+ * "Did you mean …?" suggestion for mistyped CLI subcommands.
+ *
+ * Plain Levenshtein with early-out on length difference. Suggestion
+ * threshold: distance <= 2 for short names, <= 3 for names longer than
+ * 8 chars — tight enough that unrelated commands never surface, loose
+ * enough to catch transpositions ("chekc"), drops ("screts") and fat
+ * fingers ("securty").
+ */
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/**
+ * Return the closest candidates to `input`, best first. Empty array when
+ * nothing is within the distance threshold.
+ */
+export function didYouMean(input, candidates) {
+    const lower = input.toLowerCase();
+    const maxDist = lower.length > 8 ? 3 : 2;
+    return candidates
+        .map((c) => ({ c, d: levenshtein(lower, c.toLowerCase()) }))
+        .filter(({ d }) => d > 0 && d <= maxDist)
+        .sort((x, y) => x.d - y.d)
+        .slice(0, 3)
+        .map(({ c }) => c);
+}
+//# sourceMappingURL=didYouMean.js.map

package/dist/utils/didYouMean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"didYouMean.js","sourceRoot":"","sources":["../../src/utils/didYouMean.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IAEpC,IAAI,IAAI,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAEhD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAChB,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAS,WAAW;YAC/B,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAK,YAAY;YAChC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CACnB,CAAC;QACJ,CAAC;QACD,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,UAAoB;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,OAAO,UAAU;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;SAC3D,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC;SACxC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACzB,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;SACX,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC"}

package/dist/utils/exec.d.ts

@@ -0,0 +1,21 @@
+import { execFile as execFileCb } from "node:child_process";
+/**
+ * Canonical promisified execFile for the whole codebase.
+ *
+ * Why a shared module: 30+ files previously declared their own
+ * `const exec = promisify(execFile)` — three lines of boilerplate per
+ * file, and a drift risk (anyone "simplifying" to `exec` from
+ * node:child_process reintroduces shell-injection surface). Import this
+ * instead:
+ *
+ *   import { exec } from "./utils/exec.js";
+ *
+ * SECURITY INVARIANT: always pass arguments as an array. Never build a
+ * shell string. execFile does not spawn a shell, so metacharacters in
+ * arguments are inert.
+ *
+ * For a never-throwing variant returning { stdout, stderr, exitCode, ok },
+ * use execFileNoThrow from ./execFileNoThrow.js.
+ */
+export declare const exec: typeof execFileCb.__promisify__;
+export { execFileNoThrow, type ExecResult } from "./execFileNoThrow.js";

package/dist/utils/exec.js

@@ -0,0 +1,23 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+/**
+ * Canonical promisified execFile for the whole codebase.
+ *
+ * Why a shared module: 30+ files previously declared their own
+ * `const exec = promisify(execFile)` — three lines of boilerplate per
+ * file, and a drift risk (anyone "simplifying" to `exec` from
+ * node:child_process reintroduces shell-injection surface). Import this
+ * instead:
+ *
+ *   import { exec } from "./utils/exec.js";
+ *
+ * SECURITY INVARIANT: always pass arguments as an array. Never build a
+ * shell string. execFile does not spawn a shell, so metacharacters in
+ * arguments are inert.
+ *
+ * For a never-throwing variant returning { stdout, stderr, exitCode, ok },
+ * use execFileNoThrow from ./execFileNoThrow.js.
+ */
+export const exec = promisify(execFileCb);
+export { execFileNoThrow } from "./execFileNoThrow.js";
+//# sourceMappingURL=exec.js.map

package/dist/utils/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAE1C,OAAO,EAAE,eAAe,EAAmB,MAAM,sBAAsB,CAAC"}

package/dist/utils/execFileNoThrow.d.ts

@@ -0,0 +1,14 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    ok: boolean;
+}
+/**
+ * Runs a command safely using execFile (no shell, no injection risk).
+ * Never throws — returns structured result with exitCode and ok flag.
+ */
+export declare function execFileNoThrow(command: string, args: string[], options?: {
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ExecResult>;

package/dist/utils/execFileNoThrow.js

@@ -0,0 +1,29 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Runs a command safely using execFile (no shell, no injection risk).
+ * Never throws — returns structured result with exitCode and ok flag.
+ */
+export async function execFileNoThrow(command, args, options) {
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args, {
+            timeout: options?.timeout ?? 30_000,
+            env: options?.env ?? process.env,
+        });
+        return { stdout, stderr, exitCode: 0, ok: true };
+    }
+    catch (error) {
+        if (error && typeof error === "object") {
+            const e = error;
+            return {
+                stdout: e.stdout ?? "",
+                stderr: e.stderr ?? "",
+                exitCode: typeof e.code === "number" ? e.code : 1,
+                ok: false,
+            };
+        }
+        return { stdout: "", stderr: String(error), exitCode: 1, ok: false };
+    }
+}
+//# sourceMappingURL=execFileNoThrow.js.map

package/dist/utils/execFileNoThrow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execFileNoThrow.js","sourceRoot":"","sources":["../../src/utils/execFileNoThrow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAS1C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,IAAc,EACd,OAAuD;IAEvD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE;YAC5D,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,MAAM;YACnC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG;SACjC,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACnD,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,KAAqE,CAAC;YAChF,OAAO;gBACL,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;gBACtB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;gBACtB,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACjD,EAAE,EAAE,KAAK;aACV,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACvE,CAAC;AACH,CAAC"}