create-better-t-stack 3.22.3 → 3.23.0

package/README.md

@@ -40,8 +40,8 @@ Follow the prompts to configure your project or use the `--yes` flag for default
 | **ORM**                  | • Drizzle (TypeScript-first)<br>• Prisma (feature-rich)<br>• Mongoose (for MongoDB)<br>• None                                                                                                                                                              |
 | **Database Setup**       | • Turso (SQLite)<br>• Cloudflare D1 (SQLite)<br>• Neon (PostgreSQL)<br>• Supabase (PostgreSQL)<br>• Prisma Postgres<br>• MongoDB Atlas<br>• None (manual setup)                                                                                            |
 | **Authentication**       | Better-Auth (email/password, with more options coming soon)                                                                                                                                                                                                |
-| **Styling**              | Tailwind CSS with shadcn/ui components                                                                                                                                                                                                                     |
-| **Addons**               | • PWA support<br>• Tauri (desktop applications)<br>• Starlight (documentation site)<br>• Biome (linting and formatting)<br>• Lefthook, Husky (Git hooks)<br>• Turborepo (optimized builds)                                                                 |
+| **Styling**              | Tailwind CSS with a shared shadcn/ui package for React web apps                                                                                                                                                                                            |
+| **Addons**               | • PWA support<br>• Tauri (desktop applications)<br>• Starlight (documentation site)<br>• Biome (linting and formatting)<br>• Lefthook, Husky (Git hooks)<br>• Turborepo or Nx (monorepo orchestration)                                                     |
 | **Examples**             | • Todo app<br>• AI Chat interface (using Vercel AI SDK)                                                                                                                                                                                                    |
 | **Developer Experience** | • Automatic Git initialization<br>• Package manager choice (npm, pnpm, bun)<br>• Automatic dependency installation                                                                                                                                         |
 
@@ -56,10 +56,11 @@ Options:
   --template <type>               Use a template (mern, pern, t3, uniwind, none)
   --database <type>               Database type (none, sqlite, postgres, mysql, mongodb)
   --orm <type>                    ORM type (none, drizzle, prisma, mongoose)
+  --dry-run                       Validate configuration without writing files
   --auth <provider>               Authentication (better-auth, clerk, none)
   --payments <provider>           Payments provider (polar, none)
   --frontend <types...>           Frontend types (tanstack-router, react-router, tanstack-start, next, nuxt, svelte, solid, astro, native-bare, native-uniwind, native-unistyles, none)
-  --addons <types...>             Additional addons (pwa, tauri, starlight, biome, lefthook, husky, ruler, mcp, turborepo, fumadocs, ultracite, oxlint, opentui, wxt, skills, none)
+  --addons <types...>             Additional addons (pwa, tauri, starlight, biome, lefthook, husky, ruler, mcp, turborepo, nx, fumadocs, ultracite, oxlint, opentui, wxt, skills, none)
   --examples <types...>           Examples to include (todo, ai, none)
   --git                           Initialize git repository
   --no-git                        Skip git initialization
@@ -77,6 +78,30 @@ Options:
   -h, --help                      Display help
 ```
 
+### Agent-Focused Commands
+
+```bash
+# Raw JSON payload input (agent-friendly)
+create-better-t-stack create-json --input '{"projectName":"my-app","yes":true,"dryRun":true}'
+create-better-t-stack add-json --input '{"projectDir":"./my-app","addons":["wxt"],"addonOptions":{"wxt":{"template":"react"}}}'
+create-better-t-stack create-json --input '{"projectName":"db-app","database":"postgres","orm":"drizzle","dbSetup":"neon","dbSetupOptions":{"mode":"manual"}}'
+
+# Runtime schema/introspection output
+create-better-t-stack schema --name all
+create-better-t-stack schema --name createInput
+create-better-t-stack schema --name addInput
+create-better-t-stack schema --name addonOptions
+create-better-t-stack schema --name dbSetupOptions
+create-better-t-stack schema --name cli
+
+# Local stdio MCP server
+npx create-better-t-stack@latest mcp
+```
+
+When you scaffold with the `mcp` addon, Better T Stack itself can also be installed into supported agent configs through `add-mcp` using a package runner command instead of assuming a global CLI install, for example `npx create-better-t-stack@latest mcp` or `bunx create-better-t-stack@latest mcp`.
+
+For MCP project creation, prefer `install: false`. Long dependency installs can exceed common MCP client request timeouts, so the safest flow is to scaffold first and run your package manager install command afterward in the project directory.
+
 ## Telemetry
 
 This CLI collects anonymous usage data to help improve the tool. The data collected includes:
@@ -108,6 +133,12 @@ Create a project with default configuration:
 npx create-better-t-stack --yes
 ```
 
+Validate a command without writing files:
+
+```bash
+npx create-better-t-stack --yes --dry-run
+```
+
 Create a project with specific options:
 
 ```bash

package/dist/{chunk-C8ucw2H5.mjs → chunk-BtN16TXe.mjs}

@@ -6,32 +6,23 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
-	for (var name in all) {
-		__defProp(target, name, {
-			get: all[name],
-			enumerable: true
-		});
-	}
-	if (!no_symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-	}
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
 	}
 	return to;
 };
 var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
-
 //#endregion
-export { __reExport as n, __exportAll as t };
+export { __reExport as n, __exportAll as t };

package/dist/cli.mjs

@@ -1,9 +1,293 @@
 #!/usr/bin/env node
-import "./command-handlers-Dvaw7W_l.mjs";
-import { createBtsCli } from "./index.mjs";
-
+import { _ as types_exports, i as SchemaNameSchema, l as create, m as getSchemaResult, s as add, u as createBtsCli, v as getLatestCLIVersion } from "./src-COTG6r9y.mjs";
+import z from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/mcp.ts
+const ToolResponseSchema = z.object({
+	ok: z.boolean(),
+	data: z.any().optional(),
+	error: z.string().optional()
+});
+const McpCreateProjectInputSchema = types_exports.CreateInputSchema.safeExtend({
+	projectName: z.string().describe("Project name or relative path"),
+	frontend: z.array(types_exports.FrontendSchema).describe("Explicit frontend app surfaces. Do not use native frontends as styling options."),
+	backend: types_exports.BackendSchema.describe("Explicit backend framework"),
+	runtime: types_exports.RuntimeSchema.describe("Explicit runtime environment"),
+	database: types_exports.DatabaseSchema.describe("Explicit database choice"),
+	orm: types_exports.ORMSchema.describe("Explicit ORM choice"),
+	api: types_exports.APISchema.describe("Explicit API layer"),
+	auth: types_exports.AuthSchema.describe("Explicit authentication provider"),
+	payments: types_exports.PaymentsSchema.describe("Explicit payments provider"),
+	addons: z.array(types_exports.AddonsSchema).describe("Explicit addon list. Use [] when no addons are needed."),
+	examples: z.array(types_exports.ExamplesSchema).describe("Explicit example list. Use [] when no examples are needed."),
+	git: z.boolean().describe("Whether to initialize a git repository"),
+	packageManager: types_exports.PackageManagerSchema.describe("Explicit package manager"),
+	install: z.boolean().describe("Whether to install dependencies"),
+	dbSetup: types_exports.DatabaseSetupSchema.describe("Explicit database setup/provisioning choice"),
+	webDeploy: types_exports.WebDeploySchema.describe("Explicit web deployment choice"),
+	serverDeploy: types_exports.ServerDeploySchema.describe("Explicit server deployment choice"),
+	addonOptions: types_exports.AddonOptionsSchema.optional(),
+	dbSetupOptions: types_exports.DbSetupOptionsSchema.optional(),
+	directoryConflict: types_exports.DirectoryConflictSchema.optional()
+}).describe("Explicit Better T Stack project configuration for MCP use. Provide the full stack config instead of relying on inferred defaults.");
+function formatToolSuccess(data) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}],
+		structuredContent: {
+			ok: true,
+			data
+		}
+	};
+}
+function formatToolError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		structuredContent: {
+			ok: false,
+			error: message
+		},
+		isError: true
+	};
+}
+function getProjectToolAnnotations() {
+	return {
+		destructiveHint: true,
+		idempotentHint: false,
+		openWorldHint: true
+	};
+}
+function getMcpInstallTimeoutMessage(packageManager) {
+	return [
+		"MCP project creation requires `install: false`.",
+		"Dependency installation can exceed common MCP client request timeouts and cause the connection to close before the tool returns.",
+		`Scaffold the project first, then run \`${packageManager} install\` in the generated project directory from a terminal.`
+	].join(" ");
+}
+function getStackGuidance() {
+	return {
+		workflow: [
+			"Call bts_get_schema or bts_get_stack_guidance before constructing a config if the request is ambiguous.",
+			"For project creation, build a full explicit config before calling bts_plan_project.",
+			"Always call bts_plan_project before bts_create_project.",
+			"Only call bts_create_project after the plan succeeds and matches the user's intent.",
+			"Use bts_plan_addons before bts_add_addons for existing projects."
+		],
+		createContract: {
+			requiresExplicitFields: [
+				"projectName",
+				"frontend",
+				"backend",
+				"runtime",
+				"database",
+				"orm",
+				"api",
+				"auth",
+				"payments",
+				"addons",
+				"examples",
+				"git",
+				"packageManager",
+				"install",
+				"dbSetup",
+				"webDeploy",
+				"serverDeploy"
+			],
+			optionalFields: [
+				"addonOptions",
+				"dbSetupOptions",
+				"directoryConflict"
+			],
+			rule: "Do not call bts_plan_project or bts_create_project with a partial payload. MCP project creation requires the full explicit stack config."
+		},
+		fieldNotes: {
+			frontend: "frontend is for app surfaces only. Choose explicit app targets such as next, react-router, tanstack-router, native-bare, native-uniwind, or native-unistyles.",
+			addons: "addons must be an explicit array. Use [] when no addons are requested.",
+			examples: "examples must be an explicit array. Use [] when no examples are requested.",
+			dbSetup: "dbSetup is always required. Use 'none' when no managed database provisioning is requested.",
+			webDeploy: "webDeploy is always required. Use 'none' when no web deployment target is requested.",
+			serverDeploy: "serverDeploy is always required. Use 'none' when no server deployment target is requested.",
+			packageManager: "packageManager is always required because installation and reproducible commands depend on it.",
+			install: "install is always required. For MCP project creation, prefer false because many clients enforce request timeouts around long-running dependency installs.",
+			git: "git is always required. Set it to true or false explicitly instead of relying on defaults."
+		},
+		ambiguityRules: [
+			"If the user request leaves major stack choices unspecified, stop and resolve them before calling bts_plan_project.",
+			"Do not infer extra app surfaces, addons, examples, or provisioning choices from a template name or styling preference.",
+			"If the user wants the smallest valid stack, still send the full config with explicit 'none', [] , true, or false values where appropriate.",
+			"For MCP execution, scaffold with install=false and let the user or agent run dependency installation separately from a terminal session."
+		]
+	};
+}
+function createBtsMcpServer() {
+	const server = new McpServer({
+		name: "create-better-t-stack",
+		version: getLatestCLIVersion()
+	}, { capabilities: { logging: {} } });
+	server.registerTool("bts_get_stack_guidance", {
+		title: "Get Better T Stack MCP Guidance",
+		description: "Read MCP-specific guidance for choosing valid Better T Stack configurations. Use this before planning when user intent is ambiguous. This explains the full explicit config required by MCP project creation, plus important field semantics and ambiguity rules.",
+		inputSchema: z.object({}),
+		outputSchema: ToolResponseSchema,
+		annotations: {
+			title: "Get Better T Stack MCP Guidance",
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => {
+		try {
+			return formatToolSuccess(getStackGuidance());
+		} catch (error) {
+			return formatToolError(error);
+		}
+	});
+	server.registerTool("bts_get_schema", {
+		title: "Get Better T Stack Schemas",
+		description: "Inspect Better T Stack CLI and input schemas so agents can plan valid create/add requests. Use this together with bts_get_stack_guidance before creating a project if any part of the request is ambiguous.",
+		inputSchema: z.object({ name: SchemaNameSchema.optional().describe("Schema name to inspect. Defaults to all.") }),
+		outputSchema: ToolResponseSchema,
+		annotations: {
+			title: "Get Better T Stack Schemas",
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async ({ name }) => {
+		try {
+			return formatToolSuccess(getSchemaResult(name ?? "all"));
+		} catch (error) {
+			return formatToolError(error);
+		}
+	});
+	server.registerTool("bts_plan_project", {
+		title: "Plan Better T Stack Project",
+		description: "Validate and preview a Better T Stack project creation without writing files or provisioning resources. Always use this before bts_create_project. This tool requires an explicit full stack config rather than a partial payload with inferred defaults.",
+		inputSchema: McpCreateProjectInputSchema,
+		outputSchema: ToolResponseSchema,
+		annotations: {
+			title: "Plan Better T Stack Project",
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => {
+		try {
+			const result = await create(input.projectName, {
+				...input,
+				dryRun: true,
+				disableAnalytics: true
+			});
+			if (result.isErr()) return formatToolError(result.error);
+			return formatToolSuccess(input.install ? {
+				...result.value,
+				warnings: [getMcpInstallTimeoutMessage(input.packageManager)],
+				recommendedMcpExecution: {
+					...input,
+					install: false
+				}
+			} : result.value);
+		} catch (error) {
+			return formatToolError(error);
+		}
+	});
+	server.registerTool("bts_create_project", {
+		title: "Create Better T Stack Project",
+		description: "Create a Better T Stack project on disk using the same silent programmatic flow as the CLI JSON API. Call this only after bts_plan_project succeeds and the plan clearly matches the user's intent. This tool requires an explicit full stack config.",
+		inputSchema: McpCreateProjectInputSchema,
+		outputSchema: ToolResponseSchema,
+		annotations: {
+			title: "Create Better T Stack Project",
+			...getProjectToolAnnotations()
+		}
+	}, async (input) => {
+		try {
+			if (input.install) return formatToolError(getMcpInstallTimeoutMessage(input.packageManager));
+			const result = await create(input.projectName, {
+				...input,
+				disableAnalytics: true
+			});
+			if (result.isErr()) return formatToolError(result.error);
+			return formatToolSuccess(result.value);
+		} catch (error) {
+			return formatToolError(error);
+		}
+	});
+	server.registerTool("bts_plan_addons", {
+		title: "Plan Better T Stack Addons",
+		description: "Validate and preview addon installation for an existing Better T Stack project without writing files. Always use this before bts_add_addons when the addon set or nested options are uncertain.",
+		inputSchema: types_exports.AddInputSchema,
+		outputSchema: ToolResponseSchema,
+		annotations: {
+			title: "Plan Better T Stack Addons",
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => {
+		try {
+			const result = await add({
+				...input,
+				dryRun: true
+			});
+			if (!result?.success) return formatToolError(result?.error ?? "Failed to plan addon installation");
+			return formatToolSuccess(result);
+		} catch (error) {
+			return formatToolError(error);
+		}
+	});
+	server.registerTool("bts_add_addons", {
+		title: "Add Better T Stack Addons",
+		description: "Install addons into an existing Better T Stack project using the same silent flow as add-json. Call this only after bts_plan_addons succeeds and the planned changes match the user's intent.",
+		inputSchema: types_exports.AddInputSchema,
+		outputSchema: ToolResponseSchema,
+		annotations: {
+			title: "Add Better T Stack Addons",
+			destructiveHint: true,
+			idempotentHint: false,
+			openWorldHint: true
+		}
+	}, async (input) => {
+		try {
+			const result = await add(input);
+			if (!result?.success) return formatToolError(result?.error ?? "Failed to add addons");
+			return formatToolSuccess(result);
+		} catch (error) {
+			return formatToolError(error);
+		}
+	});
+	return server;
+}
+async function startBtsMcpServer() {
+	const server = createBtsMcpServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+//#endregion
 //#region src/cli.ts
-createBtsCli().run();
+const [, , command, ...args] = process.argv;
+if (command === "mcp") {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(`Usage: create-better-t-stack mcp
+
+Start the Better T Stack MCP server over stdio.
 
+This command is intended to be launched by an MCP client, for example:
+  create-better-t-stack mcp`);
+		process.exit(0);
+	}
+	await startBtsMcpServer();
+} else createBtsCli().run();
 //#endregion
-export {  };
+export {};