soturail 0.2.1 → 0.2.2

package/dist/core/self-dogfood.js

@@ -0,0 +1,323 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { PassThrough } from "node:stream";
+import { promisify } from "node:util";
+import { runBenchmarks, summarizeBenchmarkResults } from "../commands/bench.js";
+import { executeRunCommand } from "../commands/run.js";
+import { ensureWorkspace, getWorkspacePaths, loadConfig } from "./config.js";
+import { scanRepository, writeRepoMap } from "./file-scanner.js";
+import { getCurrentGitCommit } from "./git.js";
+import { estimateTokens } from "./token-estimator.js";
+const execFileAsync = promisify(execFile);
+const REQUIRED_SOTURAIL_PATHS = [
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    path.join("src", "cli.ts"),
+    path.join("src", "commands"),
+    path.join("src", "core"),
+    "tests",
+    "docs"
+];
+export function createEmptySelfState() {
+    return { errors: [] };
+}
+export async function selfDoctor(root = process.cwd()) {
+    const resolvedRoot = path.resolve(root);
+    const missing = [];
+    for (const required of REQUIRED_SOTURAIL_PATHS) {
+        const absolute = path.resolve(resolvedRoot, required);
+        try {
+            await fs.access(absolute);
+        }
+        catch {
+            missing.push(path.normalize(required));
+        }
+    }
+    const packageJson = await readPackageJson(resolvedRoot);
+    if (packageJson.name !== "soturail") {
+        missing.push("package.json:name=soturail");
+    }
+    return {
+        ok: missing.length === 0,
+        root: resolvedRoot,
+        package_name: typeof packageJson.name === "string" ? packageJson.name : null,
+        package_version: typeof packageJson.version === "string" ? packageJson.version : null,
+        missing
+    };
+}
+export async function assertSotuRailRepository(root = process.cwd()) {
+    const doctor = await selfDoctor(root);
+    if (!doctor.ok) {
+        throw new Error(`This directory does not look like the SotuRail repository. Missing: ${doctor.missing.join(", ")}`);
+    }
+    return doctor;
+}
+export async function selfIndex(root = process.cwd()) {
+    await assertSotuRailRepository(root);
+    await ensureWorkspace(root);
+    const config = await loadConfig(root);
+    const repoMap = await scanRepository(root, config);
+    await writeRepoMap(root, repoMap);
+    return {
+        indexed_files_count: repoMap.total_files,
+        ignored_files_count: repoMap.stats.ignored_files,
+        ignored_directories_count: repoMap.stats.ignored_directories
+    };
+}
+export async function selfBuild(root = process.cwd(), terminalStdout, terminalStderr) {
+    return selfRunCommand(["npm", "run", "build"], root, terminalStdout, terminalStderr);
+}
+export async function selfTest(root = process.cwd(), terminalStdout, terminalStderr) {
+    return selfRunCommand(["npm", "test"], root, terminalStdout, terminalStderr);
+}
+export async function selfBench(root = process.cwd(), terminalStdout, terminalStderr) {
+    await assertSotuRailRepository(root);
+    const cliPath = path.resolve(root, "dist", "cli.js");
+    let runResult = null;
+    try {
+        await fs.access(cliPath);
+        runResult = await executeRunCommand([`"${process.execPath}" "${cliPath}" bench run --engine ts`], {
+            terminalStdout: terminalStdout ?? drainedStream(),
+            terminalStderr: terminalStderr ?? drainedStream(),
+            engine: "ts"
+        }, root);
+    }
+    catch {
+        // If the built CLI is unavailable, the in-process benchmark path still gives a real report.
+    }
+    const results = runResult ? await readLatestBenchmarkResults(root) : await runBenchmarks({ engine: "ts" }, root);
+    return {
+        ok: runResult ? runResult.exitCode === 0 : true,
+        raw_id: runResult?.rawId ?? null,
+        cases_count: results.length,
+        summary: summarizeBenchmarkResults(results),
+        results
+    };
+}
+export async function writeSelfReport(input) {
+    const root = path.resolve(input.root ?? process.cwd());
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const reportsDir = path.resolve(paths.workspace, "reports");
+    await fs.mkdir(reportsDir, { recursive: true });
+    const reportPath = path.resolve(reportsDir, "self-dogfood.md");
+    const packageJson = await readPackageJson(root);
+    const commit = await getCurrentGitCommit(root);
+    const branch = await getCurrentGitBranch(root);
+    const accounting = selfTokenAccounting(input);
+    const report = [
+        "# SotuRail Self-Dogfood Report",
+        "",
+        "## Stable Project Description",
+        "",
+        "SotuRail aims to unify terminal compression, progressive repo reading, Spec-Driven workflows, local memory, rules extraction, agent hooks, benchmarks and cache-friendly payloads into one local-first workflow.",
+        "",
+        `- package_name: ${stringOrUnknown(packageJson.name)}`,
+        `- package_version: ${stringOrUnknown(packageJson.version)}`,
+        "- report_schema: self-dogfood-v1",
+        "",
+        "## Stable Quality Rails",
+        "",
+        "- Build, test and benchmark commands should run through SotuRail so raw logs are recoverable.",
+        "- Token counts are deterministic estimates unless provider metadata is explicitly imported.",
+        "- Dynamic raw IDs, timestamps, logs and volatile command status stay below this stable section.",
+        "",
+        "## Dynamic Execution Data",
+        "",
+        `- repository_path: ${path.normalize(root)}`,
+        `- current_git_commit_hash: ${commit ?? "unknown"}`,
+        `- current_branch: ${branch ?? "unknown"}`,
+        `- doctor_ok: ${input.doctor?.ok ?? false}`,
+        `- indexed_files_count: ${input.index?.indexed_files_count ?? 0}`,
+        `- ignored_files_directories_count: ${(input.index?.ignored_files_count ?? 0) + (input.index?.ignored_directories_count ?? 0)}`,
+        `- build_result: ${formatStep(input.build)}`,
+        `- test_result: ${formatStep(input.test)}`,
+        `- benchmark_summary: ${input.bench?.summary.replace(/\r?\n/g, " | ") ?? "not run"}`,
+        `- build_raw_id: ${input.build?.raw_id ?? "n/a"}`,
+        `- test_raw_id: ${input.test?.raw_id ?? "n/a"}`,
+        `- benchmark_raw_id: ${input.bench?.raw_id ?? "n/a"}`,
+        `- estimated_raw_tokens: ${accounting.estimated_raw_tokens}`,
+        `- estimated_reduced_tokens: ${accounting.estimated_reduced_tokens}`,
+        `- estimated_metadata_overhead_tokens: ${accounting.estimated_metadata_overhead_tokens}`,
+        `- compression_effective: ${accounting.compression_effective}`,
+        "",
+        "## Known Limitations",
+        "",
+        "- Native benchmark rows are marked unavailable when the optional native binary is not built.",
+        "- Self-dogfood reports are local evidence, not provider cache-hit evidence.",
+        "- Small command outputs may cost more after metadata, but recovery and audit paths remain valuable.",
+        "",
+        "## Recommended Next Action",
+        "",
+        input.errors.length > 0
+            ? `Review partial failures: ${input.errors.join("; ")}`
+            : "Keep running `soturail self all` before release-oriented commits.",
+        ""
+    ].join("\n");
+    await fs.writeFile(reportPath, report, "utf8");
+    return reportPath;
+}
+export async function selfAll(root = process.cwd(), terminalStdout, terminalStderr) {
+    const state = createEmptySelfState();
+    try {
+        state.doctor = await selfDoctor(root);
+        if (!state.doctor.ok) {
+            state.errors.push(`doctor failed: ${state.doctor.missing.join(", ")}`);
+            state.report_path = await writeSelfReport({ ...state, root });
+            return state;
+        }
+        state.index = await selfIndex(root);
+        state.build = await selfBuild(root, terminalStdout, terminalStderr);
+        if (!state.build.ok) {
+            state.errors.push(`build failed: raw_id=${state.build.raw_id ?? "n/a"}`);
+            state.report_path = await writeSelfReport({ ...state, root });
+            return state;
+        }
+        state.test = await selfTest(root, terminalStdout, terminalStderr);
+        if (!state.test.ok) {
+            state.errors.push(`test failed: raw_id=${state.test.raw_id ?? "n/a"}`);
+            state.report_path = await writeSelfReport({ ...state, root });
+            return state;
+        }
+        state.bench = await selfBench(root, terminalStdout, terminalStderr);
+        if (!state.bench.ok) {
+            state.errors.push(`bench failed: raw_id=${state.bench.raw_id ?? "n/a"}`);
+        }
+    }
+    catch (error) {
+        state.errors.push(error instanceof Error ? error.message : String(error));
+    }
+    state.report_path = await writeSelfReport({ ...state, root });
+    return state;
+}
+export function formatSelfDoctor(result) {
+    return [
+        "SotuRail self doctor",
+        `ok: ${result.ok}`,
+        `root: ${path.normalize(result.root)}`,
+        `package_name: ${result.package_name ?? "unknown"}`,
+        `package_version: ${result.package_version ?? "unknown"}`,
+        `missing: ${result.missing.length === 0 ? "none" : result.missing.join(", ")}`
+    ].join("\n") + "\n";
+}
+export function formatSelfIndex(result) {
+    return [
+        "SotuRail self index",
+        `indexed_files_count: ${result.indexed_files_count}`,
+        `ignored_files_count: ${result.ignored_files_count}`,
+        `ignored_directories_count: ${result.ignored_directories_count}`
+    ].join("\n") + "\n";
+}
+export function formatSelfRunStep(label, result) {
+    return [
+        `SotuRail self ${label}`,
+        `ok: ${result.ok}`,
+        `exit_code: ${result.exit_code ?? "n/a"}`,
+        `raw_id: ${result.raw_id ?? "n/a"}`
+    ].join("\n") + "\n";
+}
+export function formatSelfBench(result) {
+    return [
+        "SotuRail self bench",
+        `ok: ${result.ok}`,
+        `raw_id: ${result.raw_id ?? "n/a"}`,
+        `cases_count: ${result.cases_count}`,
+        result.summary
+    ].join("\n") + "\n";
+}
+function selfTokenAccounting(input) {
+    const estimatedRaw = (input.build?.raw_tokens ?? 0) + (input.test?.raw_tokens ?? 0);
+    const estimatedReduced = (input.build?.reduced_tokens ?? 0) + (input.test?.reduced_tokens ?? 0);
+    const metadata = estimateTokens(JSON.stringify({
+        doctor: input.doctor?.ok,
+        index: input.index,
+        build_raw_id: input.build?.raw_id,
+        test_raw_id: input.test?.raw_id,
+        bench_raw_id: input.bench?.raw_id
+    }));
+    return {
+        estimated_raw_tokens: estimatedRaw,
+        estimated_reduced_tokens: estimatedReduced,
+        estimated_metadata_overhead_tokens: metadata,
+        compression_effective: estimatedReduced + metadata <= estimatedRaw
+    };
+}
+async function selfRunCommand(commandParts, root, terminalStdout, terminalStderr) {
+    await assertSotuRailRepository(root);
+    try {
+        const result = await executeRunCommand(commandParts, {
+            terminalStdout: terminalStdout ?? drainedStream(),
+            terminalStderr: terminalStderr ?? drainedStream(),
+            engine: "ts"
+        }, root);
+        return {
+            ok: result.exitCode === 0,
+            exit_code: result.exitCode,
+            raw_id: result.rawId,
+            raw_tokens: result.record.raw_tokens_estimated,
+            reduced_tokens: result.record.compressed_tokens_estimated,
+            summary: result.summary
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            exit_code: null,
+            raw_id: null,
+            raw_tokens: 0,
+            reduced_tokens: 0,
+            summary: "",
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+async function readPackageJson(root) {
+    try {
+        return JSON.parse(await fs.readFile(path.resolve(root, "package.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+async function readLatestBenchmarkResults(root) {
+    const filePath = path.resolve(root, "benchmarks", "results", "latest.json");
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        return Array.isArray(parsed.results) ? parsed.results : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function getCurrentGitBranch(root) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: root,
+            timeout: 3000,
+            windowsHide: true
+        });
+        const branch = stdout.trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
+function drainedStream() {
+    const stream = new PassThrough();
+    stream.resume();
+    return stream;
+}
+function formatStep(step) {
+    if (!step) {
+        return "not run";
+    }
+    return step.ok ? `pass exit_code=${step.exit_code}` : `fail exit_code=${step.exit_code ?? "n/a"}`;
+}
+function stringOrUnknown(value) {
+    return typeof value === "string" && value.length > 0 ? value : "unknown";
+}
+//# sourceMappingURL=self-dogfood.js.map

package/dist/core/self-dogfood.js.map

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

package/docs/benchmarking.md

@@ -18,9 +18,11 @@ The suite groups results as:
 
 - terminal compression;
 - agent response compression;
-- JSON/tool payload compression;
 - knowledge structuring;
-- native performance when available.
+- cache stability;
+- native engine availability/performance when available.
+
+Terminal compression includes npm install noise, Vitest failures, TypeScript diagnostics, git diff/status noise and JSON/tool payload output.
 
 Knowledge-to-Rules is not judged as pure compression. It creates reusable structured rules, citations and validator metadata.
 

package/docs/hooks/claude.md

@@ -5,6 +5,8 @@ SotuRail v0.2.1 includes a conservative Claude Code hook template.
 ```bash
 soturail hooks install claude --dry-run
 soturail hooks install claude
+soturail hooks uninstall claude
+soturail hooks prompt-only claude
 ```
 
 Generated files:
@@ -19,6 +21,8 @@ The pre-tool hook inspects incoming tool payload text when Claude Code provides
 
 The hook never routes `git push` through `soturail run`.
 
+Review generated settings and scripts before relying on them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.
+
 ## Limitation
 
 Claude Code hook schemas may vary by installed version. SotuRail writes a conservative documented template; if your Claude Code release expects a different schema, copy the generated command into the supported hook slot manually.

package/docs/hooks/codex.md

@@ -3,3 +3,14 @@
 Codex prompt-only integration uses `AGENTS.md`.
 
 SotuRail does not assume private Codex host hook APIs. The fallback rules describe when to index, read progressively, run through SotuRail and avoid `git push`.
+
+Useful commands:
+
+```bash
+soturail hooks install codex --dry-run
+soturail hooks install codex
+soturail hooks uninstall codex
+soturail hooks prompt-only codex
+```
+
+Existing `AGENTS.md` content is backed up before install. Review generated prompt rules before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/hooks/cursor.md

@@ -3,3 +3,14 @@
 Cursor prompt-only integration writes `.cursor/rules/soturail.mdc` when installed.
 
 Existing files are backed up before SotuRail adds its rules.
+
+Useful commands:
+
+```bash
+soturail hooks install cursor --dry-run
+soturail hooks install cursor
+soturail hooks uninstall cursor
+soturail hooks prompt-only cursor
+```
+
+Review generated prompt rules before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/hooks/gemini.md

@@ -3,3 +3,14 @@
 Gemini prompt-only integration uses `GEMINI.md`.
 
 The generated rules keep repository scans, progressive file reads and raw log recovery visible to Gemini CLI sessions.
+
+Useful commands:
+
+```bash
+soturail hooks install gemini --dry-run
+soturail hooks install gemini
+soturail hooks uninstall gemini
+soturail hooks prompt-only gemini
+```
+
+Existing `GEMINI.md` content is backed up before install. Review generated prompt rules before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/hooks.md

@@ -6,6 +6,8 @@ SotuRail hook support is cautious. Claude gets a conservative hook template firs
 soturail hooks list
 soturail hooks doctor
 soturail hooks install claude --dry-run
+soturail hooks install claude
+soturail hooks uninstall claude
 soturail hooks install all --dry-run
 soturail hooks prompt-only codex
 ```
@@ -13,3 +15,12 @@ soturail hooks prompt-only codex
 Installers create backups before modifying existing files. If a host config location is uncertain, SotuRail generates prompt-only guidance instead of guessing.
 
 Claude install writes `.claude/settings.json` and hook scripts under `.claude/hooks/`. Dry-run prints every file that would change.
+
+Always review generated hooks before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts. Prompt-only fallback remains available for every host:
+
+```bash
+soturail hooks prompt-only claude
+soturail hooks prompt-only codex
+soturail hooks prompt-only gemini
+soturail hooks prompt-only cursor
+```

package/docs/release-checklist.md

@@ -2,12 +2,42 @@
 
 Before publishing:
 
+- [ ] Confirm `npm whoami` works for the publishing account.
+- [ ] Confirm npm 2FA requirements and have the authenticator ready.
 - [ ] `npm install`
 - [ ] `npm run build`
 - [ ] `npm test`
-- [ ] Verify `soturail --help`
-- [ ] Verify `soturail init` in a clean temp repo
-- [ ] Confirm docs mention limitations honestly
-- [ ] Confirm no telemetry exists
-- [ ] Confirm no `git push` was run automatically
-- [ ] Tag release manually after review
+- [ ] `npm audit --omit=dev`
+- [ ] `node dist/cli.js self all`
+- [ ] `npm pack --dry-run`
+- [ ] `npm run release:check`
+- [ ] Confirm docs mention limitations honestly.
+- [ ] Confirm no telemetry exists.
+- [ ] Confirm no `git push` is routed through `soturail run`.
+
+## Audit Distinction
+
+`npm audit` checks all dependencies, including dev dependencies used for local tests and builds.
+
+`npm audit --omit=dev` checks runtime/public dependency risk for published package users.
+
+Runtime audit is clean with `npm audit --omit=dev`. Remaining audit findings, if any, are development dependency findings and should be upgraded safely without `--force`.
+
+For v0.2.2, the full audit findings are in the Vitest/Vite development test stack. npm's suggested fix is a semver-major Vitest upgrade, so do not run `npm audit fix --force` blindly.
+
+## Windows Paste Safety
+
+Do not paste Markdown prose or code-fence labels directly into `cmd.exe` as commands. For example, do not paste ```` ```bat ````. Copy only the command lines themselves.
+
+See [docs/windows.md](windows.md) for CMD and PowerShell quoting notes.
+
+## Automation
+
+Use:
+
+```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
+```

package/docs/release-workflow.md

@@ -0,0 +1,54 @@
+# Release Workflow
+
+SotuRail releases should be repeatable and evidence-backed. The release helper lives at `scripts/release.mjs`.
+
+## Check
+
+```bash
+npm run release:check
+```
+
+Runs install, build, tests, runtime audit, self-dogfooding, pack dry-run and npm version checks. It also reports whether full audit findings are development-only.
+
+## Prepare
+
+```bash
+npm run release:prepare -- --version X.Y.Z
+```
+
+Prepare mode:
+
+- validates the version argument;
+- updates `package.json`, `package-lock.json` and CLI version text;
+- updates `CHANGELOG.md`;
+- creates `RELEASE_NOTES_vX.Y.Z.md`;
+- runs validation;
+- commits `chore(release): prepare vX.Y.Z`;
+- pushes `main`;
+- never publishes to npm.
+
+## Publish
+
+```bash
+npm run release:publish -- --version X.Y.Z
+```
+
+Publish mode refuses to publish if build, tests or runtime audit fail, if the git tree is dirty, or if the version already exists on npm. If npm asks for 2FA or authentication, rerun the same command after completing the auth step.
+
+## Full
+
+```bash
+npm run release:full -- --version X.Y.Z
+```
+
+Full mode runs prepare, publish and then creates or updates the GitHub release using `gh` when available. If the npm version already exists, full mode skips npm publish and only creates or updates the GitHub release.
+
+Safety rules:
+
+- Never run `npm audit fix --force`.
+- Never publish if tests fail.
+- Never publish if build fails.
+- Never publish if runtime audit fails.
+- Never publish if the requested package version already exists on npm.
+- Never create a GitHub release before npm publish succeeds.
+- Never hide errors.

package/docs/skill-rail.md

@@ -0,0 +1,28 @@
+# Skill Rail
+
+Skill Rail is planned for v0.3.0. It is not implemented in v0.2.2.
+
+The goal is to turn approved SotuRail specs, rules and workflows into portable, reviewable agent skills without installing untrusted marketplace content automatically.
+
+Planned commands:
+
+```bash
+soturail skills init <name>
+soturail skills from-spec <spec-id>
+soturail skills from-rules <rules-file>
+soturail skills validate <path>
+soturail skills export claude|codex|gemini|cursor
+```
+
+## Security Requirements
+
+- No automatic marketplace install.
+- Validate `SKILL.md` before use.
+- Scan for prompt injection.
+- Scan for destructive shell commands.
+- Scan for secret exfiltration language.
+- Scan for `curl`/`wget` pipe execution.
+- Warn about untrusted scripts.
+- Require human approval before enabling generated skills.
+
+Skill Rail should preserve SotuRail's local-first evidence model: generated skills must cite the spec, rule or workflow that produced them.

package/docs/windows.md

@@ -0,0 +1,76 @@
+# Windows Notes
+
+SotuRail supports Windows through Node.js and uses cross-platform path handling internally. The main practical differences are shell quoting and how commands are pasted.
+
+## Install Globally
+
+PowerShell and CMD:
+
+```powershell
+npm install -g soturail
+soturail --help
+```
+
+## Run With npx
+
+```powershell
+npx soturail --help
+npx soturail init
+```
+
+## Test a Local Tarball
+
+From a source checkout:
+
+```powershell
+npm run build
+npm pack --dry-run
+npm pack
+npm install -g .\soturail-0.2.1.tgz
+soturail --version
+```
+
+If the tarball name changes, use the exact file that `npm pack` created.
+
+## CMD vs PowerShell
+
+PowerShell accepts commands like:
+
+```powershell
+node .\dist\cli.js read ".\README.md" --query "quick start"
+```
+
+CMD uses similar quoting, but it does not understand Markdown code-fence labels. Do not paste the literal fence label:
+
+```text
+```bat
+```
+
+into CMD. CMD will try to execute it and report an error.
+
+## Paths With Spaces
+
+Quote paths that contain spaces:
+
+```powershell
+soturail read "C:\Users\rafael\Documents\My Project\README.md" --query "install"
+```
+
+## Avoid Accidental Command Concatenation
+
+When copying examples, keep commands on separate lines. This is wrong:
+
+```text
+node app.jsnpx soturail --help
+```
+
+Run them separately:
+
+```powershell
+node app.js
+npx soturail --help
+```
+
+## Safety
+
+SotuRail blocks destructive command shapes through `soturail run`, including `rm -rf`, `sudo`, `del /s`, downloaded script piping and automatic `git push`.