generatesaas 2.3.0 → 3.0.1

package/dist/skill/content/SKILL.md

@@ -103,6 +103,11 @@ key once and saves it), then re-run the update. For a network error, ask them to
 > Note: this command also rewrites the skill scripts to their latest version. That is
 > expected - the scripts you run in the following steps are the freshly-installed ones.
 
+**Re-read this SKILL.md now**, from `__SKILL_ROOT__/generatesaas-update/SKILL.md`. The command
+just overwrote it along with the scripts, so the copy in your context is the PREVIOUS release's
+instructions while every script you are about to run is the new one. Follow the file on disk
+wherever the two disagree.
+
 **1b. Prepare the diff/classification data:**
 
 ```bash
@@ -117,8 +122,8 @@ Creates:
   `added` files; `unmodified`, `deleted`, and `removed` files have none.
 - `references/update-manifest.json` - lists of added, modified, and removed files,
   plus `renamed` (upstream renames detected by identical content: `[{from, to}]`)
-  and `sensitive` (database schema and `.env.example` changes that carry
-  follow-up work: migrations, new env vars)
+  and `sensitive` (database schema, `packages/database/drizzle/`, and
+  `.env.example` changes that carry follow-up work: migrations, new env vars)
 
 ### Step 2: Present Changelog
 
@@ -129,7 +134,7 @@ Each release's notes may be one of two shapes:
 - **Curated** - contains explicit `## Breaking`, `## Migration`, `## Features`, `## Fixes` (or similar) sections. Use those sections verbatim; they are authoritative.
 - **Raw** - an auto-generated flat list of change titles (one line per commit or PR, no sections). This is the common case. You can group the titles into features/fixes by reading them, but you **cannot** reliably infer breaking changes or migration steps from titles alone.
 
-Also read `sensitive` in `references/update-manifest.json`: database schema changes mean a migration is likely required, and `.env.example` changes mean new or changed environment variables. Mention both in the summary and again in the final post-update steps.
+Also read `sensitive` in `references/update-manifest.json`: database schema changes mean a migration is likely required, anything under `packages/database/drizzle/` means upstream migrations that must be regenerated into the project's own history before they will run (see [Database](#database-schema-migrations)), and `.env.example` changes mean new or changed environment variables. Mention all three in the summary and again in the final post-update steps.
 
 Present a clear, organized summary:
 
@@ -154,7 +159,7 @@ it stays complete). Read `newOptions` from `.generatesaas/staging.json`. **If it
 empty, skip this step entirely.**
 
 Otherwise, present each option so the user can decide whether to adopt it. Each entry has
-`{ key, label, hint, default, impact, requiresLabel? }`. For each one:
+`{ key, label, hint, default, impact, choices?, requiresLabel? }`. For each one:
 
 ```
 ### New since your version: {label}
@@ -172,14 +177,32 @@ it is a large surface you didn't originally choose" or "Safe to adopt - it is pu
 > 2. **Adopt it** - turn this feature on
 ```
 
+**An entry with `choices` is not a yes/no.** It takes one of several values, so the two-way block
+above cannot express it - offer the values as a numbered pick list instead, one line per choice,
+with the entry's `default` marked as the current behavior:
+
+```
+**Default:** `{default}` (your project's current behavior is unchanged).
+**My recommendation:** {your recommendation, naming one of the choices}
+
+> **Which would you like?**
+> 1. **`{choices[0]}`** {"(current)" on the one equal to default}
+> 2. **`{choices[1]}`**
+> 3. **`{choices[2]}`** ...one line per choice, however many there are
+```
+
 **Ask the user about every new option, in every mode - including Automatic.** Surfacing a new
 feature is exactly the kind of decision the update must never assume. Give your recommendation,
 but the user decides.
 
 **Applying the decisions:**
 
-1. For each option the user **adopts**, write its enabling value into `.generatesaas/manifest.json`
-   (e.g. set `"desktop": true`). The manifest is the single shaping input.
+1. For each option the user **adopts**, write the value they picked into
+   `.generatesaas/manifest.json` under the entry's `key`. For an option with no `choices` that value
+   is `true` (e.g. set `"desktop": true`); for one with `choices` it is the choice they named,
+   verbatim (e.g. set `"errorTracking": "sentry"`). Never write `true` for an option that has
+   `choices` - the CLI refuses any value outside them and stages nothing at all. The manifest is the
+   single shaping input.
 2. **If the user adopted at least one option, re-stage once** so re-shaping produces the
    feature's files. Re-run the CLI (append `auto` if you are in Automatic mode, so the staged
    metadata keeps the unattended signal):
@@ -318,13 +341,15 @@ Preview first (especially useful in Careful mode or when unsure), then apply:
 node __SKILL_ROOT__/generatesaas-update/scripts/apply-auto.js --dry-run   # lists every file it would update/create, changes nothing
 node __SKILL_ROOT__/generatesaas-update/scripts/apply-auto.js
 ```
-`apply-auto.js` copies only `unmodified` (safe replace) + `new` (genuinely-new trees). It will **never** touch `newInDeletedTree` files, and it aborts without writing anything if any source is missing from staging (no half-applied tree). Report what was applied. Mark all auto-update and new file items as `[x]` in the plan.
+`apply-auto.js` copies only `unmodified` (safe replace) + `new` (any upstream-added file whose tree the buyer has not deleted). It will **never** touch `newInDeletedTree` files, and it aborts without writing anything if any source is missing from staging (no half-applied tree). Report what was applied. Mark all auto-update and new file items as `[x]` in the plan - **except any file the script reports as held back**, which was never applied and moves to **Skipped** with the regenerate reason. Marking a held-back migration `[x]` records a table that does not exist as delivered, in the one artifact that outlives the session.
+
+It also holds back everything under `packages/database/drizzle/` and lists what it skipped. Those are NOT pending work you can copy in afterwards - migrations must be regenerated into the project's own history or they never run. See [Database](#database-schema-migrations).
 
 **Careful mode:**
 Present the list of safe auto-updates and new files to the user:
 > These {N} files haven't been customized and can be safely replaced with the new version. {N} new files will be created. Want me to apply all of these, or would you like to review any specific ones first?
 
-If the user wants to review specific files, show them the diff for each requested file. Apply only after approval.
+If the user wants to review specific files, show them the diff for each requested file. Apply only after approval. Do not count held-back migrations in either number - they are not being created, and presenting them as applied is the same error as marking them `[x]`.
 
 ### Step 7: Review Modified Files
 
@@ -476,7 +501,7 @@ After all files are processed:
 **Do NOT include:**
 - Files where the user accepted a merge or chose "Use upstream version" (template changes were applied)
 - Removed files (not in staging - template-hashes handles these automatically)
-- New files, whether created or rejected (handled correctly by staging presence)
+- New files, whether created or rejected. NB: that is only right for `newInDeletedTree`, where declining is a standing choice. A new file rejected for any other reason also stops being offered once the baseline advances, so say so when you record it as skipped
 - Any file where the template's intended change was successfully applied
 
 ```json
@@ -554,9 +579,26 @@ Config files are the most commonly customized.
 ### Database (schema, migrations)
 
 - NEVER auto-merge schema files - always present for user review
-- New migration files can be added directly
 - Warn about schema changes that may require new migrations
 
+**Never copy an upstream migration into `packages/database/drizzle/` as-is, and never overwrite the project's `drizzle/meta/_journal.json` or `drizzle/meta/*_snapshot.json` with the upstream versions.** A project's migration history is its own: upstream changes get re-derived into it, never pasted over it. Regenerate instead:
+
+1. Merge the upstream schema change into `packages/database/src/db/*.ts` (user review first, as above).
+2. Run `pnpm --filter @repo/database generate`. Drizzle diffs the project's own latest snapshot against the merged schema and writes a fresh migration carrying a current timestamp, the next `idx`, a correct `prevId`, and a snapshot that describes the project's real schema.
+3. Open the upstream `.sql` under `.generatesaas/staging/packages/database/drizzle/` and copy any hand-written statements into the generated file: seeds, backfills, data migrations, `ON CONFLICT` guards. `generate` infers structure only, so those are lost otherwise.
+4. Run `pnpm --filter @repo/database migrate`.
+
+**Why the upstream file cannot just be added.** Drizzle applies a migration only when its journal `when` value is greater than the `created_at` of the last migration already applied to the database. A project that generated its own migration after the upstream one was authored sits above that mark, so a copied-in upstream file is **skipped silently and permanently**: no error, no warning, no log line, and `migrate` still exits 0. The table or column it was supposed to create never exists, and the miss surfaces later as runtime failures on whatever code path needs it. Taking the upstream `_journal.json` and snapshots instead of the project's own is the second half of the same trap: the final snapshot then knows nothing about the project's own tables, so the next `generate` re-emits `CREATE TABLE` for tables that already exist.
+
+**If step 2 reports no schema changes**, the upstream migration is data-only and there is nothing to regenerate. This is the ONLY case where the `.sql` is copied in by hand. Copying the file is not enough on its own: drizzle reads `_journal.json` and runs only the entries listed there, so a `.sql` sitting in the folder with no entry is never opened. Do all four, in this order:
+
+1. **Append an entry** to the project's own `_journal.json`, copied from the upstream entry. This is the load-bearing step - without it nothing else matters.
+2. Set that entry's `when` **greater than the largest `when` already applied** to the database, never the upstream value. Drizzle takes the highest `created_at` in `drizzle.__drizzle_migrations` as its floor and skips everything at or below it.
+3. Set that entry's `idx` to continue the project's own sequence (last `idx` + 1).
+4. Rename the `.sql` file so its name matches the entry's `tag`, or set the `tag` to the file's existing name. Drizzle loads the file **by tag** and throws if the two disagree.
+
+Still do not bring the upstream `meta/*_snapshot.json`, here least of all. Nothing needs it: `migrate` never reads snapshots, and `generate` needs only ONE previous snapshot, which must be the project's own. Adding an upstream one breaks `generate` whichever way it sorts - `meta/` is read in filename order, so an upstream snapshot that sorts LAST silently becomes the diff base (re-emitting `CREATE TABLE` for the project's own tables, and `DROP TABLE` for anything upstream carries that the project removed), while one that sorts earlier collides on `prevId` with the project's own, which prints a warning, writes no migration, and still exits 0.
+
 ### Package Dependencies (`package.json`)
 
 - Add new dependencies from upstream

package/dist/skill/content/scripts/_helpers.js

@@ -46,7 +46,7 @@ function hashFile(filePath) {
 // asserts this set equality and the root-only matching below.
 const WALK_EXCLUSIONS = new Set([
 	".git", "node_modules", ".pnpm-store", ".env", ".env.test",
-	".turbo", ".nuxt", ".output", ".data", "dist",
+	".turbo", ".data", "dist",
 	".next", ".svelte-kit", ".wrangler",
 	".devcontainer", "playwright-report", "test-results",
 	"pnpm-lock.yaml",

package/dist/skill/content/scripts/apply-auto.js

@@ -10,6 +10,9 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { findProjectRoot, ensureDir, STAGING_DIR } = require("./_helpers.js");
 
+/** Drizzle migration history. Held back from every auto-copy - see filesToCopy. */
+const MIGRATION_DIR = "packages/database/drizzle/";
+
 function main() {
 	const root = findProjectRoot();
 	if (!root) {
@@ -36,12 +39,24 @@ function main() {
 		process.exit(1);
 	}
 
-	// `new` only ever contains genuinely-new trees - files inside buyer-deleted
-	// trees land in `newInDeletedTree`, which the AI handles by prompt (never here).
-	const filesToCopy = [...classification.unmodified, ...classification.new];
+	// `new` is any upstream-added file whose tree the buyer has NOT deleted -
+	// files inside buyer-deleted trees land in `newInDeletedTree`, which the AI
+	// handles by prompt (never here).
+	const candidates = [...classification.unmodified, ...classification.new];
+
+	// Migrations are NEVER auto-applied, and both failure modes are silent.
+	// Drizzle runs a migration only when its journal `when` beats the newest one
+	// already applied, so an upstream .sql copied in below that mark never runs
+	// and `migrate` still exits 0; and an upstream meta snapshot becomes the diff
+	// base for the next `generate`, which then re-emits the buyer's own tables.
+	// The skill's Database section regenerates them into the project's own
+	// history instead, which is only possible if this step leaves them alone.
+	const heldMigrations = candidates.filter((f) => f.startsWith(MIGRATION_DIR));
+	const filesToCopy = candidates.filter((f) => !f.startsWith(MIGRATION_DIR));
 
 	if (filesToCopy.length === 0) {
 		console.log("No files to auto-update. All changed files need manual merge.");
+		reportHeldMigrations(heldMigrations);
 		return;
 	}
 
@@ -69,6 +84,7 @@ function main() {
 			console.log(`  ${unmodifiedSet.has(filePath) ? "update" : "create"}  ${filePath}`);
 		}
 		console.log("\n[dry run] No files were modified.");
+		reportHeldMigrations(heldMigrations);
 		return;
 	}
 
@@ -102,9 +118,37 @@ function main() {
 		}
 	}
 
+	reportHeldMigrations(heldMigrations);
+
 	console.log("\nAfter merging all files, run complete-update.js to finalize.");
 }
 
+/**
+ * Report migration files deliberately NOT copied, so the AI knows they are
+ * waiting rather than assuming the tree is settled. Silent when there are none.
+ *
+ * States the whole procedure rather than pointing at SKILL.md. The AI loads
+ * SKILL.md at the start of the update, BEFORE step 1a refreshes the bundle, so
+ * for one release after this ships it is following the previous release's prose
+ * - which says migrations can be added directly. This output has to stand alone
+ * against that reader, or the fix reads as an obstacle to work around.
+ */
+function reportHeldMigrations(heldMigrations) {
+	if (heldMigrations.length === 0) return;
+	console.log(`\n${heldMigrations.length} migration file(s) held back - NOT copied into the project:`);
+	for (const f of heldMigrations) console.log(`  - ${f}`);
+	console.log("\nDo NOT copy these in by hand, and do not take the upstream meta/ snapshots either.");
+	console.log("Drizzle runs a migration only when its journal entry is newer than the newest one");
+	console.log("already applied, so a pasted-in file never runs, `migrate` still exits 0, and the");
+	console.log("table it should have created silently does not exist. Regenerate instead:");
+	console.log("  1. Merge the upstream schema change into packages/database/src/db/");
+	console.log("  2. Run: pnpm --filter @repo/database generate");
+	console.log("  3. Copy any hand-written statements (seeds, backfills, data migrations) out of the");
+	console.log("     staged .sql at .generatesaas/staging/<path above> into the file step 2 wrote -");
+	console.log("     `generate` infers structure only, so those statements are lost otherwise");
+	console.log("  4. Run: pnpm --filter @repo/database migrate");
+}
+
 try {
 	main();
 } catch (err) {

package/dist/skill/content/scripts/prepare-update.js

@@ -12,10 +12,13 @@ const { execFileSync } = require("node:child_process");
 const { findProjectRoot, ensureDir, hashFile, walkDir, shouldExcludeWalk, TEMPLATE_HASHES_FILE, TEMPLATE_DIR, STAGING_DIR, STAGING_META_FILE } = require("./_helpers.js");
 
 // Paths whose upstream changes always carry follow-up work for the user:
-// database schema changes may need a migration, .env.example changes may need
-// new environment variables. Surfaced as `sensitive` in update-manifest.json.
+// database schema changes may need a migration, incoming migrations must be
+// regenerated into the project's own history before drizzle will run them, and
+// .env.example changes may need new environment variables. Surfaced as
+// `sensitive` in update-manifest.json.
 const SENSITIVE_PATTERNS = [
 	/^packages\/database\/src\/db\//,
+	/^packages\/database\/drizzle\//,
 	/(^|\/)\.env\.example$/,
 ];
 
@@ -105,7 +108,7 @@ function main() {
 		console.log(`  Renamed: ${renamed.length} (see update-manifest.json - port customizations before deleting the old paths)`);
 	}
 	if (sensitive.length > 0) {
-		console.log(`  Sensitive (schema / env example): ${sensitive.length}`);
+		console.log(`  Sensitive (schema / migrations / env example): ${sensitive.length}`);
 	}
 
 	// Determine output directory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generatesaas",
-  "version": "2.3.0",
+  "version": "3.0.1",
   "type": "module",
   "description": "CLI for scaffolding and managing GenerateSaaS projects",
   "license": "UNLICENSED",
@@ -26,7 +26,7 @@
     "@repo/tsconfig": "1.0.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.18"
   },
   "scripts": {
     "build": "tsup",