agent-rules-init 0.2.1 → 0.4.0

package/dist/core/scanner.js

@@ -1,6 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
-const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".venv", "__pycache__"]);
+const IGNORED_DIRS = new Set([
+    "node_modules", ".git", ".hg", ".svn",
+    "dist", "build", "out", "target", "coverage", "vendor",
+    ".venv", "venv", ".tox", "__pycache__",
+    ".next", ".nuxt", ".svelte-kit", ".turbo", ".cache",
+    ".gradle", ".dart_tool",
+]);
 const MAX_DEPTH = 4;
 function walk(rootPath) {
     const results = [];
@@ -14,6 +20,9 @@ function walk(rootPath) {
         catch {
             return;
         }
+        // Filesystem enumeration order is not guaranteed. Keep discovery stable so
+        // precedence-sensitive facts (for example, the first CI command) are reproducible.
+        entries.sort((a, b) => a.name.localeCompare(b.name));
         for (const entry of entries) {
             if (entry.isDirectory()) {
                 if (IGNORED_DIRS.has(entry.name))
@@ -21,6 +30,8 @@ function walk(rootPath) {
                 recurse(path.join(dir, entry.name), depth + 1);
             }
             else {
+                if (entry.name.includes(".generated."))
+                    continue;
                 results.push(path.relative(rootPath, path.join(dir, entry.name)));
             }
         }
@@ -28,21 +39,76 @@ function walk(rootPath) {
     recurse(rootPath, 0);
     return results;
 }
+// Windows editors (Notepad, PowerShell's Set-Content, some IDE defaults) save UTF-8
+// with a leading BOM, which JSON.parse rejects and line-anchored regexes trip over.
+function stripBom(content) {
+    return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+}
 function readJsonIfExists(filePath) {
     if (!fs.existsSync(filePath))
         return undefined;
     try {
-        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return JSON.parse(stripBom(fs.readFileSync(filePath, "utf-8")));
     }
     catch {
         return undefined;
     }
 }
+function toPackageJsonManifest(raw, relativePath) {
+    return {
+        path: relativePath.split(path.sep).join("/"),
+        name: raw.name,
+        main: typeof raw.main === "string" ? raw.main : undefined,
+        dependencies: raw.dependencies ?? {},
+        devDependencies: raw.devDependencies ?? {},
+        scripts: raw.scripts ?? {},
+        moduleType: raw.type === "module" ? "module" : "commonjs",
+        packageManager: parsePackageManager(raw.packageManager),
+    };
+}
+function parsePackageManager(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const name = value.trim().split("@")[0].toLowerCase();
+    return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun" ? name : undefined;
+}
+const LOCK_MANAGERS = {
+    "package-lock.json": "npm",
+    "npm-shrinkwrap.json": "npm",
+    "pnpm-lock.yaml": "pnpm",
+    "yarn.lock": "yarn",
+    "bun.lock": "bun",
+    "bun.lockb": "bun",
+};
+function managerFromClosestLock(manifestPath, normalizedFiles) {
+    let dir = path.posix.dirname(manifestPath.split(path.sep).join("/"));
+    while (true) {
+        for (const [lockName, manager] of Object.entries(LOCK_MANAGERS)) {
+            const candidate = dir === "." ? lockName : `${dir}/${lockName}`;
+            if (normalizedFiles.has(candidate))
+                return manager;
+        }
+        if (dir === ".")
+            return undefined;
+        dir = path.posix.dirname(dir);
+    }
+}
+function managerFromClosestDeclaration(manifestPath, declarations) {
+    let dir = path.posix.dirname(manifestPath);
+    while (true) {
+        const manager = declarations.get(dir);
+        if (manager)
+            return manager;
+        if (dir === ".")
+            return undefined;
+        dir = path.posix.dirname(dir);
+    }
+}
 function readTextIfExists(filePath) {
     if (!fs.existsSync(filePath))
         return undefined;
     try {
-        return fs.readFileSync(filePath, "utf-8");
+        return stripBom(fs.readFileSync(filePath, "utf-8"));
     }
     catch {
         return undefined;
@@ -71,6 +137,8 @@ const NON_PROJECT_DIRS = new Set([
     "example",
     "benchmark",
     "benchmarks",
+    "fixture",
+    "fixtures",
 ]);
 function isUnderNonProjectDir(relativePath) {
     const segments = relativePath.split(path.sep).slice(0, -1);
@@ -100,17 +168,45 @@ function pickShallowest(paths) {
 export function scanRepo(rootPath) {
     const files = walk(rootPath);
     const fileSet = new Set(files.map((f) => f.split(path.sep).join("/")));
-    const packageJsonPath = findFirst(files, "package.json");
-    const rawPackageJson = packageJsonPath
-        ? readJsonIfExists(path.join(rootPath, packageJsonPath))
-        : undefined;
-    const packageJson = rawPackageJson
+    // Keep every project package manifest, not only the root workspace manifest. Root
+    // package.json files are often workspace glue and contain none of the dependencies
+    // that reveal React/Vitest/etc. Manifests under docs/examples/tooling are excluded to
+    // avoid treating auxiliary demos, fixtures and documentation builds as the project.
+    const packageJsonPaths = files.filter((f) => path.basename(f) === "package.json" && !isUnderNonProjectDir(f));
+    const packageJsons = packageJsonPaths
+        .map((relativePath) => {
+        const raw = readJsonIfExists(path.join(rootPath, relativePath));
+        return raw ? toPackageJsonManifest(raw, relativePath) : undefined;
+    })
+        .filter((manifest) => manifest !== undefined)
+        .sort((a, b) => {
+        const depth = a.path.split("/").length - b.path.split("/").length;
+        return depth || a.path.localeCompare(b.path);
+    });
+    const declaredManagers = new Map(packageJsons
+        .filter((manifest) => manifest.packageManager !== undefined)
+        .map((manifest) => [path.posix.dirname(manifest.path), manifest.packageManager]));
+    // A nested lock takes precedence over an ancestor workspace declaration because it
+    // denotes an independently installed package. Both lookups are O(path depth).
+    for (const manifest of packageJsons) {
+        if (manifest.packageManager)
+            continue;
+        manifest.packageManager =
+            managerFromClosestLock(manifest.path, fileSet) ??
+                managerFromClosestDeclaration(manifest.path, declaredManagers);
+    }
+    const primaryPackageJson = packageJsons[0];
+    const packageJson = primaryPackageJson
         ? {
-            name: rawPackageJson.name,
-            dependencies: rawPackageJson.dependencies ?? {},
-            devDependencies: rawPackageJson.devDependencies ?? {},
-            scripts: rawPackageJson.scripts ?? {},
-            moduleType: rawPackageJson.type === "module" ? "module" : "commonjs",
+            name: primaryPackageJson.name,
+            dependencies: Object.assign({}, ...packageJsons.map((p) => p.dependencies)),
+            devDependencies: Object.assign({}, ...packageJsons.map((p) => p.devDependencies)),
+            // Root scripts remain the default command surface. Repo facts reads packageJsons
+            // directly and adds executable --prefix commands for nested packages.
+            scripts: primaryPackageJson.scripts,
+            moduleType: primaryPackageJson.moduleType,
+            packageManager: primaryPackageJson.packageManager,
+            main: primaryPackageJson.main,
         }
         : undefined;
     const composerJsonPath = findFirst(files, "composer.json");
@@ -121,6 +217,7 @@ export function scanRepo(rootPath) {
         ? {
             require: rawComposerJson.require ?? {},
             requireDev: rawComposerJson["require-dev"] ?? {},
+            scripts: rawComposerJson.scripts ?? {},
         }
         : undefined;
     const pyprojectCandidate = findFirstPreferringRealProjectDirs(files, "pyproject.toml");
@@ -141,27 +238,45 @@ export function scanRepo(rootPath) {
     // Multi-module Maven/Gradle projects (parent + child modules) each have their own
     // pom.xml/build.gradle, and the module that actually declares the framework/Kotlin
     // plugin/test runner isn't necessarily the shallowest one. Aggregate all of them.
-    const pomPaths = findAllByNames(files, ["pom.xml"]);
-    const buildGradlePaths = findAllByNames(files, ["build.gradle", "build.gradle.kts"]);
-    const gemfilePath = findFirst(files, "Gemfile");
-    const goModPath = findFirst(files, "go.mod");
-    const cargoTomlPath = findFirst(files, "Cargo.toml");
+    const projectFiles = files.filter((file) => !isUnderNonProjectDir(file));
+    const pomPaths = findAllByNames(projectFiles, ["pom.xml"]);
+    const buildGradlePaths = findAllByNames(projectFiles, ["build.gradle", "build.gradle.kts"]);
+    const gemfilePath = findFirst(projectFiles, "Gemfile");
+    const goModPath = findFirst(projectFiles, "go.mod");
+    const cargoTomlPath = findFirst(projectFiles, "Cargo.toml");
     // .NET solutions routinely split into several .csproj files (domain/infra/web/tests);
     // picking just the "shallowest" one is close to arbitrary and often lands on a plain
     // class library that has neither the web framework nor the test runner reference.
     // Concatenate all of them so detection can find those references wherever they live.
-    const csprojPaths = findAllByExtension(files, ".csproj");
-    const packageSwiftPath = findFirst(files, "Package.swift");
+    const csprojPaths = findAllByExtension(projectFiles, ".csproj");
+    const packageSwiftPath = findFirst(projectFiles, "Package.swift");
     // Melos/pub workspaces have a root pubspec.yaml that's just workspace glue (no
     // `flutter`/`flutter_test` dependency) plus one real pubspec.yaml per package under
     // packages/*. Aggregate all of them so the actual framework/test runner is found.
-    const pubspecYamlPaths = findAllByNames(files, ["pubspec.yaml"]);
-    const cmakeListsPath = findFirst(files, "CMakeLists.txt");
-    const makefilePath = findFirst(files, "Makefile") ?? findFirst(files, "makefile");
-    const mixExsPath = findFirst(files, "mix.exs");
-    const buildSbtPath = findFirst(files, "build.sbt");
-    const rDescriptionPath = findFirst(files, "DESCRIPTION");
-    const renvLockPath = findFirst(files, "renv.lock");
+    const pubspecYamlPaths = findAllByNames(projectFiles, ["pubspec.yaml"]);
+    const cmakeListsPath = findFirst(projectFiles, "CMakeLists.txt");
+    // Un Makefile que solo existe bajo docs/, tools/, etc. es tooling auxiliar (p. ej. el
+    // Makefile de Sphinx en docs/ de Flask): sus targets no se pueden ejecutar desde la
+    // raíz y no describen el proyecto. Mismo criterio que los manifiestos Python.
+    const makefilePath = findFirstPreferringRealProjectDirs(files, "Makefile") ??
+        findFirstPreferringRealProjectDirs(files, "makefile");
+    const mixExsPath = findFirst(projectFiles, "mix.exs");
+    const buildSbtPath = findFirst(projectFiles, "build.sbt");
+    const rDescriptionPath = findFirst(projectFiles, "DESCRIPTION");
+    const renvLockPath = findFirst(projectFiles, "renv.lock");
+    const toxIniPath = findFirst(projectFiles, "tox.ini");
+    const workflowPaths = files.filter((f) => {
+        const normalized = f.split(path.sep).join("/");
+        return (normalized.startsWith(".github/workflows/") &&
+            (normalized.endsWith(".yml") || normalized.endsWith(".yaml")));
+    });
+    const guidanceNames = new Set([
+        "CONTRIBUTING.md", ".editorconfig", "tsconfig.json", "pyproject.toml",
+    ]);
+    const guidancePaths = files.filter((file) => {
+        const normalized = file.split(path.sep).join("/");
+        return guidanceNames.has(path.posix.basename(normalized));
+    });
     return {
         rootPath,
         files,
@@ -169,6 +284,7 @@ export function scanRepo(rootPath) {
         hasDir: (relativeDir) => fs.existsSync(path.join(rootPath, relativeDir)) &&
             fs.statSync(path.join(rootPath, relativeDir)).isDirectory(),
         packageJson,
+        packageJsons,
         pyprojectToml: pyprojectPath ? readTextIfExists(path.join(rootPath, pyprojectPath)) : undefined,
         requirementsTxt: requirementsPath
             ? readTextIfExists(path.join(rootPath, requirementsPath))
@@ -191,5 +307,15 @@ export function scanRepo(rootPath) {
         buildSbt: buildSbtPath ? readTextIfExists(path.join(rootPath, buildSbtPath)) : undefined,
         rDescription: rDescriptionPath ? readTextIfExists(path.join(rootPath, rDescriptionPath)) : undefined,
         renvLock: renvLockPath ? readTextIfExists(path.join(rootPath, renvLockPath)) : undefined,
+        toxIni: toxIniPath ? readTextIfExists(path.join(rootPath, toxIniPath)) : undefined,
+        githubWorkflows: workflowPaths
+            .map((p) => ({
+            path: p.split(path.sep).join("/"),
+            content: readTextIfExists(path.join(rootPath, p)),
+        }))
+            .filter((w) => w.content !== undefined),
+        guidanceFiles: guidancePaths
+            .map((p) => ({ path: p.split(path.sep).join("/"), content: readTextIfExists(path.join(rootPath, p)) }))
+            .filter((f) => f.content !== undefined),
     };
 }

package/dist/core/templates.d.ts

@@ -1,11 +1,13 @@
-import type { DetectionResult, PromptTemplate, RuleSet } from "./types.js";
+import { type Lang } from "./i18n.js";
+import type { DetectionResult, PromptTemplate, RepoFacts, RuleSet } from "./types.js";
 export interface RenderEntry {
     detection: DetectionResult;
     ruleSet: RuleSet;
 }
-export declare function renderClaudeMd(entries: RenderEntry[]): string;
-export declare function renderAgentsMd(entries: RenderEntry[]): string;
-export declare function renderCopilotInstructions(entries: RenderEntry[]): string;
+export declare function renderRepoFacts(facts: RepoFacts, lang: Lang): string;
+export declare function renderClaudeMd(entries: RenderEntry[], facts: RepoFacts | undefined, lang: Lang): string;
+export declare function renderAgentsMd(entries: RenderEntry[], facts: RepoFacts | undefined, lang: Lang): string;
+export declare function renderCopilotInstructions(entries: RenderEntry[], facts: RepoFacts | undefined, lang: Lang): string;
 export declare function renderPromptFiles(packId: string, templates: PromptTemplate[]): {
     path: string;
     content: string;

package/dist/core/templates.js

@@ -1,49 +1,147 @@
-function renderSection(entries) {
+import { UI } from "./i18n.js";
+import { SOURCE_FILES } from "./canonical-commands.js";
+function renderSection(entries, lang, options = {}) {
+    const ui = UI[lang];
+    const { summaries = true } = options;
     return entries
         .map(({ detection, ruleSet }) => {
-        const conventions = ruleSet.conventions.map((c) => `- ${c}`).join("\n");
+        const conventionItems = options.operationalConventions === false
+            ? ruleSet.conventions.filter((item) => !/^(?:Run the tests|Run the repository|Ejecuta los tests|Ejecuta la suite)/i.test(item))
+            : ruleSet.conventions;
+        const conventions = conventionItems.map((c) => `- ${c}`).join("\n");
         const architecture = ruleSet.architectureNotes.map((a) => `- ${a}`).join("\n");
-        return [
+        const parts = [
             `## ${detection.language} (${detection.packId})`,
-            "",
-            ruleSet.summary,
-            "",
-            "### Convenciones",
-            conventions,
-            "",
-            "### Arquitectura",
-            architecture,
-        ].join("\n");
+        ];
+        if (summaries)
+            parts.push("", ruleSet.summary);
+        if (options.conventions !== false && conventions)
+            parts.push("", `### ${ui.sections.conventions}`, conventions);
+        if (options.architecture !== false && architecture)
+            parts.push("", `### ${ui.sections.architecture}`, architecture);
+        return parts.join("\n");
     })
         .join("\n\n");
 }
-export function renderClaudeMd(entries) {
-    return [
-        "# CLAUDE.md",
-        "",
-        "Generado por agent-rules-init a partir de lo detectado en este repo.",
-        "",
-        renderSection(entries),
-    ].join("\n");
+function evidenceLabel(lang) {
+    return lang === "es" ? "evidencia" : "evidence";
+}
+function renderEvidenceSection(title, facts, lang) {
+    const high = facts.filter((fact) => fact.confidence === "high");
+    if (high.length === 0)
+        return "";
+    const lines = high.map((fact) => `- ${fact.statement} (${evidenceLabel(lang)}: ${fact.evidence.map((item) => `\`${item}\``).join(", ")})`);
+    return [`## ${title}`, "", ...lines].join("\n");
+}
+function architectureFactsTitle(lang) {
+    return lang === "es" ? "Arquitectura observada" : "Observed architecture";
 }
-export function renderAgentsMd(entries) {
+function localConventionsTitle(lang) {
+    return lang === "es" ? "Convenciones locales verificadas" : "Verified local conventions";
+}
+function renderCanonical(facts, lang) {
+    const commands = facts.canonical.filter((command) => command.confidence === "high");
+    if (commands.length === 0)
+        return "";
     return [
-        "# AGENTS.md",
-        "",
-        "Generado por agent-rules-init a partir de lo detectado en este repo.",
+        `## ${UI[lang].sections.canonical}`,
         "",
-        renderSection(entries),
+        ...commands.map((command) => `- ${command.kind}: \`${command.command}\` (${command.source})`),
     ].join("\n");
 }
-export function renderCopilotInstructions(entries) {
+export function renderRepoFacts(facts, lang) {
+    const ui = UI[lang];
+    const sections = [];
+    const canonical = facts.canonical.filter((c) => c.confidence === "high");
+    if (canonical.length > 0) {
+        const lines = canonical.map((c) => `- ${c.kind}: \`${c.command}\` (${c.source})`);
+        sections.push([`## ${ui.sections.canonical}`, "", ...lines].join("\n"));
+    }
+    if (facts.commands.length > 0) {
+        const lines = facts.commands.map((c) => {
+            const sourceFile = c.manifestPath ?? SOURCE_FILES[c.source];
+            return c.detail && c.detail !== c.invocation
+                ? `- \`${c.invocation}\` → \`${c.detail}\` (${sourceFile})`
+                : `- \`${c.invocation}\` (${sourceFile})`;
+        });
+        for (const o of facts.omittedCommands)
+            lines.push(`- ${ui.andMore(o.count, SOURCE_FILES[o.source])}`);
+        sections.push([`## ${ui.sections.commands}`, "", ...lines].join("\n"));
+    }
+    if (facts.structure.length > 0 || facts.testDirs.length > 0 || facts.entrypoints.length > 0) {
+        const lines = facts.structure.map((d) => (d.note ? `- \`${d.dir}\` — ${d.note}` : `- \`${d.dir}\``));
+        for (const dir of facts.testDirs) {
+            if (!facts.structure.some((d) => d.dir === dir))
+                lines.push(`- \`${dir}\` — ${ui.testDirNote}`);
+        }
+        for (const entry of facts.entrypoints) {
+            lines.push(`- ${ui.entrypointNote}: \`${entry.target}\` (${entry.source} "${entry.label}")`);
+        }
+        sections.push([`## ${ui.sections.structure}`, "", ...lines].join("\n"));
+    }
+    if (facts.ciCommands.length > 0) {
+        const lines = facts.ciCommands.map((c) => `- \`${c.command}\` (${c.workflow})`);
+        if (facts.omittedCiCount > 0)
+            lines.push(`- ${ui.andMore(facts.omittedCiCount)}`);
+        sections.push([`## ${ui.sections.ci}`, "", ...lines].join("\n"));
+    }
+    const architecture = renderEvidenceSection(architectureFactsTitle(lang), facts.architectureFacts ?? [], lang);
+    if (architecture)
+        sections.push(architecture);
+    const conventions = renderEvidenceSection(localConventionsTitle(lang), facts.conventionFacts ?? [], lang);
+    if (conventions)
+        sections.push(conventions);
+    return sections.join("\n\n");
+}
+function renderDocument(title, entries, facts, lang) {
+    const factsBlock = facts ? renderRepoFacts(facts, lang) : "";
     return [
-        "# Copilot Instructions",
+        title,
         "",
-        "Generado por agent-rules-init a partir de lo detectado en este repo.",
+        UI[lang].generatedHeader,
         "",
-        renderSection(entries),
+        renderSection(entries, lang, { architecture: !(facts?.architectureFacts?.length) }),
+        ...(factsBlock ? ["", factsBlock] : []),
     ].join("\n");
 }
+export function renderClaudeMd(entries, facts, lang) {
+    return renderDocument("# CLAUDE.md", entries, facts, lang);
+}
+export function renderAgentsMd(entries, facts, lang) {
+    const intro = lang === "es"
+        ? "Reglas operativas para modificar este repositorio. Respeta el alcance y valida los cambios con los comandos indicados."
+        : "Operational rules for modifying this repository. Respect scope and validate changes with the commands below.";
+    const blocks = [
+        "# AGENTS.md", "", UI[lang].generatedHeader, "", intro, "",
+        renderSection(entries, lang, { architecture: !(facts?.architectureFacts?.length) }),
+    ];
+    if (facts) {
+        const canonical = renderCanonical(facts, lang);
+        const architecture = renderEvidenceSection(architectureFactsTitle(lang), facts.architectureFacts ?? [], lang);
+        const conventions = renderEvidenceSection(localConventionsTitle(lang), facts.conventionFacts ?? [], lang);
+        for (const block of [canonical, architecture, conventions])
+            if (block)
+                blocks.push("", block);
+    }
+    return blocks.join("\n");
+}
+export function renderCopilotInstructions(entries, facts, lang) {
+    const intro = lang === "es"
+        ? "Aplica estas convenciones al completar y modificar código. Omite tareas operativas de terminal salvo que sean necesarias para el cambio."
+        : "Apply these conventions when completing and modifying code. Omit terminal operations unless the change requires them.";
+    const blocks = [
+        "# Copilot Instructions", "", UI[lang].generatedHeader, "", intro, "",
+        renderSection(entries, lang, { architecture: false, operationalConventions: false }),
+    ];
+    if (facts) {
+        const conventions = renderEvidenceSection(localConventionsTitle(lang), facts.conventionFacts ?? [], lang);
+        const architecture = renderEvidenceSection(architectureFactsTitle(lang), facts.architectureFacts ?? [], lang);
+        for (const block of [conventions, architecture])
+            if (block)
+                blocks.push("", block);
+    }
+    return blocks.join("\n");
+}
 export function renderPromptFiles(packId, templates) {
     return templates.flatMap((template) => [
         {

package/dist/core/types.d.ts

@@ -1,13 +1,22 @@
+import type { Lang } from "./i18n.js";
+export type JsPackageManager = "npm" | "pnpm" | "yarn" | "bun";
 export interface PackageJsonManifest {
     name?: string;
+    main?: string;
     dependencies: Record<string, string>;
     devDependencies: Record<string, string>;
     scripts: Record<string, string>;
     moduleType: "module" | "commonjs";
+    /** Gestor aplicable al manifiesto, declarado en packageManager o inferido por el lock más cercano. */
+    packageManager?: JsPackageManager;
+}
+export interface LocatedPackageJsonManifest extends PackageJsonManifest {
+    path: string;
 }
 export interface ComposerJsonManifest {
     require: Record<string, string>;
     requireDev: Record<string, string>;
+    scripts?: Record<string, unknown>;
 }
 export interface RepoSignals {
     rootPath: string;
@@ -15,6 +24,7 @@ export interface RepoSignals {
     hasFile: (relativePath: string) => boolean;
     hasDir: (relativeDir: string) => boolean;
     packageJson?: PackageJsonManifest;
+    packageJsons?: LocatedPackageJsonManifest[];
     pyprojectToml?: string;
     requirementsTxt?: string;
     environmentYml?: string;
@@ -33,6 +43,16 @@ export interface RepoSignals {
     buildSbt?: string;
     rDescription?: string;
     renvLock?: string;
+    toxIni?: string;
+    githubWorkflows?: {
+        path: string;
+        content: string;
+    }[];
+    /** Archivos locales de guía/configuración seleccionados de forma conservadora. */
+    guidanceFiles?: {
+        path: string;
+        content: string;
+    }[];
 }
 export type Confidence = "high" | "low";
 export interface DetectionField<T> {
@@ -46,6 +66,8 @@ export interface DetectionResult {
     packageManager?: DetectionField<string>;
     testRunner?: DetectionField<string>;
     linter?: DetectionField<string>;
+    /** Framework implementado por el propio repositorio; no implica una dependencia. */
+    frameworkSource?: string;
     usesTypeScript?: boolean;
     moduleFormat?: "module" | "commonjs";
 }
@@ -59,9 +81,69 @@ export interface PromptTemplate {
     title: string;
     body: string;
 }
+export type CommandSource = JsPackageManager | "composer" | "make" | "mix" | "tox";
+export interface CommandEntry {
+    source: CommandSource;
+    invocation: string;
+    detail?: string;
+    manifestPath?: string;
+}
+export interface DirEntry {
+    dir: string;
+    note?: string;
+}
+export interface CiCommand {
+    command: string;
+    workflow: string;
+}
+export interface CanonicalCommand {
+    kind: "test" | "lint" | "build" | "format" | "typecheck";
+    command: string;
+    /** Archivo o señal del que procede el comando, p. ej. `package.json`, `ci: ci.yml`, `mvnw`. */
+    source: string;
+    confidence: Confidence;
+    /** "." para la raíz del repo; ruta del workspace para unidades anidadas. */
+    scope: string;
+}
+export interface EvidenceFact {
+    statement: string;
+    evidence: string[];
+    scope: string;
+    confidence: Confidence;
+}
+export interface ArchitectureFact extends EvidenceFact {
+    kind: "entrypoint" | "tests" | "layers" | "workspace" | "source-layout";
+}
+export interface ConventionFact extends EvidenceFact {
+    kind: "formatting" | "typescript" | "python-style" | "contributing";
+}
+export interface RepoFacts {
+    commands: CommandEntry[];
+    omittedCommands: {
+        source: CommandSource;
+        count: number;
+    }[];
+    structure: DirEntry[];
+    ciCommands: CiCommand[];
+    omittedCiCount: number;
+    canonical: CanonicalCommand[];
+    testDirs: string[];
+    entrypoints: {
+        label: string;
+        target: string;
+        source: string;
+    }[];
+    architectureFacts: ArchitectureFact[];
+    conventionFacts: ConventionFact[];
+}
+export interface PackContext {
+    facts: RepoFacts;
+    /** Señales del mismo alcance que facts; permite evitar canónicos de otro stack. */
+    signals?: RepoSignals;
+}
 export interface Pack {
     id: string;
     detect(signals: RepoSignals): DetectionResult | null;
-    rules(detection: DetectionResult): RuleSet;
-    promptTemplates(detection: DetectionResult): PromptTemplate[];
+    rules(detection: DetectionResult, lang: Lang, ctx?: PackContext): RuleSet;
+    promptTemplates(detection: DetectionResult, lang: Lang, ctx?: PackContext): PromptTemplate[];
 }

package/dist/core/writer.d.ts

@@ -4,7 +4,7 @@ export interface GeneratedFile {
 }
 export interface WriteResult {
     path: string;
-    status: "written" | "error";
+    status: "written" | "skipped" | "error";
     error?: string;
 }
 export declare function writeGeneratedFiles(rootPath: string, files: GeneratedFile[]): WriteResult[];

package/dist/core/writer.js

@@ -4,14 +4,16 @@ export function writeGeneratedFiles(rootPath, files) {
     return files.map(({ path: relativePath, content }) => {
         const absolutePath = path.join(rootPath, relativePath);
         try {
-            if (fs.existsSync(absolutePath)) {
-                return { path: relativePath, status: "error", error: "file already exists" };
-            }
             fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-            fs.writeFileSync(absolutePath, content);
+            // `wx` makes the no-overwrite guarantee atomic: even if another process creates
+            // the file between directory creation and this call, Node returns EEXIST.
+            fs.writeFileSync(absolutePath, content, { flag: "wx" });
             return { path: relativePath, status: "written" };
         }
         catch (err) {
+            if (err.code === "EEXIST") {
+                return { path: relativePath, status: "skipped" };
+            }
             return { path: relativePath, status: "error", error: err.message };
         }
     });