@geekmidas/cli 10.0.0-alpha.30 → 10.0.0-alpha.32

package/dist/index.mjs

@@ -37,7 +37,7 @@ import { Subscriber } from "@geekmidas/constructs/subscribers";
 import { Topic } from "@geekmidas/constructs/topic";
 import { lookup } from "node:dns/promises";
 //#region package.json
-var version = "10.0.0-alpha.30";
+var version = "10.0.0-alpha.32";
 //#endregion
 //#region src/auth/credentials.ts
 /**
@@ -1086,7 +1086,10 @@ async function workspaceDevCommand(workspace, options) {
 		...rawSecrets,
 		...reconciled.env
 	};
-	await import("./migrate-CBICVMAi.mjs").then(({ reportPendingMigrations }) => reportPendingMigrations(workspace, reconciled.env)).catch((error) => {
+	if (options.migrate || options.seed) {
+		const { prepareDevDatabases } = await import("./migrate-CnPtWnkR.mjs");
+		await prepareDevDatabases(workspace, reconciled.env, { seed: !!options.seed });
+	} else await import("./migrate-CnPtWnkR.mjs").then(({ reportPendingMigrations }) => reportPendingMigrations(workspace, reconciled.env)).catch((error) => {
 		logger$10.log(`⚠️  Could not check for pending migrations: ${error instanceof Error ? error.message : String(error)}`);
 	});
 	const appUrls = {};
@@ -8293,7 +8296,7 @@ function layoutBlock(options, template) {
 	const { database } = options.constructs;
 	const isWorker = template.name === "worker";
 	if (monorepo) return `constructs/          # every construct: the surface, the database, topics
-${database ? "db/<construct>/      # migrations, one folder per database construct\n" : ""}${apiPath}/            # the API app
+${database ? "db/<construct>/      # migrations/ and seeds/, one folder per database construct\n" : ""}${apiPath}/            # the API app
 gkm.config.ts        # name, constructs glob, secrets`;
 	const lines = ["src/constructs/      # the surface, and anything it declares", "src/config/          # env parser, logger"];
 	if (!isWorker) lines.push("src/endpoints/       # HTTP handlers");
@@ -8301,7 +8304,7 @@ gkm.config.ts        # name, constructs glob, secrets`;
 		lines.push("src/crons/           # scheduled work");
 		lines.push("src/subscribers/     # topic consumers");
 	}
-	if (database) lines.push("db/<construct>/      # migrations, one folder per database construct");
+	if (database) lines.push("db/<construct>/      # migrations/ and seeds/, one folder per database construct");
 	lines.push("gkm.config.ts        # name, constructs glob, secrets");
 	return lines.join("\n");
 }
@@ -8430,36 +8433,80 @@ Queries go through Kysely. Never open your own connection pool — the one the
 construct provides is the one that gets credentials, pooling and shutdown.`;
 }
 function migrationsSection() {
-	return `## Migrations
+	return `## Migrations and seeds
 
 Each database construct has its own folder, named after the construct:
 \`Database\` is \`db/database/\`, a tenant \`AuthDatabase\` is
-\`db/auth-database/\`. Each keeps its own history, in its own schema, and is
-migrated as its own **owner** role — the role a handler runs as cannot create a
+\`db/auth-database/\`. It holds two folders and nothing else:
+
+\`\`\`
+db/database/
+  migrations/   # the schema's history, applied once each
+  seeds/        # the reference data the app needs, run on every pass
+\`\`\`
+
+Each construct keeps its own history, in its own schema, and is migrated and
+seeded as its own **owner** role — the role a handler runs as cannot create a
 table.
 
 \`\`\`bash
-gkm migration database add_workouts   # db/database/20260930143012_add_workouts.ts
+gkm migration database add_workouts   # db/database/migrations/20260930143012_add_workouts.ts
 gkm migration auth                    # Better Auth's schema change, as SQL
-gkm migrate                           # apply every folder, parents first
+gkm migrate                           # apply every construct's migrations, parents first
 gkm migrate database                  # apply one construct's
+gkm seed                              # migrate, then run every seed
+gkm dev --migrate                     # migrate before the apps start
+gkm dev --seed                        # migrate and seed before the apps start
 \`\`\`
 
-- Files are \`<UTC timestamp>_<name>.ts\` exporting \`up\` (and \`down\`), or
-  \`.sql\`, which runs whole. Never rename or edit one that has been applied —
-  it is recorded by name. Change the schema with a new migration.
+- Migrations are \`<UTC timestamp>_<name>.ts\` exporting \`up\` (and
+  \`down\`), or \`.sql\`, which runs whole. Never rename or edit one that has
+  been applied — it is recorded by name. Change the schema with a new
+  migration.
 - Write migrations with \`Kysely<unknown>\` and snake_case names: they are the
   SQL, and the camelCase plugin is the app's, not theirs.
 - \`gkm migration auth\` compares Better Auth's schema to its tenant and writes
   only the difference. Run it after adding a Better Auth plugin, and commit the
   file.
-- Tests migrate themselves: the root vitest config's
-  \`globalSetup: ['@geekmidas/cli/vitest']\` applies every folder to the test
-  stage before any test runs. \`gkm dev\` only reports what is pending.
+- Seeds always run after migrations, never instead of them. Each is a
+  \`.ts\` exporting \`seed(db, { stage })\`, or \`.sql\`, run in name
+  order, in a transaction of its own.
+- **Seeds run on every stage, production included.** Write them to be safe
+  there. A seed that belongs only somewhere checks the stage it is handed:
+  \`if (stage === 'production') return;\`. A \`.sql\` seed has no stage, so
+  it must be right everywhere.
+- Tests migrate and seed themselves: the root vitest config's
+  \`globalSetup: ['@geekmidas/cli/vitest']\` does both for the test stage
+  before any test runs. \`gkm dev\` without a flag only reports what is
+  pending.
 - A deploy migrates before the new version goes live, so the old version runs
   against the new schema until it is replaced. Keep each migration compatible
   with the code before it: add a column in one release, stop using the old one,
-  drop it in a later release.`;
+  drop it in a later release.
+
+**Migrations hold schema, never data.** Tables, columns, constraints, indexes.
+No inserts, updates or deletes against the application's rows.
+
+- **Reference data is a seed.** A permission catalogue, the roles and what
+  they grant, a list of statuses — rows the app needs in order to run — are
+  written by a seed in \`db/<construct>/seeds/\`, never by a migration.
+- **A seed is an upsert, run every time.** There is no history: every seed
+  runs on every \`gkm seed\`, so changing what it writes and running it again
+  is how the change is applied. Write \`onConflict(…).doUpdateSet(…)\` (or
+  \`doNothing()\`), never a bare insert.
+- **Define it once, typed, where every app can import it.** A catalogue
+  belongs in code, declared \`as const\` so its keys are a union type, and the
+  seed writes the table from that constant — so the two cannot drift, and no
+  test is needed to keep them in step. The API's guards, the web app's gates
+  and a mobile app's gates all name the same keys, and a typo — or a removed
+  permission still checked somewhere — fails to compile instead of failing
+  closed at runtime.
+- **Sample data is factories'.** Demo users, a tournament for a test — those
+  come from test factories, never a seed and never a migration.
+- **A backfill is the one data change a migration makes.** When a schema
+  change needs existing rows transformed — a new non-null column filled from
+  an old one — do it in the same migration, keyed on the rows it transforms.
+  It never inserts rows that were not there.`;
 }
 function queriesSection() {
 	return `## Writing queries and relations
@@ -8716,26 +8763,26 @@ function loadPackageJson() {
 * Run: pnpm --filter @geekmidas/cli sync-versions
 */
 const GEEKMIDAS_VERSIONS = {
-	"@geekmidas/audit": "~10.0.0-alpha.30",
-	"@geekmidas/auth": "~10.0.0-alpha.30",
-	"@geekmidas/cache": "~10.0.0-alpha.30",
-	"@geekmidas/client": "~10.0.0-alpha.30",
-	"@geekmidas/cloud": "~10.0.0-alpha.30",
-	"@geekmidas/constructs": "~10.0.0-alpha.30",
-	"@geekmidas/db": "~10.0.0-alpha.30",
-	"@geekmidas/emailkit": "~10.0.0-alpha.30",
-	"@geekmidas/envkit": "~10.0.0-alpha.30",
-	"@geekmidas/errors": "~10.0.0-alpha.30",
-	"@geekmidas/events": "~10.0.0-alpha.30",
-	"@geekmidas/logger": "~10.0.0-alpha.30",
-	"@geekmidas/manifest": "~10.0.0-alpha.30",
-	"@geekmidas/rate-limit": "~10.0.0-alpha.30",
-	"@geekmidas/schema": "~10.0.0-alpha.30",
-	"@geekmidas/services": "~10.0.0-alpha.30",
-	"@geekmidas/storage": "~10.0.0-alpha.30",
-	"@geekmidas/studio": "~10.0.0-alpha.30",
-	"@geekmidas/telescope": "~10.0.0-alpha.30",
-	"@geekmidas/testkit": "~10.0.0-alpha.30",
+	"@geekmidas/audit": "~10.0.0-alpha.32",
+	"@geekmidas/auth": "~10.0.0-alpha.32",
+	"@geekmidas/cache": "~10.0.0-alpha.32",
+	"@geekmidas/client": "~10.0.0-alpha.32",
+	"@geekmidas/cloud": "~10.0.0-alpha.32",
+	"@geekmidas/constructs": "~10.0.0-alpha.32",
+	"@geekmidas/db": "~10.0.0-alpha.32",
+	"@geekmidas/emailkit": "~10.0.0-alpha.32",
+	"@geekmidas/envkit": "~10.0.0-alpha.32",
+	"@geekmidas/errors": "~10.0.0-alpha.32",
+	"@geekmidas/events": "~10.0.0-alpha.32",
+	"@geekmidas/logger": "~10.0.0-alpha.32",
+	"@geekmidas/manifest": "~10.0.0-alpha.32",
+	"@geekmidas/rate-limit": "~10.0.0-alpha.32",
+	"@geekmidas/schema": "~10.0.0-alpha.32",
+	"@geekmidas/services": "~10.0.0-alpha.32",
+	"@geekmidas/storage": "~10.0.0-alpha.32",
+	"@geekmidas/studio": "~10.0.0-alpha.32",
+	"@geekmidas/telescope": "~10.0.0-alpha.32",
+	"@geekmidas/testkit": "~10.0.0-alpha.32",
 	"@geekmidas/cli": `~${loadPackageJson().version}`
 };
 //#endregion
@@ -15330,9 +15377,12 @@ async function testCommand(options = {}) {
 		});
 	});
 }
-/** Apply every construct's migrations to the test stage just reconciled. */
+/**
+* Migrate the test stage just reconciled, then seed it: a test run never
+* starts without the reference data the app needs.
+*/
 async function migrateTestStage(workspace, env) {
-	const { migrateDatabases } = await import("./migrate-CBICVMAi.mjs");
+	const { migrateAndSeed } = await import("./migrate-CnPtWnkR.mjs");
 	const { discover } = await import("./discover-CMxesskG.mjs").then((n) => n.n);
 	const sources = {};
 	const manifest = await discover({
@@ -15340,13 +15390,15 @@ async function migrateTestStage(workspace, env) {
 		cwd: workspace.root,
 		sources
 	});
-	const runs = await migrateDatabases({
+	const { migrations, seeds } = await migrateAndSeed({
 		root: workspace.root,
 		manifest,
 		sources,
-		env
+		env,
+		stage: TEST_STAGE
 	});
-	for (const { target, applied } of runs) if (applied.length > 0) console.log(`  🗄️  ${target.folder}: applied ${applied.join(", ")}`);
+	for (const { target, applied } of migrations) if (applied.length > 0) console.log(`  🗄️  ${target.migrations}: applied ${applied.join(", ")}`);
+	for (const { target, seeded } of seeds) if (seeded.length > 0) console.log(`  🌱 ${target.seeds}: ran ${seeded.join(", ")}`);
 }
 /** `gkm test` outside a project that declares stages, with none named. */
 var NoStageToTest = class extends Error {
@@ -15730,7 +15782,7 @@ program.command("build").description("Build handlers and the manifest from decla
 		process.exit(1);
 	}
 });
-program.command("dev").description("Reconcile constructs and start the dev server with automatic reload").option("-p, --port <port>", "Port to run the development server on").option("--entry <file>", "Entry file to run (bypasses gkm config)").option("--watch", "Watch for file changes (default: true with --entry)").option("--no-watch", "Disable file watching").option("--enable-openapi", "Enable OpenAPI documentation for development server", true).action(async (options) => {
+program.command("dev").description("Reconcile constructs and start the dev server with automatic reload").option("-p, --port <port>", "Port to run the development server on").option("--entry <file>", "Entry file to run (bypasses gkm config)").option("--watch", "Watch for file changes (default: true with --entry)").option("--no-watch", "Disable file watching").option("--enable-openapi", "Enable OpenAPI documentation for development server", true).option("--migrate", "Apply pending migrations before the apps start").option("--seed", "Migrate, then run the seeds, before the apps start").action(async (options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -15739,7 +15791,9 @@ program.command("dev").description("Reconcile constructs and start the dev serve
 			portExplicit: !!options.port,
 			enableOpenApi: options.enableOpenapi ?? true,
 			entry: options.entry,
-			watch: options.watch
+			watch: options.watch,
+			migrate: options.migrate,
+			seed: options.seed
 		});
 	} catch (error) {
 		console.error(formatError(error));
@@ -15756,7 +15810,7 @@ program.command("exec").description("Run a command with secrets injected into Cr
 		process.exit(1);
 	}
 });
-program.command("test").description("Run tests with secrets loaded from environment").option("--stage <stage>", "Stage to load secrets from (default: stages.local)").option("--run", "Run tests once without watch mode").option("--watch", "Enable watch mode").option("--coverage", "Generate coverage report").option("--ui", "Open Vitest UI").option("--auto-setup", "Generate a fresh stage (secrets + key) from the workspace config when none exists (for CI; also via GKM_AUTO_SETUP)").option("--prepare", "Write the test manifest and #test harness, then stop — for a typecheck that runs before the suite").option("--setup", "Reconcile and migrate the test stage and write the harness, then stop — what @geekmidas/cli/vitest runs").argument("[pattern]", "Pattern to filter tests").action(async (pattern, options) => {
+program.command("test").description("Run tests with secrets loaded from environment").option("--stage <stage>", "Stage to load secrets from (default: stages.local)").option("--run", "Run tests once without watch mode").option("--watch", "Enable watch mode").option("--coverage", "Generate coverage report").option("--ui", "Open Vitest UI").option("--auto-setup", "Generate a fresh stage (secrets + key) from the workspace config when none exists (for CI; also via GKM_AUTO_SETUP)").option("--prepare", "Write the test manifest and #test harness, then stop — for a typecheck that runs before the suite").option("--setup", "Reconcile, migrate and seed the test stage and write the harness, then stop — what @geekmidas/cli/vitest runs").argument("[pattern]", "Pattern to filter tests").action(async (pattern, options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
@@ -15769,11 +15823,11 @@ program.command("test").description("Run tests with secrets loaded from environm
 		process.exit(1);
 	}
 });
-program.command("migrate").description("Apply each database construct's migrations from db/<construct>/, as its owner").argument("[construct]", "Only this construct, by name").option("--stage <stage>", "The local stage (default) or test — a deploy migrates its own stage").action(async (construct, options) => {
+program.command("migrate").description("Apply each database construct's migrations from db/<construct>/migrations/, as its owner").argument("[construct]", "Only this construct, by name").option("--stage <stage>", "The local stage (default) or test — a deploy migrates its own stage").action(async (construct, options) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { migrateCommand } = await import("./migrate-CBICVMAi.mjs");
+		const { migrateCommand } = await import("./migrate-CnPtWnkR.mjs");
 		await migrateCommand({
 			...options,
 			...construct ? { construct } : {}
@@ -15783,11 +15837,25 @@ program.command("migrate").description("Apply each database construct's migratio
 		process.exit(1);
 	}
 });
+program.command("seed").description("Migrate, then run each database construct's seeds from db/<construct>/seeds/, as its owner").argument("[construct]", "Only this construct, by name").option("--stage <stage>", "The local stage (default) or test — a deploy seeds its own stage").action(async (construct, options) => {
+	try {
+		const globalOptions = program.opts();
+		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
+		const { seedCommand } = await import("./migrate-CnPtWnkR.mjs");
+		await seedCommand({
+			...options,
+			...construct ? { construct } : {}
+		});
+	} catch (error) {
+		console.error(formatError(error));
+		process.exit(1);
+	}
+});
 program.command("migration").description("Write a construct's next migration: an empty one for a database, the schema change for an auth server").argument("<construct>", "The construct, by name").argument("[name]", "What the migration is called").action(async (construct, name) => {
 	try {
 		const globalOptions = program.opts();
 		if (globalOptions.cwd) process.chdir(globalOptions.cwd);
-		const { migrationCommand } = await import("./migrate-CBICVMAi.mjs");
+		const { migrationCommand } = await import("./migrate-CnPtWnkR.mjs");
 		await migrationCommand({
 			construct,
 			...name ? { name } : {}