agent-rules-init 0.2.0 → 0.3.0

package/dist/core/repo-facts.js

@@ -0,0 +1,198 @@
+import path from "node:path";
+import { parse } from "yaml";
+import { UI } from "./i18n.js";
+const NPM_DIRECT_LIFECYCLE = new Set(["test", "start", "stop", "restart"]);
+export function extractNpmCommands(signals) {
+    const scripts = signals.packageJson?.scripts ?? {};
+    const entries = [];
+    for (const [name, body] of Object.entries(scripts)) {
+        if (typeof body !== "string" || body.trim() === "")
+            continue;
+        entries.push({
+            source: "npm",
+            invocation: NPM_DIRECT_LIFECYCLE.has(name) ? `npm ${name}` : `npm run ${name}`,
+            detail: body.trim(),
+        });
+    }
+    return entries;
+}
+export function extractMakeTargets(signals) {
+    const makefile = signals.makefile;
+    if (!makefile)
+        return [];
+    const targets = new Set();
+    for (const line of makefile.split(/\r?\n/)) {
+        // Un target va a inicio de línea (las recetas van indentadas con tab) y su nombre
+        // no lleva %, ni empieza por "." (targets especiales tipo .PHONY). El (?!=) evita
+        // asignaciones ":=". La clase de caracteres ya excluye espacios, con lo que
+        // "CFLAGS :=", los comentarios "#" y las URLs en comentarios tampoco matchean.
+        const match = /^([A-Za-z0-9_/-][A-Za-z0-9_./-]*)\s*:(?!=)/.exec(line);
+        if (!match)
+            continue;
+        targets.add(match[1]);
+    }
+    return [...targets].map((target) => ({ source: "make", invocation: `make ${target}` }));
+}
+export function extractMixAliases(signals) {
+    const mixExs = signals.mixExs;
+    if (!mixExs)
+        return [];
+    // Cuerpo de la función aliases (defp aliases do ... end). Si no existe con esa
+    // forma, no se emite nada — omitir antes que inventar.
+    const fnMatch = mixExs.match(/defp?\s+aliases\s*(?:\(\))?\s*do([\s\S]*?)\n\s*end/);
+    if (!fnMatch)
+        return [];
+    const body = fnMatch[1];
+    const names = new Set();
+    // Claves del keyword list cuyo valor empieza por lista o string: `setup: [...]`,
+    // `"ecto.setup": [...]`. Un alias con valor función (&fun/1) se omite.
+    for (const match of body.matchAll(/(?:"([^"]+)"|([a-z_][a-zA-Z0-9_.]*)):\s*(?=[["'])/g)) {
+        names.add(match[1] ?? match[2]);
+    }
+    return [...names].map((alias) => ({ source: "mix", invocation: `mix ${alias}` }));
+}
+export function extractToxEnvs(signals) {
+    const toxIni = signals.toxIni;
+    if (!toxIni)
+        return [];
+    const match = toxIni.match(/^[ \t]*env_?list\s*=\s*(.+(?:\n[ \t]+\S.*)*)/m);
+    if (!match)
+        return [];
+    const envs = match[1]
+        .split(/[,\s]+/)
+        .map((env) => env.trim())
+        // Los envs con factores generadores (py3{10,11}) se omiten en vez de expandirlos.
+        // El split por comas los parte en trozos ("py3{10", "11}"), así que basta con
+        // descartar cualquier trozo que contenga una llave.
+        .filter((env) => env !== "" && !env.startsWith("#") && !/[{}]/.test(env));
+    return [...new Set(envs)].map((env) => ({ source: "tox", invocation: `tox -e ${env}` }));
+}
+export function extractComposerCommands(signals) {
+    const scripts = signals.composerJson?.scripts ?? {};
+    const entries = [];
+    for (const [name, raw] of Object.entries(scripts)) {
+        const parts = Array.isArray(raw)
+            ? raw.filter((p) => typeof p === "string")
+            : typeof raw === "string"
+                ? [raw]
+                : [];
+        if (parts.length === 0)
+            continue;
+        entries.push({ source: "composer", invocation: `composer ${name}`, detail: parts.join(" && ") });
+    }
+    return entries;
+}
+const WELL_KNOWN_NAMES = new Set([
+    "test", "tests", "build", "lint", "fmt", "format", "check", "dev", "start",
+    "typecheck", "ci", "coverage", "e2e", "unit", "docs", "clean", "install",
+    "setup", "release", "watch", "fix", "all",
+]);
+const MAX_COMMANDS_PER_SOURCE = 15;
+function invocationName(entry) {
+    const parts = entry.invocation.split(" ");
+    return parts[parts.length - 1];
+}
+export function filterCommands(entries) {
+    const kept = [];
+    const omitted = [];
+    const sources = [...new Set(entries.map((e) => e.source))];
+    for (const source of sources) {
+        const group = entries.filter((e) => e.source === source);
+        const wellKnown = group.filter((e) => WELL_KNOWN_NAMES.has(invocationName(e)));
+        const rest = group.filter((e) => !WELL_KNOWN_NAMES.has(invocationName(e)));
+        const keptGroup = new Set([...wellKnown, ...rest].slice(0, MAX_COMMANDS_PER_SOURCE));
+        // Se emite en el orden original del manifiesto, no con los conocidos primero.
+        kept.push(...group.filter((e) => keptGroup.has(e)));
+        const omittedCount = group.length - keptGroup.size;
+        if (omittedCount > 0)
+            omitted.push({ source, count: omittedCount });
+    }
+    return { kept, omitted };
+}
+const MAX_CI_COMMANDS = 30;
+// Líneas de un script multilínea que son control de flujo del shell, no comandos:
+// `if [[ ... ]]; then`, `else`, `fi`, `for x in ...; do`, `done`, `case`/`esac`...
+const SHELL_CONTROL_FLOW = /^(?:if|elif|else|fi|then|do|done|for|while|until|case|esac)\b|^(?:fi|then|else|done|esac)$/;
+function isShellControlFlow(line) {
+    return SHELL_CONTROL_FLOW.test(line);
+}
+export function extractCiCommands(signals) {
+    const seen = new Map(); // comando -> workflow de origen
+    for (const workflow of signals.githubWorkflows ?? []) {
+        let doc;
+        try {
+            doc = parse(workflow.content);
+        }
+        catch {
+            continue; // YAML inválido: omitir antes que inventar
+        }
+        if (!doc || typeof doc !== "object")
+            continue;
+        const jobs = doc.jobs;
+        if (!jobs || typeof jobs !== "object")
+            continue;
+        const workflowName = workflow.path.split("/").pop() ?? workflow.path;
+        for (const job of Object.values(jobs)) {
+            if (!job || typeof job !== "object")
+                continue;
+            const steps = job.steps;
+            if (!Array.isArray(steps))
+                continue;
+            for (const step of steps) {
+                if (!step || typeof step !== "object")
+                    continue;
+                const run = step.run;
+                if (typeof run !== "string")
+                    continue;
+                for (const rawLine of run.split(/\r?\n/)) {
+                    const line = rawLine.trim();
+                    if (line === "" || line.startsWith("#") || isShellControlFlow(line))
+                        continue;
+                    if (!seen.has(line))
+                        seen.set(line, workflowName);
+                }
+            }
+        }
+    }
+    const all = [...seen.entries()].map(([command, workflow]) => ({ command, workflow }));
+    return {
+        commands: all.slice(0, MAX_CI_COMMANDS),
+        omittedCount: Math.max(0, all.length - MAX_CI_COMMANDS),
+    };
+}
+const MAX_DIRS = 20;
+export function extractStructure(signals, lang) {
+    const dirNotes = UI[lang].dirNotes;
+    const dirs = new Set();
+    for (const file of signals.files) {
+        const normalized = file.split(path.sep).join("/");
+        const slash = normalized.indexOf("/");
+        if (slash > 0)
+            dirs.add(normalized.slice(0, slash));
+    }
+    return [...dirs]
+        .sort()
+        .slice(0, MAX_DIRS)
+        .map((dir) => {
+        const note = dirNotes[dir.toLowerCase()];
+        return note ? { dir: `${dir}/`, note } : { dir: `${dir}/` };
+    });
+}
+export function buildRepoFacts(signals, lang) {
+    const allCommands = [
+        ...extractNpmCommands(signals),
+        ...extractComposerCommands(signals),
+        ...extractMakeTargets(signals),
+        ...extractMixAliases(signals),
+        ...extractToxEnvs(signals),
+    ];
+    const { kept, omitted } = filterCommands(allCommands);
+    const { commands: ciCommands, omittedCount: omittedCiCount } = extractCiCommands(signals);
+    return {
+        commands: kept,
+        omittedCommands: omitted,
+        structure: extractStructure(signals, lang),
+        ciCommands,
+        omittedCiCount,
+    };
+}

package/dist/core/scanner.js

@@ -28,11 +28,16 @@ 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;
@@ -42,7 +47,7 @@ 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;
@@ -56,8 +61,43 @@ function shallowest(matches) {
 function findFirst(files, fileName) {
     return shallowest(files.filter((f) => path.basename(f) === fileName));
 }
-function findFirstByExtension(files, extension) {
-    return shallowest(files.filter((f) => f.toLowerCase().endsWith(extension)));
+// Directories that routinely carry their own throwaway Python tooling manifest (a
+// mkdocs/sphinx docs build, a one-off script, a benchmark harness) in projects whose
+// primary language is something else entirely (e.g. nlohmann/json, a C++ library, ships
+// docs/mkdocs/requirements.txt). Prefer a candidate outside these dirs when one exists.
+const NON_PROJECT_DIRS = new Set([
+    "docs",
+    "doc",
+    "tools",
+    "tool",
+    "scripts",
+    "script",
+    "examples",
+    "example",
+    "benchmark",
+    "benchmarks",
+]);
+function isUnderNonProjectDir(relativePath) {
+    const segments = relativePath.split(path.sep).slice(0, -1);
+    return segments.some((segment) => NON_PROJECT_DIRS.has(segment.toLowerCase()));
+}
+function findFirstPreferringRealProjectDirs(files, fileName) {
+    const matches = files.filter((f) => path.basename(f) === fileName && !isUnderNonProjectDir(f));
+    return shallowest(matches);
+}
+function findAllByExtension(files, extension) {
+    return files.filter((f) => f.toLowerCase().endsWith(extension));
+}
+function findAllByNames(files, names) {
+    return files.filter((f) => names.includes(path.basename(f)));
+}
+function readAllConcatenated(rootPath, relativePaths) {
+    if (relativePaths.length === 0)
+        return undefined;
+    const contents = relativePaths
+        .map((p) => readTextIfExists(path.join(rootPath, p)))
+        .filter((content) => content !== undefined);
+    return contents.length > 0 ? contents.join("\n") : undefined;
 }
 function pickShallowest(paths) {
     return shallowest(paths.filter((p) => p !== undefined));
@@ -75,6 +115,7 @@ export function scanRepo(rootPath) {
             dependencies: rawPackageJson.dependencies ?? {},
             devDependencies: rawPackageJson.devDependencies ?? {},
             scripts: rawPackageJson.scripts ?? {},
+            moduleType: rawPackageJson.type === "module" ? "module" : "commonjs",
         }
         : undefined;
     const composerJsonPath = findFirst(files, "composer.json");
@@ -85,11 +126,13 @@ export function scanRepo(rootPath) {
         ? {
             require: rawComposerJson.require ?? {},
             requireDev: rawComposerJson["require-dev"] ?? {},
+            scripts: rawComposerJson.scripts ?? {},
         }
         : undefined;
-    const pyprojectCandidate = findFirst(files, "pyproject.toml");
-    const requirementsCandidate = findFirst(files, "requirements.txt");
-    const environmentYmlCandidate = findFirst(files, "environment.yml") ?? findFirst(files, "environment.yaml");
+    const pyprojectCandidate = findFirstPreferringRealProjectDirs(files, "pyproject.toml");
+    const requirementsCandidate = findFirstPreferringRealProjectDirs(files, "requirements.txt");
+    const environmentYmlCandidate = findFirstPreferringRealProjectDirs(files, "environment.yml") ??
+        findFirstPreferringRealProjectDirs(files, "environment.yaml");
     // Only the shallowest of the three "wins" as the project's Python manifest — otherwise an
     // unrelated pyproject.toml nested inside a vendored/data subdirectory (e.g. a bundled dataset
     // package) would always outrank a real root-level environment.yml just by file type.
@@ -101,20 +144,40 @@ export function scanRepo(rootPath) {
     const pyprojectPath = primaryPythonManifest === pyprojectCandidate ? pyprojectCandidate : undefined;
     const requirementsPath = primaryPythonManifest === requirementsCandidate ? requirementsCandidate : undefined;
     const environmentYmlPath = primaryPythonManifest === environmentYmlCandidate ? environmentYmlCandidate : undefined;
-    const pomPath = findFirst(files, "pom.xml");
-    const buildGradlePath = findFirst(files, "build.gradle") ?? findFirst(files, "build.gradle.kts");
+    // 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 csprojPath = findFirstByExtension(files, ".csproj");
+    // .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 pubspecYamlPath = findFirst(files, "pubspec.yaml");
+    // 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");
+    // 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(files, "mix.exs");
     const buildSbtPath = findFirst(files, "build.sbt");
     const rDescriptionPath = findFirst(files, "DESCRIPTION");
     const renvLockPath = findFirst(files, "renv.lock");
+    const toxIniPath = findFirst(files, "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")));
+    });
     return {
         rootPath,
         files,
@@ -129,20 +192,27 @@ export function scanRepo(rootPath) {
         environmentYml: environmentYmlPath
             ? readTextIfExists(path.join(rootPath, environmentYmlPath))
             : undefined,
-        pomXml: pomPath ? readTextIfExists(path.join(rootPath, pomPath)) : undefined,
-        buildGradle: buildGradlePath ? readTextIfExists(path.join(rootPath, buildGradlePath)) : undefined,
+        pomXml: readAllConcatenated(rootPath, pomPaths),
+        buildGradle: readAllConcatenated(rootPath, buildGradlePaths),
         composerJson,
         gemfile: gemfilePath ? readTextIfExists(path.join(rootPath, gemfilePath)) : undefined,
         goMod: goModPath ? readTextIfExists(path.join(rootPath, goModPath)) : undefined,
         cargoToml: cargoTomlPath ? readTextIfExists(path.join(rootPath, cargoTomlPath)) : undefined,
-        csproj: csprojPath ? readTextIfExists(path.join(rootPath, csprojPath)) : undefined,
+        csproj: readAllConcatenated(rootPath, csprojPaths),
         packageSwift: packageSwiftPath ? readTextIfExists(path.join(rootPath, packageSwiftPath)) : undefined,
-        pubspecYaml: pubspecYamlPath ? readTextIfExists(path.join(rootPath, pubspecYamlPath)) : undefined,
+        pubspecYaml: readAllConcatenated(rootPath, pubspecYamlPaths),
         cmakeLists: cmakeListsPath ? readTextIfExists(path.join(rootPath, cmakeListsPath)) : undefined,
         makefile: makefilePath ? readTextIfExists(path.join(rootPath, makefilePath)) : undefined,
         mixExs: mixExsPath ? readTextIfExists(path.join(rootPath, mixExsPath)) : undefined,
         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),
     };
 }

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,4 +1,6 @@
-function renderSection(entries) {
+import { UI } from "./i18n.js";
+function renderSection(entries, lang) {
+    const ui = UI[lang];
     return entries
         .map(({ detection, ruleSet }) => {
         const conventions = ruleSet.conventions.map((c) => `- ${c}`).join("\n");
@@ -8,41 +10,64 @@ function renderSection(entries) {
             "",
             ruleSet.summary,
             "",
-            "### Convenciones",
+            `### ${ui.sections.conventions}`,
             conventions,
             "",
-            "### Arquitectura",
+            `### ${ui.sections.architecture}`,
             architecture,
         ].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");
+const SOURCE_FILES = {
+    npm: "package.json",
+    composer: "composer.json",
+    make: "Makefile",
+    mix: "mix.exs",
+    tox: "tox.ini",
+};
+export function renderRepoFacts(facts, lang) {
+    const ui = UI[lang];
+    const sections = [];
+    if (facts.commands.length > 0) {
+        const lines = facts.commands.map((c) => c.detail && c.detail !== c.invocation
+            ? `- \`${c.invocation}\` → \`${c.detail}\` (${SOURCE_FILES[c.source]})`
+            : `- \`${c.invocation}\` (${SOURCE_FILES[c.source]})`);
+        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) {
+        const lines = facts.structure.map((d) => (d.note ? `- \`${d.dir}\` — ${d.note}` : `- \`${d.dir}\``));
+        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"));
+    }
+    return sections.join("\n\n");
 }
-export function renderAgentsMd(entries) {
+function renderDocument(title, entries, facts, lang) {
+    const factsBlock = facts ? renderRepoFacts(facts, lang) : "";
     return [
-        "# AGENTS.md",
+        title,
         "",
-        "Generado por agent-rules-init a partir de lo detectado en este repo.",
+        UI[lang].generatedHeader,
         "",
-        renderSection(entries),
+        renderSection(entries, lang),
+        ...(factsBlock ? ["", factsBlock] : []),
     ].join("\n");
 }
-export function renderCopilotInstructions(entries) {
-    return [
-        "# Copilot Instructions",
-        "",
-        "Generado por agent-rules-init a partir de lo detectado en este repo.",
-        "",
-        renderSection(entries),
-    ].join("\n");
+export function renderClaudeMd(entries, facts, lang) {
+    return renderDocument("# CLAUDE.md", entries, facts, lang);
+}
+export function renderAgentsMd(entries, facts, lang) {
+    return renderDocument("# AGENTS.md", entries, facts, lang);
+}
+export function renderCopilotInstructions(entries, facts, lang) {
+    return renderDocument("# Copilot Instructions", entries, facts, lang);
 }
 export function renderPromptFiles(packId, templates) {
     return templates.flatMap((template) => [

package/dist/core/types.d.ts

@@ -1,12 +1,15 @@
+import type { Lang } from "./i18n.js";
 export interface PackageJsonManifest {
     name?: string;
     dependencies: Record<string, string>;
     devDependencies: Record<string, string>;
     scripts: Record<string, string>;
+    moduleType: "module" | "commonjs";
 }
 export interface ComposerJsonManifest {
     require: Record<string, string>;
     requireDev: Record<string, string>;
+    scripts?: Record<string, unknown>;
 }
 export interface RepoSignals {
     rootPath: string;
@@ -32,6 +35,11 @@ export interface RepoSignals {
     buildSbt?: string;
     rDescription?: string;
     renvLock?: string;
+    toxIni?: string;
+    githubWorkflows?: {
+        path: string;
+        content: string;
+    }[];
 }
 export type Confidence = "high" | "low";
 export interface DetectionField<T> {
@@ -45,6 +53,8 @@ export interface DetectionResult {
     packageManager?: DetectionField<string>;
     testRunner?: DetectionField<string>;
     linter?: DetectionField<string>;
+    usesTypeScript?: boolean;
+    moduleFormat?: "module" | "commonjs";
 }
 export interface RuleSet {
     summary: string;
@@ -56,9 +66,33 @@ export interface PromptTemplate {
     title: string;
     body: string;
 }
+export type CommandSource = "npm" | "composer" | "make" | "mix" | "tox";
+export interface CommandEntry {
+    source: CommandSource;
+    invocation: string;
+    detail?: string;
+}
+export interface DirEntry {
+    dir: string;
+    note?: string;
+}
+export interface CiCommand {
+    command: string;
+    workflow: string;
+}
+export interface RepoFacts {
+    commands: CommandEntry[];
+    omittedCommands: {
+        source: CommandSource;
+        count: number;
+    }[];
+    structure: DirEntry[];
+    ciCommands: CiCommand[];
+    omittedCiCount: number;
+}
 export interface Pack {
     id: string;
     detect(signals: RepoSignals): DetectionResult | null;
-    rules(detection: DetectionResult): RuleSet;
-    promptTemplates(detection: DetectionResult): PromptTemplate[];
+    rules(detection: DetectionResult, lang: Lang): RuleSet;
+    promptTemplates(detection: DetectionResult, lang: Lang): 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,8 +4,10 @@ export function writeGeneratedFiles(rootPath, files) {
     return files.map(({ path: relativePath, content }) => {
         const absolutePath = path.join(rootPath, relativePath);
         try {
+            // An already-existing file is the expected outcome on a re-run (the tool's
+            // no-overwrite guarantee), not a failure — report it as skipped, exit 0.
             if (fs.existsSync(absolutePath)) {
-                return { path: relativePath, status: "error", error: "file already exists" };
+                return { path: relativePath, status: "skipped" };
             }
             fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
             fs.writeFileSync(absolutePath, content);