@bilalimamoglu/sift 0.4.0 → 0.4.2

package/README.md

@@ -4,17 +4,19 @@
 [![license](https://img.shields.io/github/license/bilalimamoglu/sift)](LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/bilalimamoglu/sift/ci.yml?branch=main&label=CI)](https://github.com/bilalimamoglu/sift/actions/workflows/ci.yml)
 
-<img src="assets/brand/sift-logo-minimal-teal-default.svg" alt="sift logo" width="140" />
+Turn 13,000 lines of test output into 2 root causes.
 
-Your AI agent should not be reading 13,000 lines of test output.
+Your agent reads a diagnosis, not a log file.
 
-On the largest real fixture in the benchmark:
-**Before:** 128 failures, 198K raw-output tokens, agent reconstructs the failure shape from scratch.
-**After:** 6 lines, 129 `standard` tokens, agent acts on a grouped diagnosis immediately.
+<p align="center">
+  <img src="assets/readme/test-status-demo.gif" alt="sift turning a pytest failure wall into a short diagnosis" width="960" />
+</p>
 
-```bash
-sift exec --preset test-status -- pytest -q
-```
+## Before / After
+
+128 test failures. 13,000 lines of logs. The agent reads all of it.
+
+With `sift`, it reads this instead:
 
 ```text
 - Tests did not pass.
@@ -28,13 +30,18 @@ sift exec --preset test-status -- pytest -q
 - Decision: stop and act.
 ```
 
-If 125 tests fail for one reason, the agent should pay for that reason once.
+Same diagnosis. One run compressed from 198,000 tokens to 129.
 
-## What it is
+## Not just tests
 
-Developers using coding agents — Claude Code, Codex, Cursor, Windsurf, Copilot, or any LLM-driven workflow that runs shell commands and reads the output.
+The same idea applies across noisy dev workflows:
 
-`sift` sits between the command and the agent. It captures noisy output, groups repeated failures into root-cause buckets, and returns a short diagnosis with an anchor, a likely fix, and a decision signal. The agent gets a map instead of a wall of text.
+- **Type errors** → grouped by error code, no model call
+- **Lint output** → grouped by rule, no model call
+- **Build failures** → first real error from webpack, esbuild/Vite, Cargo, Go, GCC/Clang
+- **`npm audit`** → high/critical vulnerabilities only, no model call
+- **`terraform plan`** → destructive risk detection, no model call
+- **Diffs and logs** → compressed through a cheaper model before reaching your agent
 
 ## Install
 
@@ -44,255 +51,101 @@ npm install -g @bilalimamoglu/sift
 
 Requires Node.js 20+.
 
-## Try it in 60 seconds
-
-If you already have an API key, you can try `sift` without any setup wizard:
+## Try it
 
 ```bash
-export OPENAI_API_KEY=your_openai_api_key
 sift exec --preset test-status -- pytest -q
+sift exec --preset test-status -- npx vitest run
+sift exec --preset test-status -- npx jest
 ```
 
-You can also use a freeform prompt for non-test output:
-
-```bash
-sift exec "what changed?" -- git diff
-```
-
-## Set it up for daily use
-
-Guided setup writes a machine-wide config, verifies the provider, and makes the CLI easier to use day to day:
+Other workflows:
 
 ```bash
-sift config setup
-sift doctor
-```
-
-Config lives at `~/.config/sift/config.yaml`. A repo-local `sift.config.yaml` can override it later.
-
-If you want your coding agent to use `sift` automatically, install the managed instruction block too:
-
-```bash
-sift agent install codex
-sift agent install claude
-```
-
-Then run noisy commands through `sift`:
-
-```bash
-sift exec --preset test-status -- <test command>
-sift exec "what changed?" -- git diff
+sift exec --preset typecheck-summary -- npx tsc --noEmit
+sift exec --preset lint-failures -- npx eslint src/
+sift exec --preset build-failure -- npm run build
 sift exec --preset audit-critical -- npm audit
 sift exec --preset infra-risk -- terraform plan
+sift exec "what changed?" -- git diff
 ```
 
-Useful flags:
-- `--dry-run` to preview the reduced input and prompt without calling a provider
-- `--show-raw` to print captured raw output to `stderr`
-- `--fail-on` to let reduced results fail CI for commands such as `npm audit` or `terraform plan`
-
-If you prefer environment variables instead of setup:
-
-```bash
-# OpenAI
-export SIFT_PROVIDER=openai
-export SIFT_BASE_URL=https://api.openai.com/v1
-export SIFT_MODEL=gpt-5-nano
-export OPENAI_API_KEY=your_openai_api_key
-
-# OpenRouter
-export SIFT_PROVIDER=openrouter
-export OPENROUTER_API_KEY=your_openrouter_api_key
-
-# Any OpenAI-compatible endpoint
-export SIFT_PROVIDER=openai-compatible
-export SIFT_BASE_URL=https://your-endpoint/v1
-export SIFT_PROVIDER_API_KEY=your_api_key
-```
-
-## Why it helps
-
-The core abstraction is a **bucket**: one distinct root cause, no matter how many tests it affects.
-
-Instead of making an agent reason over 125 repeated tracebacks, `sift` compresses them into one actionable bucket with:
-- a label
-- an affected count
-- an anchor
-- a likely fix
-- a decision signal
-
-That changes the agent's job from "figure out what happened" to "act on the diagnosis."
-
 ## How it works
 
-`sift` follows a cheapest-first pipeline:
-
-1. Capture command output.
-2. Sanitize sensitive-looking material.
-3. Apply local heuristics for known failure shapes.
-4. Escalate to a cheaper provider only if needed.
-5. Return a short diagnosis to the main agent.
+`sift` sits between a noisy command and a coding agent.
 
-It also returns a decision signal:
-- `stop and act` when the diagnosis is already actionable
-- `zoom` when one deeper pass is justified
-- raw logs only as a last resort
+1. Capture output.
+2. Run local heuristics for known failure shapes.
+3. If heuristics are confident, return the diagnosis. No model call.
+4. If not, call a cheaper model — not your agent's.
 
-For recognized formats, local heuristics can fully handle the output and skip the provider entirely.
+The agent gets the root cause, where it happens, and what to do next.
 
-The deepest local coverage today is test debugging, especially `pytest`, with growing support for `vitest` and `jest`. Other presets cover typecheck walls, lint failures, build errors, audit output, and Terraform risk detection.
+So your agent spends tokens fixing, not reading.
 
 ## Built-in presets
 
-Every preset runs local heuristics first. When the heuristic confidently handles the output, the provider is never called.
-
-| Preset | Heuristic | What it does |
-|--------|-----------|-------------|
-| `test-status` | Deep | Bucket/anchor/decision system for pytest, vitest, jest. 30+ failure patterns, confidence-gated stop/zoom decisions. |
-| `typecheck-summary` | Deterministic | Parses `tsc` output (standard and pretty formats), groups by error code, returns max 5 bullets. |
-| `lint-failures` | Deterministic | Parses ESLint stylish output, groups by rule, distinguishes errors from warnings, detects fixable hints. |
-| `audit-critical` | Deterministic | Extracts high/critical vulnerabilities from `npm audit` or similar. |
-| `infra-risk` | Deterministic | Detects destructive signals in `terraform plan` output. Returns pass/fail verdict. |
-| `build-failure` | Deterministic-first | Extracts the first concrete build error for recognized webpack, esbuild/Vite, Cargo, Go, GCC/Clang, and `tsc --build` output; falls back to the provider for unsupported formats. |
-| `diff-summary` | Provider | Summarizes changes and risks in diff output. |
-| `log-errors` | Provider | Extracts top error signals from log output. |
-
-Presets marked **Deterministic** bypass the provider entirely for recognized output formats. Presets marked **Deterministic-first** try a local heuristic first and fall back to the provider only when the captured output is unsupported or ambiguous. Presets marked **Provider** always call the LLM but benefit from input sanitization and truncation.
+Every preset runs local heuristics first. When the heuristic handles the output, the provider is never called.
 
-```bash
-sift exec --preset typecheck-summary -- npx tsc --noEmit
-sift exec --preset lint-failures -- npx eslint src/
-sift exec --preset build-failure -- npm run build
-sift exec --preset audit-critical -- npm audit
-sift exec --preset infra-risk -- terraform plan
-```
-
-On an interactive terminal, `sift` also shows a small stderr footer so humans can see whether the provider was skipped:
-
-```text
-[sift: heuristic • LLM skipped • summary 47ms]
-[sift: provider • LLM used • 380 tokens • summary 1.2s]
-```
+| Preset | What it does |
+|--------|-------------|
+| `test-status` | Groups pytest, vitest, jest failures into root-cause buckets with anchors and fix suggestions. 30+ failure patterns. |
+| `typecheck-summary` | Parses `tsc` output, groups by error code, returns max 5 bullets. No model call. |
+| `lint-failures` | Parses ESLint output, groups by rule, detects fixable hints. No model call. |
+| `build-failure` | Extracts first concrete error from webpack, esbuild/Vite, Cargo, Go, GCC/Clang, `tsc --build`. Falls back to model for unsupported formats. |
+| `audit-critical` | Extracts high/critical vulnerabilities from `npm audit`. No model call. |
+| `infra-risk` | Detects destructive signals in `terraform plan`. No model call. |
+| `diff-summary` | Summarizes changes and risks in diff output. |
+| `log-errors` | Extracts top error signals from log output. |
 
-Suppress the footer with `--quiet`:
-
-```bash
-sift exec --preset typecheck-summary --quiet -- npx tsc --noEmit
-```
+## Benchmark
 
-## Strongest today
+End-to-end debug loop on a real 640-test Python backend (125 repeated setup errors, 3 contract failures, 510 passing tests):
 
-`sift` is strongest when output is:
-- long
-- repetitive
-- triage-heavy
-- shaped by a small number of shared root causes
+| Metric | Without sift | With sift | Reduction |
+|--------|-------------|-----------|-----------|
+| Tokens | 52,944 | 20,049 | 62% fewer |
+| Tool calls | 40.8 | 12 | 71% fewer |
+| Wall-clock time | 244s | 85s | 65% faster |
+| Commands | 15.5 | 6 | 61% fewer |
+| Diagnosis | Same | Same | — |
 
-Best fits today:
-- large `pytest`, `vitest`, or `jest` runs
-- `tsc` type errors and `eslint` lint failures
-- build failures from webpack, esbuild/Vite, Cargo, Go, GCC/Clang
-- `npm audit` and `terraform plan`
-- repeated CI blockers
-- noisy diffs and log streams
+Methodology and caveats: [BENCHMARK_NOTES.md](BENCHMARK_NOTES.md)
 
 ## Test debugging workflow
 
-This is where `sift` is strongest today.
-
 Think of it like this:
 - `standard` = map
 - `focused` = zoom
 - raw traceback = last resort
 
-Typical loop:
-
 ```bash
 sift exec --preset test-status -- <test command>
 sift rerun
 sift rerun --remaining --detail focused
 ```
 
-If `standard` already gives you the root cause, anchor, and fix, stop there and act.
+If `standard` already gives you the root cause, anchor, and fix — stop and act.
 
-`sift rerun --remaining` narrows automatically for cached `pytest` runs.
+`sift rerun --remaining` narrows automatically for cached `pytest` runs. For `vitest` and `jest`, it reruns the full command and keeps diagnosis focused on what still fails.
 
-For cached `vitest` and `jest` runs, it reruns the original full command and keeps the diagnosis focused on what still fails relative to the cached baseline.
+## Setup
 
-For other runners, rerun a narrowed command manually with `sift exec --preset test-status -- <narrowed command>`.
+Guided setup writes a config, verifies the provider, and makes daily use easier:
 
 ```bash
-sift agent status
-sift agent show claude
-sift agent remove claude
-```
-
-## Where it helps less
-
-`sift` adds less value when:
-- the output is already short and obvious
-- the command is interactive or TUI-based
-- the exact raw log matters
-- the output does not expose enough evidence for reliable grouping
-
-When it cannot be confident, it tells you to zoom or read raw instead of pretending certainty.
-
-## Benchmark
-
-On a real 640-test Python backend (125 repeated setup errors, 3 contract failures, 510 passing tests):
-
-| Metric | Raw agent | sift-first | Reduction |
-|--------|-----------|------------|-----------|
-| Tokens | 305K | 600 | 99.8% |
-| Tool calls | 16 | 7 | 56% |
-| Diagnosis | Same | Same | — |
-
-The table above is the single-fixture reduction story: the largest real test log in the benchmark shrank from `198026` raw tokens to `129` `standard` tokens.
-
-The end-to-end workflow benchmark is a different metric:
-- `62%` fewer total debugging tokens
-- `71%` fewer tool calls
-- `65%` faster wall-clock time
-
-Both matter. The table shows how aggressively `sift` can compress one large noisy run. The workflow numbers show how that compounds across a full debug loop.
-
-Methodology and caveats live in [BENCHMARK_NOTES.md](BENCHMARK_NOTES.md).
-
-## Configuration
-
-Inspect and validate config with:
-
-```bash
-sift config show
-sift config show --show-secrets
-sift config validate
+sift config setup
+sift doctor
 ```
 
-To switch between saved providers without editing files:
+To wire `sift` into your coding agent automatically:
 
 ```bash
-sift config use openai
-sift config use openrouter
+sift agent install claude
+sift agent install codex
 ```
 
-Minimal YAML config:
-
-```yaml
-provider:
-  provider: openai
-  model: gpt-5-nano
-  baseUrl: https://api.openai.com/v1
-  apiKey: YOUR_API_KEY
-
-input:
-  stripAnsi: true
-  redact: false
-  maxCaptureChars: 400000
-  maxInputChars: 60000
-
-runtime:
-  rawFallback: true
-```
+Config details: [docs/cli-reference.md](docs/cli-reference.md)
 
 ## Docs
 

package/dist/cli.js

@@ -7594,7 +7594,7 @@ function buildGenericRawSlice(args) {
 
 // src/core/run.ts
 var RETRY_DELAY_MS = 300;
-var PROVIDER_PENDING_NOTICE_DELAY_MS = 150;
+var PENDING_NOTICE_DELAY_MS = 150;
 function estimateTokenCount(text) {
   return Math.max(1, Math.ceil(text.length / 4));
 }
@@ -7675,17 +7675,16 @@ function buildDryRunOutput(args) {
 async function delay(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
-function startProviderPendingNotice() {
-  if (!process.stderr.isTTY) {
+function startPendingNotice(message, enabled) {
+  if (!enabled) {
     return () => {
     };
   }
-  const message = "sift waiting for provider...";
   let shown = false;
   const timer = setTimeout(() => {
     shown = true;
     process.stderr.write(`${message}\r`);
-  }, PROVIDER_PENDING_NOTICE_DELAY_MS);
+  }, PENDING_NOTICE_DELAY_MS);
   return () => {
     clearTimeout(timer);
     if (!shown) {
@@ -7715,7 +7714,10 @@ async function generateWithRetry(args) {
     responseMode: args.responseMode,
     jsonResponseFormat: args.request.config.provider.jsonResponseFormat
   });
-  const stopPendingNotice = startProviderPendingNotice();
+  const stopPendingNotice = startPendingNotice(
+    "sift waiting for provider...",
+    Boolean(process.stderr.isTTY)
+  );
   try {
     try {
       return await generate();
@@ -9281,6 +9283,10 @@ async function runExec(request) {
     cwd: commandCwd,
     stdio: ["inherit", "pipe", "pipe"]
   });
+  const stopChildPendingNotice = startPendingNotice(
+    "sift waiting for child command...",
+    Boolean(process.stderr.isTTY) && !request.quiet
+  );
   const handleChunk = (chunk) => {
     const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
     if (bypassed) {
@@ -9301,21 +9307,25 @@ async function runExec(request) {
   };
   child.stdout.on("data", handleChunk);
   child.stderr.on("data", handleChunk);
-  await new Promise((resolve, reject) => {
-    child.on("error", (error) => {
-      reject(error);
-    });
-    child.on("close", (status, signal) => {
-      childStatus = status;
-      childSignal = signal;
-      resolve();
+  try {
+    await new Promise((resolve, reject) => {
+      child.on("error", (error) => {
+        reject(error);
+      });
+      child.on("close", (status, signal) => {
+        childStatus = status;
+        childSignal = signal;
+        resolve();
+      });
     });
-  }).catch((error) => {
+  } catch (error) {
     if (error instanceof Error) {
       throw error;
     }
     throw new Error("Failed to start child process.");
-  });
+  } finally {
+    stopChildPendingNotice();
+  }
   const exitCode = normalizeChildExitCode(childStatus, childSignal);
   const capturedOutput = capture.render();
   const autoWatchDetected = !request.watch && looksLikeWatchStream(capturedOutput);

package/dist/index.d.ts

@@ -162,6 +162,7 @@ interface RunResult {
     stats: RunStats | null;
 }
 
+declare function startPendingNotice(message: string, enabled: boolean): () => void;
 declare function runSift(request: RunRequest): Promise<string>;
 declare function runSiftWithStats(request: RunRequest): Promise<RunResult>;
 
@@ -178,4 +179,4 @@ interface ResolveOptions {
 }
 declare function resolveConfig(options?: ResolveOptions): SiftConfig;
 
-export { BoundedCapture, type DetailLevel, type ExecRequest, type GenerateInput, type GenerateResult, type Goal, type InputConfig, type JsonResponseFormatMode, type LLMProvider, type NativeProviderName, type OutputFormat, type PartialSiftConfig, type PreparedInput, type PresetDefinition, type PromptPolicyName, type ProviderConfig, type ProviderName, type ProviderProfile, type ProviderProfiles, type RawSliceStrategy, type ResolveOptions, type ResponseMode, type RunRequest, type RuntimeConfig, type SiftConfig, type TestStatusRemainingMode, type UsageInfo, buildCommandPreview, getExecSuccessShortcut, looksInteractivePrompt, mergeDefined, normalizeChildExitCode, resolveConfig, runExec, runSift, runSiftWithStats };
+export { BoundedCapture, type DetailLevel, type ExecRequest, type GenerateInput, type GenerateResult, type Goal, type InputConfig, type JsonResponseFormatMode, type LLMProvider, type NativeProviderName, type OutputFormat, type PartialSiftConfig, type PreparedInput, type PresetDefinition, type PromptPolicyName, type ProviderConfig, type ProviderName, type ProviderProfile, type ProviderProfiles, type RawSliceStrategy, type ResolveOptions, type ResponseMode, type RunRequest, type RuntimeConfig, type SiftConfig, type TestStatusRemainingMode, type UsageInfo, buildCommandPreview, getExecSuccessShortcut, looksInteractivePrompt, mergeDefined, normalizeChildExitCode, resolveConfig, runExec, runSift, runSiftWithStats, startPendingNotice };

package/dist/index.js

@@ -5774,7 +5774,7 @@ function buildGenericRawSlice(args) {
 
 // src/core/run.ts
 var RETRY_DELAY_MS = 300;
-var PROVIDER_PENDING_NOTICE_DELAY_MS = 150;
+var PENDING_NOTICE_DELAY_MS = 150;
 function estimateTokenCount(text) {
   return Math.max(1, Math.ceil(text.length / 4));
 }
@@ -5855,17 +5855,16 @@ function buildDryRunOutput(args) {
 async function delay(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
-function startProviderPendingNotice() {
-  if (!process.stderr.isTTY) {
+function startPendingNotice(message, enabled) {
+  if (!enabled) {
     return () => {
     };
   }
-  const message = "sift waiting for provider...";
   let shown = false;
   const timer = setTimeout(() => {
     shown = true;
     process.stderr.write(`${message}\r`);
-  }, PROVIDER_PENDING_NOTICE_DELAY_MS);
+  }, PENDING_NOTICE_DELAY_MS);
   return () => {
     clearTimeout(timer);
     if (!shown) {
@@ -5895,7 +5894,10 @@ async function generateWithRetry(args) {
     responseMode: args.responseMode,
     jsonResponseFormat: args.request.config.provider.jsonResponseFormat
   });
-  const stopPendingNotice = startProviderPendingNotice();
+  const stopPendingNotice = startPendingNotice(
+    "sift waiting for provider...",
+    Boolean(process.stderr.isTTY)
+  );
   try {
     try {
       return await generate();
@@ -7293,6 +7295,10 @@ async function runExec(request) {
     cwd: commandCwd,
     stdio: ["inherit", "pipe", "pipe"]
   });
+  const stopChildPendingNotice = startPendingNotice(
+    "sift waiting for child command...",
+    Boolean(process.stderr.isTTY) && !request.quiet
+  );
   const handleChunk = (chunk) => {
     const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
     if (bypassed) {
@@ -7313,21 +7319,25 @@ async function runExec(request) {
   };
   child.stdout.on("data", handleChunk);
   child.stderr.on("data", handleChunk);
-  await new Promise((resolve, reject) => {
-    child.on("error", (error) => {
-      reject(error);
-    });
-    child.on("close", (status, signal) => {
-      childStatus = status;
-      childSignal = signal;
-      resolve();
+  try {
+    await new Promise((resolve, reject) => {
+      child.on("error", (error) => {
+        reject(error);
+      });
+      child.on("close", (status, signal) => {
+        childStatus = status;
+        childSignal = signal;
+        resolve();
+      });
     });
-  }).catch((error) => {
+  } catch (error) {
     if (error instanceof Error) {
       throw error;
     }
     throw new Error("Failed to start child process.");
-  });
+  } finally {
+    stopChildPendingNotice();
+  }
   const exitCode = normalizeChildExitCode(childStatus, childSignal);
   const capturedOutput = capture.render();
   const autoWatchDetected = !request.watch && looksLikeWatchStream(capturedOutput);
@@ -7853,5 +7863,6 @@ export {
   resolveConfig,
   runExec,
   runSift,
-  runSiftWithStats
+  runSiftWithStats,
+  startPendingNotice
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilalimamoglu/sift",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Agent-first command-output reduction layer for agents, CI, and automation.",
   "type": "module",
   "bin": {