@0x0501/mystack 0.0.0-stage → 0.1.0-bootstrap.0

package/src/cli.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs, stripVTControlCharacters } from "node:util";
+import {
+	cancel,
+	confirm,
+	intro,
+	isCancel,
+	log,
+	multiselect,
+	note,
+	outro,
+	select,
+	spinner,
+	text,
+} from "@clack/prompts";
+import {
+	catalog,
+	choices,
+	defaults,
+	incompatibilities,
+	isPostgres,
+	validateSelection,
+} from "./catalog.mjs";
+import { createProject, validateName } from "./generate.mjs";
+
+const help = `mystack create [name] [options]
+
+Create a configured TanStack Start project with an interactive wizard.
+Run mystack without arguments to open the wizard.
+
+  --database ${catalog.database.map((option) => option.id).join("|")}
+  --deployment cloudflare|nitro|bun
+  --email cloudflare|resend
+  --payments stripe,creem,nowpayments,polar|none
+  --yes          Use defaults for unspecified options
+  --no-install   Generate without installing dependencies
+  --help         Show this help
+
+Example: mystack create my-app --database d1 --payments stripe,polar
+Package manager: Bun. Hyperdrive, D1 and Cloudflare Email require Cloudflare Workers.
+Turso Local needs a filesystem. Bun SQLite requires the Bun deployment.
+`;
+
+class PromptCancelled extends Error {}
+
+async function answer(prompt) {
+	const value = await prompt;
+	if (isCancel(value)) throw new PromptCancelled();
+	return value;
+}
+
+async function step(message, complete, task) {
+	const progress = spinner();
+	progress.start(message);
+	try {
+		const result = await task(progress.message);
+		progress.stop(complete);
+		return result;
+	} catch (error) {
+		progress.error("Step failed");
+		throw error;
+	}
+}
+
+export function installDependencies(target) {
+	return new Promise((resolveInstall, reject) => {
+		const child = spawn("bun", ["install"], {
+			cwd: target,
+			stdio: ["ignore", "pipe", "pipe"],
+			shell: false,
+		});
+		let output = "";
+		const capture = (chunk) => {
+			output = (output + chunk.toString()).slice(-16_384);
+		};
+		child.stdout.on("data", capture);
+		child.stderr.on("data", capture);
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			if (code === 0) resolveInstall();
+			else
+				reject(
+					new Error(
+						`bun install ${signal ? `was stopped by ${signal}` : `exited with ${code}`}\n${stripVTControlCharacters(output).trim()}`,
+					),
+				);
+		});
+	});
+}
+
+export async function main(args = process.argv.slice(2)) {
+	try {
+		const { values, positionals } = parseArgs({
+			args,
+			allowPositionals: true,
+			options: {
+				database: { type: "string" },
+				deployment: { type: "string" },
+				email: { type: "string" },
+				payments: { type: "string" },
+				yes: { type: "boolean", short: "y" },
+				"no-install": { type: "boolean" },
+				help: { type: "boolean", short: "h" },
+			},
+		});
+		if (values.help) {
+			console.log(help);
+			return 0;
+		}
+		const [command = "create", projectName] = positionals;
+		if (command !== "create" || positionals.length > 2) throw new Error(help);
+		const selection = {};
+		for (const category of ["database", "deployment", "email"]) {
+			if (values[category] !== undefined)
+				selection[category] = values[category];
+		}
+		if (values.payments !== undefined)
+			selection.payments =
+				values.payments === "none"
+					? []
+					: values.payments.split(",").map((id) => id.trim());
+		const invalid = incompatibilities(selection);
+		if (invalid.length) throw new Error(invalid.join("\n"));
+		if (!values.yes && !process.stdin.isTTY)
+			throw new Error(
+				"Interactive input requires a terminal. Use --yes and configuration flags in automation.",
+			);
+		intro(
+			values.yes
+				? `Creating a new Mystack app in ${projectName ?? "my-app"}...`
+				: "Let's configure your Mystack application",
+		);
+		const checkName = (value) => {
+			try {
+				validateName(value);
+				if (existsSync(resolve(value)))
+					return `Directory '${value}' already exists. Choose another project name.`;
+			} catch (error) {
+				return error.message;
+			}
+		};
+		const name =
+			projectName ??
+			(values.yes
+				? "my-app"
+				: await answer(
+						text({
+							message: "Project name",
+							placeholder: "my-app",
+							defaultValue: "my-app",
+							validate: (value) => checkName(value || "my-app"),
+						}),
+					));
+		const nameError = checkName(name);
+		if (nameError) throw new Error(nameError);
+		const messages = {
+			database: "Select database:",
+			deployment: "Select deployment adapter:",
+			email: "Select email provider:",
+		};
+		for (const category of ["database", "deployment", "email"]) {
+			if (selection[category] !== undefined) continue;
+			const options = choices(category, selection);
+			const preferred =
+				options.find(
+					(option) => option.value === defaults[category] && !option.disabled,
+				) ?? options.find((option) => !option.disabled);
+			if (!preferred) throw new Error(`No compatible ${category} choices.`);
+			selection[category] = values.yes
+				? preferred.value
+				: await answer(
+						select({
+							message: messages[category],
+							options: options.map((option) => ({
+								value: option.value,
+								label: option.name,
+								hint: option.disabled || option.hint,
+								disabled: Boolean(option.disabled),
+							})),
+							initialValue: preferred.value,
+							showInstructions: false,
+						}),
+					);
+		}
+		if (selection.payments === undefined) {
+			if (values.yes) selection.payments = defaults.payments;
+			else {
+				note(
+					"Use ↑/↓ to navigate • Space to select/deselect • Enter to confirm",
+					"Keyboard Shortcuts",
+				);
+				selection.payments = await answer(
+					multiselect({
+						message:
+							"What payment providers would you like? (Space to toggle, Enter to confirm)",
+						options: catalog.payments.map((option) => ({
+							label: option.label,
+							value: option.id,
+						})),
+						required: false,
+						showInstructions: false,
+					}),
+				);
+			}
+		}
+		validateSelection(selection);
+		const install = values["no-install"]
+			? false
+			: values.yes
+				? true
+				: await answer(
+						confirm({
+							message: "Would you like to install dependencies now?",
+							initialValue: true,
+						}),
+					);
+		const label = (category, id) =>
+			catalog[category].find((option) => option.id === id).label;
+		log.info(
+			`About to create:\n\n${[
+				["Project", name],
+				["Location", resolve(name)],
+				["Framework", "TanStack Start (React)"],
+				["Package manager", "Bun"],
+				["Database", label("database", selection.database)],
+				["Deploy", label("deployment", selection.deployment)],
+				["Email", label("email", selection.email)],
+				[
+					"Payments",
+					selection.payments.map((id) => label("payments", id)).join(", ") ||
+						"None",
+				],
+				["Install deps", install ? "yes" : "no"],
+			]
+				.map(([key, value]) => `  ${`${key}:`.padEnd(17)}${value}`)
+				.join("\n")}`,
+		);
+		if (
+			!values.yes &&
+			!(await answer(
+				confirm({
+					message: "Continue with these settings?",
+					initialValue: true,
+				}),
+			))
+		) {
+			cancel("Operation cancelled.");
+			return 0;
+		}
+		const target = await step(
+			"Creating project files...",
+			"Project files created",
+			(onProgress) => createProject({ name, selection, onProgress }),
+		);
+		if (install) {
+			try {
+				await step(
+					"Installing dependencies via Bun...",
+					"Installed dependencies",
+					() => installDependencies(target),
+				);
+			} catch (error) {
+				log.error(error.message);
+				note(
+					`Your project is saved at ${target}.\n\n% cd ${name}\n% bun install\n\nThen follow README.md to configure and start your app.`,
+					"Retry installation",
+				);
+				cancel("Dependency installation failed.");
+				return 1;
+			}
+		} else log.step("Dependency installation skipped");
+		outro(
+			`Your Mystack app is ready in '${name}'.\n\nUse the following commands to start your app:\n% cd ${name}\n${install ? "" : "% bun install\n"}% cp .env.example .env\n\nConfigure .env using README.md, then run:\n${isPostgres(selection.database) ? "% bun run db:up\n" : ""}% bun run db:migrate\n% bun run dev`,
+		);
+		return 0;
+	} catch (error) {
+		if (error instanceof PromptCancelled) {
+			cancel("Operation cancelled.");
+			return 130;
+		}
+		log.error(error.message);
+		return 1;
+	}
+}
+
+if (
+	process.argv[1] &&
+	import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
+)
+	process.exitCode = await main();

package/src/generate.mjs

@@ -0,0 +1,183 @@
+import { execFile } from "node:child_process";
+import {
+	mkdir,
+	mkdtemp,
+	readdir,
+	rename,
+	rm,
+	writeFile,
+} from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { Generator, getConfig } from "@tanstack/router-generator";
+import { configureDatabase } from "./adapters/database.mjs";
+import { configureDeployment } from "./adapters/deployment.mjs";
+import { configureEmail } from "./adapters/email.mjs";
+import { configurePayments } from "./adapters/payments.mjs";
+import { catalog, isPostgres, validateSelection } from "./catalog.mjs";
+import { readTemplate, text } from "./template.mjs";
+
+export function validateName(name) {
+	if (!/^[a-z][a-z0-9-]{0,57}$/.test(name))
+		throw new Error(
+			"Project name must start with a lowercase letter and contain at most 58 lowercase letters, digits or hyphens.",
+		);
+	return name;
+}
+
+const bundledTemplateRoot = fileURLToPath(
+	new URL("../template", import.meta.url),
+);
+
+export async function renderProject({
+	name,
+	selection,
+	templateRoot = bundledTemplateRoot,
+}) {
+	validateName(name);
+	validateSelection(selection);
+	const files = await readTemplate(templateRoot, {
+		packaged: templateRoot === bundledTemplateRoot,
+	});
+	const pkg = JSON.parse(text(files, "package.json"));
+	pkg.name = name;
+	delete pkg.pnpm;
+	for (const key of ["mystack", "cli:prepare", "test:cli"])
+		delete pkg.scripts[key];
+	const context = { files, pkg, name, selection };
+	await configureDeployment(context);
+	await configureDatabase(context);
+	await configureEmail(context);
+	await configurePayments(context);
+	files.set("package.json", `${JSON.stringify(pkg, null, "\t")}\n`);
+	files.set(
+		"mystack.json",
+		`${JSON.stringify({ version: 1, ...selection }, null, "\t")}\n`,
+	);
+	files.set(
+		"tsconfig.json",
+		text(files, "tsconfig.json").replace(
+			/ {2}"exclude": \["packages\/mystack\/assets".*\n/,
+			"",
+		),
+	);
+	files.set("README.md", projectReadme(context));
+	return files;
+}
+
+export async function createProject({
+	name,
+	selection,
+	cwd = process.cwd(),
+	templateRoot = bundledTemplateRoot,
+	onProgress = () => {},
+}) {
+	validateName(name);
+	validateSelection(selection);
+	const target = resolve(cwd, name);
+	// Reserve a new directory exclusively. Never overwrite even an empty existing
+	// directory, and never remove user files if installation later fails.
+	await mkdir(target);
+	let staging;
+	try {
+		staging = await mkdtemp(join(cwd, ".mystack-"));
+		onProgress("Creating project files...");
+		const files = await renderProject({ name, selection, templateRoot });
+		for (const [path, contents] of files) {
+			await mkdir(dirname(join(staging, path)), { recursive: true });
+			await writeFile(join(staging, path), contents);
+		}
+		onProgress("Generating routes...");
+		await new Generator({
+			config: getConfig({ disableLogging: true }, staging),
+			root: staging,
+		}).run();
+		onProgress("Formatting project files...");
+		const biome = createRequire(import.meta.url).resolve(
+			"@biomejs/biome/bin/biome",
+		);
+		await promisify(execFile)(process.execPath, [biome, "check", "--write"], {
+			cwd: staging,
+		});
+		// Import organization can change formatter decisions; format the fixed AST.
+		await promisify(execFile)(process.execPath, [biome, "format", "--write"], {
+			cwd: staging,
+		});
+		if ((await readdir(target)).length)
+			throw new Error(
+				"Destination changed during generation; refusing to overwrite it.",
+			);
+		await rename(staging, target);
+		return target;
+	} catch (error) {
+		if (staging) await rm(staging, { recursive: true, force: true });
+		// Only remove our reservation if it is still empty.
+		const { rmdir } = await import("node:fs/promises");
+		await rmdir(target).catch(() => {});
+		throw error;
+	}
+}
+
+function projectReadme({ name, selection }) {
+	const label = (category, id) =>
+		catalog[category].find((option) => option.id === id).label;
+	const databaseNotes = {
+		pg: "PostgreSQL connects directly through DATABASE_URL using the application role. DATABASE_MIGRATION_URL is privileged and is only for migrations. Use Docker for local development.",
+		"pg-hyperdrive":
+			"PostgreSQL connects through the Cloudflare HYPERDRIVE binding. Local development uses hyperdrive.localConnectionString in wrangler.jsonc; production requires your Hyperdrive configuration ID. DATABASE_MIGRATION_URL is only for migrations.",
+		d1: "Cloudflare D1 uses the DB binding in wrangler.jsonc. db:migrate applies local migrations; db:migrate:remote applies them to the configured Cloudflare database.",
+		"turso-cloud":
+			"Turso Cloud uses a remote database. Set TURSO_DATABASE_URL (libsql:// or https://) and TURSO_AUTH_TOKEN from your Turso database before running migrations or starting the app. This option never opens a local SQLite file. Database service tests use an isolated local libSQL fixture; they do not access your cloud database.",
+		"turso-local":
+			"Turso Local uses @libsql/client with a file: URL (TURSO_DATABASE_URL=file:local.db). No Turso Cloud token is required. Keep the database file on persistent storage when deploying.",
+		"bun-sqlite":
+			"Bun SQLite uses the native bun:sqlite driver, with SQLITE_DATABASE_PATH=local.db. Run the app with Bun and keep the database file on persistent storage. Native database tests run with bun test after Vitest.",
+	};
+	return `# ${name}
+
+Generated with \`mystack create\`. Configuration is recorded in \`mystack.json\`; editing it does not regenerate or convert the application. This project is maintained independently of the generator repository.
+
+Database: ${label("database", selection.database)}; runtime: ${label("deployment", selection.deployment)}; email: ${label("email", selection.email)}; payments: ${selection.payments.map((id) => label("payments", id)).join(", ") || "none"}.
+
+## Database
+
+${databaseNotes[selection.database]}
+
+## Local development
+
+Use Bun for application commands.${isPostgres(selection.database) ? " Local PostgreSQL also needs Docker." : ""} Mystack normally installs dependencies; run \`bun install\` if installation was skipped or failed.
+
+\`\`\`sh
+cp .env.example .env
+\`\`\`
+
+Configure the selected database and provider credentials in \`.env\`, then run:
+
+\`\`\`sh
+${isPostgres(selection.database) ? "bun run db:up\nbun run db:migrate" : "bun run db:migrate"}
+bun run dev
+\`\`\`
+
+Use **http://localhost:3000**, matching the example app/auth origins. Authentication email is printed in development when credentials are absent. ${isPostgres(selection.database) ? "Use `bun run db:seed` for optional local test users." : "Create your account through normal sign-up and use the development email to verify it."}
+
+## Project development
+
+See [docs/project-guide.md](./docs/project-guide.md) for source layout, authentication, database authorization, payment fulfillment, localization and validation. See [DESIGN.md](./DESIGN.md) for presentation conventions.
+
+\`\`\`sh
+bun run check
+bun run typecheck
+bun run test:unit
+\`\`\`
+
+## Production
+
+Set a new \`BETTER_AUTH_SECRET\` and real application origins. Configure the selected database and verified email sender. ${selection.payments.length ? `Selected payment webhooks: ${selection.payments.map((provider) => `\`/api/webhooks/${provider}\``).join(", ")}. Set their matching signature secrets and register these URLs with the providers.` : "No payment providers or webhook routes were selected."}
+
+${selection.deployment === "cloudflare" ? `Configure the selected resources in \`wrangler.jsonc\`, authenticate with \`bunx wrangler login\`, create \`.env.prod\`, and run \`bun run deploy\`. ${selection.database === "d1" ? "Create the hosted D1 database, replace its placeholder ID, and apply hosted migrations with `bun run db:migrate:remote` before deployment." : "Apply `bun run db:migrate` with production migration credentials before deployment."}${selection.database === "pg-hyperdrive" ? " Set a real Hyperdrive configuration ID and app-role connection credentials." : ""}` : "Inject production environment variables in the hosting environment, apply database migrations, run `bun run deploy` for validation and build checks, then `bun run start`."}
+
+${!isPostgres(selection.database) ? `SQLite payments commit a durable \`purchase_delivery\` event atomically with the paid state, using ${selection.database === "bun-sqlite" ? "a synchronous Bun SQLite transaction" : "the driver's atomic batch"}. Implement product fulfillment by consuming these events using \`purchase_id\` as the idempotency key. SQLite authorization uses authenticated/admin middleware and explicit ownership predicates.\n` : ""}
+`;
+}

package/src/template.mjs

@@ -0,0 +1,93 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// An allowlist prevents credentials, Git history, installed dependencies and
+// local build output from entering the published template.
+export const templateEntries = [
+	"src",
+	"public",
+	"scripts",
+	"drizzle",
+	"project.inlang/settings.json",
+	"messages",
+	"e2e",
+	"package.json",
+	"vite.config.ts",
+	"tsconfig.json",
+	"tsr.config.json",
+	"biome.json",
+	"vitest.config.ts",
+	"playwright.config.ts",
+	"drizzle.config.ts",
+	"paraglide.config.ts",
+	"wrangler.jsonc",
+	"worker-configuration.d.ts",
+	"docker-compose.yml",
+	".env.example",
+	".env.docker",
+	".gitignore",
+	"DESIGN.md",
+	"docs/project-guide.md",
+	"LICENSE",
+];
+
+export async function readTemplate(root, { packaged = false } = {}) {
+	const files = new Map();
+	async function visit(path) {
+		if (
+			path === "src/paraglide" ||
+			path.startsWith("scripts/mystack") ||
+			path === "src/__tests__/mystack.test.ts"
+		)
+			return;
+		const absolute = join(
+			root,
+			packaged && path === ".gitignore" ? "gitignore" : path,
+		);
+		const { lstat } = await import("node:fs/promises");
+		let entry;
+		try {
+			entry = await lstat(absolute);
+		} catch (error) {
+			if (error.code === "ENOENT" && templateEntries.includes(path)) return;
+			throw error;
+		}
+		if (entry.isSymbolicLink())
+			throw new Error(`Template symlinks are forbidden: ${path}`);
+		if (entry.isDirectory()) {
+			for (const name of (await readdir(absolute)).sort())
+				await visit(`${path}/${name}`);
+		} else if (entry.isFile()) files.set(path, await readFile(absolute));
+	}
+	for (const path of templateEntries) await visit(path);
+	for (const path of [
+		"package.json",
+		"src/lib/auth.ts",
+		"src/db/auth.schema.ts",
+		".gitignore",
+		".env.example",
+		"messages/en.json",
+		"messages/de.json",
+		"docs/project-guide.md",
+	]) {
+		if (!files.has(path))
+			throw new Error(
+				`Template is missing ${path}. Run template:prepare before packaging.`,
+			);
+	}
+	return files;
+}
+
+export function text(files, path) {
+	if (!files.has(path)) throw new Error(`Template is missing ${path}.`);
+	return files.get(path).toString("utf8");
+}
+
+export function replace(files, path, before, after) {
+	const source = text(files, path);
+	if (!source.includes(before))
+		throw new Error(
+			`Template changed: expected anchor in ${path}: ${before.slice(0, 80)}`,
+		);
+	files.set(path, source.replace(before, after));
+}

package/template/.env.docker

@@ -0,0 +1,16 @@
+# Local Docker Compose Postgres defaults (committed — dev only).
+# Loaded via: docker compose --env-file .env.docker up -d
+
+# Privileged superuser (migrations / drizzle-kit)
+POSTGRES_DB=starter
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres_dev_password
+# Host port published to localhost. Container always listens on 5432.
+# Use e.g. 5433 if another Postgres already owns 5432 — then update
+# DATABASE_MIGRATION_URL and hyperdrive[].localConnectionString to match.
+POSTGRES_PORT=5432
+
+# Runtime app role (Hyperdrive / Worker localConnectionString)
+# NOBYPASSRLS — created by scripts/postgres/create-app-role.sh on first boot
+APP_DB_USER=starter_app
+APP_DB_PASSWORD=starter_app_dev_password

package/template/.env.example

@@ -0,0 +1,67 @@
+# —————————————————— App config ————————————————————
+APP_ORIGIN=http://localhost:3000
+# Use http://localhost:3000 in the browser, not 127.0.0.1 (cookie/origin pitfall).
+# Public site identity (document head, OG, JSON-LD). Mirrors APP_ORIGIN for the client.
+VITE_APP_ORIGIN=http://localhost:3000
+VITE_APP_TITLE=TanStack Starter
+
+# —————————————————— Better Auth ————————————————————
+BETTER_AUTH_URL=http://localhost:3000
+# Dev-only placeholder for local generated-project development.
+# `bun run validate-prod-env` refuses it, so a deploy cannot inherit it.
+# Real secret: `bunx auth@latest secret` (same CLI as `bun run auth:generate`)
+BETTER_AUTH_SECRET=dev-only-insecure-secret-change-before-deploy
+# Optional comma-separated OAuth resource audiences (defaults to APP_ORIGIN).
+BETTER_AUTH_AUDIENCES=
+
+# —————————————————— Database ——————————————————————
+# Local Docker defaults match `.env.docker` (bun run db:up).
+#
+# Privileged superuser — drizzle-kit migrate / push / seed only.
+# Never point the Worker runtime at this URL.
+DATABASE_MIGRATION_URL=postgresql://postgres:postgres_dev_password@localhost:5432/starter
+#
+# Runtime app role (same as wrangler.jsonc hyperdrive.localConnectionString):
+# postgresql://starter_app:starter_app_dev_password@localhost:5432/starter
+#
+# Optional overrides for `bun run db:seed` (defaults are local-only).
+# SEED_ADMIN_EMAIL=admin@localhost.dev
+# SEED_ADMIN_PASSWORD=AdminPass1!
+# SEED_ADMIN_NAME=Local Admin
+# SEED_ADMIN_ROLE=superadmin
+# SEED_USER_EMAIL=user@localhost.dev
+# SEED_USER_PASSWORD=UserPass1!
+# SEED_USER_NAME=Local User
+# SEED_FORCE=1
+
+# —————————————————— GitHub social (optional) ——————
+# All three must be set together for GitHub to work end-to-end:
+#   - VITE_GITHUB_CLIENT_ID: public client id (UI button + server fallback)
+#   - GITHUB_CLIENT_ID: optional alias; if set, must match VITE_GITHUB_CLIENT_ID
+#   - GITHUB_CLIENT_SECRET: server-only secret
+# Client IDs are public by OAuth design. Leave all blank to hide GitHub in the UI.
+VITE_GITHUB_CLIENT_ID=
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# —————————————————— Turnstile —————————————————————
+TURNSTILE_SECRET_KEY=
+# Public site key. Leave blank in dev to disable captcha (CAPTCHA_ENABLED=false).
+VITE_TURNSTILE_SITE_KEY=
+
+# —————————————————— Email ————————————————————————
+# Technical From address (domain must be verified in Cloudflare Email).
+EMAIL_FROM=no-reply@example.com
+# Inbox display name (clone-time brand).
+EMAIL_FROM_NAME=Starter
+
+# —————————————————— Payments (optional) ——————————
+CREEM_API_KEY=
+CREEM_WEBHOOK_SECRET=
+CREEM_PRODUCT_ID=
+CREEM_TEST_MODE=false
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+NOW_PAYMENTS_API_KEY=
+NOW_PAYMENTS_IPN_KEY=
+NOW_PAYMENTS_TEST_MODE=false