@hassangameryt/freeflow 0.1.0 → 0.3.0

package/router/dist/processing/renderers.d.ts

@@ -0,0 +1,25 @@
+import type { EvidencePersistence, RecoveryHint } from "../config/types.js";
+import type { ProcessingFact, ProcessingSourceDescriptor, ProcessingSourceStats, ReducerSelectionResult, ScriptPolicySelectionResult } from "./engine.js";
+export type ProcessingRecoveryClass = "exact-result" | "exact-source" | "metadata-only" | "hint-only" | "none";
+export interface ProcessingRenderInput {
+    status: "ok" | "blocked" | "unavailable";
+    source: ProcessingSourceDescriptor;
+    facts: readonly ProcessingFact[];
+    maxVisibleBytes: number;
+    stats?: ProcessingSourceStats;
+    reducer?: ReducerSelectionResult;
+    script?: ScriptPolicySelectionResult;
+    recovery?: RecoveryHint;
+    persistence?: EvidencePersistence;
+    recoveryClass?: ProcessingRecoveryClass;
+    failure?: {
+        policy?: string;
+        reason: string;
+    };
+}
+export declare function renderProcessingResult(input: ProcessingRenderInput): string;
+export declare function classifyProcessingRecovery(input: {
+    recovery?: RecoveryHint;
+    persistence?: EvidencePersistence;
+    resultWillBePersisted?: boolean;
+}): ProcessingRecoveryClass;

package/router/dist/processing/renderers.js

@@ -0,0 +1,186 @@
+export function renderProcessingResult(input) {
+    const lines = input.status === "ok" ? renderOkLines(input) : renderFailureLines(input);
+    return truncateVisible(lines.join("\n"), input.maxVisibleBytes, requiredVisiblePrefix(input));
+}
+export function classifyProcessingRecovery(input) {
+    if (input.resultWillBePersisted) {
+        return "exact-result";
+    }
+    if (input.persistence?.recoverability === "exact") {
+        return "exact-result";
+    }
+    if (input.persistence?.recoverability === "metadata_only") {
+        return "metadata-only";
+    }
+    if (input.recovery?.outputId) {
+        return "exact-source";
+    }
+    if (input.recovery?.how) {
+        return "hint-only";
+    }
+    return "none";
+}
+function requiredVisiblePrefix(input) {
+    return input.script && "policy" in input.script && input.script.policy === "unsafe-unsandboxed"
+        ? processingScriptPolicyLine(input.script)
+        : "";
+}
+function renderOkLines(input) {
+    const recoveryClass = recoveryClassForInput(input);
+    const scriptLines = scriptOutputLines(input.script);
+    const visibleFacts = scriptLines.length > 0 ? scriptLines : visibleFactLines(input.facts, input.reducer);
+    const policyLine = processingScriptPolicyLine(input.script);
+    const unsafeScriptRequested = input.script && "policy" in input.script && input.script.policy === "unsafe-unsandboxed";
+    const lines = unsafeScriptRequested && policyLine
+        ? [policyLine, ...(visibleFacts.length > 0 ? visibleFacts : [`status: ${input.status}`])]
+        : (visibleFacts.length > 0 ? visibleFacts : [`status: ${input.status}`]);
+    lines.push(`source: ${sourcePointer(input.source, input.stats)}`);
+    lines.push(`recovery: ${recoveryClass}`);
+    if (!unsafeScriptRequested && policyLine) {
+        lines.push(policyLine);
+    }
+    if (input.reducer?.status === "selected") {
+        lines.push(`reducer: ${input.reducer.selected.name}@${input.reducer.selected.version} confidence=${input.reducer.selected.confidence.toFixed(2)}`);
+    }
+    return lines;
+}
+function renderFailureLines(input) {
+    const lines = [`status: ${input.status}`];
+    if (input.failure?.policy) {
+        lines.push(`policy: ${input.failure.policy}`);
+    }
+    if (input.failure?.reason) {
+        lines.push(`reason: ${oneLine(input.failure.reason, 240)}`);
+    }
+    lines.push(`source: ${sourcePointer(input.source, input.stats)}`);
+    lines.push(`recovery: ${recoveryClassForInput(input)}`);
+    return lines;
+}
+function recoveryClassForInput(input) {
+    if (input.recoveryClass !== undefined) {
+        return input.recoveryClass;
+    }
+    return classifyProcessingRecovery({
+        ...(input.recovery !== undefined ? { recovery: input.recovery } : {}),
+        ...(input.persistence !== undefined ? { persistence: input.persistence } : {}),
+    });
+}
+function processingScriptPolicyLine(script) {
+    if (script?.status === "executed" && script.policy === "unsafe-unsandboxed") {
+        return `script: ${script.language} unsafe/unsandboxed local-yolo`;
+    }
+    if (script?.status === "executed") {
+        return `script: ${script.language} sandboxed adapter=${script.adapterId}`;
+    }
+    if (script?.status === "rejected") {
+        return `script: rejected unsafe/unsandboxed; no execution`;
+    }
+    if (script?.status === "unavailable") {
+        return script.policy === "unsafe-unsandboxed"
+            ? "script: unsafe/unsandboxed unavailable; no execution"
+            : "script: unavailable; reducer fallback; no host fallback";
+    }
+    if (script?.status === "failed") {
+        return script.policy === "unsafe-unsandboxed"
+            ? "script: failed unsafe/unsandboxed; detail omitted"
+            : "script: failed; no host fallback";
+    }
+    return "";
+}
+function scriptOutputLines(script) {
+    if (script?.status !== "executed") {
+        return [];
+    }
+    const lines = script.outputText.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    if (lines.length > 0) {
+        return lines;
+    }
+    return [`script.stdoutBytes: ${script.stdoutBytes}`];
+}
+function visibleFactLines(facts, reducer) {
+    const sourceFactsHidden = reducer?.status === "selected";
+    const lines = [];
+    const statusFacts = [];
+    for (const fact of facts) {
+        if (sourceFactsHidden && fact.name.startsWith("source.")) {
+            continue;
+        }
+        if (fact.name.startsWith("status.")) {
+            statusFacts.push([fact.name.slice("status.".length), fact.value]);
+            continue;
+        }
+        lines.push(`${fact.name}: ${fact.value}`);
+    }
+    if (statusFacts.length > 0) {
+        lines.push(`status: ${statusFacts.map(([status, value]) => `${status}:${value}`).join(", ")}`);
+    }
+    return lines;
+}
+function sourcePointer(source, stats) {
+    const base = sourceRefLabel(source.ref, source.displayPath, source.stream);
+    if (!stats) {
+        return base;
+    }
+    return `${base} (${formatBytes(stats.bytes)}, ${stats.lines} lines)`;
+}
+function sourceRefLabel(source, displayPath, stream) {
+    if (source.kind === "repo") {
+        return `repo ${shortenMiddle(source.path || displayPath, 90)}`;
+    }
+    if (source.kind === "vault") {
+        const selectedStream = stream ?? source.stream;
+        return `vault ${shortenMiddle(source.outputId, 48)}${selectedStream ? `:${selectedStream}` : ""}`;
+    }
+    return `${source.tool} ${shortenMiddle(source.outputId || displayPath, 64)}${stream ? `:${stream}` : ""}`;
+}
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${round(bytes / 1024)}KB`;
+    }
+    return `${round(bytes / (1024 * 1024))}MB`;
+}
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+function oneLine(text, maxChars) {
+    const compact = text.replace(/\s+/g, " ").trim();
+    return compact.length <= maxChars ? compact : `${compact.slice(0, maxChars - 1)}…`;
+}
+function shortenMiddle(text, maxChars) {
+    if (text.length <= maxChars) {
+        return text;
+    }
+    const keep = Math.max(4, Math.floor((maxChars - 1) / 2));
+    return `${text.slice(0, keep)}…${text.slice(text.length - keep)}`;
+}
+function truncateVisible(text, maxBytes, requiredPrefix = "") {
+    if (byteLength(text) <= maxBytes) {
+        return text;
+    }
+    const marker = "\n… [truncated]";
+    if (requiredPrefix && text.startsWith(requiredPrefix)) {
+        const remainder = text.slice(requiredPrefix.length).replace(/^\n/, "");
+        const minimum = `${requiredPrefix}${marker}`;
+        if (byteLength(minimum) >= maxBytes) {
+            return minimum;
+        }
+        const available = maxBytes - byteLength(requiredPrefix) - byteLength(marker) - 1;
+        let end = Math.max(0, Math.min(remainder.length, available));
+        while (end > 0 && byteLength(remainder.slice(0, end)) > available) {
+            end -= 1;
+        }
+        const body = remainder.slice(0, end);
+        return body ? `${requiredPrefix}\n${body}${marker}` : minimum;
+    }
+    let end = Math.min(text.length, maxBytes);
+    while (end > 0 && byteLength(text.slice(0, end)) > maxBytes) {
+        end -= 1;
+    }
+    return `${text.slice(0, end)}${marker}`;
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}

package/router/dist/processing/scripts.d.ts

@@ -0,0 +1,78 @@
+import { type ScriptSandboxAdapter } from "../sandbox/script-sandbox.js";
+import type { LocalFreeflowConfig, ProcessingScriptPolicy, ScriptTransformConfig, ScriptTransformLanguage } from "../config/types.js";
+import type { LoadedProcessingSource } from "./engine.js";
+export interface ProcessingScriptRequest {
+    language: ScriptTransformLanguage;
+    code: string;
+    label?: string;
+    alias?: string;
+    policy?: ProcessingScriptPolicy;
+    limits?: Partial<ScriptTransformConfig["limits"]>;
+}
+export type ProcessingScriptResult = {
+    status: "not_configured";
+    reason: string;
+} | {
+    status: "unavailable";
+    language: ScriptTransformLanguage;
+    policy: ProcessingScriptPolicy;
+    reason: string;
+    recommendation: string;
+    noHostFallback: true;
+    rawScriptPersistence: "disabled";
+    codeHashSha256: string;
+    adapterId?: string;
+    adapterVersion?: string;
+    failedProofs?: string[];
+} | {
+    status: "rejected";
+    language: ScriptTransformLanguage;
+    policy: "unsafe-unsandboxed";
+    reason: string;
+    recommendation: string;
+    rawScriptPersistence: "disabled";
+    codeHashSha256: string;
+    localOptInRequired?: true;
+} | {
+    status: "executed";
+    language: ScriptTransformLanguage;
+    policy: ProcessingScriptPolicy;
+    adapterId?: string;
+    adapterVersion?: string;
+    runtime?: {
+        name: string;
+        version?: string;
+    };
+    outputText: string;
+    stderr: string;
+    stdoutBytes: number;
+    stderrBytes: number;
+    durationMs?: number;
+    noHostFallback?: true;
+    unsafeUnsandboxed?: true;
+    rawScriptPersistence: "disabled";
+    codeHashSha256: string;
+} | {
+    status: "failed";
+    language: ScriptTransformLanguage;
+    policy: ProcessingScriptPolicy;
+    reason: string;
+    adapterId?: string;
+    adapterVersion?: string;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    noHostFallback?: true;
+    unsafeUnsandboxed?: true;
+    rawScriptPersistence: "disabled";
+    codeHashSha256: string;
+};
+export interface RunProcessingScriptOptions {
+    loaded: LoadedProcessingSource;
+    script: ProcessingScriptRequest;
+    scriptTransform?: ScriptTransformConfig;
+    localConfig?: LocalFreeflowConfig;
+    adapters?: readonly ScriptSandboxAdapter[];
+}
+export declare function processingScriptNotConfigured(): ProcessingScriptResult;
+export declare function processingScriptUnavailableForUnloadedSource(script: ProcessingScriptRequest, reason: string): ProcessingScriptResult;
+export declare function runProcessingScript(options: RunProcessingScriptOptions): Promise<ProcessingScriptResult>;

package/router/dist/processing/scripts.js

@@ -0,0 +1,333 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_SCRIPT_TRANSFORM_CONFIG, MAX_SCRIPT_TRANSFORM_LIMITS } from "../config/config.js";
+import { selectScriptSandboxAdapter } from "../sandbox/script-sandbox.js";
+const execFileAsync = promisify(execFile);
+export function processingScriptNotConfigured() {
+    return {
+        status: "not_configured",
+        reason: "No processing script was requested.",
+    };
+}
+export function processingScriptUnavailableForUnloadedSource(script, reason) {
+    return unavailableResult(script, reason, "Load the source successfully before running the requested processing script.");
+}
+export async function runProcessingScript(options) {
+    const policy = options.script.policy ?? "sandboxed";
+    const config = effectiveProcessingScriptConfig(options.scriptTransform);
+    const limits = effectiveScriptLimits(config, options.script.limits);
+    if (policy === "unsafe-unsandboxed") {
+        return runUnsafeUnsandboxedProcessingScript({ ...options, config, limits });
+    }
+    if (policy !== "sandboxed") {
+        return unavailableResult(options.script, `Unsupported processing script policy ${JSON.stringify(policy)}. No script code was executed.`, "Use policy=sandboxed or explicitly enable local unsafe-unsandboxed processing.");
+    }
+    if (!config.enabled) {
+        return unavailableResult(options.script, "Processing script execution is disabled by config. No script code was executed.", "Enable script processing only with an approved sandbox adapter, or use a deterministic reducer.");
+    }
+    if (options.loaded.stats.bytes > limits.maxInputBytes) {
+        return unavailableResult(options.script, `Processing script input is ${options.loaded.stats.bytes} bytes, above maxInputBytes=${limits.maxInputBytes}. No script code was executed.`, "Use a deterministic reducer, raise the bounded script input limit, or process a smaller source window.");
+    }
+    const selection = await selectScriptSandboxAdapter(options.script.language, config, options.adapters ?? []);
+    if (!selection.ok) {
+        return unavailableResult(options.script, `${selection.status.reason} No script code was executed.`, "Use a deterministic reducer or configure an approved sandbox adapter. Freeflow does not fall back to an unsandboxed host script.", {
+            ...(selection.status.adapterId !== undefined ? { adapterId: selection.status.adapterId } : {}),
+            ...(selection.status.adapterVersion !== undefined ? { adapterVersion: selection.status.adapterVersion } : {}),
+            failedProofs: selection.status.failedProofs,
+        });
+    }
+    const execution = await executeProcessingScriptWithAdapter({
+        adapter: selection.adapter,
+        loaded: options.loaded,
+        script: options.script,
+        config,
+        limits,
+    });
+    if (!execution.ok) {
+        return {
+            status: "failed",
+            language: options.script.language,
+            policy: "sandboxed",
+            reason: execution.reason,
+            adapterId: selection.adapter.id,
+            adapterVersion: selection.adapter.version,
+            ...(execution.stdoutBytes !== undefined ? { stdoutBytes: execution.stdoutBytes } : {}),
+            ...(execution.stderrBytes !== undefined ? { stderrBytes: execution.stderrBytes } : {}),
+            noHostFallback: true,
+            rawScriptPersistence: "disabled",
+            codeHashSha256: sha256(options.script.code),
+        };
+    }
+    const stdout = execution.result.stdout ?? "";
+    const stderr = execution.result.stderr ?? "";
+    const executed = {
+        status: "executed",
+        language: options.script.language,
+        policy: "sandboxed",
+        adapterId: selection.adapter.id,
+        adapterVersion: selection.adapter.version,
+        outputText: stdout,
+        stderr,
+        stdoutBytes: byteLength(stdout),
+        stderrBytes: byteLength(stderr),
+        noHostFallback: true,
+        rawScriptPersistence: "disabled",
+        codeHashSha256: sha256(options.script.code),
+    };
+    if (selection.status.runtime !== undefined) {
+        executed.runtime = selection.status.runtime;
+    }
+    if (execution.result.durationMs !== undefined) {
+        executed.durationMs = execution.result.durationMs;
+    }
+    return executed;
+}
+function unavailableResult(script, reason, recommendation, adapter) {
+    return {
+        status: "unavailable",
+        language: script.language,
+        policy: script.policy ?? "sandboxed",
+        reason,
+        recommendation,
+        noHostFallback: true,
+        rawScriptPersistence: "disabled",
+        codeHashSha256: sha256(script.code),
+        ...(adapter?.adapterId !== undefined ? { adapterId: adapter.adapterId } : {}),
+        ...(adapter?.adapterVersion !== undefined ? { adapterVersion: adapter.adapterVersion } : {}),
+        ...(adapter?.failedProofs !== undefined ? { failedProofs: [...adapter.failedProofs] } : {}),
+    };
+}
+async function runUnsafeUnsandboxedProcessingScript(options) {
+    if (!options.localConfig?.processing.unsafeUnsandboxed.enabled) {
+        return {
+            status: "rejected",
+            language: options.script.language,
+            policy: "unsafe-unsandboxed",
+            reason: "Unsafe unsandboxed processing was requested, but .freeflow/local.json has not enabled processing.unsafeUnsandboxed.enabled. No script code was executed.",
+            recommendation: "Create local-only .freeflow/local.json with processing.unsafeUnsandboxed.enabled=true, then retry with script.policy=unsafe-unsandboxed.",
+            rawScriptPersistence: "disabled",
+            codeHashSha256: sha256(options.script.code),
+            localOptInRequired: true,
+        };
+    }
+    if (options.script.language !== "javascript") {
+        return {
+            status: "rejected",
+            language: options.script.language,
+            policy: "unsafe-unsandboxed",
+            reason: `Unsafe unsandboxed processing currently supports javascript only; requested ${options.script.language}. No script code was executed.`,
+            recommendation: "Use javascript for local YOLO processing, or use a proven sandbox adapter for other languages.",
+            rawScriptPersistence: "disabled",
+            codeHashSha256: sha256(options.script.code),
+        };
+    }
+    if (options.loaded.stats.bytes > options.limits.maxInputBytes) {
+        return {
+            status: "rejected",
+            language: options.script.language,
+            policy: "unsafe-unsandboxed",
+            reason: `Unsafe unsandboxed processing input is ${options.loaded.stats.bytes} bytes, above maxInputBytes=${options.limits.maxInputBytes}. No script code was executed.`,
+            recommendation: "Raise the bounded script input limit locally or process a smaller source window.",
+            rawScriptPersistence: "disabled",
+            codeHashSha256: sha256(options.script.code),
+        };
+    }
+    const execution = await executeUnsafeJavaScriptProcessingScript(options);
+    if (!execution.ok) {
+        return {
+            status: "failed",
+            language: options.script.language,
+            policy: "unsafe-unsandboxed",
+            reason: execution.reason,
+            ...(execution.stdoutBytes !== undefined ? { stdoutBytes: execution.stdoutBytes } : {}),
+            ...(execution.stderrBytes !== undefined ? { stderrBytes: execution.stderrBytes } : {}),
+            unsafeUnsandboxed: true,
+            rawScriptPersistence: "disabled",
+            codeHashSha256: sha256(options.script.code),
+        };
+    }
+    const stdout = execution.stdout;
+    const stderr = execution.stderr;
+    return {
+        status: "executed",
+        language: options.script.language,
+        policy: "unsafe-unsandboxed",
+        runtime: { name: "node", version: process.version },
+        outputText: stdout,
+        stderr,
+        stdoutBytes: byteLength(stdout),
+        stderrBytes: byteLength(stderr),
+        ...(execution.durationMs !== undefined ? { durationMs: execution.durationMs } : {}),
+        unsafeUnsandboxed: true,
+        rawScriptPersistence: "disabled",
+        codeHashSha256: sha256(options.script.code),
+    };
+}
+async function executeUnsafeJavaScriptProcessingScript(options) {
+    const tempRoot = await mkdtemp(join(tmpdir(), "freeflow-processing-unsafe-script-"));
+    const inputDir = join(tempRoot, "input");
+    const workDir = join(tempRoot, "work");
+    try {
+        await mkdir(inputDir, { recursive: true });
+        await mkdir(workDir, { recursive: true });
+        const alias = safeAlias(options.script.alias ?? "source");
+        const sourcePath = join(inputDir, `${alias}.txt`);
+        const manifestPath = join(inputDir, "manifest.json");
+        const scriptPath = join(workDir, "script.mjs");
+        await writeFile(sourcePath, options.loaded.text, "utf8");
+        await writeFile(manifestPath, JSON.stringify({
+            schemaVersion: 1,
+            unsafeUnsandboxed: true,
+            sources: [{
+                    alias,
+                    path: sourcePath,
+                    source: options.loaded.source,
+                    bytes: options.loaded.stats.bytes,
+                    sha256: options.loaded.stats.sha256,
+                }],
+        }, null, 2), "utf8");
+        await writeFile(scriptPath, options.script.code, "utf8");
+        const startedAt = Date.now();
+        try {
+            const output = await execFileAsync(process.execPath, [scriptPath], {
+                cwd: workDir,
+                timeout: options.limits.timeoutMs,
+                maxBuffer: options.limits.maxOutputBytes,
+                env: {
+                    ...process.env,
+                    FREEFLOW_PROCESSING_INPUT_DIR: inputDir,
+                    FREEFLOW_PROCESSING_SOURCE_PATH: sourcePath,
+                    FREEFLOW_PROCESSING_MANIFEST: manifestPath,
+                    FREEFLOW_PROCESSING_UNSAFE_UNSANDBOXED: "1",
+                },
+            });
+            const stdout = String(output.stdout ?? "");
+            const stderr = String(output.stderr ?? "");
+            if (byteLength(stdout) + byteLength(stderr) > options.limits.maxOutputBytes) {
+                return {
+                    ok: false,
+                    reason: `Unsafe unsandboxed processing script output bytes ${byteLength(stdout) + byteLength(stderr)} exceed maxOutputBytes ${options.limits.maxOutputBytes}.`,
+                    stdoutBytes: byteLength(stdout),
+                    stderrBytes: byteLength(stderr),
+                };
+            }
+            return { ok: true, stdout, stderr, durationMs: Date.now() - startedAt };
+        }
+        catch (error) {
+            const maybe = error;
+            const stdout = String(maybe.stdout ?? "");
+            const stderr = String(maybe.stderr ?? "");
+            const code = typeof maybe.code === "number" ? maybe.code : "unknown";
+            const signal = typeof maybe.signal === "string" ? maybe.signal : undefined;
+            const reason = maybe.killed || signal
+                ? `Unsafe unsandboxed processing script timed out or was terminated. Detail omitted to avoid returning raw script text. stdoutBytes=${byteLength(stdout)} stderrBytes=${byteLength(stderr)}.`
+                : `Unsafe unsandboxed processing script failed with exitCode=${code}. Detail omitted to avoid returning raw script text. stdoutBytes=${byteLength(stdout)} stderrBytes=${byteLength(stderr)}.`;
+            return { ok: false, reason, stdoutBytes: byteLength(stdout), stderrBytes: byteLength(stderr) };
+        }
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
+}
+async function executeProcessingScriptWithAdapter(options) {
+    const tempRoot = await mkdtemp(join(tmpdir(), "freeflow-processing-script-"));
+    const inputDir = join(tempRoot, "input");
+    const workDir = join(tempRoot, "work");
+    const outputDir = join(tempRoot, "output");
+    try {
+        await mkdir(inputDir, { recursive: true });
+        await mkdir(workDir, { recursive: true });
+        await mkdir(outputDir, { recursive: true });
+        const alias = safeAlias(options.script.alias ?? "source");
+        const sourcePath = join(inputDir, `${alias}.txt`);
+        await writeFile(sourcePath, options.loaded.text, "utf8");
+        const sources = [{
+                alias,
+                path: sourcePath,
+                bytes: options.loaded.stats.bytes,
+                sha256: options.loaded.stats.sha256,
+            }];
+        await writeFile(join(inputDir, "manifest.json"), JSON.stringify({
+            schemaVersion: 1,
+            sources: [{
+                    alias,
+                    source: options.loaded.source,
+                    bytes: options.loaded.stats.bytes,
+                    sha256: options.loaded.stats.sha256,
+                }],
+        }, null, 2), "utf8");
+        let result;
+        try {
+            result = await options.adapter.execute({
+                language: options.script.language,
+                code: options.script.code,
+                inputDir,
+                workDir,
+                outputDir,
+                sources,
+                limits: options.limits,
+                network: options.config.network,
+            });
+        }
+        catch {
+            return { ok: false, reason: `Processing script adapter ${options.adapter.id} threw before returning a result. Adapter error detail omitted to avoid returning raw script text.` };
+        }
+        const stdoutBytes = byteLength(result.stdout ?? "");
+        const stderrBytes = byteLength(result.stderr ?? "");
+        if (stdoutBytes + stderrBytes > options.limits.maxOutputBytes) {
+            return {
+                ok: false,
+                reason: `Processing script output bytes ${stdoutBytes + stderrBytes} exceed maxOutputBytes ${options.limits.maxOutputBytes}.`,
+                stdoutBytes,
+                stderrBytes,
+            };
+        }
+        if (result.status !== "success") {
+            return {
+                ok: false,
+                reason: `Processing script ${options.script.language} ${result.status}. Adapter failure detail omitted to avoid returning raw script text. stdoutBytes=${stdoutBytes} stderrBytes=${stderrBytes}.`,
+                stdoutBytes,
+                stderrBytes,
+            };
+        }
+        return { ok: true, result };
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
+}
+function effectiveProcessingScriptConfig(config) {
+    const base = config ?? { ...DEFAULT_SCRIPT_TRANSFORM_CONFIG, enabled: true };
+    return {
+        ...base,
+        languages: [...base.languages],
+        limits: { ...base.limits },
+    };
+}
+function effectiveScriptLimits(config, input) {
+    return {
+        timeoutMs: boundedScriptLimit(input?.timeoutMs, config.limits.timeoutMs, MAX_SCRIPT_TRANSFORM_LIMITS.timeoutMs),
+        maxInputBytes: boundedScriptLimit(input?.maxInputBytes, config.limits.maxInputBytes, MAX_SCRIPT_TRANSFORM_LIMITS.maxInputBytes),
+        maxOutputBytes: boundedScriptLimit(input?.maxOutputBytes, config.limits.maxOutputBytes, MAX_SCRIPT_TRANSFORM_LIMITS.maxOutputBytes),
+    };
+}
+function boundedScriptLimit(value, configured, max) {
+    const configuredLimit = Math.min(configured, max);
+    if (!Number.isInteger(value) || Number(value) <= 0) {
+        return configuredLimit;
+    }
+    return Math.min(Number(value), configuredLimit);
+}
+function safeAlias(alias) {
+    return /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(alias) ? alias : "source";
+}
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}

package/router/dist/repo/repo-traversal.d.ts

@@ -0,0 +1,18 @@
+export interface RepoTextFileRef {
+    path: string;
+    absolutePath: string;
+    sizeBytes: number;
+}
+export interface ResolvedRepoPath {
+    root: string;
+    absolutePath: string;
+    relativePath: string;
+}
+export interface CollectRepoTextFileRefsOptions {
+    root: string;
+    requestedPath?: string;
+    generatedPathGlobs?: readonly string[];
+}
+export declare function collectRepoTextFileRefs(options: CollectRepoTextFileRefsOptions): Promise<RepoTextFileRef[]>;
+export declare function resolveRepoPath(root: string, requestedPath?: string): Promise<ResolvedRepoPath>;
+export declare function matchesGeneratedPathGlob(path: string, pattern: string): boolean;