@bilalimamoglu/sift 0.1.0 → 0.2.0

package/README.md

@@ -48,8 +48,8 @@ Set credentials once in your shell:
 
 ```bash
 export SIFT_BASE_URL=https://api.openai.com/v1
-export SIFT_API_KEY=your_api_key
 export SIFT_MODEL=gpt-4.1-mini
+export OPENAI_API_KEY=your_openai_api_key
 ```
 
 Or write them to a config file:
@@ -58,7 +58,20 @@ Or write them to a config file:
 sift config init
 ```
 
-`sift` is remote-first today. The safe path is to set `SIFT_API_KEY`, `SIFT_BASE_URL`, and `SIFT_MODEL` once, then run `sift` normally.
+For the default OpenAI-compatible setup, `OPENAI_API_KEY` works directly. If you point `SIFT_BASE_URL` at a different compatible endpoint, use that provider's native key when `sift` recognizes the endpoint, or set the generic fallback env:
+
+```bash
+export SIFT_PROVIDER_API_KEY=your_provider_api_key
+```
+
+`SIFT_PROVIDER_API_KEY` is the generic wrapper env for custom or self-hosted compatible endpoints. Today's `openai-compatible` mode stays generic and does not imply OpenAI ownership.
+
+Known native env fallbacks for recognized compatible endpoints:
+
+- `OPENAI_API_KEY` for `https://api.openai.com/v1`
+- `OPENROUTER_API_KEY` for `https://openrouter.ai/api/v1`
+- `TOGETHER_API_KEY` for `https://api.together.xyz/v1`
+- `GROQ_API_KEY` for `https://api.groq.com/openai/v1`
 
 ## Quick start
 
@@ -77,6 +90,7 @@ sift exec --preset infra-risk -- terraform plan
 sift exec "did tests pass?" -- pytest
 sift exec "what changed?" -- git diff
 sift exec --preset infra-risk -- terraform plan
+sift exec --dry-run "what changed?" -- git diff
 ```
 
 What happens:
@@ -88,6 +102,8 @@ What happens:
 5. It prints a short answer or JSON.
 6. It preserves the wrapped command's exit code.
 
+Use `--dry-run` to inspect the reduced input and prompt without calling the provider.
+
 ## Pipe mode
 
 If the output already exists in a pipeline, pipe mode still works:
@@ -125,6 +141,20 @@ sift presets show audit-critical
 
 Some built-in presets also use local heuristics before calling a model. For example, `infra-risk` can mark obvious destructive plans as `fail` without sending the whole decision to the model.
 
+## JSON response format
+
+When `format` resolves to JSON, `sift` can ask the provider for native JSON output.
+
+- `auto`: enable native JSON mode only for known-safe endpoints such as `https://api.openai.com/v1`
+- `on`: always send the native JSON response format request
+- `off`: never send it
+
+Example:
+
+```bash
+sift exec --format json --json-response-format on "summarize this" -- some-command
+```
+
 ## Config
 
 Generate an example config:
@@ -150,7 +180,11 @@ Supported environment variables:
 - `SIFT_PROVIDER`
 - `SIFT_MODEL`
 - `SIFT_BASE_URL`
-- `SIFT_API_KEY`
+- `SIFT_PROVIDER_API_KEY`
+- `OPENAI_API_KEY` for `https://api.openai.com/v1`
+- `OPENROUTER_API_KEY` for `https://openrouter.ai/api/v1`
+- `TOGETHER_API_KEY` for `https://api.together.xyz/v1`
+- `GROQ_API_KEY` for `https://api.groq.com/openai/v1`
 - `SIFT_MAX_CAPTURE_CHARS`
 - `SIFT_TIMEOUT_MS`
 - `SIFT_MAX_INPUT_CHARS`
@@ -198,6 +232,34 @@ sift presets list
 sift presets show <name>
 ```
 
+## Releasing
+
+`sift` uses a manual GitHub Actions release workflow with npm trusted publishing.
+
+Before the first release:
+
+1. configure npm trusted publishing for `@bilalimamoglu/sift`
+2. point it at `bilalimamoglu/sift`
+3. use the workflow filename `release.yml`
+4. set the GitHub Actions environment name to `release`
+
+For each release:
+
+1. update `package.json` to the target version
+2. merge the final release commit to `main`
+3. open GitHub Actions and run the `release` workflow manually
+
+The workflow will:
+
+1. install dependencies
+2. typecheck, test, and build
+3. pack and smoke-test the tarball
+4. publish to npm
+5. create and push the `vX.Y.Z` tag
+6. create a GitHub Release
+
+`release.yml` uses OIDC trusted publishing, so it does not require an `NPM_TOKEN`.
+
 ## Using it with Codex
 
 `sift` does not install itself into Codex. The normal setup is:
@@ -226,6 +288,7 @@ That gives the agent a simple habit:
 - Redaction is optional and regex-based.
 - Redaction is off by default. If command output may contain secrets, enable `--redact` or set it in config before sending output to a provider.
 - Built-in JSON and verdict flows return strict error objects on provider/model failure.
+- Retriable provider failures such as `429`, timeouts, and `5xx` responses are retried once before falling back.
 - `sift exec` detects simple prompt-like output such as `[y/N]` or `password:` and skips reduction instead of guessing.
 - Pipe mode does not preserve upstream shell pipeline failures; use `set -o pipefail` if you need that behavior.
 - `sift exec` mirrors the wrapped command's exit code.

package/dist/cli.js

@@ -55,6 +55,7 @@ var defaultConfig = {
     model: "gpt-4.1-mini",
     baseUrl: "https://api.openai.com/v1",
     apiKey: "",
+    jsonResponseFormat: "auto",
     timeoutMs: 2e4,
     temperature: 0.1,
     maxOutputTokens: 220
@@ -108,6 +109,70 @@ var defaultConfig = {
   }
 };
 
+// src/config/provider-api-key.ts
+var OPENAI_COMPATIBLE_BASE_URL_ENV = [
+  { prefix: "https://api.openai.com/", envName: "OPENAI_API_KEY" },
+  { prefix: "https://openrouter.ai/api/", envName: "OPENROUTER_API_KEY" },
+  { prefix: "https://api.together.xyz/", envName: "TOGETHER_API_KEY" },
+  { prefix: "https://api.groq.com/openai/", envName: "GROQ_API_KEY" }
+];
+var PROVIDER_API_KEY_ENV = {
+  anthropic: "ANTHROPIC_API_KEY",
+  claude: "ANTHROPIC_API_KEY",
+  groq: "GROQ_API_KEY",
+  openai: "OPENAI_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  together: "TOGETHER_API_KEY"
+};
+function normalizeBaseUrl(baseUrl) {
+  if (!baseUrl) {
+    return void 0;
+  }
+  return `${baseUrl.replace(/\/+$/, "")}/`.toLowerCase();
+}
+function resolveCompatibleEnvName(baseUrl) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  if (!normalized) {
+    return void 0;
+  }
+  const match = OPENAI_COMPATIBLE_BASE_URL_ENV.find(
+    (entry) => normalized.startsWith(entry.prefix)
+  );
+  return match?.envName;
+}
+function resolveProviderApiKey(provider, baseUrl, env) {
+  if (env.SIFT_PROVIDER_API_KEY) {
+    return env.SIFT_PROVIDER_API_KEY;
+  }
+  if (provider === "openai-compatible") {
+    const envName2 = resolveCompatibleEnvName(baseUrl);
+    return envName2 ? env[envName2] : void 0;
+  }
+  if (!provider) {
+    return void 0;
+  }
+  const envName = PROVIDER_API_KEY_ENV[provider];
+  return envName ? env[envName] : void 0;
+}
+function getProviderApiKeyEnvNames(provider, baseUrl) {
+  const envNames = ["SIFT_PROVIDER_API_KEY"];
+  if (provider === "openai-compatible") {
+    const envName2 = resolveCompatibleEnvName(baseUrl);
+    if (envName2) {
+      envNames.push(envName2);
+    }
+    return envNames;
+  }
+  if (!provider) {
+    return envNames;
+  }
+  const envName = PROVIDER_API_KEY_ENV[provider];
+  if (envName) {
+    envNames.push(envName);
+  }
+  return envNames;
+}
+
 // src/config/schema.ts
 import { z } from "zod";
 var providerNameSchema = z.enum(["openai-compatible"]);
@@ -118,6 +183,7 @@ var outputFormatSchema = z.enum([
   "verdict"
 ]);
 var responseModeSchema = z.enum(["text", "json"]);
+var jsonResponseFormatModeSchema = z.enum(["auto", "on", "off"]);
 var promptPolicyNameSchema = z.enum([
   "test-status",
   "audit-critical",
@@ -131,6 +197,7 @@ var providerConfigSchema = z.object({
   model: z.string().min(1),
   baseUrl: z.string().url(),
   apiKey: z.string().optional(),
+  jsonResponseFormat: jsonResponseFormatModeSchema,
   timeoutMs: z.number().int().positive(),
   temperature: z.number().min(0).max(2),
   maxOutputTokens: z.number().int().positive()
@@ -184,14 +251,25 @@ function mergeDefined(base, override) {
   }
   return result;
 }
-function buildEnvOverrides(env) {
+function stripApiKey(overrides) {
+  if (!overrides?.provider || overrides.provider.apiKey === void 0) {
+    return overrides;
+  }
+  return {
+    ...overrides,
+    provider: {
+      ...overrides.provider,
+      apiKey: void 0
+    }
+  };
+}
+function buildNonCredentialEnvOverrides(env) {
   const overrides = {};
-  if (env.SIFT_PROVIDER || env.SIFT_MODEL || env.SIFT_BASE_URL || env.SIFT_API_KEY || env.SIFT_TIMEOUT_MS) {
+  if (env.SIFT_PROVIDER || env.SIFT_MODEL || env.SIFT_BASE_URL || env.SIFT_TIMEOUT_MS) {
     overrides.provider = {
       provider: env.SIFT_PROVIDER,
       model: env.SIFT_MODEL,
       baseUrl: env.SIFT_BASE_URL,
-      apiKey: env.SIFT_API_KEY,
       timeoutMs: env.SIFT_TIMEOUT_MS ? Number(env.SIFT_TIMEOUT_MS) : void 0
     };
   }
@@ -203,12 +281,40 @@ function buildEnvOverrides(env) {
   }
   return overrides;
 }
+function buildCredentialEnvOverrides(env, context) {
+  const apiKey = resolveProviderApiKey(context.provider, context.baseUrl, env);
+  if (apiKey === void 0) {
+    return {};
+  }
+  return {
+    provider: {
+      apiKey
+    }
+  };
+}
 function resolveConfig(options = {}) {
   const env = options.env ?? process.env;
   const fileConfig = loadRawConfig(options.configPath);
-  const envConfig = buildEnvOverrides(env);
+  const nonCredentialEnvConfig = buildNonCredentialEnvOverrides(env);
+  const contextConfig = mergeDefined(
+    mergeDefined(
+      mergeDefined(defaultConfig, fileConfig),
+      nonCredentialEnvConfig
+    ),
+    stripApiKey(options.cliOverrides) ?? {}
+  );
+  const credentialEnvConfig = buildCredentialEnvOverrides(env, {
+    provider: contextConfig.provider.provider,
+    baseUrl: contextConfig.provider.baseUrl
+  });
   const merged = mergeDefined(
-    mergeDefined(mergeDefined(defaultConfig, fileConfig), envConfig),
+    mergeDefined(
+      mergeDefined(
+        mergeDefined(defaultConfig, fileConfig),
+        nonCredentialEnvConfig
+      ),
+      credentialEnvConfig
+    ),
     options.cliOverrides ?? {}
   );
   return siftConfigSchema.parse(merged);
@@ -269,7 +375,7 @@ function configValidate(configPath) {
   });
   const resolvedPath = findConfigPath(configPath);
   process.stdout.write(
-    `Config is valid${resolvedPath ? ` (${resolvedPath})` : " (using defaults)"}.
+    `Resolved config is valid${resolvedPath ? ` (${resolvedPath})` : " (using defaults)"}.
 `
   );
 }
@@ -278,6 +384,7 @@ function configValidate(configPath) {
 function runDoctor(config) {
   const lines = [
     "sift doctor",
+    "mode: local config completeness check",
     `provider: ${config.provider.provider}`,
     `model: ${config.provider.model}`,
     `baseUrl: ${config.provider.baseUrl}`,
@@ -297,6 +404,12 @@ function runDoctor(config) {
   }
   if (config.provider.provider === "openai-compatible" && !config.provider.apiKey) {
     problems.push("Missing provider.apiKey");
+    problems.push(
+      `Set one of: ${getProviderApiKeyEnvNames(
+        config.provider.provider,
+        config.provider.baseUrl
+      ).join(", ")}`
+    );
   }
   if (problems.length > 0) {
     process.stderr.write(`${problems.join("\n")}
@@ -335,6 +448,15 @@ import pc2 from "picocolors";
 import pc from "picocolors";
 
 // src/providers/openaiCompatible.ts
+function supportsNativeJsonResponseFormat(baseUrl, mode) {
+  if (mode === "off") {
+    return false;
+  }
+  if (mode === "on") {
+    return true;
+  }
+  return /^https:\/\/api\.openai\.com(?:\/|$)/i.test(baseUrl);
+}
 function extractMessageText(payload) {
   const content = payload?.choices?.[0]?.message?.content;
   if (typeof content === "string") {
@@ -369,6 +491,7 @@ var OpenAICompatibleProvider = class {
           model: input.model,
           temperature: input.temperature,
           max_tokens: input.maxOutputTokens,
+          ...input.responseMode === "json" && supportsNativeJsonResponseFormat(this.baseUrl, input.jsonResponseFormat) ? { response_format: { type: "json_object" } } : {},
           messages: [
             {
               role: "system",
@@ -879,6 +1002,7 @@ function prepareInput(raw, config) {
 }
 
 // src/core/run.ts
+var RETRY_DELAY_MS = 300;
 function normalizeOutput(text, responseMode) {
   if (responseMode !== "json") {
     return text.trim();
@@ -890,6 +1014,68 @@ function normalizeOutput(text, responseMode) {
     throw new Error("Provider returned invalid JSON");
   }
 }
+function buildDryRunOutput(args) {
+  return JSON.stringify(
+    {
+      status: "dry-run",
+      strategy: args.heuristicOutput ? "heuristic" : "provider",
+      provider: {
+        name: args.providerName,
+        model: args.request.config.provider.model,
+        baseUrl: args.request.config.provider.baseUrl,
+        jsonResponseFormat: args.request.config.provider.jsonResponseFormat
+      },
+      question: args.request.question,
+      format: args.request.format,
+      responseMode: args.responseMode,
+      policy: args.request.policyName ?? null,
+      heuristicOutput: args.heuristicOutput ?? null,
+      input: {
+        originalLength: args.prepared.meta.originalLength,
+        finalLength: args.prepared.meta.finalLength,
+        redactionApplied: args.prepared.meta.redactionApplied,
+        truncatedApplied: args.prepared.meta.truncatedApplied,
+        text: args.prepared.truncated
+      },
+      prompt: args.prompt
+    },
+    null,
+    2
+  );
+}
+async function delay(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function generateWithRetry(args) {
+  let lastError;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await args.provider.generate({
+        model: args.request.config.provider.model,
+        prompt: args.prompt,
+        temperature: args.request.config.provider.temperature,
+        maxOutputTokens: args.request.config.provider.maxOutputTokens,
+        timeoutMs: args.request.config.provider.timeoutMs,
+        responseMode: args.responseMode,
+        jsonResponseFormat: args.request.config.provider.jsonResponseFormat
+      });
+    } catch (error) {
+      lastError = error;
+      const reason = error instanceof Error ? error.message : "unknown_error";
+      if (attempt > 0 || !isRetriableReason(reason)) {
+        throw error;
+      }
+      if (args.request.config.runtime.verbose) {
+        process.stderr.write(
+          `${pc.dim("sift")} retry=1 reason=${reason} delay_ms=${RETRY_DELAY_MS}
+`
+        );
+      }
+      await delay(RETRY_DELAY_MS);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("unknown_error");
+}
 async function runSift(request) {
   const prepared = prepareInput(request.stdin, request.config.input);
   const { prompt, responseMode } = buildPrompt({
@@ -915,15 +1101,33 @@ async function runSift(request) {
       process.stderr.write(`${pc.dim("sift")} heuristic=${request.policyName}
 `);
     }
+    if (request.dryRun) {
+      return buildDryRunOutput({
+        request,
+        providerName: provider.name,
+        prompt,
+        responseMode,
+        prepared,
+        heuristicOutput
+      });
+    }
     return heuristicOutput;
   }
+  if (request.dryRun) {
+    return buildDryRunOutput({
+      request,
+      providerName: provider.name,
+      prompt,
+      responseMode,
+      prepared,
+      heuristicOutput: null
+    });
+  }
   try {
-    const result = await provider.generate({
-      model: request.config.provider.model,
+    const result = await generateWithRetry({
+      provider,
+      request,
       prompt,
-      temperature: request.config.provider.temperature,
-      maxOutputTokens: request.config.provider.maxOutputTokens,
-      timeoutMs: request.config.provider.timeoutMs,
       responseMode
     });
     if (looksLikeRejectedModelOutput({
@@ -1138,12 +1342,13 @@ function toNumber(value) {
 }
 function buildCliOverrides(options) {
   const overrides = {};
-  if (options.provider !== void 0 || options.model !== void 0 || options.baseUrl !== void 0 || options.apiKey !== void 0 || options.timeoutMs !== void 0) {
+  if (options.provider !== void 0 || options.model !== void 0 || options.baseUrl !== void 0 || options.apiKey !== void 0 || options.jsonResponseFormat !== void 0 || options.timeoutMs !== void 0) {
     overrides.provider = {
       provider: options.provider,
       model: options.model,
       baseUrl: options.baseUrl,
       apiKey: options.apiKey,
+      jsonResponseFormat: options.jsonResponseFormat,
       timeoutMs: toNumber(options.timeoutMs)
     };
   }
@@ -1167,7 +1372,13 @@ function buildCliOverrides(options) {
   return overrides;
 }
 function applySharedOptions(command) {
-  return command.option("--provider <provider>", "Provider: openai-compatible").option("--model <model>", "Model name").option("--base-url <url>", "Provider base URL").option("--api-key <key>", "Provider API key").option("--timeout-ms <ms>", "Request timeout in milliseconds").option("--format <format>", "brief | bullets | json | verdict").option("--max-capture-chars <n>", "Maximum raw child output chars kept in memory").option("--max-input-chars <n>", "Maximum input chars sent to the model").option("--head-chars <n>", "Head chars to preserve during truncation").option("--tail-chars <n>", "Tail chars to preserve during truncation").option("--strip-ansi", "Force ANSI stripping").option("--redact", "Enable standard redaction").option("--redact-strict", "Enable strict redaction").option("--raw-fallback", "Enable raw fallback text output").option("--config <path>", "Path to config file").option("--verbose", "Enable verbose stderr logging");
+  return command.option("--provider <provider>", "Provider: openai-compatible").option("--model <model>", "Model name").option("--base-url <url>", "Provider base URL").option(
+    "--api-key <key>",
+    "Provider API key (or set SIFT_PROVIDER_API_KEY; OPENAI_API_KEY also works for api.openai.com)"
+  ).option(
+    "--json-response-format <mode>",
+    "JSON response format mode: auto | on | off"
+  ).option("--timeout-ms <ms>", "Request timeout in milliseconds").option("--format <format>", "brief | bullets | json | verdict").option("--max-capture-chars <n>", "Maximum raw child output chars kept in memory").option("--max-input-chars <n>", "Maximum input chars sent to the model").option("--head-chars <n>", "Head chars to preserve during truncation").option("--tail-chars <n>", "Tail chars to preserve during truncation").option("--strip-ansi", "Force ANSI stripping").option("--redact", "Enable standard redaction").option("--redact-strict", "Enable strict redaction").option("--raw-fallback", "Enable raw fallback text output").option("--dry-run", "Show the reduced input and prompt without calling the provider").option("--config <path>", "Path to config file").option("--verbose", "Enable verbose stderr logging");
 }
 async function executeRun(args) {
   const config = resolveConfig({
@@ -1181,6 +1392,7 @@ async function executeRun(args) {
     format: args.format,
     stdin,
     config,
+    dryRun: Boolean(args.options.dryRun),
     policyName: args.policyName,
     outputContract: args.outputContract,
     fallbackJson: args.fallbackJson
@@ -1213,6 +1425,7 @@ async function executeExec(args) {
     question: args.question,
     format: args.format,
     config,
+    dryRun: Boolean(args.options.dryRun),
     policyName: args.policyName,
     outputContract: args.outputContract,
     fallbackJson: args.fallbackJson,
@@ -1221,7 +1434,7 @@ async function executeExec(args) {
 }
 applySharedOptions(
   cli.command("preset <name>", "Run a named preset against piped CLI output")
-).action(async (name, options) => {
+).usage("preset <name> [options]").example("preset test-status < test-output.txt").action(async (name, options) => {
   const config = resolveConfig({
     configPath: options.config,
     env: process.env,
@@ -1239,7 +1452,7 @@ applySharedOptions(
 });
 applySharedOptions(
   cli.command("exec [question]", "Run a command and reduce its output").allowUnknownOptions()
-).option("--shell <command>", "Execute a shell command string instead of argv mode").option("--preset <name>", "Run a named preset in exec mode").action(async (question, options) => {
+).usage("exec [question] [options] -- <program> [args...]").example('exec "what changed?" -- git diff').example("exec --preset test-status -- pytest").example('exec --preset infra-risk --shell "terraform plan"').option("--shell <command>", "Execute a shell command string instead of argv mode").option("--preset <name>", "Run a named preset in exec mode").action(async (question, options) => {
   if (question === "preset") {
     throw new Error("Use 'sift exec --preset <name> -- <program> ...' instead.");
   }
@@ -1276,7 +1489,10 @@ applySharedOptions(
     options
   });
 });
-cli.command("config <action>", "Config commands: init | show | validate").option("--path <path>", "Target config path for init").option("--config <path>", "Path to config file").option("--show-secrets", "Show secret values in config show").action((action, options) => {
+cli.command(
+  "config <action>",
+  "Config commands: init | show | validate (show/validate use resolved runtime config)"
+).usage("config <init|show|validate> [options]").example("config init").example("config show").example("config validate --config ./sift.config.yaml").option("--path <path>", "Target config path for init").option("--config <path>", "Path to config file").option("--show-secrets", "Show secret values in config show").action((action, options) => {
   if (action === "init") {
     configInit(options.path);
     return;
@@ -1294,14 +1510,14 @@ cli.command("config <action>", "Config commands: init | show | validate").option
   }
   throw new Error(`Unknown config action: ${action}`);
 });
-cli.command("doctor", "Validate runtime configuration").option("--config <path>", "Path to config file").action((options) => {
+cli.command("doctor", "Check local runtime config completeness").usage("doctor [options]").option("--config <path>", "Path to config file").action((options) => {
   const config = resolveConfig({
     configPath: options.config,
     env: process.env
   });
   process.exitCode = runDoctor(config);
 });
-cli.command("presets <action> [name]", "Preset commands: list | show").option("--config <path>", "Path to config file").option("--internal", "Show internal preset fields in presets show").action((action, name, options) => {
+cli.command("presets <action> [name]", "Preset commands: list | show").usage("presets <list|show> [name] [options]").example("presets list").example("presets show infra-risk").option("--config <path>", "Path to config file").option("--internal", "Show internal preset fields in presets show").action((action, name, options) => {
   const config = resolveConfig({
     configPath: options.config,
     env: process.env

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 type ProviderName = "openai-compatible";
 type OutputFormat = "brief" | "bullets" | "json" | "verdict";
 type ResponseMode = "text" | "json";
+type JsonResponseFormatMode = "auto" | "on" | "off";
 type PromptPolicyName = "test-status" | "audit-critical" | "diff-summary" | "build-failure" | "log-errors" | "infra-risk";
 interface ProviderConfig {
     provider: ProviderName;
     model: string;
     baseUrl: string;
     apiKey?: string;
+    jsonResponseFormat: JsonResponseFormatMode;
     timeoutMs: number;
     temperature: number;
     maxOutputTokens: number;
@@ -50,6 +52,7 @@ interface GenerateInput {
     maxOutputTokens: number;
     timeoutMs: number;
     responseMode: ResponseMode;
+    jsonResponseFormat: JsonResponseFormatMode;
 }
 interface UsageInfo {
     inputTokens?: number;
@@ -66,6 +69,7 @@ interface RunRequest {
     format: OutputFormat;
     stdin: string;
     config: SiftConfig;
+    dryRun?: boolean;
     policyName?: PromptPolicyName;
     outputContract?: string;
     fallbackJson?: unknown;
@@ -103,4 +107,4 @@ interface ResolveOptions {
 }
 declare function resolveConfig(options?: ResolveOptions): SiftConfig;
 
-export { type ExecRequest, type GenerateInput, type GenerateResult, type InputConfig, type LLMProvider, type OutputFormat, type PartialSiftConfig, type PreparedInput, type PresetDefinition, type PromptPolicyName, type ProviderConfig, type ProviderName, type ResolveOptions, type ResponseMode, type RunRequest, type RuntimeConfig, type SiftConfig, type UsageInfo, resolveConfig, runExec, runSift };
+export { type ExecRequest, type GenerateInput, type GenerateResult, type InputConfig, type JsonResponseFormatMode, type LLMProvider, type OutputFormat, type PartialSiftConfig, type PreparedInput, type PresetDefinition, type PromptPolicyName, type ProviderConfig, type ProviderName, type ResolveOptions, type ResponseMode, type RunRequest, type RuntimeConfig, type SiftConfig, type UsageInfo, resolveConfig, runExec, runSift };

package/dist/index.js

@@ -20,6 +20,15 @@ var CAPTURE_OMITTED_MARKER = "\n...[captured output omitted]...\n";
 import pc from "picocolors";
 
 // src/providers/openaiCompatible.ts
+function supportsNativeJsonResponseFormat(baseUrl, mode) {
+  if (mode === "off") {
+    return false;
+  }
+  if (mode === "on") {
+    return true;
+  }
+  return /^https:\/\/api\.openai\.com(?:\/|$)/i.test(baseUrl);
+}
 function extractMessageText(payload) {
   const content = payload?.choices?.[0]?.message?.content;
   if (typeof content === "string") {
@@ -54,6 +63,7 @@ var OpenAICompatibleProvider = class {
           model: input.model,
           temperature: input.temperature,
           max_tokens: input.maxOutputTokens,
+          ...input.responseMode === "json" && supportsNativeJsonResponseFormat(this.baseUrl, input.jsonResponseFormat) ? { response_format: { type: "json_object" } } : {},
           messages: [
             {
               role: "system",
@@ -564,6 +574,7 @@ function prepareInput(raw, config) {
 }
 
 // src/core/run.ts
+var RETRY_DELAY_MS = 300;
 function normalizeOutput(text, responseMode) {
   if (responseMode !== "json") {
     return text.trim();
@@ -575,6 +586,68 @@ function normalizeOutput(text, responseMode) {
     throw new Error("Provider returned invalid JSON");
   }
 }
+function buildDryRunOutput(args) {
+  return JSON.stringify(
+    {
+      status: "dry-run",
+      strategy: args.heuristicOutput ? "heuristic" : "provider",
+      provider: {
+        name: args.providerName,
+        model: args.request.config.provider.model,
+        baseUrl: args.request.config.provider.baseUrl,
+        jsonResponseFormat: args.request.config.provider.jsonResponseFormat
+      },
+      question: args.request.question,
+      format: args.request.format,
+      responseMode: args.responseMode,
+      policy: args.request.policyName ?? null,
+      heuristicOutput: args.heuristicOutput ?? null,
+      input: {
+        originalLength: args.prepared.meta.originalLength,
+        finalLength: args.prepared.meta.finalLength,
+        redactionApplied: args.prepared.meta.redactionApplied,
+        truncatedApplied: args.prepared.meta.truncatedApplied,
+        text: args.prepared.truncated
+      },
+      prompt: args.prompt
+    },
+    null,
+    2
+  );
+}
+async function delay(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function generateWithRetry(args) {
+  let lastError;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await args.provider.generate({
+        model: args.request.config.provider.model,
+        prompt: args.prompt,
+        temperature: args.request.config.provider.temperature,
+        maxOutputTokens: args.request.config.provider.maxOutputTokens,
+        timeoutMs: args.request.config.provider.timeoutMs,
+        responseMode: args.responseMode,
+        jsonResponseFormat: args.request.config.provider.jsonResponseFormat
+      });
+    } catch (error) {
+      lastError = error;
+      const reason = error instanceof Error ? error.message : "unknown_error";
+      if (attempt > 0 || !isRetriableReason(reason)) {
+        throw error;
+      }
+      if (args.request.config.runtime.verbose) {
+        process.stderr.write(
+          `${pc.dim("sift")} retry=1 reason=${reason} delay_ms=${RETRY_DELAY_MS}
+`
+        );
+      }
+      await delay(RETRY_DELAY_MS);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("unknown_error");
+}
 async function runSift(request) {
   const prepared = prepareInput(request.stdin, request.config.input);
   const { prompt, responseMode } = buildPrompt({
@@ -600,15 +673,33 @@ async function runSift(request) {
       process.stderr.write(`${pc.dim("sift")} heuristic=${request.policyName}
 `);
     }
+    if (request.dryRun) {
+      return buildDryRunOutput({
+        request,
+        providerName: provider.name,
+        prompt,
+        responseMode,
+        prepared,
+        heuristicOutput
+      });
+    }
     return heuristicOutput;
   }
+  if (request.dryRun) {
+    return buildDryRunOutput({
+      request,
+      providerName: provider.name,
+      prompt,
+      responseMode,
+      prepared,
+      heuristicOutput: null
+    });
+  }
   try {
-    const result = await provider.generate({
-      model: request.config.provider.model,
+    const result = await generateWithRetry({
+      provider,
+      request,
       prompt,
-      temperature: request.config.provider.temperature,
-      maxOutputTokens: request.config.provider.maxOutputTokens,
-      timeoutMs: request.config.provider.timeoutMs,
       responseMode
     });
     if (looksLikeRejectedModelOutput({
@@ -797,6 +888,7 @@ var defaultConfig = {
     model: "gpt-4.1-mini",
     baseUrl: "https://api.openai.com/v1",
     apiKey: "",
+    jsonResponseFormat: "auto",
     timeoutMs: 2e4,
     temperature: 0.1,
     maxOutputTokens: 220
@@ -878,6 +970,52 @@ function loadRawConfig(explicitPath) {
   return YAML.parse(content) ?? {};
 }
 
+// src/config/provider-api-key.ts
+var OPENAI_COMPATIBLE_BASE_URL_ENV = [
+  { prefix: "https://api.openai.com/", envName: "OPENAI_API_KEY" },
+  { prefix: "https://openrouter.ai/api/", envName: "OPENROUTER_API_KEY" },
+  { prefix: "https://api.together.xyz/", envName: "TOGETHER_API_KEY" },
+  { prefix: "https://api.groq.com/openai/", envName: "GROQ_API_KEY" }
+];
+var PROVIDER_API_KEY_ENV = {
+  anthropic: "ANTHROPIC_API_KEY",
+  claude: "ANTHROPIC_API_KEY",
+  groq: "GROQ_API_KEY",
+  openai: "OPENAI_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  together: "TOGETHER_API_KEY"
+};
+function normalizeBaseUrl(baseUrl) {
+  if (!baseUrl) {
+    return void 0;
+  }
+  return `${baseUrl.replace(/\/+$/, "")}/`.toLowerCase();
+}
+function resolveCompatibleEnvName(baseUrl) {
+  const normalized = normalizeBaseUrl(baseUrl);
+  if (!normalized) {
+    return void 0;
+  }
+  const match = OPENAI_COMPATIBLE_BASE_URL_ENV.find(
+    (entry) => normalized.startsWith(entry.prefix)
+  );
+  return match?.envName;
+}
+function resolveProviderApiKey(provider, baseUrl, env) {
+  if (env.SIFT_PROVIDER_API_KEY) {
+    return env.SIFT_PROVIDER_API_KEY;
+  }
+  if (provider === "openai-compatible") {
+    const envName2 = resolveCompatibleEnvName(baseUrl);
+    return envName2 ? env[envName2] : void 0;
+  }
+  if (!provider) {
+    return void 0;
+  }
+  const envName = PROVIDER_API_KEY_ENV[provider];
+  return envName ? env[envName] : void 0;
+}
+
 // src/config/schema.ts
 import { z } from "zod";
 var providerNameSchema = z.enum(["openai-compatible"]);
@@ -888,6 +1026,7 @@ var outputFormatSchema = z.enum([
   "verdict"
 ]);
 var responseModeSchema = z.enum(["text", "json"]);
+var jsonResponseFormatModeSchema = z.enum(["auto", "on", "off"]);
 var promptPolicyNameSchema = z.enum([
   "test-status",
   "audit-critical",
@@ -901,6 +1040,7 @@ var providerConfigSchema = z.object({
   model: z.string().min(1),
   baseUrl: z.string().url(),
   apiKey: z.string().optional(),
+  jsonResponseFormat: jsonResponseFormatModeSchema,
   timeoutMs: z.number().int().positive(),
   temperature: z.number().min(0).max(2),
   maxOutputTokens: z.number().int().positive()
@@ -954,14 +1094,25 @@ function mergeDefined(base, override) {
   }
   return result;
 }
-function buildEnvOverrides(env) {
+function stripApiKey(overrides) {
+  if (!overrides?.provider || overrides.provider.apiKey === void 0) {
+    return overrides;
+  }
+  return {
+    ...overrides,
+    provider: {
+      ...overrides.provider,
+      apiKey: void 0
+    }
+  };
+}
+function buildNonCredentialEnvOverrides(env) {
   const overrides = {};
-  if (env.SIFT_PROVIDER || env.SIFT_MODEL || env.SIFT_BASE_URL || env.SIFT_API_KEY || env.SIFT_TIMEOUT_MS) {
+  if (env.SIFT_PROVIDER || env.SIFT_MODEL || env.SIFT_BASE_URL || env.SIFT_TIMEOUT_MS) {
     overrides.provider = {
       provider: env.SIFT_PROVIDER,
       model: env.SIFT_MODEL,
       baseUrl: env.SIFT_BASE_URL,
-      apiKey: env.SIFT_API_KEY,
       timeoutMs: env.SIFT_TIMEOUT_MS ? Number(env.SIFT_TIMEOUT_MS) : void 0
     };
   }
@@ -973,12 +1124,40 @@ function buildEnvOverrides(env) {
   }
   return overrides;
 }
+function buildCredentialEnvOverrides(env, context) {
+  const apiKey = resolveProviderApiKey(context.provider, context.baseUrl, env);
+  if (apiKey === void 0) {
+    return {};
+  }
+  return {
+    provider: {
+      apiKey
+    }
+  };
+}
 function resolveConfig(options = {}) {
   const env = options.env ?? process.env;
   const fileConfig = loadRawConfig(options.configPath);
-  const envConfig = buildEnvOverrides(env);
+  const nonCredentialEnvConfig = buildNonCredentialEnvOverrides(env);
+  const contextConfig = mergeDefined(
+    mergeDefined(
+      mergeDefined(defaultConfig, fileConfig),
+      nonCredentialEnvConfig
+    ),
+    stripApiKey(options.cliOverrides) ?? {}
+  );
+  const credentialEnvConfig = buildCredentialEnvOverrides(env, {
+    provider: contextConfig.provider.provider,
+    baseUrl: contextConfig.provider.baseUrl
+  });
   const merged = mergeDefined(
-    mergeDefined(mergeDefined(defaultConfig, fileConfig), envConfig),
+    mergeDefined(
+      mergeDefined(
+        mergeDefined(defaultConfig, fileConfig),
+        nonCredentialEnvConfig
+      ),
+      credentialEnvConfig
+    ),
     options.cliOverrides ?? {}
   );
   return siftConfigSchema.parse(merged);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bilalimamoglu/sift",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent-first command-output reduction layer for agents, CI, and automation.",
   "type": "module",
   "bin": {
@@ -37,6 +37,14 @@
   ],
   "author": "Bilal Imamoglu",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bilalimamoglu/sift.git"
+  },
+  "homepage": "https://github.com/bilalimamoglu/sift#readme",
+  "bugs": {
+    "url": "https://github.com/bilalimamoglu/sift/issues"
+  },
   "dependencies": {
     "cac": "^6.7.14",
     "picocolors": "^1.1.1",