@hassangameryt/freeflow 0.1.0 → 0.3.0

package/router/dist/routing/run-filters.js

@@ -0,0 +1,230 @@
+import { assembleImportantLines, lineEntries, } from "../evidence/evidence.js";
+export const RUN_FILTER_STREAMS = ["stdout", "stderr", "combined"];
+export function normalizeRunOutputFilters(input) {
+    if (input === undefined || input === null) {
+        return { ok: true };
+    }
+    if (!isRecord(input)) {
+        return { ok: false, path: "$.filters", message: "freeflow_run filters must be an object." };
+    }
+    const filters = {
+        include: [],
+        exclude: [],
+        flags: typeof input.flags === "string" ? input.flags : "",
+    };
+    if (input.stream !== undefined) {
+        if (!isRunFilterStream(input.stream)) {
+            return { ok: false, path: "$.filters.stream", message: "filters.stream must be stdout, stderr, or combined." };
+        }
+        filters.stream = input.stream;
+    }
+    for (const key of ["include", "exclude"]) {
+        const normalized = normalizeStringList(input[key], `$.filters.${key}`);
+        if (!normalized.ok) {
+            return normalized;
+        }
+        filters[key] = normalized.values;
+    }
+    if (!/^(?!.*([gimsu]).*\1)[gimsu]*$/.test(filters.flags)) {
+        return { ok: false, path: "$.filters.flags", message: "filters.flags may contain g, i, m, s, or u without duplicates." };
+    }
+    for (const key of ["head", "tail", "maxLines", "maxBytes"]) {
+        if (input[key] === undefined) {
+            continue;
+        }
+        const value = input[key];
+        if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+            return { ok: false, path: `$.filters.${key}`, message: `${key} must be a positive integer.` };
+        }
+        filters[key] = value;
+    }
+    for (const [kind, patterns] of [
+        ["include", filters.include],
+        ["exclude", filters.exclude],
+    ]) {
+        for (const pattern of patterns) {
+            try {
+                new RegExp(pattern, filters.flags);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { ok: false, path: `$.filters.${kind}`, message: `Invalid ${kind} regex ${JSON.stringify(pattern)}: ${message}` };
+            }
+        }
+    }
+    return { ok: true, filters };
+}
+export function hasRunOutputFilters(filters) {
+    return Boolean(filters &&
+        (filters.stream ||
+            filters.include.length > 0 ||
+            filters.exclude.length > 0 ||
+            filters.head !== undefined ||
+            filters.tail !== undefined ||
+            filters.maxLines !== undefined ||
+            filters.maxBytes !== undefined));
+}
+export function applyRunOutputFilters(options) {
+    const stream = options.filters.stream ?? options.defaultStream;
+    const text = streamText(stream, options);
+    const sourceEntries = lineEntries(text);
+    const includeRegexes = options.filters.include.map((pattern) => new RegExp(pattern, options.filters.flags));
+    const excludeRegexes = options.filters.exclude.map((pattern) => new RegExp(pattern, options.filters.flags));
+    let selected = sourceEntries.filter((entry) => {
+        if (includeRegexes.length > 0 && !includeRegexes.some((regex) => regex.test(entry.line))) {
+            return false;
+        }
+        if (excludeRegexes.some((regex) => regex.test(entry.line))) {
+            return false;
+        }
+        return true;
+    });
+    selected = applyHeadTail(selected, options.filters.head, options.filters.tail);
+    if (options.filters.maxLines !== undefined) {
+        selected = selected.slice(0, options.filters.maxLines);
+    }
+    let fallbackPreservedFailureEvidence = false;
+    let evidence;
+    if (selected.length === 0 && options.preserveFallbackFailureEvidence && options.fallbackImportantLines?.length) {
+        fallbackPreservedFailureEvidence = true;
+        evidence = importantLinesAsEvidence(options.fallbackImportantLines, text);
+    }
+    else {
+        const caps = {};
+        const maxLines = options.filters.maxLines ?? options.caps?.maxLines;
+        const maxExcerptBytes = options.filters.maxBytes ?? options.caps?.maxExcerptBytes;
+        const maxLineBytes = options.filters.maxBytes ?? options.caps?.maxLineBytes;
+        if (maxLines !== undefined) {
+            caps.maxLines = maxLines;
+        }
+        if (maxExcerptBytes !== undefined) {
+            caps.maxExcerptBytes = maxExcerptBytes;
+        }
+        if (maxLineBytes !== undefined) {
+            caps.maxLineBytes = maxLineBytes;
+        }
+        evidence = assembleImportantLines({
+            stream,
+            entries: selected,
+            sourceText: text,
+            caps,
+        });
+    }
+    const metadata = {
+        stream,
+        sourceLines: sourceEntries.length,
+        selectedLines: selected.length,
+    };
+    if (options.filters.include.length > 0) {
+        metadata.include = options.filters.include;
+    }
+    if (options.filters.exclude.length > 0) {
+        metadata.exclude = options.filters.exclude;
+    }
+    if (options.filters.flags) {
+        metadata.flags = options.filters.flags;
+    }
+    if (options.filters.head !== undefined) {
+        metadata.head = options.filters.head;
+    }
+    if (options.filters.tail !== undefined) {
+        metadata.tail = options.filters.tail;
+    }
+    if (options.filters.maxLines !== undefined) {
+        metadata.maxLines = options.filters.maxLines;
+    }
+    if (options.filters.maxBytes !== undefined) {
+        metadata.maxBytes = options.filters.maxBytes;
+    }
+    if (fallbackPreservedFailureEvidence) {
+        metadata.fallbackPreservedFailureEvidence = true;
+    }
+    return {
+        stream,
+        evidence,
+        metadata,
+        description: describeRunOutputFilters(metadata),
+    };
+}
+function normalizeStringList(value, path) {
+    if (value === undefined) {
+        return { ok: true, values: [] };
+    }
+    const values = typeof value === "string" ? [value] : Array.isArray(value) ? value : undefined;
+    if (!values) {
+        return { ok: false, path, message: `${path} must be a string or string array.` };
+    }
+    if (!values.every((item) => typeof item === "string" && item.length > 0)) {
+        return { ok: false, path, message: `${path} must contain non-empty strings.` };
+    }
+    return { ok: true, values: [...values] };
+}
+function isRunFilterStream(value) {
+    return typeof value === "string" && RUN_FILTER_STREAMS.includes(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function streamText(stream, options) {
+    if (stream === "stdout") {
+        return options.stdout;
+    }
+    if (stream === "stderr") {
+        return options.stderr;
+    }
+    return options.combined;
+}
+function applyHeadTail(entries, head, tail) {
+    if (head === undefined && tail === undefined) {
+        return entries;
+    }
+    if (head !== undefined && tail !== undefined) {
+        const byLine = new Map();
+        for (const entry of [...entries.slice(0, head), ...entries.slice(Math.max(0, entries.length - tail))]) {
+            byLine.set(entry.lineNumber, entry);
+        }
+        return [...byLine.values()].sort((left, right) => left.lineNumber - right.lineNumber);
+    }
+    if (head !== undefined) {
+        return entries.slice(0, head);
+    }
+    return entries.slice(Math.max(0, entries.length - tail));
+}
+function importantLinesAsEvidence(importantLines, sourceText) {
+    return {
+        importantLines: [...importantLines],
+        fidelity: "exact",
+        compressed: true,
+        selectedLineCount: importantLines.length,
+        sourceLineCount: lineEntries(sourceText).length,
+    };
+}
+export function describeRunOutputFilters(metadata) {
+    const parts = [`stream=${metadata.stream}`];
+    if (metadata.include?.length) {
+        parts.push(`include=${metadata.include.map((pattern) => JSON.stringify(pattern)).join("|")}`);
+    }
+    if (metadata.exclude?.length) {
+        parts.push(`exclude=${metadata.exclude.map((pattern) => JSON.stringify(pattern)).join("|")}`);
+    }
+    if (metadata.flags) {
+        parts.push(`flags=${metadata.flags}`);
+    }
+    if (metadata.head !== undefined) {
+        parts.push(`head=${metadata.head}`);
+    }
+    if (metadata.tail !== undefined) {
+        parts.push(`tail=${metadata.tail}`);
+    }
+    if (metadata.maxLines !== undefined) {
+        parts.push(`maxLines=${metadata.maxLines}`);
+    }
+    if (metadata.maxBytes !== undefined) {
+        parts.push(`maxBytes=${metadata.maxBytes}`);
+    }
+    parts.push(`selected=${metadata.selectedLines}/${metadata.sourceLines} lines`);
+    if (metadata.fallbackPreservedFailureEvidence) {
+        parts.push("fallback=failure-evidence");
+    }
+    return parts.join(" ");
+}

package/router/dist/routing/run-reducers.d.ts

@@ -0,0 +1,30 @@
+import { type ProcessingReducerResult } from "../processing/reducers.js";
+import type { CommandParserMetadata, ExecutionStatus, ImportantLine, PreserveMode, RouterThresholds } from "../config/types.js";
+export type RunReducerRoute = {
+    status: "selected";
+    result: ProcessingReducerResult;
+    sourceStream: ImportantLine["stream"];
+    reason: string;
+} | {
+    status: "not_selected";
+    reason: string;
+};
+export interface SelectRunReducerRouteOptions {
+    command: string | readonly string[];
+    goal?: string;
+    executionStatus: ExecutionStatus;
+    stdout: string;
+    stderr: string;
+    combined: string;
+    preserve: PreserveMode;
+    thresholds: RouterThresholds;
+    hasFilters: boolean;
+    hasScriptFilter: boolean;
+}
+export declare function selectRunReducerRoute(options: SelectRunReducerRouteOptions): RunReducerRoute;
+export declare function reducerImportantLines(route: Extract<RunReducerRoute, {
+    status: "selected";
+}>): ImportantLine[];
+export declare function parserWithReducer(parser: CommandParserMetadata, route: Extract<RunReducerRoute, {
+    status: "selected";
+}>): CommandParserMetadata;

package/router/dist/routing/run-reducers.js

@@ -0,0 +1,110 @@
+import { byteLength, countLines } from "../evidence/evidence.js";
+import { selectProcessingReducer } from "../processing/reducers.js";
+export function selectRunReducerRoute(options) {
+    if (options.preserve === "full") {
+        return { status: "not_selected", reason: "preserve=full requires exact command output routing." };
+    }
+    if (options.executionStatus !== "success") {
+        return { status: "not_selected", reason: "command did not succeed; preserve parser-selected failure evidence." };
+    }
+    if (options.hasFilters) {
+        return { status: "not_selected", reason: "declarative filters already define the routed command output." };
+    }
+    if (options.hasScriptFilter) {
+        return { status: "not_selected", reason: "scriptFilter already defines the routed command output." };
+    }
+    const source = reducerSourceText(options.stdout, options.stderr, options.combined);
+    if (source === undefined) {
+        return { status: "not_selected", reason: "mixed stdout/stderr success output stays near-raw to avoid hiding warnings." };
+    }
+    const selection = selectProcessingReducer({ text: source.text, ...(options.goal !== undefined ? { goal: options.goal } : {}) });
+    if (selection.status !== "selected") {
+        return { status: "not_selected", reason: selection.reason };
+    }
+    const goalText = (options.goal ?? "").toLowerCase();
+    const commandTextValue = commandText(options.command).toLowerCase();
+    const outputIsLarge = byteLength(source.text) > options.thresholds.largeOutputBytes || countLines(source.text) > options.thresholds.largeOutputLines;
+    const intentAllowsReducer = reducerIntentAllowsSelection(goalText, commandTextValue, selection.result.name);
+    const largeOutputAllowsReducer = outputIsLarge && reducerLargeOutputAllowsSelection(goalText, selection.result);
+    if (!largeOutputAllowsReducer && !intentAllowsReducer) {
+        return {
+            status: "not_selected",
+            reason: `Reducer ${selection.result.name}@${selection.result.version} matched, but neither output size nor reducer-oriented goal/command intent allowed automatic reduction.`,
+        };
+    }
+    return {
+        status: "selected",
+        result: selection.result,
+        sourceStream: source.stream,
+        reason: `Selected ${selection.result.name}@${selection.result.version} reducer for successful command output (confidence=${selection.result.confidence.toFixed(2)}; ${largeOutputAllowsReducer ? "large output" : "goal/command intent"}).`,
+    };
+}
+export function reducerImportantLines(route) {
+    return [{
+            stream: route.sourceStream,
+            lines: lineRangeForText(route.result.visibleText),
+            excerpt: route.result.visibleText,
+        }];
+}
+export function parserWithReducer(parser, route) {
+    return {
+        ...parser,
+        name: `${parser.name}+reducer:${route.result.name}`,
+        confidence: Math.max(parser.confidence, route.result.confidence),
+        fidelity: "exact",
+        compressed: true,
+        counts: {
+            ...(parser.counts ?? {}),
+            reducerFacts: route.result.facts.length,
+        },
+    };
+}
+function reducerSourceText(stdout, stderr, combined) {
+    if (stdout.length > 0 && stderr.length === 0) {
+        return { stream: "stdout", text: stdout };
+    }
+    if (stderr.length > 0 && stdout.length === 0) {
+        return { stream: "stderr", text: stderr };
+    }
+    if (stdout.length === 0 && stderr.length === 0 && combined.length > 0) {
+        return { stream: "combined", text: combined };
+    }
+    return undefined;
+}
+function reducerIntentAllowsSelection(goalText, commandTextValue, reducerName) {
+    switch (reducerName) {
+        case "test-output":
+            return /\b(test|tests|vitest|jest|pytest)\b/.test(goalText);
+        case "diagnostics":
+            return /\b(typecheck|type-check|tsc|lint|eslint|diagnostic)\b/.test(goalText);
+        case "build-output":
+            return /\b(build|compile|bundle|next)\b/.test(goalText);
+        case "access-log":
+            return /\b(log|logs|access|nginx|apache)\b/.test(goalText);
+        case "table":
+            return /\b(csv|json|table|analytics)\b/.test(goalText);
+        case "mcp-tools":
+            return /\b(mcp|tools?|schema|signatures?)\b/.test(goalText);
+        case "json-query":
+            return /\b(json|github|issues?|labels?|repo|repository|summary|summarize|summarise|analysis|analyze|analyse)\b/.test(goalText);
+        case "browser-snapshot":
+            return /\b(browser|snapshot|playwright|accessibility|dom)\b/.test(goalText);
+        case "git-log":
+            return /\b(git\s+log|commits?|history|changelog)\b/.test(goalText) || /\bgit\s+log\b/.test(commandTextValue);
+        default:
+            return false;
+    }
+}
+function reducerLargeOutputAllowsSelection(goalText, result) {
+    if (result.name === "json-query") {
+        return result.confidence >= 0.8;
+    }
+    return true;
+}
+function lineRangeForText(text) {
+    const lines = Math.max(1, countLines(text));
+    return `1-${lines}`;
+}
+function commandText(command) {
+    return typeof command === "string" ? command : command.join(" ");
+}

package/router/dist/sandbox/adapter-roots.d.ts

@@ -0,0 +1,38 @@
+export declare const SCRIPT_TRANSFORM_ADAPTERS_HOME_ENV = "FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME";
+export declare const SCRIPT_TRANSFORM_NODE_ENV = "FREEFLOW_SCRIPT_TRANSFORM_NODE";
+export declare const SCRIPT_TRANSFORM_ADAPTER_PACKAGES: {
+    readonly javascript: {
+        readonly packageName: "quickjs-wasi";
+        readonly version: "3.0.1";
+        readonly env: "FREEFLOW_QUICKJS_WASI_ROOT";
+    };
+    readonly jq: {
+        readonly packageName: "jq-wasm";
+        readonly version: "1.2.0-jq-1.8.2";
+        readonly env: "FREEFLOW_JQ_WASM_ROOT";
+    };
+    readonly python: {
+        readonly packageName: "@bsull/eryx";
+        readonly version: "0.5.0";
+        readonly env: "FREEFLOW_ERYX_ROOT";
+    };
+};
+export declare const SCRIPT_TRANSFORM_SUPPORT_PACKAGES: {
+    readonly node: {
+        readonly packageName: "node";
+        readonly version: "24";
+        readonly env: "FREEFLOW_SCRIPT_TRANSFORM_NODE";
+    };
+};
+export type ScriptTransformAdapterLanguage = keyof typeof SCRIPT_TRANSFORM_ADAPTER_PACKAGES;
+export interface ScriptTransformAdapterRootCandidate {
+    packageRoot: string;
+    source: "env" | "global-cache";
+    envVar: string;
+}
+export declare function defaultScriptTransformAdaptersHome(env?: NodeJS.ProcessEnv): string;
+export declare function defaultScriptTransformAdapterRoot(language: ScriptTransformAdapterLanguage, env?: NodeJS.ProcessEnv): string;
+export declare function resolveScriptTransformAdapterRoot(language: ScriptTransformAdapterLanguage, env?: NodeJS.ProcessEnv): Promise<ScriptTransformAdapterRootCandidate | null>;
+export declare function defaultScriptTransformNodeBinary(env?: NodeJS.ProcessEnv): string;
+export declare function scriptTransformAdapterInstallSpecs(languages?: readonly ScriptTransformAdapterLanguage[]): string[];
+export declare function scriptTransformAdapterEnvExports(home?: string): Record<string, string>;

package/router/dist/sandbox/adapter-roots.js

@@ -0,0 +1,64 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const SCRIPT_TRANSFORM_ADAPTERS_HOME_ENV = "FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME";
+export const SCRIPT_TRANSFORM_NODE_ENV = "FREEFLOW_SCRIPT_TRANSFORM_NODE";
+export const SCRIPT_TRANSFORM_ADAPTER_PACKAGES = {
+    javascript: { packageName: "quickjs-wasi", version: "3.0.1", env: "FREEFLOW_QUICKJS_WASI_ROOT" },
+    jq: { packageName: "jq-wasm", version: "1.2.0-jq-1.8.2", env: "FREEFLOW_JQ_WASM_ROOT" },
+    python: { packageName: "@bsull/eryx", version: "0.5.0", env: "FREEFLOW_ERYX_ROOT" },
+};
+export const SCRIPT_TRANSFORM_SUPPORT_PACKAGES = {
+    node: { packageName: "node", version: "24", env: SCRIPT_TRANSFORM_NODE_ENV },
+};
+export function defaultScriptTransformAdaptersHome(env = process.env) {
+    return env[SCRIPT_TRANSFORM_ADAPTERS_HOME_ENV] || join(homedir(), ".cache", "freeflow-script-adapters");
+}
+export function defaultScriptTransformAdapterRoot(language, env = process.env) {
+    const packageName = SCRIPT_TRANSFORM_ADAPTER_PACKAGES[language].packageName;
+    return join(defaultScriptTransformAdaptersHome(env), "node_modules", ...packageName.split("/"));
+}
+export async function resolveScriptTransformAdapterRoot(language, env = process.env) {
+    const adapter = SCRIPT_TRANSFORM_ADAPTER_PACKAGES[language];
+    const explicitRoot = env[adapter.env];
+    if (explicitRoot) {
+        return { packageRoot: explicitRoot, source: "env", envVar: adapter.env };
+    }
+    const packageRoot = defaultScriptTransformAdapterRoot(language, env);
+    if (await packageRootExists(packageRoot)) {
+        return { packageRoot, source: "global-cache", envVar: adapter.env };
+    }
+    return null;
+}
+export function defaultScriptTransformNodeBinary(env = process.env) {
+    return env[SCRIPT_TRANSFORM_NODE_ENV] || join(defaultScriptTransformAdaptersHome(env), "node_modules", "node", "bin", "node");
+}
+export function scriptTransformAdapterInstallSpecs(languages = ["javascript", "jq", "python"]) {
+    const specs = languages.map((language) => {
+        const adapter = SCRIPT_TRANSFORM_ADAPTER_PACKAGES[language];
+        return `${adapter.packageName}@${adapter.version}`;
+    });
+    if (languages.includes("python")) {
+        const node = SCRIPT_TRANSFORM_SUPPORT_PACKAGES.node;
+        specs.push(`${node.packageName}@${node.version}`);
+    }
+    return specs;
+}
+export function scriptTransformAdapterEnvExports(home = defaultScriptTransformAdaptersHome()) {
+    return {
+        [SCRIPT_TRANSFORM_ADAPTERS_HOME_ENV]: home,
+        [SCRIPT_TRANSFORM_ADAPTER_PACKAGES.javascript.env]: join(home, "node_modules", "quickjs-wasi"),
+        [SCRIPT_TRANSFORM_ADAPTER_PACKAGES.jq.env]: join(home, "node_modules", "jq-wasm"),
+        [SCRIPT_TRANSFORM_ADAPTER_PACKAGES.python.env]: join(home, "node_modules", "@bsull", "eryx"),
+        [SCRIPT_TRANSFORM_NODE_ENV]: join(home, "node_modules", "node", "bin", "node"),
+    };
+}
+async function packageRootExists(packageRoot) {
+    try {
+        await access(join(packageRoot, "package.json"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/router/dist/sandbox/eryx-python-adapter.d.ts

@@ -0,0 +1,9 @@
+import type { ScriptSandboxAdapter } from "./script-sandbox.js";
+export declare const ERYX_ROOT_ENV = "FREEFLOW_ERYX_ROOT";
+export interface EryxPythonSandboxAdapterOptions {
+    packageRoot: string;
+    id?: string;
+    version?: string;
+}
+export declare function discoverEryxPythonSandboxAdaptersFromEnv(env?: NodeJS.ProcessEnv): Promise<ScriptSandboxAdapter[]>;
+export declare function createEryxPythonSandboxAdapter(options: EryxPythonSandboxAdapterOptions): Promise<ScriptSandboxAdapter>;