soturail 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Ryan Ramos de Souza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+<p align="center">
+  <img src="docs/assets/soturail-fox.svg" alt="SotuRail fox logo" width="180" />
+</p>
+
+# SotuRail
+
+[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-3c873a)](package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![CI](https://github.com/Soturine/soturail/actions/workflows/ci.yml/badge.svg)](https://github.com/Soturine/soturail/actions/workflows/ci.yml)
+[![local-first](https://img.shields.io/badge/local--first-yes-f97316)](docs/security-model.md)
+[![context-engineering](https://img.shields.io/badge/context--engineering-SotuRail-7c3aed)](docs/prompt-caching.md)
+
+SotuRail — Local-first context rails for AI coding agents.  
+SotuRail — trilhos locais de contexto para agentes de IA.
+
+## 1. What Is SotuRail?
+
+SotuRail is a local-first Context OS for AI coding agents such as Claude Code, Codex CLI, Gemini CLI, Cursor and similar tools.
+
+It wraps a repository and terminal session with reversible evidence rails: heuristic repo maps, progressive file reading, safe command execution, raw log recovery, reducers, prompt-cache-friendly blocks, Spec-Driven Development artifacts, local memory, hooks, benchmarks and rules extraction.
+
+## Project Status
+
+v0.2.x is early but functional. TypeScript mode is stable for local usage. Native Rust mode is optional and focused on hot paths. Benchmarks are local and reproducible. External comparisons are optional and user-provided.
+
+## 2. Why SotuRail Exists
+
+AI coding agents often receive too much unstable context: full files, noisy test logs, repeated terminal output and long conversational summaries. SotuRail is designed to unify those workflows into one independent local-first tool without sending telemetry or inventing provider metrics.
+
+## 3. Key Features
+
+- Heuristic Repo Map with cross-platform ignore handling.
+- Progressive reader for large files with reversible collapsed ranges.
+- Safe tee-stream runner with raw log preservation.
+- Git, test, JSON and generic terminal reducers.
+- Optional Rust native reducer and runner hot paths with TypeScript fallback.
+- Cross-call dedupe for repeated command output.
+- Reproducible local benchmark suite.
+- Agent response compression modes.
+- Knowledge-to-Rules ingestion and validators.
+- Prompt-only and hook-style agent integrations.
+- SDD specs, approved memory and cache block normalization.
+- Honest local metrics.
+
+## 4. How It Differs Conceptually
+
+SotuRail is an independent implementation. It may be conceptually adjacent to terminal reducers, host hook systems, Spec-Driven Development kits and memory tools, but it does not depend on RTK, Squeez, Spec Kit, Caveman, MemPalace or proprietary workflows.
+
+SotuRail aims to unify these ideas into one local-first workflow: reversible raw logs, safety policy, benchmarks, prompt cache ordering, specs, memory, hooks and rules.
+
+## 5. Installation
+
+```bash
+npm install
+npm run build
+npm link
+soturail --help
+```
+
+Rust is optional. TypeScript builds do not require Rust.
+
+```bash
+npm run build:native   # optional, requires cargo
+npm run build:all      # TypeScript + native, requires cargo
+```
+
+## Native Performance Path
+
+TypeScript remains the public CLI, orchestration, docs and npm distribution layer. Rust handles optional hot paths where streaming, low overhead and binary execution matter:
+
+- native terminal reducers;
+- native JSON/tool payload reducer;
+- native tee-stream runner with raw log and summary sidecar support.
+
+SotuRail does not claim native speedups unless local benchmark results show them for your machine.
+
+## 6. Quick Start
+
+```bash
+soturail init
+soturail index
+soturail read README.md --query "quick start"
+soturail run npm test
+soturail expand <raw_id>
+soturail stats
+```
+
+## 7. Commands
+
+```bash
+soturail init
+soturail index
+soturail read <file> --query "goal"
+soturail run --engine auto <command...>
+soturail run --engine native <command...>
+soturail expand <raw_id>
+soturail bench prepare
+soturail bench run --engine ts
+soturail hooks list
+soturail format README.md --mode concise
+soturail ingest README.md --type docs
+soturail rules check
+soturail spec status
+soturail memory propose "decision"
+soturail doctor cache
+```
+
+## 8. Benchmarks
+
+SotuRail includes deterministic local fixtures for terminal compression, agent response compression, JSON/tool payload compression, Knowledge-to-Rules structuring and native performance readiness.
+
+```bash
+npm run build
+soturail bench prepare
+soturail bench run --engine ts
+soturail bench report
+```
+
+The latest report is written to [benchmarks/reports/latest.md](benchmarks/reports/latest.md). External comparisons are optional and user-provided only:
+
+```bash
+soturail bench compare-optional --tool rtk
+soturail bench compare-optional --tool squeez
+```
+
+### Benchmark Interpretation
+
+- Terminal compression measures how reducers shrink logs while preserving errors, paths and recovery links.
+- Agent response compression measures deterministic formatting modes.
+- JSON/tool payload compression preserves relevant primitive values while collapsing repetitive structure.
+- Knowledge-to-Rules is reusable structuring, not pure compression; structured rules can be larger than a tiny source document because they add citations and validator metadata.
+- Native performance compares Rust and TypeScript only when `soturail-native` is built locally.
+
+## 9. Agent Hooks
+
+SotuRail provides cautious hook scaffolding and prompt-only fallbacks:
+
+```bash
+soturail hooks list
+soturail hooks doctor
+soturail hooks install claude --dry-run
+soturail hooks prompt-only codex
+```
+
+Host APIs vary, so SotuRail never writes guessed config without showing the target and creating backups for existing files.
+
+## 10. Agent Response Compression
+
+SotuRail includes Caveman-like output compression as inspiration, implemented independently with professional modes:
+
+- `normal`
+- `concise`
+- `ultra`
+- `review`
+- `commit`
+- `debug`
+- `docs`
+
+It preserves fenced code blocks, shell commands, file paths, line numbers, security warnings and failure details using deterministic reducers. See [docs/response-compression.md](docs/response-compression.md).
+
+## 11. Knowledge-to-Rules Engine
+
+SotuRail can ingest Markdown, TXT, JSON and YAML into structured YAML/JSON rules, checklists, citations and simple validators.
+
+```bash
+soturail ingest docs/requirements.md --type requirements
+soturail rules list
+soturail rules check
+soturail rules export --format yaml
+```
+
+This makes heavy docs smaller, reusable and auditable without inventing rules that do not appear in the source. See [docs/knowledge-to-rules.md](docs/knowledge-to-rules.md).
+
+## 12. Prompt Caching Design
+
+Stable blocks are ordered before dynamic data:
+
+1. static_header
+2. governance
+3. config
+4. repo_map
+5. approved_specs
+6. approved_memory
+7. dynamic_footer
+
+SotuRail reports estimated cache stability only. It never claims real provider cache hits unless imported metadata exists.
+
+## 13. Security Model
+
+`soturail run` blocks dangerous patterns by default, including `rm -rf`, `sudo`, `format`, `dd if=`, `curl | sh`, `del /s` and `git push`.
+
+Raw logs may contain secrets because they preserve real terminal output. Treat `.soturail/raw/` as local evidence, not public artifact material.
+
+## 14. Roadmap
+
+See [ROADMAP.md](ROADMAP.md). v0.3.0 focuses on deeper native paths, MCP, hardened PDF extraction, semantic memory approval, Tree-sitter repo maps and optional local embeddings.
+
+## 15. Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Reducers, hooks and rules should include tests, safety notes and benchmark impact when relevant.
+
+## 16. License
+
+MIT © Rafael Ryan Ramos de Souza

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+export declare function buildProgram(): Command;

package/dist/cli.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { registerBenchCommand } from "./commands/bench.js";
+import { registerDedupeCommand } from "./commands/dedupe.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerExpandCommand } from "./commands/expand.js";
+import { registerFormatCommand } from "./commands/format.js";
+import { registerHooksCommand } from "./commands/hooks.js";
+import { registerIngestCommand } from "./commands/ingest.js";
+import { registerIndexCommand } from "./commands/index.js";
+import { registerInitCommand } from "./commands/init.js";
+import { registerMemoryCommand } from "./commands/memory.js";
+import { registerNativeCommand } from "./commands/native.js";
+import { registerReadCommand } from "./commands/read.js";
+import { registerRunCommand } from "./commands/run.js";
+import { registerRulesCommand } from "./commands/rules.js";
+import { registerSpecCommand } from "./commands/spec.js";
+import { registerStatsCommand } from "./commands/stats.js";
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name("soturail")
+        .description("Local-first Context OS rails for AI coding agents.")
+        .version("0.2.1")
+        .showHelpAfterError();
+    registerInitCommand(program);
+    registerIndexCommand(program);
+    registerReadCommand(program);
+    registerRunCommand(program);
+    registerBenchCommand(program);
+    registerDedupeCommand(program);
+    registerExpandCommand(program);
+    registerFormatCommand(program);
+    registerHooksCommand(program);
+    registerIngestCommand(program);
+    registerSpecCommand(program);
+    registerMemoryCommand(program);
+    registerNativeCommand(program);
+    registerRulesCommand(program);
+    registerDoctorCommand(program);
+    registerStatsCommand(program);
+    return program;
+}
+const currentFile = fileURLToPath(import.meta.url);
+if (process.argv[1] && path.resolve(process.argv[1]) === currentFile) {
+    buildProgram().parseAsync(process.argv).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`SotuRail error: ${message}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO;SACJ,IAAI,CAAC,UAAU,CAAC;SAChB,WAAW,CAAC,oDAAoD,CAAC;SACjE,OAAO,CAAC,OAAO,CAAC;SAChB,kBAAkB,EAAE,CAAC;IAExB,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAE9B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,WAAW,EAAE,CAAC;IACrE,YAAY,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC/D,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,OAAO,IAAI,CAAC,CAAC;QACrD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/bench.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from "commander";
+import { type ReducerEngine } from "../core/native-engine.js";
+interface BenchOptions {
+    engine?: ReducerEngine;
+    tool?: string;
+}
+interface BenchResult {
+    name: string;
+    category: "terminal_compression" | "agent_response_compression" | "json_tool_payload_compression" | "knowledge_structuring" | "native_performance";
+    engine: string;
+    raw_bytes: number;
+    reduced_bytes: number;
+    estimated_raw_tokens: number;
+    estimated_reduced_tokens: number;
+    compression_ratio_percent: number | null;
+    wall_time_ms: number;
+    preserved_error_lines_count: number;
+    preserved_file_paths_count: number;
+    raw_id: string | null;
+    raw_sha256: string;
+    reduced_sha256: string;
+    quality_passed: boolean;
+    details: Record<string, unknown>;
+}
+export declare function prepareBenchmarks(root?: string): Promise<string>;
+export declare function runBenchmarks(options?: BenchOptions, root?: string): Promise<BenchResult[]>;
+export declare function compareEngines(root?: string): Promise<string>;
+export declare function reportBenchmarks(root?: string): Promise<string>;
+export declare function compareOptional(tool: string, root?: string): Promise<string>;
+export declare function registerBenchCommand(program: Command): void;
+export {};