soturail 0.2.1 → 0.2.3

package/README.md

@@ -8,6 +8,8 @@
 [![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)
+[![npm version](https://img.shields.io/npm/v/soturail.svg)](https://www.npmjs.com/package/soturail)
+[![npm downloads](https://img.shields.io/npm/dm/soturail.svg)](https://www.npmjs.com/package/soturail)
 [![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)
 
@@ -24,6 +26,48 @@ It wraps a repository and terminal session with reversible evidence rails: heuri
 
 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.
 
+## Built With SotuRail
+
+SotuRail now dogfoods itself for release-oriented development. `soturail self all` runs repository checks, indexing, build, tests, benchmarks and a local Markdown report through SotuRail's own rails.
+
+## Self-Dogfooding
+
+```bash
+soturail self doctor
+soturail self index
+soturail self build
+soturail self test
+soturail self bench
+soturail self report
+soturail self all
+```
+
+Reports are written to `.soturail/reports/self-dogfood.md` with stable project context first and dynamic raw IDs, command status and benchmark data later.
+
+## Release Workflow
+
+Release automation is local-first and conservative:
+
+```bash
+npm run release:check
+npm run release:prepare -- --version X.Y.Z
+npm run release:publish -- --version X.Y.Z
+npm run release:full -- --version X.Y.Z
+```
+
+The release script never runs `npm audit fix --force`, never publishes when build/tests/runtime audit fail and never creates a GitHub release before npm publish succeeds. See [docs/release-workflow.md](docs/release-workflow.md).
+
+## Release Reliability
+
+SotuRail includes a release preflight check to prevent stale package metadata, broken npm CLI binaries, missing release notes, and changelog/version mismatches.
+
+```bash
+npm run build
+npm test
+npm run release:check
+npm pack --dry-run
+```
+
 ## 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.
@@ -51,6 +95,23 @@ SotuRail aims to unify these ideas into one local-first workflow: reversible raw
 
 ## 5. Installation
 
+Use directly with npx:
+
+```bash
+npx soturail --help
+npx soturail@0.2.3 --help
+```
+
+Install globally:
+
+```bash
+npm install -g soturail
+soturail --help
+soturail --version
+```
+
+For local development from source:
+
 ```bash
 npm install
 npm run build
@@ -65,6 +126,8 @@ npm run build:native   # optional, requires cargo
 npm run build:all      # TypeScript + native, requires cargo
 ```
 
+npm package: https://www.npmjs.com/package/soturail
+
 ## 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:
@@ -132,6 +195,10 @@ soturail bench compare-optional --tool squeez
 - 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.
 
+## Honest Metrics
+
+Local token counts are deterministic estimates. SotuRail reports raw payload tokens, reduced payload tokens, metadata overhead and net estimated tokens. For tiny outputs, compression may be ineffective once recovery metadata is included; SotuRail says that directly while preserving raw recovery paths.
+
 ## 9. Agent Hooks
 
 SotuRail provides cautious hook scaffolding and prompt-only fallbacks:
@@ -145,6 +212,8 @@ soturail hooks prompt-only codex
 
 Host APIs vary, so SotuRail never writes guessed config without showing the target and creating backups for existing files.
 
+Review generated hooks before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.
+
 ## 10. Agent Response Compression
 
 SotuRail includes Caveman-like output compression as inspiration, implemented independently with professional modes:
@@ -192,6 +261,18 @@ SotuRail reports estimated cache stability only. It never claims real provider c
 
 Raw logs may contain secrets because they preserve real terminal output. Treat `.soturail/raw/` as local evidence, not public artifact material.
 
+## Windows Notes
+
+Windows users should see [docs/windows.md](docs/windows.md) for CMD vs PowerShell quoting, global install, `npx`, local tarball testing and common paste mistakes such as copying Markdown code-fence labels into CMD.
+
+## Road To Skill Rail
+
+Skill Rail and Workflow Rail are planned, not implemented in v0.2.x. See [docs/skill-rail.md](docs/skill-rail.md) and [docs/workflow-rail.md](docs/workflow-rail.md) for the security-first roadmap.
+
+## Comparison Philosophy
+
+SotuRail is inspired by the broader context-engineering ecosystem, including terminal reducers, agent response compression, spec-driven workflows, local memory, rules extraction, hooks, benchmarks and skill registries. SotuRail does not vendor or depend on those projects. It aims to unify similar ideas into one local-first workflow while keeping benchmarks honest.
+
 ## 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.

package/dist/cli.js

@@ -16,14 +16,17 @@ 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 { registerSelfCommand } from "./commands/self.js";
 import { registerSpecCommand } from "./commands/spec.js";
 import { registerStatsCommand } from "./commands/stats.js";
+import { registerReleaseCommand } from "./commands/release.js";
+import { SOTURAIL_VERSION } from "./core/version.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")
+        .version(SOTURAIL_VERSION)
         .showHelpAfterError();
     registerInitCommand(program);
     registerIndexCommand(program);
@@ -39,6 +42,8 @@ export function buildProgram() {
     registerMemoryCommand(program);
     registerNativeCommand(program);
     registerRulesCommand(program);
+    registerReleaseCommand(program);
+    registerSelfCommand(program);
     registerDoctorCommand(program);
     registerStatsCommand(program);
     return program;

package/dist/cli.js.map

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

package/dist/commands/bench.d.ts

@@ -4,28 +4,39 @@ interface BenchOptions {
     engine?: ReducerEngine;
     tool?: string;
 }
-interface BenchResult {
+export type BenchmarkCategory = "terminal_compression" | "agent_response_compression" | "knowledge_structuring" | "cache_stability" | "native_engine";
+export interface BenchResult {
+    case_id: string;
     name: string;
-    category: "terminal_compression" | "agent_response_compression" | "json_tool_payload_compression" | "knowledge_structuring" | "native_performance";
+    category: BenchmarkCategory;
     engine: string;
     raw_bytes: number;
     reduced_bytes: number;
+    raw_tokens: number;
+    reduced_tokens: number;
+    reduction_percent: number | null;
     estimated_raw_tokens: number;
     estimated_reduced_tokens: number;
     compression_ratio_percent: number | null;
+    runtime_ms: number;
     wall_time_ms: number;
+    quality_passed: boolean;
+    preserved_errors_count: number;
+    preserved_paths_count: number;
+    preserved_commands_count: number;
     preserved_error_lines_count: number;
     preserved_file_paths_count: number;
     raw_id: string | null;
     raw_sha256: string;
     reduced_sha256: string;
-    quality_passed: boolean;
+    notes: string;
     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 summarizeBenchmarkResults(results: BenchResult[]): string;
 export declare function compareOptional(tool: string, root?: string): Promise<string>;
 export declare function registerBenchCommand(program: Command): void;
 export {};