agent-rules-init 0.6.2 → 0.7.0

package/README.md

@@ -1,17 +1,26 @@
-# agent-rules-init
-
+# agent-rules-init
+
+This is the publishable CLI package from the
+[`agent-rules-init` repository](https://github.com/racama29/agent-rules-init).
+The root README is the canonical source for the complete feature, configuration,
+security and contribution documentation.
+
+The operating model is intentionally simple: generate staging files, review them,
+then activate them with `npx agent-rules-init --apply`. Existing active files are
+backed up before replacement.
+
 Generate repository-specific instructions for Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI and Windsurf from the manifests and commands that already exist in your project.
-
-```bash
-npx agent-rules-init
-```
-
-The CLI detects JavaScript/TypeScript, Python, Java, PHP, Ruby, Go, Rust, C#/.NET, Kotlin, Swift, Dart/Flutter, C/C++, Elixir, Scala and R projects. It also understands mixed repositories and npm, pnpm, Yarn and Bun workspaces, generating package-scoped `AGENTS.generated.md` files.
-
+
+```bash
+npx agent-rules-init
+```
+
+The CLI detects JavaScript/TypeScript, Python, Java, PHP, Ruby, Go, Rust, C#/.NET, Kotlin, Swift, Dart/Flutter, C/C++, Elixir, Scala and R projects. It also understands mixed repositories and npm, pnpm, Yarn and Bun workspaces, generating package-scoped `AGENTS.generated.md` files.
+
 All output is written with a `.generated` suffix and existing files are never overwritten during generation. Review them and run `--apply` to activate with safe backups.
-
-Use `--lang es` or `--lang en` to select the output language. See the [full documentation](https://github.com/racama29/agent-rules-init#readme) for supported frameworks, generated files and contribution instructions.
-
+
+Use `--lang es` or `--lang en` to select the output language. See the [full documentation](https://github.com/racama29/agent-rules-init#readme) for supported frameworks, generated files and contribution instructions.
+
 Automation is supported through `--dry-run`, `--force`, `--apply`, `--check`, `--json` and `--non-interactive`. Repository defaults, enrichment assistant/model and per-project overrides can be stored in `.agent-rules-init.yml`.
 
 Use `--apply` after review to activate staging files; replaced finals are backed up under `.agent-rules-init/backups/`.
@@ -20,10 +29,12 @@ Complete generations store a git-ignored hash receipt so `--check` can verify de
 
 AI enrichment runs assistants with read-only restrictions and falls back to deterministic output when invocation or validation fails. Review generated files before activation, especially when the repository did not come from a trusted source.
 
-Enrichment also reports batch, retry, input-size, fallback and duration metrics.
-
-Generated documents share an evidence-backed model but are not duplicates: Claude receives broad repository context, AGENTS receives operational commands and scope, and Copilot receives concise implementation conventions. Observed architecture and local conventions include their source files so specific claims can be audited.
-
-## License
-
-MIT
+Verified enrichment is reused when repository inputs, assistant/model and accepted staging hashes are unchanged. Use `--no-enrich-cache` for a deliberate fresh run, and bound latency with `--enrich-timeout <seconds>` plus `--enrich-retries <0..2>`.
+
+Semantic validation rejects prompt-injection language, new sections, destructive instructions, commands absent from repository facts and evidence paths outside the repository. Metrics report cache hits, changed lines and security rejections in addition to batch, retry, input-size, fallback and duration data.
+
+Generated documents share an evidence-backed model but are not duplicates: Claude receives broad repository context, AGENTS receives operational commands and scope, and Copilot receives concise implementation conventions. Observed architecture and local conventions include their source files so specific claims can be audited.
+
+## License
+
+MIT

package/dist/bin.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 import { main } from "./cli.js";
-main();
+void main();

package/dist/cli.d.ts

@@ -3,7 +3,9 @@ import { type Lang } from "./core/i18n.js";
 import { type AgentRulesConfig } from "./core/config.js";
 import { type PromptFn } from "./core/prompt-engine.js";
 import { type AssistantId, type EnrichMetrics, type ExecFn } from "./core/llm-bridge.js";
-import type { RepoFacts } from "./core/types.js";
+import type { RepoFacts, RepoSignals } from "./core/types.js";
+export { resolveCliAction } from "./core/cli-options.js";
+export type { CliAction, CliRunOptions } from "./core/cli-options.js";
 export interface RunCliOptions {
     /** @deprecated Project metadata is no longer requested interactively. */
     promptFn?: PromptFn;
@@ -22,6 +24,12 @@ export interface RunCliOptions {
     assistant?: AssistantId;
     /** Model forwarded verbatim to the assistant CLI; its default when omitted. */
     model?: string;
+    /** Per-assistant-attempt timeout in seconds. */
+    enrichTimeoutSeconds?: number;
+    /** Disable reuse of verified enriched staging for this invocation. */
+    noEnrichCache?: boolean;
+    /** Number of retries after the first assistant attempt (0..2). */
+    enrichRetries?: number;
     /** Receives the rendered files before they are written (or planned). */
     onGeneratedFiles?: (files: readonly GeneratedFile[]) => void;
     /** Receives the deterministic generation fingerprint before optional enrichment. */
@@ -32,39 +40,11 @@ export interface RunCliOptions {
     onConfigWarnings?: (warnings: readonly string[]) => void;
     /** Receives the facts extracted from the repo (including canonical commands). */
     onFacts?: (facts: RepoFacts) => void;
+    onScanWarnings?: (warnings: readonly string[]) => void;
+    onScanStats?: (stats: NonNullable<RepoSignals["scanStats"]>) => void;
+    /** Offload repository traversal to a worker thread. Enabled by the published binary. */
+    useScannerWorker?: boolean;
 }
 export declare function runCli(rootPath: string, options?: RunCliOptions): Promise<WriteResult[]>;
-export interface CliRunOptions {
-    lang?: Lang;
-    dryRun?: true;
-    force?: true;
-    apply?: true;
-    check?: true;
-    json?: true;
-    nonInteractive?: true;
-    enrich?: true;
-    assistant?: AssistantId;
-    model?: string;
-}
-export type CliAction = ({
-    kind: "run";
-} & CliRunOptions) | {
-    kind: "help";
-} | {
-    kind: "version";
-} | {
-    kind: "invalid-lang";
-    value: string;
-} | {
-    kind: "invalid-assistant";
-    value: string;
-} | {
-    kind: "missing-value";
-    flag: string;
-} | {
-    kind: "unknown";
-    flag: string;
-};
-export declare function resolveCliAction(argv: string[]): CliAction;
 export declare function getVersion(): string;
 export declare function main(): Promise<void>;

package/dist/cli.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import * as clack from "@clack/prompts";
 import { scanRepo } from "./core/scanner.js";
+import { scanRepoInWorker } from "./core/scanner-async.js";
 import { writeGeneratedFiles } from "./core/writer.js";
 import { renderClaudeMd, renderAgentsMd, renderCopilotInstructions, renderCursorRules, renderGeminiMd, renderPromptFiles, } from "./core/templates.js";
 import { buildRepoFacts } from "./core/repo-facts.js";
@@ -11,73 +12,48 @@ import { loadConfig } from "./core/config.js";
 import { applyProjectExcludes, buildPackageUnits } from "./core/project-units.js";
 import { renderProjectUnitAgents } from "./core/project-unit-output.js";
 import { hasInteractiveTty, } from "./core/prompt-engine.js";
-import { detectAvailableAssistants, enrichFilesWithAssistant, estimateEnrichment, defaultExecFn, } from "./core/llm-bridge.js";
+import { detectAvailableAssistants, enrichFilesWithAssistant, estimateEnrichment, createDefaultExecFn, DEFAULT_EXEC_TIMEOUT_MS, summarizeEnrichmentChanges, } from "./core/llm-bridge.js";
 import { hashGeneratedFiles, makeGenerationState, writeGenerationState, } from "./core/generation-state.js";
+import { loadCachedEnrichment, makeEnrichmentState } from "./core/enrichment-cache.js";
 import { evaluateGenerationCheck } from "./core/check-state.js";
 import { applyGeneratedFiles } from "./core/activation.js";
-import { jsTsPack } from "./packs/js-ts.js";
-import { pythonPack } from "./packs/python.js";
-import { javaPack } from "./packs/java.js";
-import { phpPack } from "./packs/php.js";
-import { rubyPack } from "./packs/ruby.js";
-import { goPack } from "./packs/go.js";
-import { rustPack } from "./packs/rust.js";
-import { csharpPack } from "./packs/csharp.js";
-import { kotlinPack } from "./packs/kotlin.js";
-import { swiftPack } from "./packs/swift.js";
-import { dartPack } from "./packs/dart.js";
-import { cppPack } from "./packs/cpp.js";
-import { elixirPack } from "./packs/elixir.js";
-import { scalaPack } from "./packs/scala.js";
-import { rPack } from "./packs/r.js";
-const ALL_PACKS = [
-    jsTsPack,
-    pythonPack,
-    javaPack,
-    phpPack,
-    rubyPack,
-    goPack,
-    rustPack,
-    csharpPack,
-    kotlinPack,
-    swiftPack,
-    dartPack,
-    cppPack,
-    elixirPack,
-    scalaPack,
-    rPack,
-];
-// Final-name docs the tool itself would generate; when they already exist they carry the
-// team's hand-written intent, so enrichment must integrate them instead of ignoring them.
-const EXISTING_DOC_PATHS = [
-    "CLAUDE.md",
-    "AGENTS.md",
-    "GEMINI.md",
-    ".github/copilot-instructions.md",
-    ".cursor/rules/repository.mdc",
-];
-const MAX_EXISTING_DOC_CHARS = 20_000;
-function readExistingDocs(rootPath) {
-    const docs = [];
-    for (const relativePath of EXISTING_DOC_PATHS) {
-        const absolutePath = path.join(rootPath, relativePath);
-        if (!fs.existsSync(absolutePath))
-            continue;
-        const content = fs.readFileSync(absolutePath, "utf8");
-        if (content.trim() === "")
-            continue;
-        docs.push({ path: relativePath, content: content.slice(0, MAX_EXISTING_DOC_CHARS) });
-    }
-    return docs;
-}
+import { ALL_PACKS, findPack } from "./packs/index.js";
+import { readExistingDocs } from "./core/existing-docs.js";
+import { resolveCliAction } from "./core/cli-options.js";
+export { resolveCliAction } from "./core/cli-options.js";
 export async function runCli(rootPath, options = {}) {
     const loadedConfig = options.config ? { config: options.config, warnings: [] } : loadConfig(rootPath);
     const config = loadedConfig.config;
     options.onConfigWarnings?.(loadedConfig.warnings);
-    const execFn = options.execFn ?? defaultExecFn;
+    const timeoutSeconds = options.enrichTimeoutSeconds ?? config.enrichTimeoutSeconds ?? DEFAULT_EXEC_TIMEOUT_MS / 1000;
+    const execFn = options.execFn ?? createDefaultExecFn(timeoutSeconds * 1000);
     const lang = options.lang ?? config.lang ?? detectLang();
     const ui = UI[lang];
-    const signals = applyProjectExcludes(scanRepo(rootPath), config.exclude ?? []);
+    const scanOptions = {
+        maxDepth: config.scanMaxDepth,
+        maxFiles: config.scanMaxFiles,
+    };
+    let scanned;
+    if (options.useScannerWorker) {
+        try {
+            scanned = await scanRepoInWorker(rootPath, scanOptions, (config.scanWorkerTimeoutSeconds ?? 30) * 1_000);
+        }
+        catch (error) {
+            scanned = scanRepo(rootPath, scanOptions);
+            scanned.scanWarnings = [
+                ...(scanned.scanWarnings ?? []),
+                `Scanner worker unavailable; used synchronous fallback: ${error.message}`,
+            ];
+            if (scanned.scanStats)
+                scanned.scanStats.mode = "sync-fallback";
+        }
+    }
+    else
+        scanned = scanRepo(rootPath, scanOptions);
+    const signals = applyProjectExcludes(scanned, config.exclude ?? []);
+    options.onScanWarnings?.(signals.scanWarnings ?? []);
+    if (signals.scanStats)
+        options.onScanStats?.(signals.scanStats);
     const rawDetections = ALL_PACKS.map((pack) => pack.detect(signals)).filter((d) => d !== null);
     // Missing framework/tooling signals are valid facts, not questions the user should
     // have to answer. Keep the low-confidence `none` value and render conservative,
@@ -88,7 +64,7 @@ export async function runCli(rootPath, options = {}) {
     options.onFacts?.(facts);
     const ctx = { facts, signals };
     const entries = detections.map((detection) => {
-        const pack = ALL_PACKS.find((p) => p.id === detection.packId);
+        const pack = findPack(detection.packId);
         return { detection, ruleSet: pack.rules(detection, lang, ctx) };
     });
     const files = [];
@@ -105,7 +81,7 @@ export async function runCli(rootPath, options = {}) {
         });
         files.push({ path: "GEMINI.generated.md", content: renderGeminiMd(entries, facts, lang) });
         for (const detection of detections) {
-            const pack = ALL_PACKS.find((p) => p.id === detection.packId);
+            const pack = findPack(detection.packId);
             for (const file of renderPromptFiles(detection.packId, pack.promptTemplates(detection, lang, ctx))) {
                 files.push(file);
             }
@@ -130,6 +106,7 @@ export async function runCli(rootPath, options = {}) {
     }
     const baselineHash = hashGeneratedFiles(files);
     options.onBaselineHash?.(baselineHash);
+    let acceptedEnrichmentState;
     const wantsEnrich = (options.enrich ?? config.enrich) === true;
     const canOfferEnrich = !options.nonInteractive && hasInteractiveTty();
     if (!options.skipLlm && !config.noAi && (wantsEnrich || canOfferEnrich)) {
@@ -153,30 +130,77 @@ export async function runCli(rootPath, options = {}) {
                 proceed = (await clack.confirm({ message: ui.enrichConfirm(chosenAssistant) })) === true;
             }
             if (proceed) {
-                const estimate = estimateEnrichment(files);
-                if (estimate.batches > 1)
-                    notify(ui.enrichLargeInput(estimate.characters, estimate.batches));
-                const spinner = canOfferEnrich ? clack.spinner() : undefined;
-                if (spinner)
-                    spinner.start(ui.enrichWorking(chosenAssistant));
-                else
-                    notify(ui.enrichWorking(chosenAssistant));
-                const enriched = await enrichFilesWithAssistant(chosenAssistant, files, {
-                    execFn,
-                    lang,
-                    cwd: rootPath,
-                    mustKeep: facts.canonical.map((c) => c.command),
-                    existingDocs: readExistingDocs(rootPath),
-                    model: options.model ?? config.model,
-                    onMetrics: options.onEnrichMetrics,
-                });
-                const changed = enriched.some((file, i) => file.content !== files[i].content);
-                const outcome = changed ? ui.enrichDone : ui.enrichKept;
-                if (spinner)
-                    spinner.stop(outcome);
-                else
-                    notify(outcome);
-                files.splice(0, files.length, ...enriched);
+                const existingDocs = readExistingDocs(rootPath);
+                const model = options.model ?? config.model;
+                const requestedState = makeEnrichmentState(rootPath, signals.files, baselineHash, existingDocs, chosenAssistant, model);
+                const useCache = options.noEnrichCache !== true && config.enrichCache !== false;
+                const cached = useCache
+                    ? loadCachedEnrichment(rootPath, baselineHash, files, requestedState)
+                    : undefined;
+                if (cached) {
+                    const changes = summarizeEnrichmentChanges(files, cached);
+                    options.onEnrichMetrics?.({
+                        assistant: chosenAssistant,
+                        model,
+                        batches: 0,
+                        attempts: 0,
+                        fallbackBatches: 0,
+                        inputChars: 0,
+                        outputChars: cached.reduce((sum, file) => sum + file.content.length, 0),
+                        durationMs: 0,
+                        cacheHit: true,
+                        ...changes,
+                        securityRejections: 0,
+                    });
+                    acceptedEnrichmentState = requestedState;
+                    files.splice(0, files.length, ...cached);
+                    notify(ui.enrichCacheHit);
+                }
+                else {
+                    const estimate = estimateEnrichment(files);
+                    if (estimate.batches > 1)
+                        notify(ui.enrichLargeInput(estimate.characters, estimate.batches));
+                    const spinner = canOfferEnrich ? clack.spinner() : undefined;
+                    const retries = options.enrichRetries ?? config.enrichRetries ?? 1;
+                    notify(ui.enrichBudget(timeoutSeconds, retries + 1));
+                    if (spinner)
+                        spinner.start(ui.enrichWorking(chosenAssistant));
+                    else
+                        notify(ui.enrichWorking(chosenAssistant));
+                    let runMetrics;
+                    const verifiedCommands = [...new Set([
+                            ...facts.canonical.map((entry) => entry.command),
+                            ...facts.commands.map((entry) => entry.invocation),
+                            ...facts.ciCommands.map((entry) => entry.command),
+                        ])];
+                    const enriched = await enrichFilesWithAssistant(chosenAssistant, files, {
+                        execFn,
+                        lang,
+                        cwd: rootPath,
+                        mustKeep: verifiedCommands,
+                        existingDocs,
+                        model,
+                        maxAttempts: retries + 1,
+                        onMetrics: (metrics) => {
+                            runMetrics = metrics;
+                            options.onEnrichMetrics?.(metrics);
+                        },
+                    });
+                    const changed = enriched.some((file, i) => file.content !== files[i].content);
+                    const outcome = changed ? ui.enrichDone : ui.enrichKept;
+                    if (spinner)
+                        spinner.stop(outcome);
+                    else
+                        notify(outcome);
+                    files.splice(0, files.length, ...enriched);
+                    if (changed && runMetrics && runMetrics.fallbackBatches === 0) {
+                        acceptedEnrichmentState = requestedState;
+                    }
+                    else if (!changed) {
+                        // Never cache a deterministic fallback as a successful enrichment.
+                        acceptedEnrichmentState = undefined;
+                    }
+                }
             }
         }
     }
@@ -191,76 +215,10 @@ export async function runCli(rootPath, options = {}) {
     }
     const results = writeGeneratedFiles(rootPath, files, { force: options.force });
     const completeRefresh = results.every((result) => result.status === "written" || result.status === "overwritten");
-    if (completeRefresh)
-        writeGenerationState(rootPath, makeGenerationState(baselineHash, files));
-    return results;
-}
-function isLang(value) {
-    return value === "es" || value === "en";
-}
-function isAssistant(value) {
-    return value === "claude" || value === "codex";
-}
-export function resolveCliAction(argv) {
-    const options = {};
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "--help" || arg === "-h")
-            return { kind: "help" };
-        if (arg === "--version" || arg === "-v")
-            return { kind: "version" };
-        if (arg === "--lang" || arg.startsWith("--lang=")) {
-            const value = arg.startsWith("--lang=") ? arg.slice("--lang=".length) : argv[++i] ?? "";
-            if (!isLang(value))
-                return { kind: "invalid-lang", value };
-            options.lang = value;
-            continue;
-        }
-        if (arg === "--dry-run") {
-            options.dryRun = true;
-            continue;
-        }
-        if (arg === "--force") {
-            options.force = true;
-            continue;
-        }
-        if (arg === "--apply") {
-            options.apply = true;
-            continue;
-        }
-        if (arg === "--check") {
-            options.check = true;
-            continue;
-        }
-        if (arg === "--json") {
-            options.json = true;
-            continue;
-        }
-        if (arg === "--non-interactive") {
-            options.nonInteractive = true;
-            continue;
-        }
-        if (arg === "--enrich") {
-            options.enrich = true;
-            continue;
-        }
-        if (arg === "--assistant" || arg.startsWith("--assistant=")) {
-            const value = arg.startsWith("--assistant=") ? arg.slice("--assistant=".length) : argv[++i] ?? "";
-            if (!isAssistant(value))
-                return { kind: "invalid-assistant", value };
-            options.assistant = value;
-            continue;
-        }
-        if (arg === "--model" || arg.startsWith("--model=")) {
-            const value = arg.startsWith("--model=") ? arg.slice("--model=".length) : argv[++i] ?? "";
-            if (value === "")
-                return { kind: "missing-value", flag: "--model" };
-            options.model = value;
-            continue;
-        }
-        return { kind: "unknown", flag: arg };
+    if (completeRefresh) {
+        writeGenerationState(rootPath, makeGenerationState(baselineHash, files, acceptedEnrichmentState));
     }
-    return { kind: "run", ...options };
+    return results;
 }
 function usageWithAutomationOptions(ui) {
     return `${ui.usage}\n\n${ui.automationUsage}`;
@@ -298,6 +256,16 @@ export async function main() {
         process.exitCode = 1;
         return;
     }
+    if (action.kind === "invalid-timeout") {
+        console.error(`${ui.invalidTimeout(action.value)}\n\n${usageWithAutomationOptions(ui)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (action.kind === "invalid-retries") {
+        console.error(`${ui.invalidRetries(action.value)}\n\n${usageWithAutomationOptions(ui)}`);
+        process.exitCode = 1;
+        return;
+    }
     if (action.kind === "missing-value") {
         console.error(`${ui.missingFlagValue(action.flag)}\n\n${usageWithAutomationOptions(ui)}`);
         process.exitCode = 1;
@@ -334,6 +302,8 @@ export async function main() {
         let repoFacts;
         let baselineHash;
         let enrichMetrics;
+        let scanWarnings = [];
+        let scanStats;
         const results = await runCli(process.cwd(), {
             lang,
             config: loadedConfig.config,
@@ -344,6 +314,9 @@ export async function main() {
             enrich,
             assistant: action.assistant ?? loadedConfig.config.assistant,
             model: action.model ?? loadedConfig.config.model,
+            enrichTimeoutSeconds: action.enrichTimeoutSeconds ?? loadedConfig.config.enrichTimeoutSeconds,
+            noEnrichCache: action.noEnrichCache === true,
+            enrichRetries: action.enrichRetries ?? loadedConfig.config.enrichRetries,
             onGeneratedFiles: (files) => {
                 generatedFiles = files;
             },
@@ -356,7 +329,17 @@ export async function main() {
             onFacts: (facts) => {
                 repoFacts = facts;
             },
+            onScanWarnings: (warnings) => {
+                scanWarnings = warnings;
+            },
+            onScanStats: (stats) => {
+                scanStats = stats;
+            },
+            useScannerWorker: true,
         });
+        if (!machineOutput)
+            for (const warning of scanWarnings)
+                console.warn(warning);
         let activationResults = [];
         if (apply) {
             if (!baselineHash)
@@ -377,6 +360,8 @@ export async function main() {
             console.log(JSON.stringify({
                 mode: action.check ? "check" : action.dryRun ? "dry-run" : apply ? "apply" : "write",
                 configWarnings: loadedConfig.warnings,
+                scanWarnings,
+                scanStats,
                 facts: repoFacts,
                 wouldCreate: action.check ? missing.length : written.length,
                 missing: missing.map((file) => file.path),

package/dist/core/cli-options.d.ts

@@ -0,0 +1,43 @@
+import type { Lang } from "./i18n.js";
+import type { AssistantId } from "./llm-bridge.js";
+export interface CliRunOptions {
+    lang?: Lang;
+    dryRun?: true;
+    force?: true;
+    apply?: true;
+    check?: true;
+    json?: true;
+    nonInteractive?: true;
+    enrich?: true;
+    assistant?: AssistantId;
+    model?: string;
+    enrichTimeoutSeconds?: number;
+    noEnrichCache?: true;
+    enrichRetries?: number;
+}
+export type CliAction = ({
+    kind: "run";
+} & CliRunOptions) | {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "invalid-lang";
+    value: string;
+} | {
+    kind: "invalid-assistant";
+    value: string;
+} | {
+    kind: "invalid-timeout";
+    value: string;
+} | {
+    kind: "invalid-retries";
+    value: string;
+} | {
+    kind: "missing-value";
+    flag: string;
+} | {
+    kind: "unknown";
+    flag: string;
+};
+export declare function resolveCliAction(argv: string[]): CliAction;

package/dist/core/cli-options.js

@@ -0,0 +1,70 @@
+function optionValue(argv, index, name) {
+    const argument = argv[index];
+    return argument.startsWith(`${name}=`)
+        ? [argument.slice(name.length + 1), index]
+        : [argv[index + 1] ?? "", index + 1];
+}
+export function resolveCliAction(argv) {
+    const options = {};
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        if (argument === "--help" || argument === "-h")
+            return { kind: "help" };
+        if (argument === "--version" || argument === "-v")
+            return { kind: "version" };
+        if (argument === "--lang" || argument.startsWith("--lang=")) {
+            const [value, consumed] = optionValue(argv, index, "--lang");
+            index = consumed;
+            if (value !== "es" && value !== "en")
+                return { kind: "invalid-lang", value };
+            options.lang = value;
+            continue;
+        }
+        if (argument === "--assistant" || argument.startsWith("--assistant=")) {
+            const [value, consumed] = optionValue(argv, index, "--assistant");
+            index = consumed;
+            if (value !== "claude" && value !== "codex")
+                return { kind: "invalid-assistant", value };
+            options.assistant = value;
+            continue;
+        }
+        if (argument === "--model" || argument.startsWith("--model=")) {
+            const [value, consumed] = optionValue(argv, index, "--model");
+            index = consumed;
+            if (!value)
+                return { kind: "missing-value", flag: "--model" };
+            options.model = value;
+            continue;
+        }
+        if (argument === "--enrich-timeout" || argument.startsWith("--enrich-timeout=")) {
+            const [value, consumed] = optionValue(argv, index, "--enrich-timeout");
+            index = consumed;
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed < 10 || parsed > 3600)
+                return { kind: "invalid-timeout", value };
+            options.enrichTimeoutSeconds = parsed;
+            continue;
+        }
+        if (argument === "--enrich-retries" || argument.startsWith("--enrich-retries=")) {
+            const [value, consumed] = optionValue(argv, index, "--enrich-retries");
+            index = consumed;
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed < 0 || parsed > 2)
+                return { kind: "invalid-retries", value };
+            options.enrichRetries = parsed;
+            continue;
+        }
+        const booleanOptions = {
+            "--dry-run": "dryRun", "--force": "force", "--apply": "apply", "--check": "check",
+            "--json": "json", "--non-interactive": "nonInteractive", "--enrich": "enrich",
+            "--no-enrich-cache": "noEnrichCache",
+        };
+        const key = booleanOptions[argument];
+        if (key) {
+            Object.assign(options, { [key]: true });
+            continue;
+        }
+        return { kind: "unknown", flag: argument };
+    }
+    return { kind: "run", ...options };
+}

package/dist/core/config.d.ts

@@ -13,6 +13,18 @@ export interface AgentRulesConfig {
     enrich?: boolean;
     assistant?: "claude" | "codex";
     model?: string;
+    /** Reuse verified enriched staging when repository inputs are unchanged. Defaults to true. */
+    enrichCache?: boolean;
+    /** Per-assistant-attempt timeout in seconds (10..3600). */
+    enrichTimeoutSeconds?: number;
+    /** Validation retries after the first attempt (0..2). */
+    enrichRetries?: number;
+    /** Maximum directory nesting inspected by the repository scanner (1..64). */
+    scanMaxDepth?: number;
+    /** Maximum files collected before stopping the repository scan (100..1,000,000). */
+    scanMaxFiles?: number;
+    /** Worker scan timeout before a synchronous compatibility fallback (1..300 seconds). */
+    scanWorkerTimeoutSeconds?: number;
 }
 export interface LoadedConfig {
     config: AgentRulesConfig;