@netanelyasi/agent-ready 0.2.0

package/dist/generators/generate.js

@@ -0,0 +1,482 @@
+import path from "node:path";
+export function generateFiles(scan, score, force) {
+    const files = [];
+    add("CLAUDE.md", generateClaudeMd(scan));
+    add("CODEMAP.md", generateCodemap(scan));
+    add(".aiignore", generateAiIgnore(scan));
+    add(".claude/settings.json", generateClaudeSettings(scan));
+    add(".claude/hooks/prevent-destructive.mjs", generatePreventDestructiveHook());
+    add(".claude/hooks/protect-generated.mjs", generateProtectGeneratedHook());
+    add(".claude/hooks/suggest-validation.mjs", generateSuggestValidationHook(scan));
+    add(".agent-ready/report.md", generateReport(scan, score));
+    add(".agent-ready/recommendations.md", generateRecommendations(scan));
+    add(".agent-ready/hooks/README.md", generateHooksReadme(scan));
+    for (const subdir of subdirClaudeFiles(scan)) {
+        add(`${subdir.dir}/CLAUDE.md`, subdir.content);
+    }
+    for (const skill of generateSkills(scan)) {
+        add(`.agent-ready/skills/${skill.slug}/SKILL.md`, skill.content);
+    }
+    return files;
+    function add(relativePath, content) {
+        files.push({ path: path.join(scan.root, relativePath), content, kind: force ? "overwrite" : "create" });
+    }
+}
+function subdirClaudeFiles(scan) {
+    if (!scan.monorepo.detected)
+        return [];
+    return scan.packages
+        .filter((pkg) => pkg.path !== "package.json")
+        .map((pkg) => {
+        const dir = path.posix.dirname(pkg.path);
+        const commands = packageCommandLines(pkg, scan.packageManager);
+        return {
+            dir,
+            content: [
+                `# ${dir} — Local AI Agent Guide`,
+                "",
+                "This file should contain only conventions and commands for this workspace. Keep broad repository rules in the root `CLAUDE.md`.",
+                "",
+                "## Workspace",
+                `- Package: ${pkg.name ?? "unnamed"}`,
+                `- Path: \`${dir}\``,
+                "",
+                "## Local Commands",
+                ...commands,
+                "",
+                "## Local Navigation",
+                "- Start searches inside this directory before searching the whole repository.",
+                "- Prefer local tests/builds over root-wide validation unless the change crosses package boundaries.",
+                "- Add workspace-specific gotchas here as they are discovered.",
+                "",
+            ].join("\n"),
+        };
+    });
+}
+function packageCommandLines(pkg, projectPackageManager) {
+    const dir = path.posix.dirname(pkg.path) === "." ? "." : path.posix.dirname(pkg.path);
+    const pm = pkg.packageManager?.split("@")[0] ?? projectPackageManager ?? "npm";
+    const rows = [];
+    const candidates = [
+        ["dev", ["dev", "start:dev", "serve"]],
+        ["build", ["build", "compile"]],
+        ["test", ["test", "test:unit", "unit"]],
+        ["lint", ["lint", "eslint"]],
+        ["typecheck", ["typecheck", "type-check", "check", "tsc"]],
+        ["format", ["format", "prettier"]],
+    ];
+    for (const [label, names] of candidates) {
+        const scriptName = names.find((name) => pkg.scripts[name]);
+        if (scriptName)
+            rows.push(`- ${label}: \`cd ${dir} && ${pm} run ${scriptName}\``);
+    }
+    return rows.length ? rows : ["- No local package scripts detected. Add workspace-specific validation commands here."];
+}
+function generateClaudeMd(scan) {
+    const lines = [
+        `# ${scan.name} — AI Agent Guide`,
+        "",
+        "This file is generated by `agent-ready`. Keep it lean: broad project facts, critical gotchas, and validation commands only. Move task-specific expertise into skills.",
+        "",
+        "## Project Snapshot",
+        `- Languages: ${list(scan.languages)}`,
+        `- Frameworks: ${list(scan.frameworks)}`,
+        `- Databases/tools: ${list(scan.databases)}`,
+        `- Deployment: ${list(scan.deployment)}`,
+        `- Package manager: ${scan.packageManager ?? "unknown"}`,
+        `- Monorepo: ${scan.monorepo.detected ? `yes (${list(scan.monorepo.tools)})` : "no/unclear"}`,
+        "",
+        "## How to Navigate",
+        "- Start from `CODEMAP.md` before broad searches.",
+        "- Prefer targeted file reads and symbol/reference search over opening many files.",
+        "- Do not inspect generated/build/vendor folders unless the task explicitly requires it.",
+        "- In monorepos, work from the relevant subdirectory and use local commands when possible.",
+        "",
+        "## Important Directories",
+        ...scan.importantDirs.map((dir) => `- \`${dir.path}\` — ${dir.reason}${dir.children.length ? ` (${dir.children.slice(0, 8).join(", ")})` : ""}`),
+        "",
+        "## Validation Commands",
+        ...commandLines(scan),
+        "",
+        "## Agent Operating Rules",
+        "- Make the smallest safe change that satisfies the request.",
+        "- Before editing, identify the exact file(s) and local conventions.",
+        "- After code changes, run the narrowest relevant validation command listed above.",
+        "- If validation is missing or expensive, state what could not be verified.",
+        "- Never claim actions were performed unless the tool/command actually succeeded.",
+    ];
+    if (scan.traits.hasHebrewOrRtl) {
+        lines.push("- This project appears to contain Hebrew/RTL UI. Preserve RTL semantics and use logical CSS (`start`/`end`) where possible.");
+    }
+    if (scan.databases.includes("Supabase")) {
+        lines.push("- Supabase detected: verify schema/RLS/query behavior before proposing database changes.");
+    }
+    if (scan.frameworks.includes("Next.js")) {
+        lines.push("- Next.js detected: avoid hydration mismatches; access browser-only APIs only in client-safe code.");
+    }
+    lines.push("", "## Generated Skills", "See `.agent-ready/skills/*/SKILL.md` for task-specific instructions that should be loaded on demand, not copied wholesale into this file.", "");
+    return lines.join("\n");
+}
+function commandLines(scan) {
+    const order = ["dev", "build", "test", "lint", "typecheck", "format"];
+    const lines = [];
+    for (const name of order) {
+        const commands = scan.commands[name];
+        if (!commands?.length)
+            continue;
+        lines.push(`- ${name}:`);
+        for (const command of commands.slice(0, 8))
+            lines.push(`  - \`${command}\``);
+    }
+    if (!lines.length)
+        lines.push("- No standard validation commands were detected. Add project-specific commands here.");
+    return lines;
+}
+function generateCodemap(scan) {
+    return [
+        `# ${scan.name} — CODEMAP`,
+        "",
+        "Generated by `agent-ready`. Use this as the first stop for AI agents before broad code search.",
+        "",
+        "## Entry Points",
+        ...entryPointLines(scan),
+        "",
+        "## Central Files",
+        "Files with the most internal imports pointing at them. These are often shared utilities, public APIs, or architectural choke points.",
+        "",
+        ...centralFileLines(scan),
+        "",
+        "## Internal Import Graph",
+        "Representative resolved internal imports. Read this before doing broad grep-style exploration.",
+        "",
+        ...importEdgeLines(scan),
+        "",
+        "## External Dependencies in Code",
+        ...externalImportLines(scan),
+        "",
+        "## Top-level Map",
+        ...scan.importantDirs.map((dir) => [
+            `### \`${dir.path}\``,
+            dir.reason,
+            dir.children.length ? `Children: ${dir.children.map((child) => `\`${child}\``).join(", ")}` : "Children: not listed.",
+            "",
+        ].join("\n")),
+        "## Package Manifests",
+        ...scan.packages.map((pkg) => `- \`${pkg.path}\`${pkg.name ? ` — ${pkg.name}` : ""}`),
+        "",
+        "## Search Guidance",
+        "- Start at an entry point, then follow imports to the relevant implementation.",
+        "- Use central files to identify shared abstractions before editing duplicated logic.",
+        "- Use exact symbols, route names, table names, or component names when possible.",
+        "- Start in the directory closest to the task before searching globally.",
+        "- Avoid noisy paths listed in `.aiignore` unless directly relevant.",
+        "",
+    ].join("\n");
+}
+function entryPointLines(scan) {
+    if (!scan.codeGraph.entryPoints.length)
+        return ["- No entry points detected. Add known application, CLI, route, or library entry points here."];
+    return scan.codeGraph.entryPoints.map((entry) => `- \`${entry.path}\` — ${entry.kind}; ${entry.reason}`);
+}
+function centralFileLines(scan) {
+    if (!scan.codeGraph.centralFiles.length)
+        return ["- No central files detected from imports yet."];
+    return scan.codeGraph.centralFiles.slice(0, 15).map((file) => `- \`${file.path}\` — inbound: ${file.inbound}, outbound: ${file.outbound}`);
+}
+function importEdgeLines(scan) {
+    if (!scan.codeGraph.importEdges.length)
+        return ["- No resolved internal imports detected."];
+    return scan.codeGraph.importEdges.slice(0, 40).map((edge) => `- \`${edge.from}\` → \`${edge.to}\``);
+}
+function externalImportLines(scan) {
+    if (!scan.codeGraph.externalImports.length)
+        return ["- No external imports detected in scanned source files."];
+    return scan.codeGraph.externalImports.slice(0, 20).map((entry) => `- \`${entry.packageName}\` — used by ${entry.importedBy.slice(0, 5).map((file) => `\`${file}\``).join(", ")}${entry.importedBy.length > 5 ? " …" : ""}`);
+}
+function generateAiIgnore(scan) {
+    const base = [
+        "# Generated by agent-ready",
+        "node_modules/",
+        ".next/",
+        ".nuxt/",
+        "dist/",
+        "build/",
+        "coverage/",
+        ".turbo/",
+        ".cache/",
+        ".venv/",
+        "venv/",
+        "__pycache__/",
+        "vendor/",
+        "target/",
+        "bin/",
+        "obj/",
+        "*.log",
+        "*.lock",
+        "generated/",
+        "**/*.generated.*",
+    ];
+    for (const noisy of scan.noisyPaths)
+        if (!base.includes(`${noisy}/`))
+            base.push(`${noisy}/`);
+    return `${[...new Set(base)].join("\n")}\n`;
+}
+function generateClaudeSettings(scan) {
+    const deny = [
+        "node_modules/**",
+        ".next/**",
+        "dist/**",
+        "build/**",
+        "coverage/**",
+        ".turbo/**",
+        "vendor/**",
+        "generated/**",
+        "**/*.generated.*",
+    ];
+    const settings = {
+        permissions: { deny: [...new Set(deny)] },
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: "Bash",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: "node",
+                            args: ["${CLAUDE_PROJECT_DIR}/.claude/hooks/prevent-destructive.mjs"],
+                            timeout: 10,
+                            statusMessage: "Checking command safety",
+                        },
+                    ],
+                },
+                {
+                    matcher: "Write|Edit|MultiEdit",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: "node",
+                            args: ["${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-generated.mjs"],
+                            timeout: 10,
+                            statusMessage: "Checking generated/noisy path safety",
+                        },
+                    ],
+                },
+            ],
+            PostToolUse: [
+                {
+                    matcher: "Write|Edit|MultiEdit",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: "node",
+                            args: ["${CLAUDE_PROJECT_DIR}/.claude/hooks/suggest-validation.mjs"],
+                            timeout: 10,
+                            statusMessage: "Suggesting validation",
+                        },
+                    ],
+                },
+            ],
+        },
+        agentReady: { generatedBy: "agent-ready", project: scan.name },
+    };
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+function generatePreventDestructiveHook() {
+    return `#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+const input = JSON.parse(readFileSync(0, "utf8") || "{}");
+const command = String(input.tool_input?.command ?? "");
+
+const blockedPatterns = [
+  { pattern: /(^|[;&|]\\s*)rm\\s+-[^\\n;]*r[^\\n;]*f[^\\n;]*(\\/|~|\\.|\\*)?(\\s|$)/i, reason: "Blocks rm -rf style destructive deletion." },
+  { pattern: /git\\s+reset\\s+--hard/i, reason: "Blocks git reset --hard." },
+  { pattern: /git\\s+clean\\s+-[^\\n;]*f/i, reason: "Blocks git clean -f." },
+  { pattern: /git\\s+push\\s+([^\\n;]*\\s)?--force/i, reason: "Blocks force-push." },
+  { pattern: /:\\(\\)\\s*\\{\\s*:\\|:&\\s*\\};:/, reason: "Blocks fork bomb pattern." },
+];
+
+const match = blockedPatterns.find((item) => item.pattern.test(command));
+if (!match) process.exit(0);
+
+console.log(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: \`agent-ready safety hook denied command. \${match.reason} Ask the user for explicit approval and use a narrower command.\`,
+  },
+}));
+`;
+}
+function generateProtectGeneratedHook() {
+    return `#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const input = JSON.parse(readFileSync(0, "utf8") || "{}");
+const rawPath = input.tool_input?.file_path ?? input.tool_input?.path ?? "";
+if (!rawPath) process.exit(0);
+
+const normalized = String(rawPath).replaceAll("\\\\", "/");
+const parts = normalized.split("/").filter(Boolean);
+const deniedDirs = new Set(["node_modules", ".next", ".nuxt", "dist", "build", "coverage", ".turbo", "vendor", "target", "generated"]);
+const generatedFile = /(^|\\/)generated(\\/|$)|\\.generated\\.[^/]+$/i.test(normalized);
+const noisyDir = parts.some((part) => deniedDirs.has(part));
+
+if (!generatedFile && !noisyDir) process.exit(0);
+
+console.log(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: \`agent-ready safety hook denied editing generated/noisy path: \${path.basename(normalized)}. If this is intentional, ask the user to approve and edit settings.\`,
+  },
+}));
+`;
+}
+function generateSuggestValidationHook(scan) {
+    const commands = [...(scan.commands.lint ?? []), ...(scan.commands.typecheck ?? []), ...(scan.commands.test ?? []), ...(scan.commands.build ?? [])].slice(0, 3);
+    const message = commands.length
+        ? `Suggested validation after edits: ${commands.map((command) => `\`${command}\``).join(", ")}. Run the narrowest relevant command before completion.`
+        : "No validation command was detected by agent-ready. Before completion, state that validation is undocumented unless the user provides a command.";
+    return `#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+
+readFileSync(0, "utf8");
+console.log(JSON.stringify({
+  systemMessage: ${JSON.stringify(message)},
+}));
+`;
+}
+function generateReport(scan, score) {
+    return [
+        `# Agent Readiness Report — ${scan.name}`,
+        "",
+        `Score: **${score.score}/100**`,
+        "",
+        "## Detected",
+        `- Languages: ${list(scan.languages)}`,
+        `- Frameworks: ${list(scan.frameworks)}`,
+        `- Databases/tools: ${list(scan.databases)}`,
+        `- Deployment: ${list(scan.deployment)}`,
+        `- Monorepo: ${scan.monorepo.detected ? "yes" : "no/unclear"}`,
+        `- Entry points: ${scan.codeGraph.entryPoints.length}`,
+        `- Resolved internal imports: ${scan.codeGraph.importEdges.length}`,
+        `- External packages imported: ${scan.codeGraph.externalImports.length}`,
+        "",
+        "## Strengths",
+        ...bullet(score.strengths),
+        "",
+        "## Missing / Recommended Fixes",
+        ...bullet(score.missing),
+        "",
+        "## Warnings",
+        ...bullet(score.warnings),
+        "",
+    ].join("\n");
+}
+function generateHooksReadme(scan) {
+    return [
+        "# Hook Templates",
+        "",
+        "These are safe starter hook policies. Wire them into your agent harness only after reviewing them for this repository.",
+        "",
+        "## Start Hook",
+        "- Load the nearest `CLAUDE.md` files for the current working directory.",
+        "- If the task mentions a framework/library, prefer current docs before implementation.",
+        "- For monorepos, identify the affected workspace before broad search.",
+        "",
+        "## Pre-edit / Pre-delete Hook",
+        "- Block edits in ignored/generated paths unless the user explicitly asked for generated output.",
+        "- Require confirmation before deleting files, rewriting broad directories, or changing deployment secrets.",
+        "",
+        "## Post-edit Hook",
+        ...postEditHookLines(scan),
+        "",
+        "## Stop Hook",
+        "- Summarize what changed and what was validated.",
+        "- If a reusable gotcha/pattern was discovered, propose a focused update to the nearest `CLAUDE.md` or a skill.",
+        "- Do not store temporary session state as long-term memory.",
+        "",
+    ].join("\n");
+}
+function postEditHookLines(scan) {
+    const lines = ["- Run or suggest the narrowest relevant validation command."];
+    if (scan.commands.lint?.length)
+        lines.push(`- Lint candidate: \`${scan.commands.lint[0]}\``);
+    if (scan.commands.typecheck?.length)
+        lines.push(`- Typecheck candidate: \`${scan.commands.typecheck[0]}\``);
+    if (scan.commands.test?.length)
+        lines.push(`- Test candidate: \`${scan.commands.test[0]}\``);
+    if (!scan.commands.lint?.length && !scan.commands.typecheck?.length && !scan.commands.test?.length)
+        lines.push("- No validation commands detected yet; ask maintainers to document them.");
+    return lines;
+}
+function generateRecommendations(scan) {
+    const recs = [];
+    recs.push("# Agent Harness Recommendations", "");
+    recs.push("## LSP", ...bullet(lspRecommendations(scan)), "");
+    recs.push("## MCP", ...bullet(mcpRecommendations(scan)), "");
+    recs.push("## Hooks", ...bullet(hookRecommendations(scan)), "");
+    recs.push("## Maintenance", "- Review CLAUDE.md and generated skills every 3–6 months or after major model/tool releases.", "- Move repeated session learnings into skills or focused subdirectory CLAUDE.md files.", "");
+    return recs.join("\n");
+}
+function lspRecommendations(scan) {
+    const out = [];
+    if (scan.traits.hasTypeScript || scan.languages.includes("JavaScript"))
+        out.push("Install/enable TypeScript language server and ESLint language server for symbol-aware navigation.");
+    if (scan.languages.includes("Python"))
+        out.push("Enable Pyright or basedpyright for Python symbol navigation.");
+    if (scan.languages.includes("Java"))
+        out.push("Enable Java language server (jdtls). ");
+    if (scan.languages.includes("C#"))
+        out.push("Enable C# Dev Kit / Roslyn LSP.");
+    if (scan.languages.includes("C/C++"))
+        out.push("Enable clangd with a compile_commands.json where possible.");
+    return out.length ? out : ["No specific LSP recommendation detected; add one for the primary language if available."];
+}
+function mcpRecommendations(scan) {
+    const out = ["Use Context7/library-docs MCP for up-to-date framework/library APIs."];
+    if (scan.databases.includes("Supabase"))
+        out.push("Use Supabase MCP for schema/RLS inspection before DB changes.");
+    if (scan.deployment.includes("GitHub Actions"))
+        out.push("Expose CI logs/status through GitHub tooling/MCP if available.");
+    if (scan.deployment.includes("Vercel"))
+        out.push("Use Vercel tooling/MCP for deployments and production logs.");
+    return out;
+}
+function hookRecommendations(scan) {
+    const out = [
+        "Stop hook: summarize useful session learnings and propose focused CLAUDE.md/skill updates.",
+        "Pre-edit/pre-delete hook: require confirmation for destructive operations and broad rewrites.",
+    ];
+    if (scan.commands.lint?.length)
+        out.push("Post-edit hook: suggest or run the narrowest lint command for changed workspace.");
+    if (scan.commands.test?.length)
+        out.push("Post-edit hook: suggest targeted tests related to changed files.");
+    return out;
+}
+function generateSkills(scan) {
+    const skills = [
+        { slug: "codebase-navigation", content: skill("codebase-navigation", "Use when starting work in this repository or when a task spans unfamiliar directories.", ["Read CODEMAP.md first.", "Use narrow searches from the relevant directory before global search.", "Prefer symbol/reference search when LSP is available.", "Do not inspect ignored/generated directories unless explicitly needed."]) },
+        { slug: "validation", content: skill("validation", "Use after code edits or before declaring a task complete.", [...commandLines(scan).map((line) => line.replace(/^[- ]+/, "")), "Run the narrowest relevant command first.", "If validation cannot be run, report the exact reason."]) },
+    ];
+    if (scan.frameworks.includes("Next.js"))
+        skills.push({ slug: "nextjs-hydration", content: skill("nextjs-hydration", "Use when editing Next.js/React components, routes, or client/server boundaries.", ["Do not read localStorage/sessionStorage/window/document during server render or initial state.", "Use useEffect or guarded client-only code for browser APIs.", "Avoid Math.random() or new Date() in render paths that must hydrate identically.", "Keep server/client boundaries explicit."]) });
+    if (scan.databases.includes("Supabase"))
+        skills.push({ slug: "supabase-debugging", content: skill("supabase-debugging", "Use when debugging Supabase queries, RLS, migrations, auth, or PostgREST errors.", ["Inspect the actual query shape before changing schema.", "Prefer maybeSingle() unless a row is guaranteed.", "Check RLS policies and authenticated role behavior before assuming frontend bugs.", "For DB changes, verify current schema first and use migrations."]) });
+    if (scan.traits.hasHebrewOrRtl)
+        skills.push({ slug: "rtl-ui", content: skill("rtl-ui", "Use when changing UI, layout, forms, tables, icons, or mixed Hebrew/English text.", ["Use logical alignment (`start`/`end`) and RTL-aware flex direction.", "Do not remove or hide broader parent containers when only one UI element was requested.", "Check mixed LTR/RTL content such as numbers, currency, percentages, paths, and code.", "Prefer targeted layout changes over broad CSS rewrites."]) });
+    if (scan.traits.hasDocker || scan.deployment.length)
+        skills.push({ slug: "deployment", content: skill("deployment", "Use when changing Docker, CI, deploy config, environment variables, or release flow.", ["Document required environment variables.", "Keep build-time and runtime environment requirements separate.", "Run local build or the closest available validation before deployment.", "Check git status so new files are not missed."]) });
+    return skills;
+}
+function skill(name, description, rules) {
+    return [`# ${name}`, "", `Description: ${description}`, "", "## Rules", ...rules.map((rule) => `- ${rule}`), ""].join("\n");
+}
+function list(items) {
+    return items.length ? items.join(", ") : "none detected";
+}
+function bullet(items) {
+    return items.length ? items.map((item) => `- ${item}`) : ["- None."];
+}

package/dist/scanner/scanProject.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectScan } from "../types.js";
+export declare function scanProject(rootInput: string): Promise<ProjectScan>;