agent-rules-init 0.3.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-rules-init contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# agent-rules-init
+
+Generate repository-specific instructions for Claude Code, Codex and GitHub Copilot 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.
+
+All output is written with a `.generated` suffix and existing files are never overwritten. Review the generated files and remove the suffix when you are ready to activate them.
+
+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`, `--check`, `--json` and `--non-interactive`. Repository defaults and per-project overrides can be stored in `.agent-rules-init.yml`.
+
+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/cli.d.ts

@@ -1,24 +1,58 @@
-import { type WriteResult } from "./core/writer.js";
+import { type GeneratedFile, type WriteResult } from "./core/writer.js";
 import { type Lang } from "./core/i18n.js";
+import { type AgentRulesConfig } from "./core/config.js";
 import { type PromptFn } from "./core/prompt-engine.js";
-import { type ExecFn } from "./core/llm-bridge.js";
+import { type AssistantId, type ExecFn } from "./core/llm-bridge.js";
+import type { RepoFacts } from "./core/types.js";
 export interface RunCliOptions {
     promptFn?: PromptFn;
     execFn?: ExecFn;
     skipLlm?: boolean;
     lang?: Lang;
+    /** Generate results without changing the filesystem. */
+    dryRun?: boolean;
+    /** Do not prompt or offer AI enrichment. */
+    nonInteractive?: boolean;
+    /** Run AI enrichment without asking, even without a TTY. Ignored when skipLlm or noAi apply. */
+    enrich?: boolean;
+    /** Assistant to enrich with; defaults to the first one installed. */
+    assistant?: AssistantId;
+    /** Model forwarded verbatim to the assistant CLI; its default when omitted. */
+    model?: string;
+    /** Receives the rendered files before they are written (or planned). */
+    onGeneratedFiles?: (files: readonly GeneratedFile[]) => void;
+    /** Preloaded repository configuration; loaded from disk when omitted. */
+    config?: AgentRulesConfig;
+    onConfigWarnings?: (warnings: readonly string[]) => void;
+    /** Receives the facts extracted from the repo (including canonical commands). */
+    onFacts?: (facts: RepoFacts) => void;
 }
 export declare function runCli(rootPath: string, options?: RunCliOptions): Promise<WriteResult[]>;
-export type CliAction = {
-    kind: "run";
+export interface CliRunOptions {
     lang?: Lang;
-} | {
+    dryRun?: 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;

package/dist/cli.js

@@ -1,12 +1,17 @@
 import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
 import * as clack from "@clack/prompts";
 import { scanRepo } from "./core/scanner.js";
 import { writeGeneratedFiles } from "./core/writer.js";
-import { renderClaudeMd, renderAgentsMd, renderCopilotInstructions, renderPromptFiles, renderRepoFacts, } from "./core/templates.js";
+import { renderClaudeMd, renderAgentsMd, renderCopilotInstructions, renderPromptFiles, } from "./core/templates.js";
 import { buildRepoFacts } from "./core/repo-facts.js";
 import { UI, detectLang } from "./core/i18n.js";
+import { loadConfig } from "./core/config.js";
+import { applyProjectExcludes, buildPackageUnits } from "./core/project-units.js";
+import { renderProjectUnitAgents } from "./core/project-unit-output.js";
 import { collectLowConfidenceQuestions, askQuestions, applyAnswers, makeDefaultPromptFn, hasInteractiveTty, } from "./core/prompt-engine.js";
-import { detectAvailableAssistants, polishWithAssistant, defaultExecFn } from "./core/llm-bridge.js";
+import { detectAvailableAssistants, enrichFilesWithAssistant, defaultExecFn, } from "./core/llm-bridge.js";
 import { jsTsPack } from "./packs/js-ts.js";
 import { pythonPack } from "./packs/python.js";
 import { javaPack } from "./packs/java.js";
@@ -39,20 +44,42 @@ const ALL_PACKS = [
     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", ".github/copilot-instructions.md"];
+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;
+}
 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 lang = options.lang ?? detectLang();
+    const lang = options.lang ?? config.lang ?? detectLang();
     const promptFn = options.promptFn ?? makeDefaultPromptFn(lang);
     const ui = UI[lang];
-    const signals = scanRepo(rootPath);
+    const signals = applyProjectExcludes(scanRepo(rootPath), config.exclude ?? []);
     const rawDetections = ALL_PACKS.map((pack) => pack.detect(signals)).filter((d) => d !== null);
     const questions = collectLowConfidenceQuestions(rawDetections, lang);
-    const answers = await askQuestions(questions, promptFn);
+    const answers = options.nonInteractive ? {} : await askQuestions(questions, promptFn);
     const detections = applyAnswers(rawDetections, answers);
     const facts = buildRepoFacts(signals, lang);
+    options.onFacts?.(facts);
+    const ctx = { facts, signals };
     const entries = detections.map((detection) => {
         const pack = ALL_PACKS.find((p) => p.id === detection.packId);
-        return { detection, ruleSet: pack.rules(detection, lang) };
+        return { detection, ruleSet: pack.rules(detection, lang, ctx) };
     });
     const files = [];
     if (entries.length > 0) {
@@ -64,38 +91,88 @@ export async function runCli(rootPath, options = {}) {
         });
         for (const detection of detections) {
             const pack = ALL_PACKS.find((p) => p.id === detection.packId);
-            for (const file of renderPromptFiles(detection.packId, pack.promptTemplates(detection, lang))) {
+            for (const file of renderPromptFiles(detection.packId, pack.promptTemplates(detection, lang, ctx))) {
                 files.push(file);
             }
         }
     }
     else {
-        const factsBlock = renderRepoFacts(facts, lang);
-        files.push({
-            path: "CLAUDE.generated.md",
-            content: `# CLAUDE.md\n\n${ui.noStackFallback}\n` + (factsBlock ? `\n${factsBlock}\n` : ""),
+        const withFallback = (content) => content.replace(ui.generatedHeader, `${ui.generatedHeader}\n\n${ui.noStackFallback}`);
+        files.push({ path: "CLAUDE.generated.md", content: withFallback(renderClaudeMd([], facts, lang)) }, { path: "AGENTS.generated.md", content: withFallback(renderAgentsMd([], facts, lang)) }, {
+            path: ".github/copilot-instructions.generated.md",
+            content: withFallback(renderCopilotInstructions([], facts, lang)),
         });
     }
-    if (!options.skipLlm && hasInteractiveTty()) {
+    // Nested AGENTS files are intentionally limited to package-local facts and stack
+    // signals. The root documents remain the cross-repository overview.
+    for (const unit of buildPackageUnits(signals)) {
+        const scoped = renderProjectUnitAgents(unit, lang, config.projects?.[unit.path]);
+        if (scoped)
+            files.push(scoped);
+    }
+    const wantsEnrich = options.enrich === true;
+    const canOfferEnrich = !options.nonInteractive && hasInteractiveTty();
+    if (!options.skipLlm && !config.noAi && (wantsEnrich || canOfferEnrich)) {
+        // With --enrich there may be no TTY (scripts, CI); route progress through stderr so
+        // stdout stays parseable in --json mode.
+        const notify = canOfferEnrich ? (message) => clack.log.info(message) : (message) => console.warn(message);
         const assistants = await detectAvailableAssistants(execFn);
-        if (assistants.length > 0) {
-            const chosenAssistant = assistants[0];
-            clack.log.info(ui.polishDetected(chosenAssistant));
-            const usePolish = await clack.confirm({ message: ui.polishConfirm(chosenAssistant) });
-            if (usePolish === true) {
-                for (const file of files) {
-                    file.content = await polishWithAssistant(chosenAssistant, file.content, execFn, lang);
-                }
+        const requested = options.assistant;
+        if (requested && !assistants.includes(requested)) {
+            console.warn(ui.assistantNotAvailable(requested));
+        }
+        else if (assistants.length === 0) {
+            if (wantsEnrich)
+                console.warn(ui.enrichNoAssistant);
+        }
+        else {
+            const chosenAssistant = requested ?? assistants[0];
+            let proceed = wantsEnrich;
+            if (!proceed) {
+                clack.log.info(ui.enrichDetected(chosenAssistant));
+                proceed = (await clack.confirm({ message: ui.enrichConfirm(chosenAssistant) })) === true;
+            }
+            if (proceed) {
+                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,
+                });
+                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);
             }
         }
     }
+    options.onGeneratedFiles?.(files);
+    if (options.dryRun) {
+        return files.map((file) => ({
+            path: file.path,
+            status: fs.existsSync(path.join(rootPath, file.path)) ? "skipped" : "written",
+        }));
+    }
     return writeGeneratedFiles(rootPath, files);
 }
 function isLang(value) {
     return value === "es" || value === "en";
 }
+function isAssistant(value) {
+    return value === "claude" || value === "codex";
+}
 export function resolveCliAction(argv) {
-    let lang;
+    const options = {};
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg === "--help" || arg === "-h")
@@ -106,12 +183,49 @@ export function resolveCliAction(argv) {
             const value = arg.startsWith("--lang=") ? arg.slice("--lang=".length) : argv[++i] ?? "";
             if (!isLang(value))
                 return { kind: "invalid-lang", value };
-            lang = value;
+            options.lang = value;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            options.dryRun = 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 };
     }
-    return lang ? { kind: "run", lang } : { kind: "run" };
+    return { kind: "run", ...options };
+}
+function usageWithAutomationOptions(ui) {
+    return `${ui.usage}\n\n${ui.automationUsage}`;
 }
 export function getVersion() {
     // Works both from src/ (tests) and dist/ (published bin): ../package.json
@@ -121,10 +235,10 @@ export function getVersion() {
 }
 export async function main() {
     const action = resolveCliAction(process.argv.slice(2));
-    const lang = action.kind === "run" && action.lang ? action.lang : detectLang();
-    const ui = UI[lang];
+    const defaultLang = action.kind === "run" && action.lang ? action.lang : detectLang();
+    let ui = UI[defaultLang];
     if (action.kind === "help") {
-        console.log(ui.usage);
+        console.log(usageWithAutomationOptions(ui));
         return;
     }
     if (action.kind === "version") {
@@ -132,46 +246,131 @@ export async function main() {
         return;
     }
     if (action.kind === "unknown") {
-        console.error(`${ui.unknownOption(action.flag)}\n\n${ui.usage}`);
+        console.error(`${ui.unknownOption(action.flag)}\n\n${usageWithAutomationOptions(ui)}`);
         process.exitCode = 1;
         return;
     }
     if (action.kind === "invalid-lang") {
-        console.error(`${ui.invalidLang(action.value)}\n\n${ui.usage}`);
+        console.error(`${ui.invalidLang(action.value)}\n\n${usageWithAutomationOptions(ui)}`);
+        process.exitCode = 1;
+        return;
+    }
+    if (action.kind === "invalid-assistant") {
+        console.error(`${ui.invalidAssistant(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;
         return;
     }
-    clack.intro("agent-rules-init");
-    if (!hasInteractiveTty()) {
+    const machineOutput = action.json === true;
+    const planningOnly = action.dryRun === true || action.check === true;
+    const nonInteractive = action.nonInteractive === true || machineOutput || planningOnly;
+    // Enrichment output is non-deterministic, so --check (freshness comparison) must stay
+    // on the deterministic baseline.
+    const enrich = action.enrich === true && action.check !== true;
+    if (action.enrich === true && action.check === true)
+        console.warn("--enrich is ignored with --check.");
+    if (!machineOutput)
+        clack.intro("agent-rules-init");
+    if (!machineOutput && !nonInteractive && !hasInteractiveTty()) {
         console.warn(ui.noTtyWarning);
     }
     try {
-        const results = await runCli(process.cwd(), { lang });
+        const loadedConfig = loadConfig(process.cwd());
+        const lang = action.lang ?? loadedConfig.config.lang ?? defaultLang;
+        ui = UI[lang];
+        if (!machineOutput) {
+            for (const warning of loadedConfig.warnings)
+                console.warn(warning);
+        }
+        let generatedFiles = [];
+        let repoFacts;
+        const results = await runCli(process.cwd(), {
+            lang,
+            config: loadedConfig.config,
+            dryRun: planningOnly,
+            nonInteractive,
+            skipLlm: nonInteractive && !enrich,
+            enrich,
+            assistant: action.assistant,
+            model: action.model,
+            onGeneratedFiles: (files) => {
+                generatedFiles = files;
+            },
+            onFacts: (facts) => {
+                repoFacts = facts;
+            },
+        });
         const written = results.filter((r) => r.status === "written");
         const failures = results.filter((r) => r.status === "error");
-        for (const result of results) {
-            if (result.status === "written") {
-                clack.log.success(result.path);
-            }
-            else if (result.status === "skipped") {
-                clack.log.info(ui.fileSkipped(result.path));
+        const outdated = action.check
+            ? generatedFiles.filter((file) => {
+                const absolutePath = path.join(process.cwd(), file.path);
+                return fs.existsSync(absolutePath) && fs.readFileSync(absolutePath, "utf8") !== file.content;
+            })
+            : [];
+        const checkIssues = written.length + outdated.length;
+        if (machineOutput) {
+            const contentByPath = new Map(generatedFiles.map((file) => [file.path, file.content]));
+            console.log(JSON.stringify({
+                mode: action.check ? "check" : action.dryRun ? "dry-run" : "write",
+                configWarnings: loadedConfig.warnings,
+                facts: repoFacts,
+                wouldCreate: written.length,
+                outdated: outdated.map((file) => file.path),
+                results: results.map((result) => ({
+                    ...result,
+                    ...(planningOnly ? { content: contentByPath.get(result.path) } : {}),
+                })),
+            }));
+        }
+        else if (action.dryRun) {
+            const statusByPath = new Map(results.map((result) => [result.path, result.status]));
+            for (const file of generatedFiles) {
+                console.log(`\n--- ${file.path} (${statusByPath.get(file.path) === "written" ? "would create" : "exists"}) ---\n${file.content}`);
             }
-            else {
-                clack.log.warn(`${result.path}: ${result.error}`);
+        }
+        else if (!action.check)
+            for (const result of results) {
+                if (result.status === "written") {
+                    clack.log.success(result.path);
+                }
+                else if (result.status === "skipped") {
+                    clack.log.info(ui.fileSkipped(result.path));
+                }
+                else {
+                    clack.log.warn(`${result.path}: ${result.error}`);
+                }
             }
+        if (!machineOutput && action.check) {
+            console.log(checkIssues > 0
+                ? `${written.length} file(s) missing; ${outdated.length} file(s) outdated.`
+                : "Generated files are present and up to date.");
+        }
+        else if (!machineOutput && action.dryRun) {
+            console.log(`\n${written.length} file(s) would be generated.`);
         }
-        if (written.length > 0) {
+        else if (!machineOutput && written.length > 0) {
             clack.outro(ui.outroWritten);
         }
-        else {
+        else if (!machineOutput) {
             clack.outro(ui.outroNothing);
         }
-        if (failures.length > 0) {
+        if (failures.length > 0 || (action.check && checkIssues > 0)) {
             process.exitCode = 1;
         }
     }
     catch (err) {
-        clack.log.error(ui.unexpectedError(err.message));
+        const message = ui.unexpectedError(err.message);
+        if (machineOutput) {
+            console.log(JSON.stringify({ mode: action.check ? "check" : action.dryRun ? "dry-run" : "write", error: message }));
+        }
+        else {
+            clack.log.error(message);
+        }
         process.exitCode = 1;
     }
 }

package/dist/core/canonical-commands.d.ts

@@ -0,0 +1,4 @@
+import type { CanonicalCommand, CiCommand, CommandEntry, CommandSource, PackContext, RepoSignals } from "./types.js";
+export declare const SOURCE_FILES: Record<CommandSource, string>;
+export declare function selectCanonicalCommands(signals: RepoSignals, commands: CommandEntry[], ciCommands: CiCommand[]): CanonicalCommand[];
+export declare function canonicalOf(ctx: PackContext | undefined, kind: CanonicalCommand["kind"], family?: "js-ts" | "python" | "java"): CanonicalCommand | undefined;

package/dist/core/canonical-commands.js

@@ -0,0 +1,169 @@
+export const SOURCE_FILES = {
+    npm: "package.json",
+    pnpm: "package.json",
+    yarn: "package.json",
+    bun: "package.json",
+    composer: "composer.json",
+    make: "Makefile",
+    mix: "mix.exs",
+    tox: "tox.ini",
+};
+const KIND_ORDER = ["test", "lint", "build", "format", "typecheck"];
+// Nombre de script → kind. Solo nombres inequívocos; "check" o "ci" quedan fuera a propósito.
+const SCRIPT_KINDS = {
+    test: "test",
+    lint: "lint",
+    build: "build",
+    format: "format",
+    fmt: "format",
+    typecheck: "typecheck",
+    "type-check": "typecheck",
+};
+function scriptName(entry) {
+    const parts = entry.invocation.split(" ");
+    return parts[parts.length - 1];
+}
+function isRootManifest(entry) {
+    return entry.manifestPath === undefined || entry.manifestPath === "package.json";
+}
+function fromScripts(commands) {
+    const found = [];
+    for (const entry of commands) {
+        if (!isRootManifest(entry))
+            continue;
+        const kind = SCRIPT_KINDS[scriptName(entry)];
+        if (!kind || found.some((c) => c.kind === kind))
+            continue;
+        found.push({
+            kind,
+            command: entry.invocation,
+            source: entry.manifestPath ?? SOURCE_FILES[entry.source],
+            confidence: "high",
+            scope: ".",
+        });
+    }
+    return found;
+}
+// El comando de CI se conserva textual (evidencia), solo se clasifica su kind.
+const CI_PATTERNS = [
+    [/^(?:npm|pnpm|yarn|bun)(?: run)? test\b/, "test"],
+    [/^(?:npm|pnpm|yarn|bun) run lint\b/, "lint"],
+    [/^(?:npm|pnpm|yarn|bun) run build\b/, "build"],
+    [/^(?:npm|pnpm|yarn|bun) run (?:format|fmt)\b/, "format"],
+    [/^(?:npm|pnpm|yarn|bun) run (?:typecheck|type-check)\b/, "typecheck"],
+    [/^(?:\.[\\/])?mvnw(?:\.cmd)?\b.*\b(?:verify|test)\b/, "test"],
+    [/^(?:\.[\\/])?mvnw(?:\.cmd)?\b.*\bpackage\b/, "build"],
+    [/^(?:\.[\\/])?gradlew(?:\.bat)?\b.*\b(?:check|test)\b/, "test"],
+    [/^(?:\.[\\/])?gradlew(?:\.bat)?\b.*\b(?:build|assemble)\b/, "build"],
+    [/^uv run\b.*\b(?:pytest|tox(?:\s+run)?)\b/, "test"],
+    [/^poetry run\b.*\b(?:pytest|tox)\b/, "test"],
+    [/^pytest\b/, "test"],
+    [/^tox(?:\s+run)?\b/, "test"],
+    [/^cargo test\b/, "test"],
+    [/^go test\b/, "test"],
+];
+function fromCi(ciCommands) {
+    const found = [];
+    for (const ci of ciCommands) {
+        for (const [pattern, kind] of CI_PATTERNS) {
+            if (!pattern.test(ci.command))
+                continue;
+            if (found.some((c) => c.kind === kind))
+                break;
+            found.push({
+                kind,
+                command: ci.command,
+                source: `ci: ${ci.workflow}`,
+                confidence: "high",
+                scope: ".",
+            });
+            break;
+        }
+    }
+    return found;
+}
+function fromSignals(signals) {
+    const out = [];
+    if (signals.pomXml) {
+        const unixWrapper = signals.hasFile("mvnw");
+        const windowsWrapper = !unixWrapper && signals.hasFile("mvnw.cmd");
+        const hasWrapper = unixWrapper || windowsWrapper;
+        out.push({
+            kind: "test",
+            command: unixWrapper ? "./mvnw test" : windowsWrapper ? "mvnw.cmd test" : "mvn test",
+            source: unixWrapper ? "mvnw" : windowsWrapper ? "mvnw.cmd" : "pom.xml",
+            confidence: hasWrapper ? "high" : "low",
+            scope: ".",
+        });
+    }
+    else if (signals.buildGradle) {
+        const unixWrapper = signals.hasFile("gradlew");
+        const windowsWrapper = !unixWrapper && signals.hasFile("gradlew.bat");
+        const hasWrapper = unixWrapper || windowsWrapper;
+        out.push({
+            kind: "test",
+            command: unixWrapper ? "./gradlew test" : windowsWrapper ? "gradlew.bat test" : "gradle test",
+            source: unixWrapper ? "gradlew" : windowsWrapper ? "gradlew.bat" : "build.gradle",
+            confidence: hasWrapper ? "high" : "low",
+            scope: ".",
+        });
+    }
+    const pythonManifest = signals.pyprojectToml ?? signals.requirementsTxt ?? signals.environmentYml;
+    const hasPytest = pythonManifest !== undefined && /\bpytest\b/i.test(pythonManifest);
+    if (signals.toxIni) {
+        out.push({ kind: "test", command: "tox", source: "tox.ini", confidence: "high", scope: "." });
+    }
+    else if (hasPytest && signals.hasFile("uv.lock")) {
+        // El lock demuestra el gestor, no que pytest pertenezca a un grupo instalado por defecto.
+        out.push({ kind: "test", command: "uv run pytest", source: "uv.lock", confidence: "low", scope: "." });
+    }
+    else if (hasPytest && signals.hasFile("poetry.lock")) {
+        out.push({ kind: "test", command: "poetry run pytest", source: "poetry.lock", confidence: "low", scope: "." });
+    }
+    else if (hasPytest) {
+        const source = signals.pyprojectToml
+            ? "pyproject.toml"
+            : signals.requirementsTxt
+                ? "requirements.txt"
+                : "environment.yml";
+        out.push({ kind: "test", command: "pytest", source, confidence: "low", scope: "." });
+    }
+    return out;
+}
+export function selectCanonicalCommands(signals, commands, ciCommands) {
+    const byKind = new Map();
+    for (const candidate of [...fromScripts(commands), ...fromCi(ciCommands), ...fromSignals(signals)]) {
+        if (!byKind.has(candidate.kind))
+            byKind.set(candidate.kind, candidate);
+    }
+    return KIND_ORDER.flatMap((kind) => byKind.get(kind) ?? []);
+}
+export function canonicalOf(ctx, kind, family) {
+    if (family && ctx?.signals) {
+        return selectCanonicalForFamily({ ...ctx, signals: ctx.signals }, family).find((c) => c.kind === kind && c.confidence === "high");
+    }
+    return ctx?.facts.canonical.find((c) => c.kind === kind && c.confidence === "high");
+}
+function selectCanonicalForFamily(ctx, family) {
+    const jsSources = new Set(["npm", "pnpm", "yarn", "bun"]);
+    const commands = ctx.facts.commands.filter((command) => family === "js-ts" ? jsSources.has(command.source) : family === "python" ? command.source === "tox" : false);
+    const ciCommands = ctx.facts.ciCommands.filter(({ command }) => {
+        if (family === "js-ts")
+            return /^(?:npm|pnpm|yarn|bun)\b/.test(command);
+        if (family === "python")
+            return /^(?:uv|poetry|pytest|tox)\b/.test(command);
+        return /^(?:\.[\\/])?(?:mvnw(?:\.cmd)?|gradlew(?:\.bat)?)\b|^(?:mvn|gradle)\b/.test(command);
+    });
+    const signals = {
+        ...ctx.signals,
+        packageJson: family === "js-ts" ? ctx.signals.packageJson : undefined,
+        packageJsons: family === "js-ts" ? ctx.signals.packageJsons : undefined,
+        pyprojectToml: family === "python" ? ctx.signals.pyprojectToml : undefined,
+        requirementsTxt: family === "python" ? ctx.signals.requirementsTxt : undefined,
+        environmentYml: family === "python" ? ctx.signals.environmentYml : undefined,
+        toxIni: family === "python" ? ctx.signals.toxIni : undefined,
+        pomXml: family === "java" ? ctx.signals.pomXml : undefined,
+        buildGradle: family === "java" ? ctx.signals.buildGradle : undefined,
+    };
+    return selectCanonicalCommands(signals, commands, ciCommands);
+}