agent-rules-init 0.2.1 → 0.4.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,10 +1,47 @@
-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 { 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 polishing. */
+    nonInteractive?: boolean;
+    /** 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 interface CliRunOptions {
+    lang?: Lang;
+    dryRun?: true;
+    check?: true;
+    json?: true;
+    nonInteractive?: true;
+}
+export type CliAction = ({
+    kind: "run";
+} & CliRunOptions) | {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "invalid-lang";
+    value: 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

@@ -1,9 +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, } from "./core/templates.js";
-import { collectLowConfidenceQuestions, askQuestions, applyAnswers, defaultPromptFn, hasInteractiveTty, } from "./core/prompt-engine.js";
-import { detectAvailableAssistants, polishWithAssistant, defaultExecFn } from "./core/llm-bridge.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, polishFilesWithAssistant, 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";
@@ -37,87 +45,242 @@ const ALL_PACKS = [
     rPack,
 ];
 export async function runCli(rootPath, options = {}) {
-    const promptFn = options.promptFn ?? defaultPromptFn;
+    const loadedConfig = options.config ? { config: options.config, warnings: [] } : loadConfig(rootPath);
+    const config = loadedConfig.config;
+    options.onConfigWarnings?.(loadedConfig.warnings);
     const execFn = options.execFn ?? defaultExecFn;
-    const signals = scanRepo(rootPath);
+    const lang = options.lang ?? config.lang ?? detectLang();
+    const promptFn = options.promptFn ?? makeDefaultPromptFn(lang);
+    const ui = UI[lang];
+    const signals = applyProjectExcludes(scanRepo(rootPath), config.exclude ?? []);
     const rawDetections = ALL_PACKS.map((pack) => pack.detect(signals)).filter((d) => d !== null);
-    const questions = collectLowConfidenceQuestions(rawDetections);
-    const answers = await askQuestions(questions, promptFn);
+    const questions = collectLowConfidenceQuestions(rawDetections, lang);
+    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) };
+        return { detection, ruleSet: pack.rules(detection, lang, ctx) };
     });
     const files = [];
     if (entries.length > 0) {
-        files.push({ path: "CLAUDE.generated.md", content: renderClaudeMd(entries) });
-        files.push({ path: "AGENTS.generated.md", content: renderAgentsMd(entries) });
+        files.push({ path: "CLAUDE.generated.md", content: renderClaudeMd(entries, facts, lang) });
+        files.push({ path: "AGENTS.generated.md", content: renderAgentsMd(entries, facts, lang) });
         files.push({
             path: ".github/copilot-instructions.generated.md",
-            content: renderCopilotInstructions(entries),
+            content: renderCopilotInstructions(entries, facts, lang),
         });
         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))) {
+            for (const file of renderPromptFiles(detection.packId, pack.promptTemplates(detection, lang, ctx))) {
                 files.push(file);
             }
         }
     }
     else {
-        files.push({
-            path: "CLAUDE.generated.md",
-            content: "# CLAUDE.md\n\nNo se detectó ningún stack conocido. Completa este archivo manualmente.\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);
+    }
+    if (!options.skipLlm && !config.noAi && !options.nonInteractive && hasInteractiveTty()) {
         const assistants = await detectAvailableAssistants(execFn);
         if (assistants.length > 0) {
             const chosenAssistant = assistants[0];
-            clack.log.info(`${chosenAssistant} detectado — puede ayudar a pulir la redacción final.`);
-            const usePolish = await clack.confirm({
-                message: `Se detectó ${chosenAssistant}. ¿Quieres que pula la redacción final?`,
-            });
+            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);
-                }
+                const polished = await polishFilesWithAssistant(chosenAssistant, files, execFn, lang);
+                files.splice(0, files.length, ...polished);
             }
         }
     }
+    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";
+}
+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 === "--check") {
+            options.check = true;
+            continue;
+        }
+        if (arg === "--json") {
+            options.json = true;
+            continue;
+        }
+        if (arg === "--non-interactive") {
+            options.nonInteractive = true;
+            continue;
+        }
+        return { kind: "unknown", flag: arg };
+    }
+    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
+    // resolves to packages/cli/package.json in either layout.
+    const pkg = createRequire(import.meta.url)("../package.json");
+    return pkg.version;
+}
 export async function main() {
-    clack.intro("agent-rules-init");
-    if (!hasInteractiveTty()) {
-        console.warn("No se detectó una terminal interactiva (esto pasa a veces en Git Bash en Windows). " +
-            "Continuando sin preguntas ni oferta de pulido con IA; se usarán los valores detectados.");
+    const action = resolveCliAction(process.argv.slice(2));
+    const defaultLang = action.kind === "run" && action.lang ? action.lang : detectLang();
+    let ui = UI[defaultLang];
+    if (action.kind === "help") {
+        console.log(usageWithAutomationOptions(ui));
+        return;
+    }
+    if (action.kind === "version") {
+        console.log(getVersion());
+        return;
+    }
+    if (action.kind === "unknown") {
+        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${usageWithAutomationOptions(ui)}`);
+        process.exitCode = 1;
+        return;
+    }
+    const machineOutput = action.json === true;
+    const planningOnly = action.dryRun === true || action.check === true;
+    const nonInteractive = action.nonInteractive === true || machineOutput || planningOnly;
+    if (!machineOutput)
+        clack.intro("agent-rules-init");
+    if (!machineOutput && !nonInteractive && !hasInteractiveTty()) {
+        console.warn(ui.noTtyWarning);
     }
     try {
-        const results = await runCli(process.cwd());
+        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,
+            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);
+        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.");
         }
-        if (written.length > 0) {
-            clack.outro("Revisa los archivos *.generated.* y, cuando estés conforme, quita el sufijo " +
-                '".generated" (ej. "CLAUDE.generated.md" → "CLAUDE.md") para activarlos — ' +
-                "tu asistente de IA solo lee el nombre final, no el generado.");
+        else if (!machineOutput && action.dryRun) {
+            console.log(`\n${written.length} file(s) would be generated.`);
         }
-        else {
-            clack.outro("No se generó ningún archivo nuevo.");
+        else if (!machineOutput && written.length > 0) {
+            clack.outro(ui.outroWritten);
         }
-        if (failures.length > 0) {
+        else if (!machineOutput) {
+            clack.outro(ui.outroNothing);
+        }
+        if (failures.length > 0 || (action.check && checkIssues > 0)) {
             process.exitCode = 1;
         }
     }
     catch (err) {
-        clack.log.error(`Fallo inesperado: ${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);
+}

package/dist/core/config.d.ts

@@ -0,0 +1,25 @@
+import type { Lang } from "./i18n.js";
+export interface ProjectConfig {
+    framework?: string;
+    testRunner?: string;
+    linter?: string;
+    packageManager?: string;
+}
+export interface AgentRulesConfig {
+    lang?: Lang;
+    exclude?: string[];
+    projects?: Record<string, ProjectConfig>;
+    noAi?: boolean;
+}
+export interface LoadedConfig {
+    config: AgentRulesConfig;
+    /** Absolute path to the selected config file, if one exists. */
+    sourcePath?: string;
+    warnings: string[];
+}
+export declare class ConfigError extends Error {
+    readonly configPath: string;
+    constructor(message: string, configPath: string, options?: ErrorOptions);
+}
+/** Loads and validates the optional repository-local agent-rules configuration. */
+export declare function loadConfig(rootPath: string): LoadedConfig;