@bilalimamoglu/sift 0.1.0 → 0.2.1

package/dist/cli.js

@@ -51,22 +51,23 @@ function loadRawConfig(explicitPath) {
 // src/config/defaults.ts
 var defaultConfig = {
   provider: {
-    provider: "openai-compatible",
-    model: "gpt-4.1-mini",
+    provider: "openai",
+    model: "gpt-5-nano",
     baseUrl: "https://api.openai.com/v1",
     apiKey: "",
+    jsonResponseFormat: "auto",
     timeoutMs: 2e4,
     temperature: 0.1,
-    maxOutputTokens: 220
+    maxOutputTokens: 400
   },
   input: {
     stripAnsi: true,
     redact: false,
     redactStrict: false,
-    maxCaptureChars: 25e4,
-    maxInputChars: 2e4,
-    headChars: 6e3,
-    tailChars: 6e3
+    maxCaptureChars: 4e5,
+    maxInputChars: 6e4,
+    headChars: 2e4,
+    tailChars: 2e4
   },
   runtime: {
     rawFallback: true,
@@ -100,6 +101,16 @@ var defaultConfig = {
       format: "bullets",
       policy: "log-errors"
     },
+    "typecheck-summary": {
+      question: "Summarize the blocking typecheck failures. Group repeated errors by root cause and point to the first files or symbols to fix.",
+      format: "bullets",
+      policy: "typecheck-summary"
+    },
+    "lint-failures": {
+      question: "Summarize the blocking lint failures. Group repeated rules, highlight the top offending files, and call out only failures that matter for fixing the run.",
+      format: "bullets",
+      policy: "lint-failures"
+    },
     "infra-risk": {
       question: "Assess whether the infrastructure changes are risky and whether they look safe to apply.",
       format: "verdict",
@@ -108,9 +119,76 @@ 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 (provider === "openai-compatible") {
+    if (env.SIFT_PROVIDER_API_KEY) {
+      return env.SIFT_PROVIDER_API_KEY;
+    }
+    const envName2 = resolveCompatibleEnvName(baseUrl);
+    return envName2 ? env[envName2] : void 0;
+  }
+  if (!provider) {
+    return env.SIFT_PROVIDER_API_KEY;
+  }
+  const envName = PROVIDER_API_KEY_ENV[provider];
+  if (envName && env[envName]) {
+    return env[envName];
+  }
+  return env.SIFT_PROVIDER_API_KEY;
+}
+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) {
+    return [envName, ...envNames];
+  }
+  return envNames;
+}
+
 // src/config/schema.ts
 import { z } from "zod";
-var providerNameSchema = z.enum(["openai-compatible"]);
+var providerNameSchema = z.enum(["openai", "openai-compatible"]);
 var outputFormatSchema = z.enum([
   "brief",
   "bullets",
@@ -118,19 +196,23 @@ 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",
   "diff-summary",
   "build-failure",
   "log-errors",
-  "infra-risk"
+  "infra-risk",
+  "typecheck-summary",
+  "lint-failures"
 ]);
 var providerConfigSchema = z.object({
   provider: providerNameSchema,
   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 +266,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 +296,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 +390,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 +399,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}`,
@@ -295,8 +417,14 @@ function runDoctor(config) {
   if (!config.provider.model) {
     problems.push("Missing provider.model");
   }
-  if (config.provider.provider === "openai-compatible" && !config.provider.apiKey) {
+  if ((config.provider.provider === "openai" || 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")}
@@ -331,10 +459,160 @@ import { spawn } from "child_process";
 import { constants as osConstants } from "os";
 import pc2 from "picocolors";
 
+// src/core/gate.ts
+var FAIL_ON_SUPPORTED_PRESETS = /* @__PURE__ */ new Set(["infra-risk", "audit-critical"]);
+function parseJson(output) {
+  try {
+    return JSON.parse(output);
+  } catch {
+    return null;
+  }
+}
+function supportsFailOnPreset(presetName) {
+  return typeof presetName === "string" && FAIL_ON_SUPPORTED_PRESETS.has(presetName);
+}
+function assertSupportedFailOnPreset(presetName) {
+  if (!supportsFailOnPreset(presetName)) {
+    throw new Error(
+      "--fail-on is supported only for built-in presets: infra-risk, audit-critical."
+    );
+  }
+}
+function assertSupportedFailOnFormat(args) {
+  const expectedFormat = args.presetName === "infra-risk" ? "verdict" : "json";
+  if (args.format !== expectedFormat) {
+    throw new Error(
+      `--fail-on requires the default ${expectedFormat} format for preset ${args.presetName}.`
+    );
+  }
+}
+function evaluateGate(args) {
+  const parsed = parseJson(args.output);
+  if (!parsed || typeof parsed !== "object") {
+    return { shouldFail: false };
+  }
+  if (args.presetName === "infra-risk") {
+    return {
+      shouldFail: parsed["verdict"] === "fail"
+    };
+  }
+  if (args.presetName === "audit-critical") {
+    const status = parsed["status"];
+    const vulnerabilities = parsed["vulnerabilities"];
+    return {
+      shouldFail: status === "ok" && Array.isArray(vulnerabilities) && vulnerabilities.length > 0
+    };
+  }
+  return { shouldFail: false };
+}
+
 // src/core/run.ts
 import pc from "picocolors";
 
+// src/providers/systemInstruction.ts
+var REDUCTION_SYSTEM_INSTRUCTION = "You reduce noisy command output into compact answers for agents and automation.";
+
+// src/providers/openai.ts
+function usesNativeJsonResponseFormat(mode) {
+  return mode !== "off";
+}
+function extractResponseText(payload) {
+  if (typeof payload?.output_text === "string") {
+    return payload.output_text.trim();
+  }
+  if (!Array.isArray(payload?.output)) {
+    return "";
+  }
+  return payload.output.flatMap((item) => Array.isArray(item?.content) ? item.content : []).map((item) => item?.type === "output_text" ? item.text : "").filter((text) => typeof text === "string" && text.trim().length > 0).join("").trim();
+}
+async function buildOpenAIError(response) {
+  let detail = `Provider returned HTTP ${response.status}`;
+  try {
+    const data = await response.json();
+    const message = data?.error?.message;
+    if (typeof message === "string" && message.trim().length > 0) {
+      detail = `${detail}: ${message.trim()}`;
+    }
+  } catch {
+  }
+  return new Error(detail);
+}
+var OpenAIProvider = class {
+  name = "openai";
+  baseUrl;
+  apiKey;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.apiKey = options.apiKey;
+  }
+  async generate(input) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), input.timeoutMs);
+    try {
+      const url = new URL("responses", `${this.baseUrl}/`);
+      const response = await fetch(url, {
+        method: "POST",
+        signal: controller.signal,
+        headers: {
+          "content-type": "application/json",
+          ...this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}
+        },
+        body: JSON.stringify({
+          model: input.model,
+          instructions: REDUCTION_SYSTEM_INSTRUCTION,
+          input: input.prompt,
+          reasoning: {
+            effort: "minimal"
+          },
+          text: {
+            verbosity: "low",
+            ...input.responseMode === "json" && usesNativeJsonResponseFormat(input.jsonResponseFormat) ? {
+              format: {
+                type: "json_object"
+              }
+            } : {}
+          },
+          max_output_tokens: input.maxOutputTokens
+        })
+      });
+      if (!response.ok) {
+        throw await buildOpenAIError(response);
+      }
+      const data = await response.json();
+      const text = extractResponseText(data);
+      if (!text) {
+        throw new Error("Provider returned an empty response");
+      }
+      return {
+        text,
+        usage: data?.usage ? {
+          inputTokens: data.usage.input_tokens,
+          outputTokens: data.usage.output_tokens,
+          totalTokens: data.usage.total_tokens
+        } : void 0,
+        raw: data
+      };
+    } catch (error) {
+      if (error.name === "AbortError") {
+        throw new Error("Provider request timed out");
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+
 // 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") {
@@ -345,6 +623,18 @@ function extractMessageText(payload) {
   }
   return "";
 }
+async function buildOpenAICompatibleError(response) {
+  let detail = `Provider returned HTTP ${response.status}`;
+  try {
+    const data = await response.json();
+    const message = data?.error?.message;
+    if (typeof message === "string" && message.trim().length > 0) {
+      detail = `${detail}: ${message.trim()}`;
+    }
+  } catch {
+  }
+  return new Error(detail);
+}
 var OpenAICompatibleProvider = class {
   name = "openai-compatible";
   baseUrl;
@@ -369,10 +659,11 @@ 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",
-              content: "You reduce noisy command output into compact answers for agents and automation."
+              content: REDUCTION_SYSTEM_INSTRUCTION
             },
             {
               role: "user",
@@ -382,7 +673,7 @@ var OpenAICompatibleProvider = class {
         })
       });
       if (!response.ok) {
-        throw new Error(`Provider returned HTTP ${response.status}`);
+        throw await buildOpenAICompatibleError(response);
       }
       const data = await response.json();
       const text = extractMessageText(data);
@@ -411,6 +702,12 @@ var OpenAICompatibleProvider = class {
 
 // src/providers/factory.ts
 function createProvider(config) {
+  if (config.provider.provider === "openai") {
+    return new OpenAIProvider({
+      baseUrl: config.provider.baseUrl,
+      apiKey: config.provider.apiKey
+    });
+  }
   if (config.provider.provider === "openai-compatible") {
     return new OpenAICompatibleProvider({
       baseUrl: config.provider.baseUrl,
@@ -536,6 +833,33 @@ var BUILT_IN_POLICIES = {
       `If there is no clear error signal, reply exactly with: ${INSUFFICIENT_SIGNAL_TEXT}`
     ]
   },
+  "typecheck-summary": {
+    name: "typecheck-summary",
+    responseMode: "text",
+    taskRules: [
+      "Return at most 5 short bullet points.",
+      "Determine whether the typecheck failed or passed.",
+      "Group repeated diagnostics into root-cause buckets instead of echoing many duplicate lines.",
+      "Mention the first concrete files, symbols, or error categories to fix when they are visible.",
+      "Prefer compiler or type-system errors over timing, progress, or summary noise.",
+      "If the output clearly indicates success, say that briefly and do not add extra bullets.",
+      `If you cannot tell whether the typecheck failed, reply exactly with: ${INSUFFICIENT_SIGNAL_TEXT}`
+    ]
+  },
+  "lint-failures": {
+    name: "lint-failures",
+    responseMode: "text",
+    taskRules: [
+      "Return at most 5 short bullet points.",
+      "Determine whether lint failed or whether there are no blocking lint failures.",
+      "Group repeated rule violations instead of listing the same rule many times.",
+      "Mention the top offending files and rule names when they are visible.",
+      "Distinguish blocking failures from warnings only when that distinction is clearly visible in the input.",
+      "Do not invent autofixability; only mention autofix or --fix support when the tool output explicitly says so.",
+      "If the output clearly indicates success or no blocking failures, say that briefly and stop.",
+      `If there is not enough evidence to determine the lint result, reply exactly with: ${INSUFFICIENT_SIGNAL_TEXT}`
+    ]
+  },
   "infra-risk": {
     name: "infra-risk",
     responseMode: "json",
@@ -879,6 +1203,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 +1215,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 +1302,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({
@@ -1101,6 +1506,12 @@ async function runExec(request) {
     });
     process.stdout.write(`${output}
 `);
+    if (request.failOn && !request.dryRun && exitCode === 0 && supportsFailOnPreset(request.presetName) && evaluateGate({
+      presetName: request.presetName,
+      output
+    }).shouldFail) {
+      return 1;
+    }
   }
   return exitCode;
 }
@@ -1138,12 +1549,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,9 +1579,25 @@ 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 | openai-compatible").option("--model <model>", "Model name").option("--base-url <url>", "Provider base URL").option(
+    "--api-key <key>",
+    "Provider API key (or set OPENAI_API_KEY for provider=openai; use SIFT_PROVIDER_API_KEY or endpoint-native envs for openai-compatible)"
+  ).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(
+    "--fail-on",
+    "Fail with exit code 1 when a supported built-in preset produces a blocking result"
+  ).option("--config <path>", "Path to config file").option("--verbose", "Enable verbose stderr logging");
 }
 async function executeRun(args) {
+  if (Boolean(args.options.failOn)) {
+    assertSupportedFailOnPreset(args.presetName);
+    assertSupportedFailOnFormat({
+      presetName: args.presetName,
+      format: args.format
+    });
+  }
   const config = resolveConfig({
     configPath: args.options.config,
     env: process.env,
@@ -1181,12 +1609,20 @@ async function executeRun(args) {
     format: args.format,
     stdin,
     config,
+    dryRun: Boolean(args.options.dryRun),
+    presetName: args.presetName,
     policyName: args.policyName,
     outputContract: args.outputContract,
     fallbackJson: args.fallbackJson
   });
   process.stdout.write(`${output}
 `);
+  if (Boolean(args.options.failOn) && !Boolean(args.options.dryRun) && args.presetName && evaluateGate({
+    presetName: args.presetName,
+    output
+  }).shouldFail) {
+    process.exitCode = 1;
+  }
 }
 function extractExecCommand(options) {
   const passthrough = Array.isArray(options["--"]) ? options["--"].map((value) => String(value)) : [];
@@ -1203,6 +1639,13 @@ function extractExecCommand(options) {
   };
 }
 async function executeExec(args) {
+  if (Boolean(args.options.failOn)) {
+    assertSupportedFailOnPreset(args.presetName);
+    assertSupportedFailOnFormat({
+      presetName: args.presetName,
+      format: args.format
+    });
+  }
   const config = resolveConfig({
     configPath: args.options.config,
     env: process.env,
@@ -1213,6 +1656,9 @@ async function executeExec(args) {
     question: args.question,
     format: args.format,
     config,
+    dryRun: Boolean(args.options.dryRun),
+    failOn: Boolean(args.options.failOn),
+    presetName: args.presetName,
     policyName: args.policyName,
     outputContract: args.outputContract,
     fallbackJson: args.fallbackJson,
@@ -1221,7 +1667,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,
@@ -1231,6 +1677,7 @@ applySharedOptions(
   await executeRun({
     question: preset.question,
     format: options.format ?? preset.format,
+    presetName: name,
     policyName: options.format === void 0 || options.format === preset.format ? preset.policy : void 0,
     options,
     outputContract: preset.outputContract,
@@ -1239,7 +1686,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.");
   }
@@ -1259,6 +1706,7 @@ applySharedOptions(
     await executeExec({
       question: preset.question,
       format: options.format ?? preset.format,
+      presetName,
       policyName: options.format === void 0 || options.format === preset.format ? preset.policy : void 0,
       options,
       outputContract: preset.outputContract,
@@ -1276,7 +1724,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 +1745,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