soturail 0.2.1

package/dist/commands/run.js

@@ -0,0 +1,200 @@
+import { promises as fs } from "node:fs";
+import { DedupeStore, sha256Text } from "../core/dedupe-store.js";
+import { ensureWorkspace } from "../core/config.js";
+import { MetricsStore } from "../core/metrics-store.js";
+import { NativeRunnerAdapter } from "../core/native-runner-adapter.js";
+import { RawStore } from "../core/raw-store.js";
+import { validateCommand } from "../core/safety-policy.js";
+import { estimateTokens } from "../core/token-estimator.js";
+import { detectNativeEngine, runWithNative } from "../core/native-engine.js";
+import { compressOutputWithEngine } from "../compressors/index.js";
+function commandFromParts(parts) {
+    if (parts.length === 1) {
+        return parts[0]?.trim() ?? "";
+    }
+    return parts.map(shellQuoteIfNeeded).join(" ").trim();
+}
+function shellQuoteIfNeeded(part) {
+    if (!/\s/.test(part)) {
+        return part;
+    }
+    if ((part.startsWith("\"") && part.endsWith("\"")) || (part.startsWith("'") && part.endsWith("'"))) {
+        return part;
+    }
+    return `"${part.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+function normalizeEngine(value) {
+    if (value === undefined) {
+        return "auto";
+    }
+    if (["auto", "ts", "native"].includes(value)) {
+        return value;
+    }
+    throw new Error(`Unknown reducer engine "${value}". Use auto, ts, or native.`);
+}
+export async function executeRunCommand(commandParts, options = {}, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const command = commandFromParts(commandParts);
+    if (command.length === 0) {
+        throw new Error("No command provided. Example: soturail run npm test");
+    }
+    const validation = validateCommand(command, options.unsafeConfirm);
+    if (!validation.ok) {
+        throw new Error(validation.reason ?? "Command blocked by SotuRail safety policy.");
+    }
+    if (validation.bypassed) {
+        options.terminalStderr?.write(`SotuRail safety bypass accepted for ${validation.matchedPattern ?? "dangerous command"}.\n`);
+    }
+    if (options.interactive) {
+        options.terminalStderr?.write("Interactive mode: stdin is forwarded when possible; compression may be partial for watch/TTY sessions.\n");
+    }
+    const requestedEngine = options.native ? "native" : normalizeEngine(options.engine);
+    const nativeInfo = requestedEngine === "ts" ? { available: false } : await detectNativeEngine(root);
+    if (requestedEngine === "native" && !nativeInfo.available) {
+        throw new Error("Native engine requested but soturail-native was not found. Run npm run build:native or use --engine ts.");
+    }
+    const rawStore = new RawStore(root);
+    const metrics = new MetricsStore(root);
+    const dedupe = new DedupeStore(root);
+    const log = await rawStore.createLog(command);
+    const result = nativeInfo.available
+        ? await runNativePath(commandParts, log, options, root)
+        : await runTypeScriptPath(command, log.stream, options, root);
+    const outputHash = sha256Text(result.rawText);
+    const previous = await dedupe.findReusable(outputHash, result.exitCode);
+    const compression = previous
+        ? {
+            compressor: "dedupe",
+            summary: `Output identical to previous raw_id ${previous.raw_id}; use soturail expand ${previous.raw_id} for full output.\nCurrent raw log is still preserved as ${log.rawId}.\n`,
+            compressed_tokens_estimated: estimateTokens(`Output identical to previous raw_id ${previous.raw_id}.`),
+            engine: "ts"
+        }
+        : await compressOutputWithEngine(command, result.rawText, log.rawId, nativeInfo.available ? requestedEngine : "ts", root);
+    const record = {
+        raw_id: log.rawId,
+        path: log.relativePath,
+        command,
+        exit_code: result.exitCode,
+        created_at: log.createdAt,
+        compressor: compression.compressor,
+        raw_tokens_estimated: estimateTokens(result.rawText),
+        compressed_tokens_estimated: compression.compressed_tokens_estimated
+    };
+    await rawStore.appendRunRecord(record);
+    await dedupe.append({
+        output_sha256: outputHash,
+        raw_id: log.rawId,
+        command,
+        exit_code: result.exitCode,
+        raw_path: log.relativePath,
+        created_at: log.createdAt
+    });
+    if (previous) {
+        await metrics.append({
+            type: "dedupe_hit",
+            raw_id: log.rawId,
+            details: { previous_raw_id: previous.raw_id, output_sha256: outputHash }
+        });
+    }
+    await metrics.append({
+        type: "command_run",
+        raw_id: log.rawId,
+        command,
+        exit_code: result.exitCode,
+        raw_tokens_estimated: record.raw_tokens_estimated,
+        compressed_tokens_estimated: record.compressed_tokens_estimated
+    });
+    const summary = [
+        "",
+        "SotuRail run complete.",
+        `Exit code: ${result.exitCode}`,
+        `Compressor: ${compression.compressor}`,
+        `Engine: ${compression.engine}`,
+        `raw_id: ${log.rawId}`,
+        `Recovery: soturail expand ${log.rawId}`,
+        "",
+        compression.summary
+    ].join("\n");
+    return {
+        rawId: log.rawId,
+        exitCode: result.exitCode,
+        summary,
+        record
+    };
+}
+async function runTypeScriptPath(command, rawLogStream, options, root) {
+    const adapter = new NativeRunnerAdapter();
+    const runnerOptions = {
+        command,
+        cwd: root,
+        interactive: options.interactive === true,
+        rawLogStream
+    };
+    if (options.terminalStdout) {
+        runnerOptions.terminalStdout = options.terminalStdout;
+    }
+    if (options.terminalStderr) {
+        runnerOptions.terminalStderr = options.terminalStderr;
+    }
+    return adapter.run(runnerOptions);
+}
+async function runNativePath(commandParts, log, options, root) {
+    await closeLogStream(log.stream);
+    const summaryJsonPath = `${log.absolutePath}.summary.json`;
+    const nativeOptions = {
+        commandParts,
+        rawLogPath: log.absolutePath,
+        summaryJsonPath,
+        cwd: root,
+        interactive: options.interactive === true
+    };
+    if (options.terminalStdout) {
+        nativeOptions.terminalStdout = options.terminalStdout;
+    }
+    if (options.terminalStderr) {
+        nativeOptions.terminalStderr = options.terminalStderr;
+    }
+    const native = await runWithNative(nativeOptions, root);
+    if (!native) {
+        throw new Error("Native engine was detected but native run failed to start.");
+    }
+    const rawText = await fs.readFile(log.absolutePath, "utf8");
+    return { exitCode: native.exitCode, rawText };
+}
+async function closeLogStream(stream) {
+    await new Promise((resolve) => stream.end(resolve));
+}
+export function registerRunCommand(program) {
+    program
+        .command("run")
+        .description("Run a command through the safe tee-stream runner.")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .option("--interactive", "Forward stdin/TTY behavior when possible")
+        .option("--native", "Prefer the optional native reducer engine")
+        .option("--engine <engine>", "Reducer engine: auto, ts, or native", "auto")
+        .option("--unsafe-confirm <phrase>", "Exact phrase required to bypass dangerous-command blocking")
+        .argument("[command...]", "Command and arguments to execute")
+        .action(async (commandParts = [], options) => {
+        const runOptions = {
+            terminalStdout: process.stdout,
+            terminalStderr: process.stderr
+        };
+        if (options.interactive !== undefined) {
+            runOptions.interactive = options.interactive;
+        }
+        if (options.unsafeConfirm !== undefined) {
+            runOptions.unsafeConfirm = options.unsafeConfirm;
+        }
+        if (options.native !== undefined) {
+            runOptions.native = options.native;
+        }
+        if (options.engine !== undefined) {
+            runOptions.engine = options.engine;
+        }
+        const result = await executeRunCommand(commandParts, runOptions);
+        process.stdout.write(result.summary);
+        process.exitCode = result.exitCode;
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/run.js.map

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

package/dist/commands/spec.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+export declare function createSpec(featureIdea: string, root?: string): Promise<{
+    folder: string;
+    files: string[];
+}>;
+export declare function registerSpecCommand(program: Command): void;
+export declare function specStatus(root?: string): Promise<string>;
+export declare function validateSpecs(specFolder?: string, root?: string): Promise<string>;
+export declare function addSpecTask(specFolder: string, text: string, root?: string): Promise<string>;
+export declare function listSpecTasks(specFolder: string, root?: string): Promise<string>;
+export declare function markSpecTaskDone(specFolder: string, index: number, root?: string): Promise<string>;

package/dist/commands/spec.js

@@ -0,0 +1,217 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, getWorkspacePaths, relativeToRoot, writeFileIfMissing } from "../core/config.js";
+function slugify(input) {
+    const slug = input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 50);
+    return slug || "feature";
+}
+async function nextSpecNumber(specsDir) {
+    try {
+        const entries = await fs.readdir(specsDir, { withFileTypes: true });
+        const numbers = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => Number(entry.name.match(/^(\d{3})-/)?.[1] ?? 0))
+            .filter((value) => Number.isFinite(value));
+        return Math.max(0, ...numbers) + 1;
+    }
+    catch {
+        return 1;
+    }
+}
+function specTemplates(featureIdea) {
+    const title = featureIdea.trim();
+    return {
+        "constitution.md": `# Constitution: ${title}
+
+Status: Draft
+
+## Principles
+
+- Local-first behavior is mandatory.
+- Raw evidence must remain recoverable.
+- Safety gates must be explicit and reversible.
+- Metrics must distinguish estimates from provider-reported facts.
+`,
+        "spec.md": `# Spec: ${title}
+
+Status: Draft
+
+## User Need
+
+Describe the user-facing problem and the smallest verifiable outcome.
+
+## Functional Requirements
+
+- The implementation must be testable locally.
+- The behavior must preserve user data.
+- Any compression must point back to raw evidence.
+
+## Acceptance Criteria
+
+- Given the feature is used, then the user can inspect the result.
+- Given a failure occurs, then the user receives a recoverable explanation.
+`,
+        "plan.md": `# Plan: ${title}
+
+## Technical Approach
+
+1. Define boundaries and storage format.
+2. Implement the smallest reversible path.
+3. Add tests for safety, failure and recovery.
+4. Update docs after behavior is verified.
+`,
+        "tasks.md": `# Tasks: ${title}
+
+- [ ] Confirm scope and non-goals.
+- [ ] Add focused tests.
+- [ ] Implement behavior.
+- [ ] Run build and tests.
+- [ ] Document usage and limitations.
+`,
+        "verification.md": `# Verification: ${title}
+
+## Verification Plan
+
+- Build succeeds locally.
+- Tests cover the expected behavior.
+- CLI examples are exercised when applicable.
+`,
+        "context-budget.md": `# Context Budget: ${title}
+
+## Context Budget
+
+- Prefer repo maps and targeted reads.
+- Keep raw logs recoverable through soturail expand.
+- Place stable spec content before dynamic run output.
+`,
+        "security-impact.md": `# Security Impact: ${title}
+
+## Security Impact
+
+- Identify destructive command risks.
+- Identify secret-bearing raw logs.
+- Confirm no automatic remote push is introduced.
+`
+    };
+}
+export async function createSpec(featureIdea, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const number = await nextSpecNumber(paths.specsDir);
+    const folder = path.resolve(paths.specsDir, `${String(number).padStart(3, "0")}-${slugify(featureIdea)}`);
+    await fs.mkdir(folder, { recursive: true });
+    const files = [];
+    const templates = specTemplates(featureIdea);
+    for (const [fileName, content] of Object.entries(templates)) {
+        const filePath = path.resolve(folder, fileName);
+        await writeFileIfMissing(filePath, content, undefined, root);
+        files.push(relativeToRoot(root, filePath));
+    }
+    return { folder: relativeToRoot(root, folder), files };
+}
+export function registerSpecCommand(program) {
+    const spec = program.command("spec").description("Manage Spec-Driven Development artifacts.");
+    spec
+        .command("new")
+        .description("Create a new local SDD spec folder.")
+        .argument("<feature idea>", "Feature idea")
+        .action(async (featureIdea) => {
+        const result = await createSpec(featureIdea);
+        process.stdout.write(`Created spec folder: ${result.folder}\n${result.files.map((file) => `  + ${file}`).join("\n")}\n`);
+    });
+    spec.command("status").description("List local spec folders and task progress.").action(async () => {
+        process.stdout.write(await specStatus());
+    });
+    spec.command("validate").description("Validate spec folders for required SDD sections.").argument("[spec-folder]", "Optional spec folder").action(async (folder) => {
+        process.stdout.write(await validateSpecs(folder));
+    });
+    const task = spec.command("task").description("Manage tasks in a spec folder.");
+    task.command("add").argument("<spec-folder>", "Spec folder").argument("<text>", "Task text").action(async (folder, text) => {
+        process.stdout.write(await addSpecTask(folder, text));
+    });
+    task.command("list").argument("<spec-folder>", "Spec folder").action(async (folder) => {
+        process.stdout.write(await listSpecTasks(folder));
+    });
+    task.command("done").argument("<spec-folder>", "Spec folder").argument("<index>", "1-based task index").action(async (folder, index) => {
+        process.stdout.write(await markSpecTaskDone(folder, Number(index)));
+    });
+}
+async function specFolders(root = process.cwd()) {
+    const paths = getWorkspacePaths(root);
+    try {
+        const entries = await fs.readdir(paths.specsDir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => path.resolve(paths.specsDir, entry.name)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function readFileOrEmpty(filePath) {
+    return fs.readFile(filePath, "utf8").catch(() => "");
+}
+export async function specStatus(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const folders = await specFolders(root);
+    if (folders.length === 0) {
+        return "No specs found. Run soturail spec new \"feature idea\".\n";
+    }
+    const lines = ["SotuRail spec status"];
+    for (const folder of folders) {
+        const tasks = await readFileOrEmpty(path.resolve(folder, "tasks.md"));
+        const done = (tasks.match(/^- \[x\]/gim) ?? []).length;
+        const total = (tasks.match(/^- \[[ x]\]/gim) ?? []).length;
+        lines.push(`${relativeToRoot(root, folder)}: ${done}/${total} tasks done`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function validateSpecs(specFolder, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const folders = specFolder ? [path.resolve(root, specFolder)] : await specFolders(root);
+    const checks = [
+        { file: "spec.md", label: "problem statement", pattern: /problem|user need/i },
+        { file: "spec.md", label: "acceptance criteria", pattern: /acceptance criteria/i },
+        { file: "verification.md", label: "verification plan", pattern: /verification plan/i },
+        { file: "context-budget.md", label: "context budget", pattern: /context budget/i },
+        { file: "security-impact.md", label: "security impact", pattern: /security impact/i }
+    ];
+    const lines = ["SotuRail spec validate"];
+    for (const folder of folders) {
+        lines.push(relativeToRoot(root, folder));
+        for (const check of checks) {
+            const content = await readFileOrEmpty(path.resolve(folder, check.file));
+            lines.push(`  ${check.pattern.test(content) ? "OK" : "FAIL"} ${check.label}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function addSpecTask(specFolder, text, root = process.cwd()) {
+    const tasksFile = path.resolve(root, specFolder, "tasks.md");
+    await fs.appendFile(tasksFile, `- [ ] ${text}\n`, "utf8");
+    return `Added task to ${path.normalize(specFolder).replace(/\\/g, "/")}\n`;
+}
+export async function listSpecTasks(specFolder, root = process.cwd()) {
+    const tasks = await readFileOrEmpty(path.resolve(root, specFolder, "tasks.md"));
+    const lines = tasks.split(/\r?\n/).filter((line) => /^- \[[ x]\]/i.test(line));
+    return lines.length > 0 ? `${lines.map((line, index) => `${index + 1}. ${line}`).join("\n")}\n` : "No tasks found.\n";
+}
+export async function markSpecTaskDone(specFolder, index, root = process.cwd()) {
+    const tasksFile = path.resolve(root, specFolder, "tasks.md");
+    const content = await fs.readFile(tasksFile, "utf8");
+    let seen = 0;
+    const next = content.split(/\r?\n/).map((line) => {
+        if (/^- \[[ x]\]/i.test(line)) {
+            seen += 1;
+            if (seen === index) {
+                return line.replace(/^- \[[ x]\]/i, "- [x]");
+            }
+        }
+        return line;
+    }).join("\n");
+    await fs.writeFile(tasksFile, next, "utf8");
+    return `Marked task ${index} done in ${path.normalize(specFolder).replace(/\\/g, "/")}\n`;
+}
+//# sourceMappingURL=spec.js.map

package/dist/commands/spec.js.map

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

package/dist/commands/stats.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from "commander";
+export interface StatsReport {
+    estimated_raw_tokens: number;
+    estimated_compressed_tokens: number;
+    compression_ratio: number | null;
+    command_count: number;
+    expansion_count: number;
+    manual_omission_or_failure_count: number;
+    estimated_cache_stability_score: number;
+    provider_cache_hits: number | null;
+    provider_cache_source: string | null;
+}
+export declare function collectStats(root?: string): Promise<StatsReport>;
+export declare function formatStats(report: StatsReport): string;
+export declare function registerStatsCommand(program: Command): void;

package/dist/commands/stats.js

@@ -0,0 +1,82 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { readCacheBlocks } from "../core/cache-normalizer.js";
+import { getWorkspacePaths } from "../core/config.js";
+import { MetricsStore } from "../core/metrics-store.js";
+import { RawStore } from "../core/raw-store.js";
+async function readProviderCacheMetadata(root) {
+    const paths = getWorkspacePaths(root);
+    const filePath = path.resolve(paths.metricsDir, "provider-cache.json");
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        const hits = parsed.provider_cache_hits;
+        if (typeof hits === "number" && Number.isFinite(hits)) {
+            return { hits, source: path.normalize(path.relative(root, filePath)).replace(/\\/g, "/") };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectStats(root = process.cwd()) {
+    const rawStore = new RawStore(root);
+    const metrics = new MetricsStore(root);
+    const records = await rawStore.readManifest();
+    const events = await metrics.readAll();
+    const blocks = await readCacheBlocks(root);
+    const rawTokens = records.reduce((sum, record) => sum + record.raw_tokens_estimated, 0);
+    const compressedTokens = records.reduce((sum, record) => sum + record.compressed_tokens_estimated, 0);
+    const expansionCount = events.filter((event) => event.type === "expand").length;
+    const omissionCount = events.filter((event) => event.type === "omission_report").length;
+    const failureCount = records.filter((record) => record.exit_code !== 0).length;
+    const lastDoctorCache = [...events]
+        .reverse()
+        .find((event) => event.type === "doctor_cache" && typeof event.estimated_cache_stability_score === "number");
+    const stableTokens = blocks.reduce((sum, block) => sum + block.token_estimate, 0);
+    const cacheScore = typeof lastDoctorCache?.estimated_cache_stability_score === "number"
+        ? lastDoctorCache.estimated_cache_stability_score
+        : stableTokens > 0
+            ? Number((stableTokens / (stableTokens + 800)).toFixed(4))
+            : 0;
+    const provider = await readProviderCacheMetadata(root);
+    return {
+        estimated_raw_tokens: rawTokens,
+        estimated_compressed_tokens: compressedTokens,
+        compression_ratio: compressedTokens > 0 ? Number((rawTokens / compressedTokens).toFixed(2)) : null,
+        command_count: records.length,
+        expansion_count: expansionCount,
+        manual_omission_or_failure_count: omissionCount + failureCount,
+        estimated_cache_stability_score: cacheScore,
+        provider_cache_hits: provider?.hits ?? null,
+        provider_cache_source: provider?.source ?? null
+    };
+}
+export function formatStats(report) {
+    const providerLine = report.provider_cache_hits === null
+        ? "real_provider_cache_hits: not imported"
+        : `real_provider_cache_hits: ${report.provider_cache_hits} (source: ${report.provider_cache_source})`;
+    return [
+        "SotuRail local stats",
+        `estimated_raw_tokens: ${report.estimated_raw_tokens}`,
+        `estimated_compressed_tokens: ${report.estimated_compressed_tokens}`,
+        `compression_ratio: ${report.compression_ratio === null ? "n/a" : `${report.compression_ratio}:1`}`,
+        `command_count: ${report.command_count}`,
+        `expansion_count: ${report.expansion_count}`,
+        `manual_omission_or_failure_count: ${report.manual_omission_or_failure_count}`,
+        `estimated_cache_stability_score: ${report.estimated_cache_stability_score}`,
+        providerLine,
+        "",
+        "Token counts and cache stability are local estimates unless provider metadata is explicitly imported."
+    ].join("\n");
+}
+export function registerStatsCommand(program) {
+    program
+        .command("stats")
+        .description("Print honest local metrics from raw and metrics manifests.")
+        .action(async () => {
+        const report = await collectStats();
+        process.stdout.write(`${formatStats(report)}\n`);
+    });
+}
+//# sourceMappingURL=stats.js.map

package/dist/commands/stats.js.map

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

package/dist/compressors/agent-response-reducer.d.ts

@@ -0,0 +1,13 @@
+import { type ResponseMode } from "../core/response-policy.js";
+export interface ResponseReductionResult {
+    mode: ResponseMode;
+    output: string;
+    raw_tokens: number;
+    compressed_tokens: number;
+    reduction_percent: number;
+    preserved_commands_count: number;
+    preserved_paths_count: number;
+    preserved_code_blocks_count: number;
+    preserved_security_warnings_count: number;
+}
+export declare function reduceAgentResponse(input: string, mode: ResponseMode): ResponseReductionResult;