soturail 0.4.1 → 0.7.0

package/dist/core/format-compare.js

@@ -0,0 +1,68 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { estimateTokens, tokenEstimateNote } from "./token-estimator.js";
+export async function compareFormats(file, root = process.cwd()) {
+    const absolute = path.resolve(root, file);
+    const raw = await fs.readFile(absolute, "utf8");
+    const json = tryParseJson(raw);
+    const lineCount = raw.split(/\r?\n/).length;
+    const repeatedKeys = [...raw.matchAll(/"([^"]+)"\s*:/g)].map((match) => match[1] ?? "");
+    const keyFrequency = new Map();
+    for (const key of repeatedKeys)
+        keyFrequency.set(key, (keyFrequency.get(key) ?? 0) + 1);
+    const maxKeyRepeats = Math.max(0, ...keyFrequency.values());
+    const warnings = [];
+    if (hasProbableSecret(raw))
+        warnings.push("probable secret-like text; redact before agent handoff");
+    if (json && containsHugeArray(json))
+        warnings.push("huge array detected; summarize or offload repeated rows");
+    if (raw.length > 12000)
+        warnings.push("long prompt context; prefer tagged blocks or offload");
+    return {
+        file,
+        bytes: Buffer.byteLength(raw, "utf8"),
+        markdownTokens: estimateTokens(raw),
+        jsonTokens: json ? estimateTokens(JSON.stringify(json)) : null,
+        taggedTokens: estimateTokens(`<soturail_context source="${file}">\n${raw}\n</soturail_context>`),
+        compactSuggestion: maxKeyRepeats >= 4 || lineCount > 80 ? "consider compact table/TOON-like summary for repetitive records" : "markdown is probably adequate",
+        taggedSuggestion: raw.length > 4000 ? "tagged blocks may help boundary clarity" : "tagged blocks optional",
+        warnings
+    };
+}
+export function renderFormatCompare(report) {
+    return [
+        "SotuRail format compare",
+        `file: ${report.file}`,
+        `bytes: ${report.bytes}`,
+        `markdown_estimated_tokens: ${report.markdownTokens}`,
+        `json_estimated_tokens: ${report.jsonTokens ?? "not valid json"}`,
+        `tagged_estimated_tokens: ${report.taggedTokens}`,
+        `compact_suggestion: ${report.compactSuggestion}`,
+        `tagged_suggestion: ${report.taggedSuggestion}`,
+        tokenEstimateNote(),
+        "",
+        "Warnings:",
+        ...(report.warnings.length > 0 ? report.warnings.map((warning) => `- ${warning}`) : ["- none"])
+    ].join("\n") + "\n";
+}
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function hasProbableSecret(raw) {
+    return /(?:api[_-]?key|token|secret|password)\s*[:=]\s*["']?[A-Za-z0-9._-]{6,}/i.test(raw)
+        || /authorization\s*:\s*bearer\s+[A-Za-z0-9._-]+/i.test(raw)
+        || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(raw);
+}
+function containsHugeArray(value) {
+    if (Array.isArray(value))
+        return value.length > 50 || value.some(containsHugeArray);
+    if (value && typeof value === "object")
+        return Object.values(value).some(containsHugeArray);
+    return false;
+}
+//# sourceMappingURL=format-compare.js.map

package/dist/core/format-compare.js.map

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

package/dist/core/fs-evidence.d.ts

@@ -0,0 +1,25 @@
+export interface FsSnapshot {
+    schemaVersion: "soturail.fs.snapshot.v1";
+    id: string;
+    createdAt: string;
+    files: Array<{
+        path: string;
+        size: number;
+        hash: string | null;
+        timestamp: string;
+    }>;
+}
+export declare function createFsSnapshot(root?: string): Promise<{
+    snapshot: FsSnapshot;
+    path: string;
+}>;
+export declare function touchedFiles(root?: string): Promise<string>;
+export declare function fsDiff(root?: string): Promise<string>;
+export declare function planEdit(description: string, root?: string): Promise<{
+    path: string;
+    id: string;
+}>;
+export declare function renderSnapshot(pathRoot: string, result: {
+    snapshot: FsSnapshot;
+    path: string;
+}): string;

package/dist/core/fs-evidence.js

@@ -0,0 +1,96 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { ensureWorkspace, getWorkspacePaths, loadConfig, relativeToRoot, writeJson } from "./config.js";
+import { scanRepository } from "./file-scanner.js";
+import { hashFile } from "./git.js";
+import { makeRailId } from "./rail-utils.js";
+const execFileAsync = promisify(execFile);
+export async function createFsSnapshot(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const config = await loadConfig(root);
+    const repo = await scanRepository(root, config);
+    const files = [];
+    for (const file of repo.files) {
+        const absolute = path.join(root, file.path);
+        const stat = await fs.stat(absolute);
+        files.push({ path: file.path, size: stat.size, hash: await hashFile(absolute), timestamp: stat.mtime.toISOString() });
+    }
+    const snapshot = {
+        schemaVersion: "soturail.fs.snapshot.v1",
+        id: makeRailId("fs", root),
+        createdAt: new Date().toISOString(),
+        files
+    };
+    const filePath = path.join(getWorkspacePaths(root).fsSnapshotsDir, `${snapshot.id}.json`);
+    await writeJson(filePath, snapshot);
+    return { snapshot, path: filePath };
+}
+export async function touchedFiles(root = process.cwd()) {
+    const latest = await latestSnapshot(root);
+    if (!latest)
+        return "No filesystem snapshot found.\nCreate one with: soturail fs snapshot\n";
+    const current = (await createFsSnapshot(root)).snapshot;
+    const before = new Map(latest.files.map((file) => [file.path, file.hash]));
+    const changed = current.files.filter((file) => before.get(file.path) !== file.hash);
+    return [
+        "SotuRail fs touched",
+        `snapshot_id: ${latest.id}`,
+        `changed_count: ${changed.length}`,
+        "",
+        ...changed.map((file) => `- ${file.path}`)
+    ].join("\n") + "\n";
+}
+export async function fsDiff(root = process.cwd()) {
+    try {
+        const { stdout } = await execFileAsync("git", ["diff", "--stat", "--", "."], {
+            cwd: root,
+            timeout: 5000,
+            windowsHide: true
+        });
+        const summary = stdout.trim() || "No git diff changes detected.";
+        return ["SotuRail fs diff", summary].join("\n") + "\n";
+    }
+    catch {
+        return "SotuRail fs diff\ngit_diff: unavailable\nUse `soturail fs touched` after a snapshot for local evidence.\n";
+    }
+}
+export async function planEdit(description, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const id = makeRailId("edit", description);
+    const filePath = path.join(getWorkspacePaths(root).fsDir, `${id}.md`);
+    await fs.writeFile(filePath, [
+        `# Planned Edit ${id}`,
+        "",
+        "schemaVersion: soturail.fs.plan-edit.v1",
+        `createdAt: ${new Date().toISOString()}`,
+        "",
+        "## Description",
+        description,
+        "",
+        "## Safety",
+        "- This is an intent note only.",
+        "- No files were modified by this command.",
+        ""
+    ].join("\n"), "utf8");
+    return { path: filePath, id };
+}
+async function latestSnapshot(root) {
+    const dir = getWorkspacePaths(root).fsSnapshotsDir;
+    const entries = await fs.readdir(dir).catch(() => []);
+    const json = entries.filter((entry) => entry.endsWith(".json")).sort().at(-1);
+    if (!json)
+        return null;
+    const raw = await fs.readFile(path.join(dir, json), "utf8");
+    return JSON.parse(raw);
+}
+export function renderSnapshot(pathRoot, result) {
+    return [
+        "SotuRail fs snapshot",
+        `snapshot_id: ${result.snapshot.id}`,
+        `files_count: ${result.snapshot.files.length}`,
+        `path: ${relativeToRoot(pathRoot, result.path)}`
+    ].join("\n") + "\n";
+}
+//# sourceMappingURL=fs-evidence.js.map

package/dist/core/fs-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-evidence.js","sourceRoot":"","sources":["../../src/core/fs-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAS1C,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACzD,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACxH,CAAC;IACD,MAAM,QAAQ,GAAe;QAC3B,aAAa,EAAE,yBAAyB;QACxC,EAAE,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;QAC1B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,KAAK;KACN,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,GAAG,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC;IAC1F,MAAM,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACpC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACrD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM;QAAE,OAAO,wEAAwE,CAAC;IAC7F,MAAM,OAAO,GAAG,CAAC,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;IACpF,OAAO;QACL,qBAAqB;QACrB,gBAAgB,MAAM,CAAC,EAAE,EAAE;QAC3B,kBAAkB,OAAO,CAAC,MAAM,EAAE;QAClC,EAAE;QACF,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;KAC3C,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IAC/C,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE;YAC3E,GAAG,EAAE,IAAI;YACT,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,+BAA+B,CAAC;QACjE,OAAO,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,2GAA2G,CAAC;IACrH,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,WAAmB,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACtE,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IACtE,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE;QAC3B,kBAAkB,EAAE,EAAE;QACtB,EAAE;QACF,yCAAyC;QACzC,cAAc,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE;QACxC,EAAE;QACF,gBAAgB;QAChB,WAAW;QACX,EAAE;QACF,WAAW;QACX,gCAAgC;QAChC,2CAA2C;QAC3C,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IACtB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,IAAY;IACxC,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,cAAc,CAAC;IACnD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,MAA8C;IAC7F,OAAO;QACL,sBAAsB;QACtB,gBAAgB,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE;QACpC,gBAAgB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE;QAC9C,SAAS,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE;KACjD,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACtB,CAAC"}

package/dist/core/harness-rail.d.ts

@@ -0,0 +1,34 @@
+export interface HarnessFailureRecord {
+    schemaVersion: "soturail.harness.failure.v1";
+    id: string;
+    createdAt: string;
+    whatFailed: string;
+    workflowId?: string;
+    suspectedRootCause?: string;
+    preventionCandidate: string;
+    evidence?: string;
+}
+export interface HarnessContract {
+    schemaVersion: "soturail.harness.contract.v1";
+    checks: Array<{
+        name: string;
+        command: string;
+        required: boolean;
+    }>;
+    acceptanceRules: string[];
+}
+export declare function noteHarnessFailure(text: string, options?: {
+    workflow?: string;
+    cause?: string;
+    prevention?: string;
+    evidence?: string;
+}, root?: string): Promise<HarnessFailureRecord>;
+export declare function listHarnessFailures(root?: string): Promise<HarnessFailureRecord[]>;
+export declare function explainHarnessFailure(id: string, root?: string): Promise<string>;
+export declare function harnessDoctor(root?: string): Promise<string>;
+export declare function initHarnessContract(root?: string): Promise<{
+    path: string;
+    created: boolean;
+}>;
+export declare function checkHarnessContract(root?: string): Promise<string>;
+export declare function renderHarnessFailures(records: HarnessFailureRecord[]): string;

package/dist/core/harness-rail.js

@@ -0,0 +1,158 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { appendJsonl, ensureWorkspace, getWorkspacePaths, readJsonl, relativeToRoot, writeJson } from "./config.js";
+import { makeRailId } from "./rail-utils.js";
+export async function noteHarnessFailure(text, options = {}, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const record = {
+        schemaVersion: "soturail.harness.failure.v1",
+        id: makeRailId("hfail", text),
+        createdAt: new Date().toISOString(),
+        whatFailed: text,
+        preventionCandidate: options.prevention ?? "workflow check"
+    };
+    if (options.workflow)
+        record.workflowId = options.workflow;
+    if (options.cause)
+        record.suspectedRootCause = options.cause;
+    if (options.evidence)
+        record.evidence = options.evidence;
+    await appendJsonl(getWorkspacePaths(root).harnessFailuresFile, record);
+    return record;
+}
+export async function listHarnessFailures(root = process.cwd()) {
+    return readJsonl(getWorkspacePaths(root).harnessFailuresFile);
+}
+export async function explainHarnessFailure(id, root = process.cwd()) {
+    const record = (await listHarnessFailures(root)).find((item) => item.id === id);
+    if (!record)
+        throw new Error(`Harness failure not found: ${id}`);
+    return [
+        "SotuRail harness failure",
+        `id: ${record.id}`,
+        `created_at: ${record.createdAt}`,
+        `what_failed: ${record.whatFailed}`,
+        `workflow_id: ${record.workflowId ?? "none"}`,
+        `suspected_root_cause: ${record.suspectedRootCause ?? "none"}`,
+        `prevention_candidate: ${record.preventionCandidate}`,
+        `evidence: ${record.evidence ?? "none"}`
+    ].join("\n") + "\n";
+}
+export async function harnessDoctor(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const failures = await listHarnessFailures(root);
+    const currentWorkflow = await readCurrentWorkflow(paths.workflowCurrentFile);
+    const contractPath = path.join(paths.harnessContractsDir, "default.json");
+    const verifyPath = currentWorkflow ? path.join(paths.workflowsDir, currentWorkflow, "verify.json") : "";
+    const checks = [
+        ["README", "README.md"],
+        ["ROADMAP", "ROADMAP.md"],
+        ["tests", "tests"],
+        ["context_pack_support", "src/commands/context.ts"],
+        ["agent_docs", "docs/agents.md"],
+        ["policy_docs", "docs/policy-rail.md"],
+        ["workflow_state", ".soturail/workflows"]
+    ];
+    const lines = ["SotuRail Harness Rail doctor"];
+    for (const [name, file] of checks) {
+        lines.push(`${name}: ${(await exists(path.resolve(root, file))) ? "present" : "missing"}`);
+    }
+    lines.push(`active_workflow: ${currentWorkflow ?? "none"}`);
+    lines.push(`contract_present: ${await exists(contractPath)}`);
+    lines.push(`failure_count: ${failures.length}`);
+    lines.push(`latest_verify_status: ${verifyPath && await exists(verifyPath) ? "present" : "missing"}`);
+    lines.push(`suggested_prevention_action: ${suggestPrevention(failures)}`);
+    lines.push("acceptance_contract: soturail harness contract init");
+    lines.push("safe_default: contract check validates by default; it does not run commands unless future explicit flags add that behavior.");
+    lines.push("workflow_connection: workflow verify/evidence reads harness contracts and failures.");
+    return `${lines.join("\n")}\n`;
+}
+export async function initHarnessContract(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const filePath = path.join(getWorkspacePaths(root).harnessContractsDir, "default.json");
+    if (await exists(filePath))
+        return { path: filePath, created: false };
+    await writeJson(filePath, defaultContract());
+    return { path: filePath, created: true };
+}
+export async function checkHarnessContract(root = process.cwd()) {
+    const filePath = path.join(getWorkspacePaths(root).harnessContractsDir, "default.json");
+    const raw = await fs.readFile(filePath, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            throw new Error("Harness contract not found. Run: soturail harness contract init");
+        throw error;
+    });
+    const parsed = JSON.parse(raw);
+    const ok = parsed.schemaVersion === "soturail.harness.contract.v1"
+        && Array.isArray(parsed.checks)
+        && parsed.checks.every((check) => typeof check.name === "string" && typeof check.command === "string" && typeof check.required === "boolean")
+        && Array.isArray(parsed.acceptanceRules);
+    return [
+        "SotuRail harness contract check",
+        `path: ${relativeToRoot(root, filePath)}`,
+        `valid: ${ok}`,
+        `checks_count: ${Array.isArray(parsed.checks) ? parsed.checks.length : 0}`,
+        "commands_run: none",
+        "note: v0.5.0 validates the contract without executing checks by default."
+    ].join("\n") + "\n";
+}
+export function renderHarnessFailures(records) {
+    if (records.length === 0)
+        return "No harness failures recorded.\n";
+    return [
+        "SotuRail harness failures",
+        `failures_count: ${records.length}`,
+        "",
+        ...records.map((record) => `- ${record.id}: ${record.whatFailed} [candidate: ${record.preventionCandidate}]`)
+    ].join("\n") + "\n";
+}
+function defaultContract() {
+    return {
+        schemaVersion: "soturail.harness.contract.v1",
+        checks: [
+            { name: "build", command: "npm run build", required: true },
+            { name: "typecheck", command: "npm run typecheck", required: true },
+            { name: "test", command: "npm test", required: true }
+        ],
+        acceptanceRules: [
+            "Do not mark work as done if build fails.",
+            "Do not mark work as done if tests fail.",
+            "Do not mark work as done if policy checks fail.",
+            "Record evidence before release.",
+            "Convert repeated failures into a rule, doc, memory, workflow check or diagram/spec update."
+        ]
+    };
+}
+async function readCurrentWorkflow(filePath) {
+    const raw = await fs.readFile(filePath, "utf8").catch(() => "");
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function suggestPrevention(failures) {
+    if (failures.length === 0)
+        return "record failures with soturail harness note";
+    const latest = failures.at(-1);
+    if (!latest)
+        return "record failures with soturail harness note";
+    if (/diagram|visual|spec/i.test(latest.whatFailed))
+        return "diagram/spec update";
+    return latest.preventionCandidate;
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=harness-rail.js.map

package/dist/core/harness-rail.js.map

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

package/dist/core/json-validator.d.ts

@@ -0,0 +1,24 @@
+export interface DuplicateKeyFinding {
+    key: string;
+    count: number;
+    line: number;
+    column: number;
+}
+export interface HugeArrayFinding {
+    path: string;
+    length: number;
+}
+export interface JsonValidationReport {
+    file: string;
+    strict: boolean;
+    validJson: boolean;
+    parseError: string | null;
+    duplicateKeys: DuplicateKeyFinding[];
+    probableSecrets: string[];
+    hugeArrays: HugeArrayFinding[];
+    result: "pass" | "warn" | "fail";
+}
+export declare function validateJsonFile(file: string, options?: {
+    strict?: boolean;
+}, root?: string): Promise<JsonValidationReport>;
+export declare function renderJsonValidation(report: JsonValidationReport): string;

package/dist/core/json-validator.js

@@ -0,0 +1,138 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export async function validateJsonFile(file, options = {}, root = process.cwd()) {
+    const absolute = path.resolve(root, file);
+    const raw = await fs.readFile(absolute, "utf8");
+    const duplicateKeys = options.strict ? detectDuplicateKeys(raw) : [];
+    const probableSecrets = detectProbableSecrets(raw);
+    let parsed = null;
+    let parseError = null;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        parseError = error instanceof Error ? error.message : String(error);
+    }
+    const hugeArrays = parseError ? [] : findHugeArrays(parsed);
+    const validJson = parseError === null;
+    const warningCount = duplicateKeys.length + probableSecrets.length + hugeArrays.length;
+    return {
+        file,
+        strict: options.strict === true,
+        validJson,
+        parseError,
+        duplicateKeys,
+        probableSecrets,
+        hugeArrays,
+        result: !validJson ? "fail" : warningCount > 0 ? "warn" : "pass"
+    };
+}
+export function renderJsonValidation(report) {
+    const lines = [
+        "SotuRail JSON strict validate",
+        `file: ${report.file}`,
+        `strict: ${report.strict}`,
+        `valid_json: ${report.validJson}`,
+        `result: ${report.result}`
+    ];
+    if (report.parseError)
+        lines.push(`parse_error: ${report.parseError}`);
+    lines.push(`duplicate_keys: ${report.duplicateKeys.length}`, `probable_secrets: ${report.probableSecrets.length}`, `huge_arrays: ${report.hugeArrays.length}`, "", "Duplicate keys:");
+    lines.push(...(report.duplicateKeys.length > 0
+        ? report.duplicateKeys.map((finding) => `- ${finding.key} (${finding.count} copies at ${finding.line}:${finding.column})`)
+        : ["- none"]));
+    lines.push("", "Probable secrets:");
+    lines.push(...(report.probableSecrets.length > 0 ? report.probableSecrets.map((finding) => `- ${finding}`) : ["- none"]));
+    lines.push("", "Huge arrays:");
+    lines.push(...(report.hugeArrays.length > 0 ? report.hugeArrays.map((finding) => `- ${finding.path}: ${finding.length} items`) : ["- none"]));
+    lines.push("", "Safety:", "- Redact probable secrets before agent handoff.", "- Summarize or offload huge arrays instead of pasting them into prompts.");
+    return `${lines.join("\n")}\n`;
+}
+function detectDuplicateKeys(raw) {
+    const findings = [];
+    const stack = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const char = raw[i];
+        if (char === "{") {
+            stack.push({ keys: new Map() });
+            continue;
+        }
+        if (char === "}") {
+            stack.pop();
+            continue;
+        }
+        if (char !== "\"")
+            continue;
+        const parsed = readJsonString(raw, i);
+        if (!parsed)
+            continue;
+        const next = skipWhitespace(raw, parsed.end + 1);
+        if (raw[next] === ":" && stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const previous = frame.keys.get(parsed.value);
+            if (previous) {
+                previous.count += 1;
+                const position = lineColumn(raw, parsed.start);
+                findings.push({ key: parsed.value, count: previous.count, line: position.line, column: position.column });
+            }
+            else {
+                frame.keys.set(parsed.value, { count: 1, index: parsed.start });
+            }
+        }
+        i = parsed.end;
+    }
+    return findings;
+}
+function readJsonString(raw, start) {
+    for (let i = start + 1; i < raw.length; i += 1) {
+        const char = raw[i];
+        if (char === "\\") {
+            i += 1;
+            continue;
+        }
+        if (char === "\"") {
+            try {
+                return { value: JSON.parse(raw.slice(start, i + 1)), start, end: i };
+            }
+            catch {
+                return { value: raw.slice(start + 1, i), start, end: i };
+            }
+        }
+    }
+    return null;
+}
+function skipWhitespace(raw, index) {
+    let i = index;
+    while (i < raw.length && /\s/.test(raw[i] ?? ""))
+        i += 1;
+    return i;
+}
+function lineColumn(raw, index) {
+    const before = raw.slice(0, index);
+    const lines = before.split(/\r?\n/);
+    return { line: lines.length, column: (lines[lines.length - 1]?.length ?? 0) + 1 };
+}
+function detectProbableSecrets(raw) {
+    const findings = new Set();
+    const patterns = [
+        [/"?(api[_-]?key|token|secret|password|authorization)"?\s*:/gi, "secret-like key name"],
+        [/authorization\s*:\s*bearer\s+[A-Za-z0-9._-]+/gi, "authorization bearer value"],
+        [/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, "private key block"]
+    ];
+    for (const [pattern, label] of patterns) {
+        if (pattern.test(raw))
+            findings.add(label);
+    }
+    return [...findings];
+}
+function findHugeArrays(value, currentPath = "$") {
+    if (Array.isArray(value)) {
+        const own = value.length > 50 ? [{ path: currentPath, length: value.length }] : [];
+        return [...own, ...value.flatMap((item, index) => findHugeArrays(item, `${currentPath}[${index}]`))];
+    }
+    if (value && typeof value === "object") {
+        return Object.entries(value).flatMap(([key, child]) => findHugeArrays(child, `${currentPath}.${key}`));
+    }
+    return [];
+}
+//# sourceMappingURL=json-validator.js.map

package/dist/core/json-validator.js.map

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

package/dist/core/mcp-exposure.d.ts

@@ -0,0 +1,20 @@
+export interface McpExposureReport {
+    schemaVersion: "soturail.mcp.exposure.v1";
+    createdAt: string;
+    tools: Array<{
+        name: string;
+        risk: "low" | "medium" | "high";
+        note: string;
+    }>;
+    resources: Array<{
+        uri: string;
+        risk: "low" | "medium" | "high";
+        note: string;
+    }>;
+    prompts: string[];
+    roots: string[];
+    arbitraryShellExecutionExposed: boolean;
+    policyNotes: string[];
+}
+export declare function mcpExposureReport(): Promise<McpExposureReport>;
+export declare function renderMcpExposure(report: McpExposureReport): string;