create-reactor 0.1.0

package/lib/templates/ai-docs.mjs

@@ -0,0 +1,80 @@
+// AI-native development: AGENTS.md + CLAUDE.md so AI coding assistants
+// (Claude Code, Cursor, Copilot, Windsurf, ...) understand the project instantly.
+import { stackList } from "./app.mjs";
+
+/** AGENTS.md — the emerging cross-tool standard for AI assistant instructions. */
+export function agentsMd(c) {
+  const stack = stackList(c);
+
+  const commands = [
+    [`${c.pmRunLabel("dev")}`, c.backend === "convex" ? "start Vite + Convex together" : c.backend === "hono" ? "start Vite + the tRPC server together" : "start the dev server"],
+    [`${c.pmRunLabel("build")}`, "production build + full typecheck (run this to verify changes)"],
+    [`${c.pmRunLabel("lint")}`, "lint the codebase"],
+  ];
+  if (c.extras.includes("testing")) commands.push([`${c.pmRunLabel("test")}`, "run unit/component tests (Vitest)"]);
+  if (c.extras.includes("e2e")) commands.push([`${c.pmRunLabel("test:e2e")}`, "run Playwright E2E tests (needs browsers installed)"]);
+  if (c.extras.includes("fallow"))
+    commands.push([`${c.pmRunLabel("quality:audit")}`, "Fallow changed-code audit: dead code, duplication, complexity (run before finishing a task; use --format json for structured findings)"]);
+  if (c.orm !== "none") commands.push([`${c.pmRunLabel("db:push")}`, "push schema changes to the database"]);
+
+  const conventions = [
+    "- TypeScript strict mode is on; fix type errors, don't suppress them.",
+    "- UI components come from shadcn/ui (`src/components/ui/`) — add new ones with `" + c.pmDlxLabel("shadcn@latest") + " add <component>`, don't hand-write them.",
+    "- Styling is Tailwind CSS v4 utility classes; theme tokens are CSS variables defined in `src/index.css`.",
+    "- Path alias: `@/` maps to `src/`.",
+  ];
+  if (c.router === "tanstack") {
+    conventions.push("- Routes are file-based in `src/routes/`; `src/routeTree.gen.ts` is generated — never edit it.");
+  }
+  if (c.backend === "convex") {
+    conventions.push("- Backend functions live in `convex/`; `convex/_generated/` is generated by `convex dev` — never edit it.");
+  }
+  if (c.backend === "hono") {
+    conventions.push("- The API lives in `server/router.ts` (tRPC); the frontend gets full type-safety via `src/lib/trpc.ts`.");
+  }
+  if (c.orm === "drizzle") {
+    conventions.push("- Database schema is in `db/schema.ts` (Drizzle); db code is server-side only, never import it in `src/`.");
+  }
+  if (c.extras.includes("fallow")) {
+    conventions.push(
+      "- Don't leave dead code behind: after refactors, run `" +
+        c.pmRunLabel("quality") +
+        "` (Fallow) and clean up unused exports/files/dependencies it reports.",
+    );
+  }
+  if (c.secure) {
+    conventions.push(
+      "- Supply-chain protection is on: packages must be at least 7 days old to install. If an install fails on a brand-new version, add the package to the exclusion list instead of disabling the protection.",
+    );
+  }
+
+  return `# ${c.name} — agent instructions
+
+## Stack
+
+${stack.map((s) => `- ${s}`).join("\n")}
+
+## Commands
+
+| Command | Purpose |
+| ------- | ------- |
+${commands.map(([cmd, why]) => `| \`${cmd}\` | ${why} |`).join("\n")}
+
+Always run the build (and tests, if present) after making changes to verify they work.
+
+## Conventions
+
+${conventions.join("\n")}
+
+## Environment
+
+Secrets live in \`.env.local\` (client-side, VITE_-prefixed) and \`.env\` (server-side).
+Never commit either file; \`.env.example\` documents what is needed.
+`;
+}
+
+/** CLAUDE.md — imports AGENTS.md (Claude Code @-import syntax). */
+export function claudeMd() {
+  return `@AGENTS.md
+`;
+}