soturail 0.2.1

package/dist/commands/format.js

@@ -0,0 +1,48 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, loadConfig } from "../core/config.js";
+import { MetricsStore } from "../core/metrics-store.js";
+import { isResponseMode } from "../core/response-policy.js";
+import { reduceAgentResponse } from "../compressors/agent-response-reducer.js";
+export async function formatFile(file, options = {}, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const config = await loadConfig(root);
+    const modeCandidate = options.mode ?? config.response_compression.default_mode;
+    if (!isResponseMode(modeCandidate)) {
+        throw new Error(`Unknown response compression mode "${modeCandidate}".`);
+    }
+    const absolute = path.resolve(root, file);
+    const input = await fs.readFile(absolute, "utf8");
+    const result = reduceAgentResponse(input, modeCandidate);
+    await new MetricsStore(root).append({
+        type: "response_format",
+        details: {
+            file,
+            mode: result.mode,
+            raw_tokens: result.raw_tokens,
+            compressed_tokens: result.compressed_tokens,
+            reduction_percent: result.reduction_percent,
+            preserved_commands_count: result.preserved_commands_count,
+            preserved_paths_count: result.preserved_paths_count,
+            preserved_code_blocks_count: result.preserved_code_blocks_count,
+            preserved_security_warnings_count: result.preserved_security_warnings_count
+        }
+    });
+    return [
+        `SotuRail format mode: ${result.mode}`,
+        `Estimated tokens: ${result.raw_tokens} -> ${result.compressed_tokens} (${result.reduction_percent}% reduction)`,
+        "",
+        result.output
+    ].join("\n");
+}
+export function registerFormatCommand(program) {
+    program
+        .command("format")
+        .description("Compress verbose AI or documentation output into task-oriented modes.")
+        .argument("<input-file>", "Input text file")
+        .option("--mode <mode>", "normal, concise, ultra, review, commit, debug, or docs", "normal")
+        .action(async (file, options) => {
+        process.stdout.write(await formatFile(file, options));
+    });
+}
+//# sourceMappingURL=format.js.map

package/dist/commands/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/commands/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,cAAc,EAAqB,MAAM,4BAA4B,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAM/E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAE,UAAyB,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IAC9F,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,oBAAoB,CAAC,YAAY,CAAC;IAC/E,IAAI,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,sCAAsC,aAAa,IAAI,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,EAAE,aAA6B,CAAC,CAAC;IACzE,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QAClC,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE;YACP,IAAI;YACJ,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;YAC3C,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;YAC3C,wBAAwB,EAAE,MAAM,CAAC,wBAAwB;YACzD,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;YACnD,2BAA2B,EAAE,MAAM,CAAC,2BAA2B;YAC/D,iCAAiC,EAAE,MAAM,CAAC,iCAAiC;SAC5E;KACF,CAAC,CAAC;IACH,OAAO;QACL,yBAAyB,MAAM,CAAC,IAAI,EAAE;QACtC,qBAAqB,MAAM,CAAC,UAAU,OAAO,MAAM,CAAC,iBAAiB,KAAK,MAAM,CAAC,iBAAiB,cAAc;QAChH,EAAE;QACF,MAAM,CAAC,MAAM;KACd,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,uEAAuE,CAAC;SACpF,QAAQ,CAAC,cAAc,EAAE,iBAAiB,CAAC;SAC3C,MAAM,CAAC,eAAe,EAAE,wDAAwD,EAAE,QAAQ,CAAC;SAC3F,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,OAAsB,EAAE,EAAE;QACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/hooks.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+export type HookHost = "claude" | "codex" | "gemini" | "cursor";
+export interface HookInstallOptions {
+    dryRun?: boolean;
+}
+export declare function listHooks(): Promise<string>;
+export declare function hooksDoctor(root?: string): Promise<string>;
+export declare function installHooks(hostValue: string, options?: HookInstallOptions, root?: string): Promise<string>;
+export declare function uninstallHooks(hostValue: string, root?: string): Promise<string>;
+export declare function promptOnly(hostValue: string): Promise<string>;
+export declare function registerHooksCommand(program: Command): void;

package/dist/commands/hooks.js

@@ -0,0 +1,248 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, getWorkspacePaths, writeJson } from "../core/config.js";
+import { MetricsStore } from "../core/metrics-store.js";
+const hosts = ["claude", "codex", "gemini", "cursor"];
+const claudePreToolHook = `#!/usr/bin/env node
+const fs = require("node:fs");
+
+const input = fs.readFileSync(0, "utf8");
+let payload = {};
+try {
+  payload = input.trim() ? JSON.parse(input) : {};
+} catch {
+  payload = { raw: input };
+}
+
+const text = JSON.stringify(payload);
+const dangerous = [
+  /\\brm\\s+-[^\\n]*r[^\\n]*f/i,
+  /(^|[;&|]\\s*)sudo\\b/i,
+  /(^|[;&|]\\s*)git\\s+push\\b/i,
+  /\\bcurl\\b[^|]*\\|\\s*(sh|bash)\\b/i,
+  /\\bdd\\s+[^\\n]*\\bif=/i,
+  /(^|[;&|]\\s*)del\\s+\\/s\\b/i
+];
+
+if (dangerous.some((pattern) => pattern.test(text))) {
+  console.error("SotuRail blocked a destructive Claude shell command. Do not route git push through soturail run.");
+  process.exit(2);
+}
+
+if (/\\b(npm|pnpm|yarn|bun|cargo|pytest|vitest|jest|tsc|node)\\b/.test(text)) {
+  console.error("SotuRail suggestion: run tests/builds/log commands through soturail run so raw logs are recoverable.");
+}
+process.exit(0);
+`;
+const claudePostToolHook = `#!/usr/bin/env node
+const fs = require("node:fs");
+const input = fs.readFileSync(0, "utf8");
+if (/raw_id/.test(input)) {
+  console.error("SotuRail note: use soturail expand <raw_id> when the compressed summary lacks needed evidence.");
+}
+process.exit(0);
+`;
+function rules(host) {
+    return `# SotuRail prompt-only rules for ${host}
+
+- Use soturail index before large repository changes.
+- Use soturail read <file> --query "goal" instead of reading giant files directly.
+- Use soturail run for tests, builds and logs so raw output is recoverable.
+- Use soturail expand <raw_id> only when the compressed summary lacks needed information.
+- Never use soturail run for git push.
+`;
+}
+function targetFor(host) {
+    switch (host) {
+        case "claude":
+            return { host, file: "CLAUDE.md", mode: "adapter-template", content: `${rules(host)}\n## Pre-tool adapter template\n\nWhen supported by host hooks, route shell commands through: soturail run <command...>\n` };
+        case "codex":
+            return { host, file: "AGENTS.md", mode: "prompt-only", content: rules(host) };
+        case "gemini":
+            return { host, file: "GEMINI.md", mode: "prompt-only", content: rules(host) };
+        case "cursor":
+            return { host, file: ".cursor/rules/soturail.mdc", mode: "prompt-only", content: rules(host) };
+    }
+}
+function parseHost(value) {
+    if (value === "all") {
+        return "all";
+    }
+    if (hosts.includes(value)) {
+        return value;
+    }
+    throw new Error(`Unknown hook host "${value}".`);
+}
+async function installTarget(target, root, dryRun) {
+    const absolute = path.resolve(root, target.file);
+    const actions = [`${dryRun ? "Would update" : "Update"} ${target.file} (${target.mode})`];
+    try {
+        await fs.access(absolute);
+        actions.push(`${dryRun ? "Would create" : "Create"} backup ${target.file}.soturail.bak`);
+        if (!dryRun) {
+            await fs.copyFile(absolute, `${absolute}.soturail.bak`);
+            const existing = await fs.readFile(absolute, "utf8");
+            const marker = "<!-- soturail-hooks -->";
+            const next = existing.includes(marker) ? existing : `${existing.trimEnd()}\n\n${marker}\n${target.content}`;
+            await fs.writeFile(absolute, `${next.trimEnd()}\n`, "utf8");
+        }
+    }
+    catch {
+        actions.push(`${dryRun ? "Would create" : "Create"} ${target.file}`);
+        if (!dryRun) {
+            await fs.mkdir(path.dirname(absolute), { recursive: true });
+            await fs.writeFile(absolute, `<!-- soturail-hooks -->\n${target.content}`, "utf8");
+        }
+    }
+    return actions;
+}
+async function writeWithBackup(filePath, content, root, dryRun) {
+    const relative = path.normalize(path.relative(root, filePath)).replace(/\\/g, "/");
+    const actions = [`${dryRun ? "Would write" : "Write"} ${relative}`];
+    try {
+        await fs.access(filePath);
+        actions.push(`${dryRun ? "Would create" : "Create"} backup ${relative}.soturail.bak`);
+        if (!dryRun) {
+            await fs.copyFile(filePath, `${filePath}.soturail.bak`);
+        }
+    }
+    catch {
+        actions.push(`${dryRun ? "Would create" : "Create"} ${relative}`);
+    }
+    if (!dryRun) {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, content, "utf8");
+    }
+    return actions;
+}
+async function installClaude(root, dryRun) {
+    const settingsPath = path.resolve(root, ".claude", "settings.json");
+    const preHookPath = path.resolve(root, ".claude", "hooks", "soturail-pre-tool-use.js");
+    const postHookPath = path.resolve(root, ".claude", "hooks", "soturail-post-tool-use.js");
+    const settings = await buildClaudeSettings(settingsPath);
+    return [
+        ...(await writeWithBackup(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, root, dryRun)),
+        ...(await writeWithBackup(preHookPath, claudePreToolHook, root, dryRun)),
+        ...(await writeWithBackup(postHookPath, claudePostToolHook, root, dryRun)),
+        "Claude hook template is conservative; verify the schema against your installed Claude Code version."
+    ];
+}
+async function buildClaudeSettings(settingsPath) {
+    const existing = await readJsonObject(settingsPath);
+    const hooks = isRecord(existing.hooks) ? { ...existing.hooks } : {};
+    hooks.PreToolUse = appendClaudeHook(hooks.PreToolUse, "Bash", "node .claude/hooks/soturail-pre-tool-use.js");
+    hooks.PostToolUse = appendClaudeHook(hooks.PostToolUse, "Bash", "node .claude/hooks/soturail-post-tool-use.js");
+    return {
+        ...existing,
+        hooks,
+        soturail: {
+            ...(isRecord(existing.soturail) ? existing.soturail : {}),
+            mode: "conservative-template",
+            note: "If your Claude Code version uses a different hook schema, copy these commands into the supported hook slots manually."
+        }
+    };
+}
+async function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function appendClaudeHook(value, matcher, command) {
+    const entries = Array.isArray(value) ? [...value] : [];
+    if (!entries.some((entry) => JSON.stringify(entry).includes(command))) {
+        entries.push({ matcher, hooks: [{ type: "command", command }] });
+    }
+    return entries;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+export async function listHooks() {
+    return `${hosts
+        .map((host) => {
+        const target = targetFor(host);
+        return `${host}: ${target.mode}, target ${target.file}`;
+    })
+        .join("\n")}\n`;
+}
+export async function hooksDoctor(root = process.cwd()) {
+    const paths = getWorkspacePaths(root);
+    const registryExists = await fs.access(paths.hooksHosts).then(() => true).catch(() => false);
+    return [
+        "SotuRail hooks doctor",
+        `supported_hosts: ${hosts.join(", ")}`,
+        `registry: ${registryExists ? ".soturail/hooks/hosts.json exists" : "not installed yet"}`,
+        "host APIs vary; prompt-only fallback is always available"
+    ].join("\n") + "\n";
+}
+export async function installHooks(hostValue, options = {}, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const parsed = parseHost(hostValue);
+    const selected = parsed === "all" ? hosts : [parsed];
+    const dryRun = options.dryRun === true;
+    const lines = [`SotuRail hooks install ${hostValue}${dryRun ? " --dry-run" : ""}`];
+    const installed = [];
+    for (const host of selected) {
+        if (host === "claude") {
+            lines.push(...(await installClaude(root, dryRun)));
+            installed.push({ host, target: ".claude/settings.json", mode: "adapter-template", installed_at: new Date().toISOString() });
+        }
+        else {
+            const target = targetFor(host);
+            lines.push(...(await installTarget(target, root, dryRun)));
+            installed.push({ host, target: target.file, mode: target.mode, installed_at: new Date().toISOString() });
+        }
+    }
+    if (!dryRun) {
+        const paths = getWorkspacePaths(root);
+        await writeJson(paths.hooksHosts, { hosts: installed });
+        await new MetricsStore(root).append({ type: "hook_install", details: { host: hostValue, count: installed.length } });
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function uninstallHooks(hostValue, root = process.cwd()) {
+    const parsed = parseHost(hostValue);
+    const selected = parsed === "all" ? hosts : [parsed];
+    const lines = [`SotuRail hooks uninstall ${hostValue}`];
+    for (const host of selected) {
+        const target = targetFor(host);
+        const absolute = path.resolve(root, target.file);
+        const backup = `${absolute}.soturail.bak`;
+        if (await fs.access(backup).then(() => true).catch(() => false)) {
+            await fs.copyFile(backup, absolute);
+            lines.push(`Restored backup for ${target.file}`);
+        }
+        else {
+            lines.push(`No backup found for ${target.file}; left file unchanged`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function promptOnly(hostValue) {
+    const parsed = parseHost(hostValue);
+    const selected = parsed === "all" ? hosts : [parsed];
+    return selected.map((host) => targetFor(host).content).join("\n---\n") + "\n";
+}
+export function registerHooksCommand(program) {
+    const hooks = program.command("hooks").description("Install or inspect agent hook and prompt-only integrations.");
+    hooks.command("list").description("List supported hook hosts.").action(async () => {
+        process.stdout.write(await listHooks());
+    });
+    hooks.command("doctor").description("Check hook registry state.").action(async () => {
+        process.stdout.write(await hooksDoctor());
+    });
+    hooks.command("install").description("Install hook rules for a host.").argument("<host>", "claude, codex, gemini, cursor, or all").option("--dry-run", "Print changes without writing").action(async (host, options) => {
+        process.stdout.write(await installHooks(host, options));
+    });
+    hooks.command("uninstall").description("Restore backed up host files when available.").argument("<host>", "claude, codex, gemini, cursor, or all").action(async (host) => {
+        process.stdout.write(await uninstallHooks(host));
+    });
+    hooks.command("prompt-only").description("Print prompt-only fallback rules.").argument("<host>", "claude, codex, gemini, cursor, or all").action(async (host) => {
+        process.stdout.write(await promptOnly(host));
+    });
+}
+//# sourceMappingURL=hooks.js.map

package/dist/commands/hooks.js.map

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

package/dist/commands/index.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function runIndex(root?: string): Promise<string>;
+export declare function registerIndexCommand(program: Command): void;

package/dist/commands/index.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { ensureWorkspace, loadConfig, relativeToRoot } from "../core/config.js";
+import { scanRepository, writeRepoMap } from "../core/file-scanner.js";
+export async function runIndex(root = process.cwd()) {
+    await ensureWorkspace(root);
+    const config = await loadConfig(root);
+    const repoMap = await scanRepository(root, config);
+    const written = await writeRepoMap(root, repoMap);
+    const lines = [
+        "Heuristic Repo Map written.",
+        `Files indexed: ${repoMap.total_files}`,
+        `Ignored files: ${repoMap.stats.ignored_files}`,
+        `Ignored directories: ${repoMap.stats.ignored_directories}`,
+        `Repo map: ${relativeToRoot(root, written.repoMapPath)}`,
+        `Tree: ${relativeToRoot(root, written.treePath)}`
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function registerIndexCommand(program) {
+    program
+        .command("index")
+        .description("Scan the repository and write a Heuristic Repo Map.")
+        .action(async () => {
+        const output = await runIndex(path.resolve(process.cwd()));
+        process.stdout.write(output);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACjD,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG;QACZ,6BAA6B;QAC7B,kBAAkB,OAAO,CAAC,WAAW,EAAE;QACvC,kBAAkB,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE;QAC/C,wBAAwB,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE;QAC3D,aAAa,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,EAAE;QACxD,SAAS,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE;KAClD,CAAC;IACF,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,qDAAqD,CAAC;SAClE,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/ingest.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+export interface IngestOptions {
+    type?: string;
+}
+export declare function ingestCommand(file: string, options?: IngestOptions, root?: string): Promise<string>;
+export declare function registerIngestCommand(program: Command): void;

package/dist/commands/ingest.js

@@ -0,0 +1,52 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, getWorkspacePaths, writeJson } from "../core/config.js";
+import { ingestDocument, isIngestType } from "../core/document-ingest.js";
+import { MetricsStore } from "../core/metrics-store.js";
+import { extractRules, rulesToYaml } from "../core/rule-extractor.js";
+export async function ingestCommand(file, options = {}, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const type = options.type ?? "docs";
+    if (!isIngestType(type)) {
+        throw new Error(`Unknown ingest type "${type}".`);
+    }
+    const paths = getWorkspacePaths(root);
+    const document = await ingestDocument(file, type, root);
+    const rules = extractRules(document);
+    await fs.mkdir(paths.rulesValidatorsDir, { recursive: true });
+    await fs.writeFile(paths.rulesFile, rulesToYaml(rules), "utf8");
+    await fs.writeFile(paths.rulesChecklist, `# SotuRail Rules Checklist\n\n${rules.map((rule) => `- [ ] ${rule.title} (${rule.severity})`).join("\n")}\n`, "utf8");
+    await writeJson(paths.rulesCitations, rules.map((rule) => ({
+        id: rule.id,
+        source_file: rule.source_file,
+        source_section: rule.source_section,
+        content_hash: rule.content_hash
+    })));
+    await new MetricsStore(root).append({
+        type: "rules_ingest",
+        details: {
+            file: path.normalize(file).replace(/\\/g, "/"),
+            ingest_type: type,
+            extracted_rules_count: rules.length,
+            citations_count: rules.length
+        }
+    });
+    return [
+        `Ingested ${document.source_file} as ${type}.`,
+        `Extracted rules: ${rules.length}`,
+        `Rules: ${path.normalize(path.relative(root, paths.rulesFile)).replace(/\\/g, "/")}`,
+        `Checklist: ${path.normalize(path.relative(root, paths.rulesChecklist)).replace(/\\/g, "/")}`,
+        `Citations: ${path.normalize(path.relative(root, paths.rulesCitations)).replace(/\\/g, "/")}`
+    ].join("\n") + "\n";
+}
+export function registerIngestCommand(program) {
+    program
+        .command("ingest")
+        .description("Ingest Markdown, TXT, JSON or YAML into structured local rules.")
+        .argument("<file>", "Source file")
+        .option("--type <type>", "rules, requirements, docs, or course", "docs")
+        .action(async (file, options) => {
+        process.stdout.write(await ingestCommand(file, options));
+    });
+}
+//# sourceMappingURL=ingest.js.map

package/dist/commands/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../src/commands/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAmB,MAAM,4BAA4B,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAMtE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY,EAAE,UAAyB,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACjG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IACpC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,IAAI,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,IAAkB,EAAE,IAAI,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,kBAAkB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,MAAM,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,EAAE,CAAC,SAAS,CAChB,KAAK,CAAC,cAAc,EACpB,iCAAiC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAC7G,MAAM,CACP,CAAC;IACF,MAAM,SAAS,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzD,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC,CAAC,CAAC,CAAC;IACL,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QAClC,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;YAC9C,WAAW,EAAE,IAAI;YACjB,qBAAqB,EAAE,KAAK,CAAC,MAAM;YACnC,eAAe,EAAE,KAAK,CAAC,MAAM;SAC9B;KACF,CAAC,CAAC;IACH,OAAO;QACL,YAAY,QAAQ,CAAC,WAAW,OAAO,IAAI,GAAG;QAC9C,oBAAoB,KAAK,CAAC,MAAM,EAAE;QAClC,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE;QACpF,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE;QAC7F,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE;KAC9F,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,iEAAiE,CAAC;SAC9E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;SACjC,MAAM,CAAC,eAAe,EAAE,sCAAsC,EAAE,MAAM,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,IAAY,EAAE,OAAsB,EAAE,EAAE;QACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from "commander";
+import { type EnsureResult } from "../core/config.js";
+export interface InitReport extends EnsureResult {
+}
+export declare function runInit(root?: string): Promise<InitReport>;
+export declare function formatInitReport(report: InitReport): string;
+export declare function registerInitCommand(program: Command): void;

package/dist/commands/init.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import { ensureWorkspace, writeFileIfMissing } from "../core/config.js";
+const text = {
+    agents: `# AGENTS.md
+
+SotuRail context rails for AI coding agents.
+
+- Prefer soturail index before asking an agent to reason about the whole repo.
+- Use soturail read <file> --query "goal" for large files.
+- Run commands through soturail run so raw logs remain recoverable.
+- Do not run git push automatically.
+`,
+    claude: `# CLAUDE.md
+
+Claude Code should treat SotuRail output as scoped context.
+
+Stable project blocks belong before dynamic session data. Raw logs are recoverable with soturail expand <raw_id>.
+`,
+    gemini: `# GEMINI.md
+
+Gemini CLI should use SotuRail as a local context boundary.
+
+Prefer repo maps and progressive reads over dumping entire repositories into prompts.
+`,
+    architecture: `# Architecture
+
+SotuRail v0.1.0 is local-first TypeScript/Node.js software.
+
+Core loops:
+
+1. Scan the repository into a Heuristic Repo Map.
+2. Read large files progressively.
+3. Run commands through a safe tee-stream adapter.
+4. Store raw logs locally and summarize them for agent context.
+5. Keep stable prompt blocks before dynamic session data.
+`,
+    mvp: `# MVP
+
+SotuRail v0.1.0 focuses on functional local rails:
+
+- init
+- index
+- read
+- run
+- expand
+- spec
+- memory
+- doctor
+- stats
+`,
+    usage: `# Usage
+
+\`\`\`bash
+soturail init
+soturail index
+soturail read src/cli.ts --query "commands"
+soturail run npm test
+soturail expand <raw_id>
+\`\`\`
+`,
+    security: `# Security Model
+
+SotuRail blocks dangerous commands by default, including rm -rf, sudo, format, dd if=, curl | sh, del /s and git push.
+
+Bypass requires the exact unsafe confirmation phrase and should be used rarely.
+`,
+    caching: `# Prompt Caching
+
+SotuRail separates stable and dynamic blocks. Dynamic data such as timestamps, raw ids, command status and recent logs belongs after stable governance, config, repo maps, approved specs and approved memory.
+
+v0.1.0 reports estimated cache stability only. It does not claim provider cache hits.
+`,
+    metrics: `# Metrics
+
+Metrics are append-only local JSONL events. Token counts are deterministic estimates and not provider billing numbers.
+`,
+    release: `# Release Checklist
+
+- npm install
+- npm run build
+- npm test
+- Review docs and security model
+- Confirm no telemetry exists
+- Do not git push automatically
+`,
+    screenshots: `# Screenshots
+
+Add terminal screenshots or Markdown previews here when preparing releases.
+`,
+    ptBr: `# Visao geral
+
+SotuRail e um Context OS local-first para agentes de IA de desenvolvimento. Ele indexa repositorios, le arquivos progressivamente, executa comandos com logs brutos recuperaveis e organiza contexto estavel para prompt caching.
+`,
+    benchmarking: `# Benchmarking
+
+Run soturail bench prepare, soturail bench run and soturail bench report to generate local benchmark evidence.
+`,
+    hooks: `# Agent Hooks
+
+SotuRail provides dry-run hook installers and prompt-only fallbacks for Claude, Codex, Gemini and Cursor.
+`,
+    nativeRunner: `# Native Runner
+
+The optional Rust reducer engine is detected automatically and TypeScript reducers remain the fallback.
+`,
+    reducers: `# Reducers
+
+SotuRail reducers preserve raw-log recovery while compressing Git, test, JSON and generic output.
+`,
+    responseCompression: `# Agent Response Compression
+
+soturail format compresses verbose AI responses into deterministic task-oriented modes.
+`,
+    knowledgeToRules: `# Knowledge-to-Rules
+
+soturail ingest turns Markdown, TXT, JSON and YAML into structured local rules and validators.
+`,
+    rules: `# Rules
+
+Rules are stored under .soturail/rules and can be listed, checked and exported.
+`,
+    specWorkflow: `# Spec-Driven Workflow
+
+soturail spec manages constitution, spec, plan, tasks, verification, context budget and security impact files.
+`
+};
+function documentationTemplates(root) {
+    return [
+        { path: path.resolve(root, "AGENTS.md"), content: text.agents },
+        { path: path.resolve(root, "CLAUDE.md"), content: text.claude },
+        { path: path.resolve(root, "GEMINI.md"), content: text.gemini },
+        { path: path.resolve(root, "docs", "architecture.md"), content: text.architecture },
+        { path: path.resolve(root, "docs", "mvp.md"), content: text.mvp },
+        { path: path.resolve(root, "docs", "usage.md"), content: text.usage },
+        { path: path.resolve(root, "docs", "security-model.md"), content: text.security },
+        { path: path.resolve(root, "docs", "prompt-caching.md"), content: text.caching },
+        { path: path.resolve(root, "docs", "metrics.md"), content: text.metrics },
+        { path: path.resolve(root, "docs", "benchmarking.md"), content: text.benchmarking },
+        { path: path.resolve(root, "docs", "hooks.md"), content: text.hooks },
+        { path: path.resolve(root, "docs", "native-runner.md"), content: text.nativeRunner },
+        { path: path.resolve(root, "docs", "reducers.md"), content: text.reducers },
+        { path: path.resolve(root, "docs", "response-compression.md"), content: text.responseCompression },
+        { path: path.resolve(root, "docs", "knowledge-to-rules.md"), content: text.knowledgeToRules },
+        { path: path.resolve(root, "docs", "rules.md"), content: text.rules },
+        { path: path.resolve(root, "docs", "spec-driven-workflow.md"), content: text.specWorkflow },
+        { path: path.resolve(root, "docs", "release-checklist.md"), content: text.release },
+        { path: path.resolve(root, "docs", "assets", "screenshots", "README.md"), content: text.screenshots },
+        { path: path.resolve(root, "docs", "pt-BR", "visao-geral.md"), content: text.ptBr }
+    ];
+}
+export async function runInit(root = process.cwd()) {
+    const report = await ensureWorkspace(root);
+    for (const template of documentationTemplates(root)) {
+        await writeFileIfMissing(template.path, template.content, report, root);
+    }
+    return report;
+}
+export function formatInitReport(report) {
+    const lines = [
+        "SotuRail workspace initialized.",
+        "",
+        `Created paths (${report.created.length}):`,
+        ...(report.created.length > 0 ? report.created.map((item) => `  + ${item}`) : ["  none"]),
+        "",
+        `Skipped existing paths (${report.skipped.length}):`,
+        ...(report.skipped.length > 0 ? report.skipped.map((item) => `  = ${item}`) : ["  none"])
+    ];
+    return `${lines.join("\n")}\n`;
+}
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("Create a non-destructive .soturail workspace and starter docs.")
+        .action(async () => {
+        const report = await runInit();
+        process.stdout.write(formatInitReport(report));
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

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