@beignet/cli 0.0.9 → 0.0.11

package/src/mcp.ts

@@ -0,0 +1,367 @@
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { applyDoctorFixes, inspectApp } from "./inspect.js";
+import { lintApp } from "./lint.js";
+import {
+  type MakeResourceResult,
+  makeAdapter,
+  makeContract,
+  makeEvent,
+  makeFactory,
+  makeFeature,
+  makeFeatureAddonChoices,
+  makeJob,
+  makeListener,
+  makeNotification,
+  makePolicy,
+  makePort,
+  makeResource,
+  makeSchedule,
+  makeSeed,
+  makeTask,
+  makeTest,
+  makeUpload,
+  makeUseCase,
+} from "./make.js";
+
+/**
+ * Options for building or running the Beignet MCP server.
+ */
+export type McpServerOptions = {
+  cwd: string;
+  version: string;
+};
+
+const makeArtifactChoices = [
+  "adapter",
+  "contract",
+  "event",
+  "factory",
+  "feature",
+  "job",
+  "listener",
+  "notification",
+  "policy",
+  "port",
+  "resource",
+  "schedule",
+  "seed",
+  "task",
+  "test",
+  "upload",
+  "use-case",
+] as const;
+
+type MakeArtifact = (typeof makeArtifactChoices)[number];
+
+const makeInputSchema = {
+  artifact: z
+    .enum(makeArtifactChoices)
+    .describe("Kind of artifact to generate."),
+  name: z
+    .string()
+    .describe(
+      "Artifact name. Feature-owned artifacts use feature-scoped paths such as posts/backfill.",
+    ),
+  with: z
+    .array(z.enum(makeFeatureAddonChoices))
+    .optional()
+    .describe(
+      "feature only: add feature-owned artifacts such as policy, events, jobs, notifications, tasks, ui, and uploads.",
+    ),
+  event: z
+    .string()
+    .optional()
+    .describe(
+      "listener only (required): event to listen to, for example posts/published.",
+    ),
+  cron: z
+    .string()
+    .optional()
+    .describe("schedule only: cron expression. Defaults to 0 9 * * *."),
+  timezone: z
+    .string()
+    .optional()
+    .describe("schedule only: IANA timezone, for example America/Chicago."),
+  route: z
+    .boolean()
+    .optional()
+    .describe("schedule only: generate a Next.js cron route for the schedule."),
+  auth: z
+    .boolean()
+    .optional()
+    .describe(
+      "resource only: generate policy metadata and use-case authorization checks for mutating routes.",
+    ),
+  tenant: z
+    .boolean()
+    .optional()
+    .describe(
+      "resource only: generate tenant-scoped schemas, repository methods, and use-case checks.",
+    ),
+  events: z
+    .boolean()
+    .optional()
+    .describe(
+      "resource only: generate domain event definitions and publish resource events.",
+    ),
+  softDelete: z
+    .boolean()
+    .optional()
+    .describe(
+      "resource only: generate soft-delete persistence that archives rows with deletedAt.",
+    ),
+  force: z
+    .boolean()
+    .optional()
+    .describe("Overwrite conflicting files instead of failing."),
+  dryRun: z
+    .boolean()
+    .optional()
+    .describe("Preview generated changes without writing files."),
+};
+
+type MakeToolInput = {
+  artifact: MakeArtifact;
+  name: string;
+  with?: Array<(typeof makeFeatureAddonChoices)[number]>;
+  event?: string;
+  cron?: string;
+  timezone?: string;
+  route?: boolean;
+  auth?: boolean;
+  tenant?: boolean;
+  events?: boolean;
+  softDelete?: boolean;
+  force?: boolean;
+  dryRun?: boolean;
+};
+
+type McpToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+};
+
+function jsonResult(value: unknown): McpToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+  };
+}
+
+function errorResult(error: unknown): McpToolResult {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: error instanceof Error ? error.message : String(error),
+      },
+    ],
+  };
+}
+
+async function safeToolResult(
+  run: () => Promise<McpToolResult>,
+): Promise<McpToolResult> {
+  try {
+    return await run();
+  } catch (error) {
+    return errorResult(error);
+  }
+}
+
+async function runMakeTool(
+  cwd: string,
+  input: MakeToolInput,
+): Promise<MakeResourceResult> {
+  const base = {
+    name: input.name,
+    cwd,
+    force: input.force,
+    dryRun: input.dryRun,
+  };
+
+  switch (input.artifact) {
+    case "adapter":
+      return makeAdapter(base);
+    case "contract":
+      return makeContract(base);
+    case "event":
+      return makeEvent(base);
+    case "factory":
+      return makeFactory(base);
+    case "feature":
+      return makeFeature({ ...base, with: input.with });
+    case "job":
+      return makeJob(base);
+    case "listener":
+      if (!input.event) {
+        throw new Error(
+          "make listener requires an event, for example event: posts/published.",
+        );
+      }
+      return makeListener({ ...base, event: input.event });
+    case "notification":
+      return makeNotification(base);
+    case "policy":
+      return makePolicy(base);
+    case "port":
+      return makePort(base);
+    case "resource":
+      return makeResource({
+        ...base,
+        auth: input.auth,
+        tenant: input.tenant,
+        events: input.events,
+        softDelete: input.softDelete,
+      });
+    case "schedule":
+      return makeSchedule({
+        ...base,
+        cron: input.cron,
+        timezone: input.timezone,
+        route: input.route,
+      });
+    case "seed":
+      return makeSeed(base);
+    case "task":
+      return makeTask(base);
+    case "test":
+      return makeTest(base);
+    case "upload":
+      return makeUpload(base);
+    case "use-case":
+      return makeUseCase(base);
+  }
+}
+
+/**
+ * Build the Beignet MCP server with routes, doctor, lint, and make tools.
+ * Every tool resolves against the app directory captured at launch.
+ */
+export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
+  const cwd = path.resolve(options.cwd);
+  const server = new McpServer({
+    name: "beignet",
+    version: options.version,
+  });
+
+  server.registerTool(
+    "routes",
+    {
+      description:
+        "List the app's registered Beignet HTTP routes as JSON: method, path, contract export, contract file, and route handler mapping.",
+      annotations: { readOnlyHint: true },
+    },
+    async () =>
+      safeToolResult(async () => {
+        const result = await inspectApp({ cwd });
+        return jsonResult(
+          result.routes.map((route) => ({
+            method: route.method,
+            path: route.path,
+            contract: route.exportName,
+            file: route.file,
+            handlerFile: route.handlerFile,
+            handlerSource: route.handlerSource,
+            metadata: route.metadata,
+          })),
+        );
+      }),
+  );
+
+  server.registerTool(
+    "doctor",
+    {
+      description:
+        "Check app wiring and Beignet conventions, returning diagnostics, the detected convention, and applied fixes as JSON. Strict mode (the default) is the CI bar and includes CI-oriented warnings. Read-only; use doctor_fix to repair registration drift.",
+      inputSchema: {
+        strict: z
+          .boolean()
+          .optional()
+          .describe("Include CI-oriented warnings. Defaults to true."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async (input) =>
+      safeToolResult(async () => {
+        const result = await inspectApp({ cwd, strict: input.strict ?? true });
+        return jsonResult({
+          diagnostics: result.diagnostics,
+          convention: result.convention,
+          fixes: result.fixes,
+        });
+      }),
+  );
+
+  server.registerTool(
+    "doctor_fix",
+    {
+      description:
+        "Apply low-risk doctor fixes, then re-check the app. Repairs route-group, schedule, task, and outbox registration drift; listener registration drift is report-only. Returns applied fixes and remaining diagnostics as JSON.",
+      inputSchema: {
+        strict: z
+          .boolean()
+          .optional()
+          .describe("Include CI-oriented warnings. Defaults to true."),
+      },
+    },
+    async (input) =>
+      safeToolResult(async () => {
+        const strict = input.strict ?? true;
+        const fixes = await applyDoctorFixes({ cwd, strict });
+        const result = await inspectApp({ cwd, strict });
+        return jsonResult({
+          diagnostics: result.diagnostics,
+          convention: result.convention,
+          fixes,
+        });
+      }),
+  );
+
+  server.registerTool(
+    "lint",
+    {
+      description:
+        "Check Beignet dependency-direction conventions across domain, use cases, routes, components, and infra. Returns lint diagnostics as JSON.",
+      annotations: { readOnlyHint: true },
+    },
+    async () =>
+      safeToolResult(async () => {
+        return jsonResult(await lintApp({ cwd }));
+      }),
+  );
+
+  server.registerTool(
+    "make",
+    {
+      description:
+        "Generate Beignet app files for one artifact: adapter, contract, event, factory, feature, job, listener, notification, policy, port, resource, schedule, seed, task, test, upload, or use-case. Generators auto-register artifacts, so doctor stays clean. Options by artifact: feature accepts with (addons); resource accepts auth, tenant, events, softDelete; listener requires event; schedule accepts cron, timezone, route. All artifacts accept force and dryRun. Returns created, updated, and skipped files as JSON.",
+      inputSchema: makeInputSchema,
+    },
+    async (input) =>
+      safeToolResult(async () => {
+        return jsonResult(await runMakeTool(cwd, input));
+      }),
+  );
+
+  return server;
+}
+
+/**
+ * Run the Beignet MCP server over stdio until the client disconnects.
+ * Stdout belongs to the transport; diagnostics must go to stderr.
+ */
+export async function runMcpServer(options: McpServerOptions): Promise<void> {
+  const server = buildBeignetMcpServer(options);
+  const transport = new StdioServerTransport();
+  const closed = new Promise<void>((resolve) => {
+    server.server.onclose = () => {
+      resolve();
+    };
+  });
+  await server.connect(transport);
+  await closed;
+}

package/src/templates/agents.ts

@@ -0,0 +1,103 @@
+import { json, packageRunner, type TemplateContext } from "./shared.js";
+
+/**
+ * AGENTS.md teaches coding agents the conventions that are not discoverable
+ * from the code: registration wiring, generators, and the validation loop.
+ * README.md owns setup and the app map; this file must not duplicate it.
+ */
+export function agentsMd(ctx: TemplateContext): string {
+  const cli = packageRunner(ctx);
+  const test =
+    ctx.packageManager === "npm"
+      ? "npm run test"
+      : `${ctx.packageManager} run test`;
+  const typecheck =
+    ctx.packageManager === "npm"
+      ? "npm run typecheck"
+      : `${ctx.packageManager} run typecheck`;
+
+  return `# ${ctx.name} — agent guide
+
+This is a Beignet contract-first app. Full framework docs live at
+https://beignetjs.com (agent-friendly index at https://beignetjs.com/llms.txt).
+README.md covers setup and the app map; this file covers what is not
+discoverable from the code.
+
+## Registration is not automatic
+
+Creating an artifact file does not wire it into the app. Non-registration is
+a silent failure — the file exists but never runs:
+
+- Feature route groups in \`features/<feature>/routes.ts\` must be composed in
+  \`server/routes.ts\` via \`defineRoutes([...])\`.
+- Schedules must be added to the \`schedules\` array in \`server/schedules.ts\`.
+- Tasks must be added to \`defineTasks([...])\` in \`server/tasks.ts\`.
+- Outbox events and jobs must be registered in \`defineOutboxRegistry({...})\`
+  in \`server/outbox.ts\`.
+- Listeners must be wired through a \`registerListeners(...)\` call in infra
+  wiring.
+
+The starter ships no workflow registries — generators create them on first
+use, so their absence is fine. \`${cli} doctor\` detects registration drift.
+\`${cli} doctor --fix\` repairs route-group, schedule, task, and outbox
+registration; listener drift is report-only and must be fixed by hand.
+
+## Prefer generators
+
+\`${cli} make <artifact> <name>\` creates correctly placed, pre-registered
+files — prefer it over hand-writing them. See \`${cli} make --help\` for the
+artifact list. After changing the Drizzle schema in \`infra/db/schema/\`, run
+\`${cli} db generate\` then \`${cli} db migrate\`.
+
+## Validation loop
+
+Run after every change:
+
+\`\`\`bash
+${cli} lint
+${cli} doctor --strict
+${test}
+${typecheck}
+\`\`\`
+
+## Placement rules
+
+- Feature artifacts live under \`features/<feature>/\`, with tests in
+  \`features/<feature>/tests/\` (not \`__tests__/\`).
+- Domain and use-case code must not import infra, providers, or React.
+- Routes must not import concrete infra.
+
+## Naming grammar
+
+- \`defineX\` declares things you register: contracts, routes, jobs,
+  schedules, and the rest.
+- \`createX\` builds runtime objects you call: servers, clients, providers,
+  and the \`createX<AppContext>()\` factories that return app-bound
+  \`defineX\` builders.
+
+## MCP server
+
+\`.mcp.json\` registers the \`beignet mcp\` stdio server, which exposes
+routes/doctor/lint/make as structured tools named exactly: \`routes\`,
+\`doctor\`, \`doctor_fix\`, \`lint\`, \`make\`. Clients that do not read
+\`.mcp.json\` can launch \`${cli} mcp\` directly.
+`;
+}
+
+/**
+ * .mcp.json registers the `beignet mcp` stdio server for MCP-aware clients.
+ * The runner must not print banners on stdout, which corrupts JSON-RPC, so
+ * the config launches the locally installed CLI bin via bunx/npx.
+ */
+export function mcpJson(ctx: TemplateContext): string {
+  const command = ctx.packageManager === "bun" ? "bunx" : "npx";
+
+  return json({
+    mcpServers: {
+      beignet: {
+        command,
+        args: ["beignet", "mcp"],
+      },
+    },
+  });
+}

package/src/templates/base.ts

@@ -1,3 +1,4 @@
+import { databaseLocalUrl, databaseStartCommand } from "../choices.js";
 import { shadcnDependencies, shadcnDevDependencies } from "./shadcn.js";
 import {
   externalVersions,
@@ -17,7 +18,6 @@ export function packageJson(ctx: TemplateContext): string {
     "@beignet/provider-auth-better-auth": ctx.beignetVersion,
     "@beignet/provider-db-drizzle": ctx.beignetVersion,
     "@beignet/provider-logger-pino": ctx.beignetVersion,
-    "@libsql/client": externalVersions.libsqlClient,
     "better-auth": externalVersions.betterAuth,
     "drizzle-orm": externalVersions.drizzleOrm,
     next: externalVersions.next,
@@ -27,6 +27,19 @@ export function packageJson(ctx: TemplateContext): string {
     zod: externalVersions.zod,
   };
 
+  // Ship only the selected database driver.
+  switch (ctx.database) {
+    case "postgres":
+      dependencies.pg = externalVersions.pg;
+      break;
+    case "mysql":
+      dependencies.mysql2 = externalVersions.mysql2;
+      break;
+    default:
+      dependencies["@libsql/client"] = externalVersions.libsqlClient;
+      break;
+  }
+
   if (!ctx.api) {
     dependencies["@beignet/react-query"] = ctx.beignetVersion;
     dependencies["@beignet/react-hook-form"] = ctx.beignetVersion;
@@ -61,6 +74,12 @@ export function packageJson(ctx: TemplateContext): string {
     typescript: externalVersions.typescript,
   };
 
+  if (ctx.database === "postgres") {
+    // PGlite backs infra/db/test-database.ts with in-process Postgres.
+    devDependencies["@electric-sql/pglite"] = externalVersions.pglite;
+    devDependencies["@types/pg"] = externalVersions.typesPg;
+  }
+
   if (!ctx.api) {
     for (const [name, version] of Object.entries(shadcnDevDependencies)) {
       devDependencies[name] = version;
@@ -134,6 +153,30 @@ export function readme(ctx: TemplateContext): string {
 - \`client/\` owns the typed API client, React Query helpers, and the Better Auth client.
 `;
 
+  const startDatabase =
+    ctx.database === "sqlite"
+      ? ""
+      : `## Start the database
+
+\`\`\`bash
+${databaseStartCommand(ctx.database, ctx.name)}
+\`\`\`
+
+The starter's \`.env.example\` points at this local ${ctx.database === "postgres" ? "Postgres" : "MySQL"} container. Point \`${ctx.database === "postgres" ? "POSTGRES_DB_URL" : "MYSQL_DB_URL"}\` at your own server to skip Docker.
+
+`;
+
+  const testingNotes =
+    ctx.database === "postgres"
+      ? `
+\`infra/db/test-database.ts\` runs repository tests against in-process Postgres via PGlite, so \`${test}\` needs no database server.
+`
+      : ctx.database === "mysql"
+        ? `
+The starter's shipped tests use in-memory ports and need no database server. Database-backed tests can use \`createTestDatabase()\` from \`infra/db/test-database.ts\`, which requires \`MYSQL_TEST_URL\` (see the docker one-liner in \`.env.example\`), creates a uniquely named database per call, and drops it on close. Gate such tests with \`test.skipIf(!isMysqlTestDatabaseAvailable())\`.
+`
+        : "";
+
   return `# ${ctx.name}
 
 Beignet app scaffolded with \`@beignet/cli\`.
@@ -145,7 +188,7 @@ ${install}
 cp .env.example .env.local
 \`\`\`
 
-## Prepare the database
+${startDatabase}## Prepare the database
 
 \`\`\`bash
 ${cli} db migrate
@@ -173,7 +216,7 @@ ${typecheck}
 \`\`\`
 
 \`routes\` shows the contracts Beignet can inspect. \`lint\` checks dependency direction. \`doctor\` catches route, OpenAPI, and resource drift.
-
+${testingNotes}
 ## Build for production
 
 \`\`\`bash
@@ -207,16 +250,42 @@ ${cli} doctor
 - \`infra/db/schema/\` contains the Drizzle schema, \`drizzle/\` contains the checked-in migrations, and \`infra/todos/\` contains the durable todo repository adapter.
 - \`server/routes.ts\` keeps the central route registry and OpenAPI contract list.
 - \`server/context.ts\` declares the context blueprint shared by the server and route tests.
-- \`server/providers.ts\` wires devtools, Better Auth, pino, Drizzle/libSQL, and the starter database provider.
+- \`server/providers.ts\` wires devtools, Better Auth, pino, ${
+    ctx.database === "sqlite"
+      ? "Drizzle/libSQL"
+      : ctx.database === "postgres"
+        ? "Drizzle/node-postgres"
+        : "Drizzle/mysql2"
+  }, and the starter database provider.
 - \`lib/env.ts\` validates deployment configuration at startup.
 - \`lib/auth.ts\` exposes \`requireUser(ctx)\` for protected use cases.
 - \`lib/better-auth.ts\` owns Better Auth setup and keeps provider-specific auth details outside use cases.
 ${shellMap}
 ## Before deploying
 
-- Keep \`SQLITE_DB_URL=file:local.db\` for local libSQL development or point it at a hosted libSQL database such as Turso.
+- ${
+    ctx.database === "sqlite"
+      ? "Keep `SQLITE_DB_URL=file:local.db` for local libSQL development or point it at a hosted libSQL database such as Turso."
+      : ctx.database === "postgres"
+        ? "Point `POSTGRES_DB_URL` at your production Postgres 14+ server and run `" +
+          cli +
+          " db migrate` against it before starting the app."
+        : "Point `MYSQL_DB_URL` at your production MySQL 8.0+ server and run `" +
+          cli +
+          " db migrate` against it before starting the app."
+  }
 - Run \`${cli} db generate\` and \`${cli} db migrate\` after changing the Drizzle schema.
-- Run \`${cli} db reset\` to rebuild a local SQLite database from the checked-in migrations.
+- Run \`${cli} db reset\` to rebuild a local ${
+    ctx.database === "sqlite"
+      ? "SQLite"
+      : ctx.database === "postgres"
+        ? "Postgres"
+        : "MySQL"
+  } database from the checked-in migrations${
+    ctx.database === "sqlite"
+      ? ""
+      : "; it refuses non-local hosts unless `BEIGNET_ALLOW_DATABASE_RESET=true`"
+  }.
 - Remove \`DEVTOOLS_ENABLED=true\` in production unless you add authentication and stricter redaction.
 - Set \`APP_URL\`, \`BETTER_AUTH_SECRET\`, \`LOG_LEVEL\`, and service-specific integration variables in your hosting environment.
 - Set \`BETTER_AUTH_TRUSTED_ORIGINS\` before serving auth across multiple origins.
@@ -276,6 +345,25 @@ export function integrationsDoc(ctx: TemplateContext): string {
 }
 
 export function envExample(ctx: TemplateContext): string {
+  const databaseLines =
+    ctx.database === "sqlite"
+      ? [
+          "# Use file:local.db for local libSQL or libsql://... for Turso cloud.",
+          "SQLITE_DB_URL=file:local.db",
+          "# SQLITE_DB_AUTH_TOKEN=",
+        ]
+      : ctx.database === "postgres"
+        ? [
+            "# Local Postgres matching the docker one-liner below; point at your own server in production.",
+            `# ${databaseStartCommand("postgres", ctx.name)}`,
+            `POSTGRES_DB_URL=${databaseLocalUrl("postgres", ctx.name)}`,
+          ]
+        : [
+            "# Local MySQL matching the docker one-liner below; point at your own server in production.",
+            `# ${databaseStartCommand("mysql", ctx.name)}`,
+            `MYSQL_DB_URL=${databaseLocalUrl("mysql", ctx.name)}`,
+          ];
+
   const lines = [
     "# Copy to .env.local and fill in values for your app.",
     "APP_URL=http://localhost:3000",
@@ -287,9 +375,7 @@ export function envExample(ctx: TemplateContext): string {
     "LOG_FORMAT=json",
     `LOG_SERVICE=${ctx.name}`,
     "",
-    "# Use file:local.db for local libSQL or libsql://... for Turso cloud.",
-    "SQLITE_DB_URL=file:local.db",
-    "# SQLITE_DB_AUTH_TOKEN=",
+    ...databaseLines,
     "",
     "BETTER_AUTH_SECRET=local-dev-better-auth-secret-change-me",
     "BETTER_AUTH_URL=http://localhost:3000",

package/src/templates/db/index.ts

@@ -0,0 +1,34 @@
+import type { TemplateContext } from "../shared.js";
+import { mysqlDbFiles } from "./mysql.js";
+import { postgresDbFiles } from "./postgres.js";
+import { sqliteDbFiles } from "./sqlite.js";
+
+/**
+ * Generated database files shared by every dialect. Each dialect module
+ * provides the full set so the scaffold surface stays stable across `--db`
+ * choices.
+ */
+export type DbTemplateFiles = {
+  drizzleConfig: string;
+  dbSchema: string;
+  drizzleTodoRepository: string;
+  dbRepositories: string;
+  databaseReady: string;
+  dbProvider: string;
+  dbReset: string;
+  dbTestDatabase: string;
+  starterMigrationSql: string;
+  starterMigrationJournal: string;
+  starterMigrationSnapshot: string;
+};
+
+export function dbFiles(ctx: TemplateContext): DbTemplateFiles {
+  switch (ctx.database) {
+    case "postgres":
+      return postgresDbFiles(ctx);
+    case "mysql":
+      return mysqlDbFiles(ctx);
+    default:
+      return sqliteDbFiles();
+  }
+}