@beignet/cli 0.0.10 → 0.0.12

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,115 @@
+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 lint =
+    ctx.packageManager === "npm"
+      ? "npm run lint"
+      : `${ctx.packageManager} run lint`;
+  const format =
+    ctx.packageManager === "npm"
+      ? "npm run format"
+      : `${ctx.packageManager} run format`;
+  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
+${lint}
+${cli} lint
+${cli} doctor --strict
+${test}
+${typecheck}
+\`\`\`
+
+\`${lint}\` runs Biome's code lint. Use \`${format}\` to apply formatting.
+\`${cli} lint\` is Beignet's dependency-direction lint.
+
+## 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

@@ -66,6 +66,7 @@ export function packageJson(ctx: TemplateContext): string {
   const devDependencies: Record<string, string> = {
     "@beignet/cli": ctx.beignetVersion,
     "@beignet/web": ctx.beignetVersion,
+    "@biomejs/biome": externalVersions.biome,
     "@types/bun": externalVersions.typesBun,
     "@types/node": externalVersions.typesNode,
     "@types/react": externalVersions.typesReact,
@@ -94,6 +95,8 @@ export function packageJson(ctx: TemplateContext): string {
     dev: "next dev",
     build: "next build",
     start: "next start",
+    lint: "biome lint .",
+    format: "biome format --write .",
     test: "bun test",
     typecheck: "tsc --noEmit",
     "db:generate": "drizzle-kit generate",
@@ -136,6 +139,14 @@ export function readme(ctx: TemplateContext): string {
     ctx.packageManager === "npm"
       ? "npm run test"
       : `${ctx.packageManager} run test`;
+  const lint =
+    ctx.packageManager === "npm"
+      ? "npm run lint"
+      : `${ctx.packageManager} run lint`;
+  const format =
+    ctx.packageManager === "npm"
+      ? "npm run format"
+      : `${ctx.packageManager} run format`;
   const typecheck =
     ctx.packageManager === "npm"
       ? "npm run typecheck"
@@ -209,13 +220,15 @@ ${firstOpen}
 \`\`\`bash
 # in another terminal
 ${cli} routes
+${lint}
 ${cli} lint
 ${cli} doctor
 ${test}
 ${typecheck}
 \`\`\`
 
-\`routes\` shows the contracts Beignet can inspect. \`lint\` checks dependency direction. \`doctor\` catches route, OpenAPI, and resource drift.
+\`routes\` shows the contracts Beignet can inspect. \`${cli} lint\` checks dependency direction. \`doctor\` catches route, OpenAPI, and resource drift.
+\`${lint}\` runs Biome over the starter; use \`${format}\` to apply formatting.
 ${testingNotes}
 ## Build for production
 
@@ -231,6 +244,7 @@ ${cli} make feature projects
 ${cli} db generate
 ${cli} db migrate
 ${test}
+${lint}
 ${typecheck}
 ${cli} lint
 ${cli} doctor
@@ -429,6 +443,42 @@ const nextConfig = {};
 
 export default nextConfig;
 `,
+  biomeConfig: json({
+    $schema: "https://biomejs.dev/schemas/2.4.14/schema.json",
+    vcs: {
+      enabled: true,
+      clientKind: "git",
+      useIgnoreFile: true,
+    },
+    formatter: {
+      enabled: true,
+      indentStyle: "tab",
+    },
+    linter: {
+      enabled: true,
+      rules: {
+        recommended: true,
+        suspicious: {
+          noExplicitAny: "warn",
+          useIterableCallbackReturn: "warn",
+        },
+        correctness: {
+          noUnusedImports: "off",
+          useHookAtTopLevel: "off",
+        },
+      },
+    },
+    javascript: {
+      formatter: {
+        quoteStyle: "double",
+      },
+    },
+    css: {
+      parser: {
+        tailwindDirectives: true,
+      },
+    },
+  }),
   tsconfig: json({
     compilerOptions: {
       target: "ES2017",

package/src/templates/db/mysql.ts

@@ -207,7 +207,7 @@ export function createDrizzleTodoRepository(
     dbRepositories: `import type { DrizzleMysqlDatabase } from "@beignet/provider-db-drizzle/mysql";
 import { createDrizzleTodoRepository } from "@/infra/todos/drizzle-todo-repository";
 import type { AppTransactionPorts } from "@/ports";
-import * as schema from "./schema";
+import type * as schema from "./schema";
 
 export function createRepositories(
 	db: DrizzleMysqlDatabase<typeof schema>,

package/src/templates/db/postgres.ts

@@ -195,7 +195,7 @@ export function createDrizzleTodoRepository(
     dbRepositories: `import type { DrizzlePostgresDatabase } from "@beignet/provider-db-drizzle/postgres";
 import { createDrizzleTodoRepository } from "@/infra/todos/drizzle-todo-repository";
 import type { AppTransactionPorts } from "@/ports";
-import * as schema from "./schema";
+import type * as schema from "./schema";
 
 export function createRepositories(
 	db: DrizzlePostgresDatabase<typeof schema>,

package/src/templates/db/sqlite.ts

@@ -191,7 +191,7 @@ export function createDrizzleTodoRepository(
   dbRepositories: `import type { DrizzleSqliteDatabase } from "@beignet/provider-db-drizzle/sqlite";
 import { createDrizzleTodoRepository } from "@/infra/todos/drizzle-todo-repository";
 import type { AppTransactionPorts } from "@/ports";
-import * as schema from "./schema";
+import type * as schema from "./schema";
 
 export function createRepositories(
 	db: DrizzleSqliteDatabase<typeof schema>,
@@ -354,8 +354,8 @@ export type TestDatabase = {
 };
 
 export async function createTestDatabase(): Promise<TestDatabase> {
-	const path = join(tmpdir(), "beignet-test-" + crypto.randomUUID() + ".db");
-	const client = createClient({ url: "file:" + path });
+	const path = join(tmpdir(), \`beignet-test-\${crypto.randomUUID()}.db\`);
+	const client = createClient({ url: \`file:\${path}\` });
 	const db = drizzle(client, { schema });
 	await migrate(db, { migrationsFolder: "drizzle" });
 

package/src/templates/index.ts

@@ -7,6 +7,7 @@ export type {
 export { databaseChoices, integrationChoices } from "../choices.js";
 export type { TemplateContext, TemplateFile } from "./shared.js";
 
+import { agentsMd, mcpJson } from "./agents.js";
 import {
   baseFiles,
   envExample,
@@ -42,10 +43,13 @@ export function getTemplateFiles(ctx: TemplateContext): TemplateFile[] {
   const templateFiles: TemplateFile[] = [
     { path: "package.json", content: packageJson(ctx) },
     { path: "README.md", content: readme(ctx) },
+    { path: "AGENTS.md", content: agentsMd(ctx) },
+    { path: ".mcp.json", content: mcpJson(ctx) },
     { path: ".gitignore", content: baseFiles.gitignore },
     { path: ".env.example", content: envExample(ctx) },
     { path: "next-env.d.ts", content: baseFiles.nextEnv },
     { path: "next.config.js", content: baseFiles.nextConfig },
+    { path: "biome.json", content: baseFiles.biomeConfig },
     { path: "tsconfig.json", content: baseFiles.tsconfig },
     { path: "app-context.ts", content: serverFiles.appContext },
     {

package/src/templates/shared.ts

@@ -31,6 +31,7 @@ export type TemplateContext = {
 };
 
 export const externalVersions = {
+  biome: "^2.4.14",
   next: "^16.2.4",
   react: "^19.2.5",
   reactDom: "^19.2.5",