agent-rules-init 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { type WriteResult } from "./core/writer.js";
+import { type PromptFn } from "./core/prompt-engine.js";
+import { type ExecFn } from "./core/llm-bridge.js";
+export interface RunCliOptions {
+    promptFn?: PromptFn;
+    execFn?: ExecFn;
+    skipLlm?: boolean;
+}
+export declare function runCli(rootPath: string, options?: RunCliOptions): Promise<WriteResult[]>;

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import * as clack from "@clack/prompts";
+import { pathToFileURL } from "node:url";
+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, } from "./core/prompt-engine.js";
+import { detectAvailableAssistants, polishWithAssistant, defaultExecFn } from "./core/llm-bridge.js";
+import { jsTsPack } from "agent-rules-pack-js-ts";
+import { pythonPack } from "agent-rules-pack-python";
+import { javaPack } from "agent-rules-pack-java";
+import { phpPack } from "agent-rules-pack-php";
+const ALL_PACKS = [jsTsPack, pythonPack, javaPack, phpPack];
+export async function runCli(rootPath, options = {}) {
+    const promptFn = options.promptFn ?? defaultPromptFn;
+    const execFn = options.execFn ?? defaultExecFn;
+    const signals = scanRepo(rootPath);
+    const rawDetections = ALL_PACKS.map((pack) => pack.detect(signals)).filter((d) => d !== null);
+    const questions = collectLowConfidenceQuestions(rawDetections);
+    const answers = await askQuestions(questions, promptFn);
+    const detections = applyAnswers(rawDetections, answers);
+    const entries = detections.map((detection) => {
+        const pack = ALL_PACKS.find((p) => p.id === detection.packId);
+        return { detection, ruleSet: pack.rules(detection) };
+    });
+    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: ".github/copilot-instructions.generated.md",
+            content: renderCopilotInstructions(entries),
+        });
+        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))) {
+                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",
+        });
+    }
+    if (!options.skipLlm) {
+        const assistants = await detectAvailableAssistants(execFn);
+        if (assistants.length > 0) {
+            const chosenAssistant = assistants[0];
+            const usePolish = await clack.confirm({
+                message: `Se detectó ${chosenAssistant}. ¿Quieres que pula la redacción final?`,
+            });
+            if (usePolish === true) {
+                for (const file of files) {
+                    file.content = await polishWithAssistant(chosenAssistant, file.content, execFn);
+                }
+            }
+        }
+    }
+    return writeGeneratedFiles(rootPath, files);
+}
+async function main() {
+    const results = await runCli(process.cwd());
+    const failures = results.filter((r) => r.status === "error");
+    for (const result of results) {
+        if (result.status === "written") {
+            clack.log.success(result.path);
+        }
+        else {
+            clack.log.warn(`${result.path}: ${result.error}`);
+        }
+    }
+    if (failures.length > 0) {
+        process.exitCode = 1;
+    }
+}
+const isMainModule = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+    main();
+}

package/dist/core/llm-bridge.d.ts

@@ -0,0 +1,9 @@
+export type AssistantId = "claude" | "codex";
+export interface ExecResult {
+    stdout: string;
+    exitCode: number;
+}
+export type ExecFn = (command: string, args: string[]) => Promise<ExecResult>;
+export declare const defaultExecFn: ExecFn;
+export declare function detectAvailableAssistants(execFn?: ExecFn): Promise<AssistantId[]>;
+export declare function polishWithAssistant(assistant: AssistantId, content: string, execFn?: ExecFn): Promise<string>;

package/dist/core/llm-bridge.js

@@ -0,0 +1,45 @@
+import { spawn } from "node:child_process";
+const VERSION_ARGS = {
+    claude: ["--version"],
+    codex: ["--version"],
+};
+export const defaultExecFn = (command, args) => new Promise((resolve, reject) => {
+    // shell:true is only needed on Windows, to resolve npm-installed .cmd/.ps1 shims.
+    // On POSIX, spawn(command, args) execs the binary directly with argv, so passing
+    // large generated content as an argument (see polishWithAssistant) can never be
+    // reinterpreted by a shell there.
+    const child = spawn(command, args, { shell: process.platform === "win32" });
+    let stdout = "";
+    child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
+    child.on("error", reject);
+    child.on("close", (exitCode) => {
+        if (exitCode === 0)
+            resolve({ stdout, exitCode });
+        else
+            reject(new Error(`${command} exited with code ${exitCode}`));
+    });
+});
+export async function detectAvailableAssistants(execFn = defaultExecFn) {
+    const candidates = ["claude", "codex"];
+    const results = await Promise.all(candidates.map(async (id) => {
+        try {
+            await execFn(id, VERSION_ARGS[id]);
+            return id;
+        }
+        catch {
+            return null;
+        }
+    }));
+    return results.filter((id) => id !== null);
+}
+export async function polishWithAssistant(assistant, content, execFn = defaultExecFn) {
+    const prompt = `Pule la redacción del siguiente documento de instrucciones para un agente de IA, sin cambiar su significado ni estructura:\n\n${content}`;
+    try {
+        const result = await execFn(assistant, ["-p", prompt]);
+        return result.stdout.trim() || content;
+    }
+    catch (err) {
+        console.warn(`No se pudo pulir el contenido con ${assistant}, se mantiene el original: ${err.message}`);
+        return content;
+    }
+}

package/dist/core/prompt-engine.d.ts

@@ -0,0 +1,12 @@
+import type { DetectionResult } from "./types.js";
+export type QuestionField = "framework" | "testRunner" | "linter" | "packageManager";
+export interface Question {
+    packId: string;
+    field: QuestionField;
+    message: string;
+}
+export declare function collectLowConfidenceQuestions(detections: DetectionResult[]): Question[];
+export type PromptFn = (message: string) => Promise<string>;
+export declare const defaultPromptFn: PromptFn;
+export declare function askQuestions(questions: Question[], promptFn?: PromptFn): Promise<Record<string, string>>;
+export declare function applyAnswers(detections: DetectionResult[], answers: Record<string, string>): DetectionResult[];

package/dist/core/prompt-engine.js

@@ -0,0 +1,45 @@
+import * as clack from "@clack/prompts";
+const FIELDS = ["framework", "testRunner", "linter", "packageManager"];
+export function collectLowConfidenceQuestions(detections) {
+    const questions = [];
+    for (const detection of detections) {
+        for (const field of FIELDS) {
+            const detectionField = detection[field];
+            if (detectionField && detectionField.confidence === "low") {
+                questions.push({
+                    packId: detection.packId,
+                    field,
+                    message: `No se pudo determinar el ${field} para ${detection.language}. ¿Cuál usáis?`,
+                });
+            }
+        }
+    }
+    return questions;
+}
+export const defaultPromptFn = async (message) => {
+    const answer = await clack.text({ message });
+    if (clack.isCancel(answer)) {
+        clack.cancel("Operación cancelada.");
+        process.exit(1);
+    }
+    return answer;
+};
+export async function askQuestions(questions, promptFn = defaultPromptFn) {
+    const answers = {};
+    for (const question of questions) {
+        answers[`${question.packId}:${question.field}`] = await promptFn(question.message);
+    }
+    return answers;
+}
+export function applyAnswers(detections, answers) {
+    return detections.map((detection) => {
+        const updated = { ...detection };
+        for (const field of FIELDS) {
+            const answer = answers[`${detection.packId}:${field}`];
+            if (answer) {
+                updated[field] = { value: answer, confidence: "high" };
+            }
+        }
+        return updated;
+    });
+}

package/dist/core/scanner.d.ts

@@ -0,0 +1,2 @@
+import type { RepoSignals } from "./types.js";
+export declare function scanRepo(rootPath: string): RepoSignals;

package/dist/core/scanner.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".venv", "__pycache__"]);
+const MAX_DEPTH = 4;
+function walk(rootPath) {
+    const results = [];
+    function recurse(dir, depth) {
+        if (depth > MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                recurse(path.join(dir, entry.name), depth + 1);
+            }
+            else {
+                results.push(path.relative(rootPath, path.join(dir, entry.name)));
+            }
+        }
+    }
+    recurse(rootPath, 0);
+    return results;
+}
+function readJsonIfExists(filePath) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTextIfExists(filePath) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function findFirst(files, fileName) {
+    const matches = files.filter((f) => path.basename(f) === fileName);
+    if (matches.length === 0)
+        return undefined;
+    return matches.reduce((shallowest, candidate) => candidate.split(path.sep).length < shallowest.split(path.sep).length ? candidate : shallowest);
+}
+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
+        ? {
+            name: rawPackageJson.name,
+            dependencies: rawPackageJson.dependencies ?? {},
+            devDependencies: rawPackageJson.devDependencies ?? {},
+            scripts: rawPackageJson.scripts ?? {},
+        }
+        : undefined;
+    const composerJsonPath = findFirst(files, "composer.json");
+    const rawComposerJson = composerJsonPath
+        ? readJsonIfExists(path.join(rootPath, composerJsonPath))
+        : undefined;
+    const composerJson = rawComposerJson
+        ? {
+            require: rawComposerJson.require ?? {},
+            requireDev: rawComposerJson["require-dev"] ?? {},
+        }
+        : undefined;
+    const pyprojectPath = findFirst(files, "pyproject.toml");
+    const requirementsPath = findFirst(files, "requirements.txt");
+    const pomPath = findFirst(files, "pom.xml");
+    const buildGradlePath = findFirst(files, "build.gradle") ?? findFirst(files, "build.gradle.kts");
+    return {
+        rootPath,
+        files,
+        hasFile: (relativePath) => fileSet.has(relativePath.split(path.sep).join("/")),
+        hasDir: (relativeDir) => fs.existsSync(path.join(rootPath, relativeDir)) &&
+            fs.statSync(path.join(rootPath, relativeDir)).isDirectory(),
+        packageJson,
+        pyprojectToml: pyprojectPath ? readTextIfExists(path.join(rootPath, pyprojectPath)) : undefined,
+        requirementsTxt: requirementsPath
+            ? readTextIfExists(path.join(rootPath, requirementsPath))
+            : undefined,
+        pomXml: pomPath ? readTextIfExists(path.join(rootPath, pomPath)) : undefined,
+        buildGradle: buildGradlePath ? readTextIfExists(path.join(rootPath, buildGradlePath)) : undefined,
+        composerJson,
+    };
+}

package/dist/core/templates.d.ts

@@ -0,0 +1,12 @@
+import type { DetectionResult, PromptTemplate, 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 renderPromptFiles(packId: string, templates: PromptTemplate[]): {
+    path: string;
+    content: string;
+}[];

package/dist/core/templates.js

@@ -0,0 +1,58 @@
+function renderSection(entries) {
+    return entries
+        .map(({ detection, ruleSet }) => {
+        const conventions = ruleSet.conventions.map((c) => `- ${c}`).join("\n");
+        const architecture = ruleSet.architectureNotes.map((a) => `- ${a}`).join("\n");
+        return [
+            `## ${detection.language} (${detection.packId})`,
+            "",
+            ruleSet.summary,
+            "",
+            "### Convenciones",
+            conventions,
+            "",
+            "### Arquitectura",
+            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");
+}
+export function renderAgentsMd(entries) {
+    return [
+        "# AGENTS.md",
+        "",
+        "Generado por agent-rules-init a partir de lo detectado en este repo.",
+        "",
+        renderSection(entries),
+    ].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 renderPromptFiles(packId, templates) {
+    return templates.flatMap((template) => [
+        {
+            path: `.claude/commands/${packId}-${template.id}.generated.md`,
+            content: `# ${template.title}\n\n${template.body}\n`,
+        },
+        {
+            path: `.github/prompts/${packId}-${template.id}.generated.prompt.md`,
+            content: `# ${template.title}\n\n${template.body}\n`,
+        },
+    ]);
+}

package/dist/core/types.d.ts

@@ -0,0 +1 @@
+export * from "agent-rules-pack-types";

package/dist/core/types.js

@@ -0,0 +1 @@
+export * from "agent-rules-pack-types";

package/dist/core/writer.d.ts

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

package/dist/core/writer.js

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+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);
+            return { path: relativePath, status: "written" };
+        }
+        catch (err) {
+            return { path: relativePath, status: "error", error: err.message };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agent-rules-init",
+  "version": "0.1.0",
+  "description": "Generates CLAUDE.md, AGENTS.md, copilot-instructions.md and prompt files from what your repo actually is.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "agent-rules-init": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "agent-rules-pack-java": "0.1.0",
+    "agent-rules-pack-js-ts": "0.1.0",
+    "agent-rules-pack-php": "0.1.0",
+    "agent-rules-pack-python": "0.1.0",
+    "agent-rules-pack-types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}