generatesaas 1.0.0 → 1.1.0

package/dist/skill/content/SKILL.md

@@ -19,7 +19,7 @@ Update your project to the latest GenerateSaaS boilerplate version while preserv
 
 ```
 Step 0: Pre-flight safety checks
-Step 1: Prepare update data (script)
+Step 1: Fetch + stage + prepare update data (you run the CLI, then the script)
 Step 2: Present changelog to user
 Step 3: Classify files (script)
 Step 4: Analyze dependencies
@@ -30,13 +30,26 @@ Step 8: Post-update validation
 Step 9: Complete update (script)
 ```
 
+**You own the whole flow.** When the user says "update my GenerateSaaS project," do
+everything end-to-end — including fetching and staging the new version (Step 1).
+The user does not run any CLI command themselves.
+
+**What the staged update contains (important):** `generatesaas update` re-shapes the
+new version's template into THIS project's exact configuration before staging — same
+frontend, payment provider, database, feature flags, etc. So everything in
+`.generatesaas/staging/` and the `.generatesaas/template/` baseline is buyer-shaped:
+you will never see another framework's files, a provider the project doesn't use, the
+boilerplate's internal tooling, or dev-only secrets. Every diff you surface already
+applies to this project. The 3-way merge baseline (`.generatesaas/template/`) is a
+faithful pristine copy of what this project started from — trust it.
+
 ---
 
 ### Step 0: Pre-flight
 
 Before starting the update:
 
-1. **Check git status.** Run `git status`. If there are ANY uncommitted changes (staged, unstaged, or untracked files in tracked directories), **STOP immediately**. Do NOT proceed with the update. Tell the user:
+1. **Check git status.** Run `git status --porcelain -- . ':(exclude).generatesaas'` (or otherwise ignore changes under `.generatesaas/`). The update process writes its own artifacts there — `staging.json`, `manifest.json` (license refresh), `held-back.json`, hash files — so those must NOT count as a dirty tree. If, ignoring `.generatesaas/`, there are ANY uncommitted changes (staged, unstaged, or untracked files in tracked directories), **STOP immediately**. Do NOT proceed with the update. Tell the user:
 
 > You have uncommitted changes. The update cannot proceed until your working tree is clean — this ensures you have a safe rollback point if anything needs to be reverted.
 >
@@ -60,7 +73,27 @@ If the user chooses option 1, stop completely. Do not continue the update.
 
 If starting fresh, delete the old plan file. Note: files that were auto-applied in the previous attempt may now have V2 content but template-hashes.json still has V1 hashes — these will be correctly classified as "modified" (since they differ from the V1 template hash) and the AI will see they match the staging file, making them trivial merges.
 
-### Step 1: Prepare Update Data
+### Step 1: Fetch, Stage, and Prepare Update Data
+
+**1a. Stage the new version yourself.** Unless a staged update already exists
+(`.generatesaas/staging.json` present), run the CLI to fetch the latest version and
+stage it — re-shaped for this project's exact configuration:
+
+```bash
+npx generatesaas@latest update
+```
+
+This resolves the saved API key from `~/.generatesaas` (written at init), so it runs
+non-interactively. It refreshes the skill files, downloads the new version, shapes it
+into this project's configuration, and writes `.generatesaas/staging/` + `staging.json`.
+If it reports "Already on the latest version," there is nothing to update — tell the
+user and stop. If it fails for lack of an API key or network, ask the user to run
+`npx generatesaas@latest update` themselves, then continue.
+
+> 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.
+
+**1b. Prepare the diff/classification data:**
 
 ```bash
 node __SKILL_ROOT__/generatesaas-update/scripts/prepare-update.js
@@ -68,19 +101,29 @@ node __SKILL_ROOT__/generatesaas-update/scripts/prepare-update.js
 
 Creates:
 - `references/changelog.md` — what changed and why
-- `references/diffs/*.diff` — unified diffs for each changed file
+- `references/diffs/<path>.diff` — one unified diff per changed file, named by the
+  file's project-relative path with `.diff` appended (e.g.
+  `references/diffs/packages/config/src/index.ts.diff`). Diffs cover `modified` +
+  `added` files; `unmodified`, `deleted`, and `removed` files have none.
 - `references/update-manifest.json` — lists of added, modified, and removed files
 
 ### Step 2: Present Changelog
 
-Read `references/changelog.md` and present a clear, organized summary:
+Read `references/changelog.md`. It may be one of two shapes:
+
+- **Curated** — contains explicit `## Breaking`, `## Migration`, `## Features`, `## Fixes` (or similar) sections. Use those sections verbatim; they are authoritative.
+- **Raw** — auto-generated release notes (a flat list of PR titles, no sections). This is the common case. You can group PR titles into features/fixes by reading them, but you **cannot** reliably infer breaking changes or migration steps from PR titles.
+
+Present a clear, organized summary:
 
 > ## What's New in v{targetVersion}
 >
-> **Breaking changes:** {list or "None"}
+> **Breaking changes:** {from a Breaking section, or "⚠️ Not specified in the changelog — review the diffs in Step 7 carefully, especially database/schema and config files"}
 > **New features:** {list}
 > **Bug fixes:** {list}
-> **Migration steps required:** {list or "None"}
+> **Migration steps required:** {from a Migration section, or "⚠️ None listed — if this update changes the database schema or required env vars, you may still need to migrate. I'll flag schema/config changes as we review them."}
+
+**Be honest about uncertainty.** Never present an inferred "Breaking changes: None" or "Migration steps: None" as if it were authoritative when the changelog is raw PR titles — say it's not specified and that you'll watch for schema/config/env changes during the file review. A silently-missed migration (e.g. a new DB column) is the worst failure mode.
 
 Then ask: *"Ready to proceed with the file analysis?"*
 
@@ -97,7 +140,8 @@ Read `references/classification.json`. It contains:
 - **unmodified** — file matches the original template, safe to replace
 - **modified** — user has customized this file, needs careful review
 - **deleted** — user deleted this file, skip update for it
-- **new** — file doesn't exist locally, safe to create
+- **new** — file doesn't exist locally and its directory tree is genuinely new upstream, safe to create
+- **newInDeletedTree** — file is new upstream BUT lives inside a directory tree the user intentionally deleted (the tree existed in the baseline and is now gone on disk). **Never auto-create these.** Ask the user whether to bring the tree back (see "For New Files In Deleted Trees" in Step 7).
 - **removed** — file was removed upstream, user decides whether to delete
 - **crossDependencies** — import relationships between categories (if detected)
 
@@ -110,9 +154,10 @@ This step prevents breaking the user's code through indirect effects.
    - `unmodifiedImportsModified` — auto-apply files that import from modified files
    - `newImportsModified` — new files that import from modified files
 
-2. **For each cross-dependency**, read the relevant diff at `references/diffs/<path>.diff`:
-   - If an auto-apply file's diff changes **exports, function signatures, types, or interfaces** that a modified file uses → promote it from `unmodified` to `modified` (it needs user review alongside its dependent)
-   - If an auto-apply file imports from a modified file → flag it as needing review after the modified file is handled
+2. **For each cross-dependency**, read the relevant diff at `references/diffs/<path>.diff`. Handle all three directions the classifier emits:
+   - **`modifiedImportsUnmodified`** — a modified file imports from an auto-apply (unmodified) file. If the auto-apply file's diff changes **exports, function signatures, types, or interfaces** that the modified file uses → promote it from `unmodified` to `modified` (it needs user review alongside its dependent, so the merge accounts for the new API).
+   - **`unmodifiedImportsModified`** — an auto-apply file imports from a modified file. After the modified file is handled in Step 7, re-check this auto-apply file: if the user kept their version of the modified file but the auto-apply file's new version expects the upstream API, the auto-apply file may not be compatible. Flag it and revisit in the Step 7 cascade-awareness check.
+   - **`newImportsModified`** — a new file imports from a modified file. The new file will be auto-created in Step 6. After the modified file is handled, verify the new file's imports resolve against whatever version of the modified file the user ended up with (their merge, their kept version, or upstream). If the new file expects the upstream API but the user kept their version, surface it.
 
 3. **Update `references/classification.json`**: before making any changes, copy the file to `references/classification-original.json` as a backup. Then move any promoted files from the `unmodified` array to the `modified` array. This ensures `apply-auto.js` only touches truly safe files. If you need to redo the analysis, restore from the backup.
 
@@ -167,10 +212,13 @@ Then ask the user to choose their interaction level:
 Based on the user's chosen mode:
 
 **Recommended / Quick mode:**
+
+Preview first (especially useful in Careful mode or when unsure), then apply:
 ```bash
+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
 ```
-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` (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.
 
 **Careful mode:**
 Present the list of safe auto-updates and new files to the user:
@@ -248,6 +296,23 @@ If ANY files import the removed file, always warn before deletion and explain wh
 
 Files the user intentionally deleted — skip silently. Just note in the plan: "Skipped — user previously deleted this file."
 
+#### For New Files In Deleted Trees (`newInDeletedTree`)
+
+These are files the new version adds inside a directory the user previously deleted (e.g. a feature package they removed). Auto-creating them would silently resurrect the deleted tree. Group them by their deleted ancestor directory and ask once per tree:
+
+```
+### New upstream files under `{deleted dir}/` (which you removed)
+
+The new version adds {N} files under `{deleted dir}/` — a directory you previously deleted:
+- `{path}` — {what it is}
+
+> **What would you like to do?**
+> 1. **Keep it deleted** — Skip these files (you removed this feature on purpose)
+> 2. **Bring the tree back** — Create these files (you want this feature after all)
+```
+
+Default to **keep deleted** unless the user says otherwise. If they keep it deleted, note in the plan and do nothing (the completion script handles the hashes correctly — these files simply won't exist).
+
 #### After Each File
 
 1. Apply the user's chosen action immediately
@@ -276,10 +341,11 @@ After all files are processed:
 
 1. **Check for obvious issues:**
    - Scan merged files for syntax errors or broken imports
-   - If the project has TypeScript, suggest running type check
-   - Note: auto-applied files may have changed their exports/API in ways that affect **user-created files** (files not part of the template). The classification script only scans template files for cross-dependencies. A type check is the best way to catch breakage in user-created files.
+   - If the project has TypeScript, run the type check (`pnpm check-types`)
+   - **Run the test suite (`pnpm test`) too — do not rely on the type check alone.** Most packages scope `check-types` to `src/**` and exclude `tests/**`, so a type error introduced into a **test file** during a merge will pass `check-types` silently. If any of your merges landed in a `tests/` file, the test suite is the only gate that exercises it. When in doubt, also type-check the specific merged test files directly (e.g. `npx tsc --noEmit <file>` with the package's tsconfig settings).
+   - Note: auto-applied files may have changed their exports/API in ways that affect **user-created files** (files not part of the template). The classification script only scans template files for cross-dependencies. A type check + test run is the best way to catch breakage in user-created files.
 
-> All changes have been applied. Would you like me to run a type check / build to verify nothing is broken? This is especially important since some auto-applied files may have changed their API, which could affect your custom files.
+> All changes have been applied. I'll run the type check **and** the test suite to verify nothing is broken — the type check alone skips test files, and some auto-applied files may have changed their API in ways that affect your custom code or tests.
 
 2. If issues are found, present them:
 

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

@@ -36,6 +36,8 @@ 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];
 
 	if (filesToCopy.length === 0) {
@@ -43,25 +45,42 @@ function main() {
 		return;
 	}
 
-	console.log(`Copying ${filesToCopy.length} files from staging...`);
-
+	const dryRun = process.argv.includes("--dry-run");
 	const unmodifiedSet = new Set(classification.unmodified);
+
+	// Pre-flight: every source must exist in staging. Abort BEFORE touching the
+	// project if any are missing — never leave a half-applied tree (there is no
+	// rollback besides git). Buyer-shaped staging should always contain them; a
+	// miss means staging is stale or incomplete.
+	const missing = filesToCopy.filter((f) => !fs.existsSync(path.join(stagingDir, f)));
+	if (missing.length > 0) {
+		console.error(`Error: ${missing.length} file(s) not found in staging — aborting without changes:`);
+		for (const f of missing) console.error(`  - ${f}`);
+		console.error("Re-stage the update (run 'npx generatesaas@latest update') and retry.");
+		process.exit(1);
+	}
+
+	const willUpdate = filesToCopy.filter((f) => unmodifiedSet.has(f)).length;
+	const willCreate = filesToCopy.length - willUpdate;
+
+	if (dryRun) {
+		console.log(`[dry run] Would update ${willUpdate} file(s) and create ${willCreate} new file(s):`);
+		for (const filePath of filesToCopy) {
+			console.log(`  ${unmodifiedSet.has(filePath) ? "update" : "create"}  ${filePath}`);
+		}
+		console.log("\n[dry run] No files were modified.");
+		return;
+	}
+
+	console.log(`Copying ${filesToCopy.length} files from staging...`);
 	let updated = 0;
 	let created = 0;
-	const failed = [];
 
 	for (const filePath of filesToCopy) {
 		const stagingPath = path.join(stagingDir, filePath);
 		const fullPath = path.join(root, filePath);
-
-		if (!fs.existsSync(stagingPath)) {
-			failed.push(filePath);
-			continue;
-		}
-
 		ensureDir(path.dirname(fullPath));
 		fs.copyFileSync(stagingPath, fullPath);
-
 		if (unmodifiedSet.has(filePath)) {
 			updated++;
 		} else {
@@ -71,13 +90,6 @@ function main() {
 
 	console.log(`\nUpdated ${updated} files, created ${created} new files.`);
 
-	if (failed.length > 0) {
-		console.log(`\nWarning: ${failed.length} files not found in staging:`);
-		for (const f of failed) {
-			console.log(`  - ${f}`);
-		}
-	}
-
 	if (classification.modified.length > 0) {
 		console.log(`\n${classification.modified.length} files still need manual merge.`);
 		console.log("Review diffs in references/diffs/ and apply changes preserving your customizations.");

package/dist/skill/content/scripts/classify-files.js

@@ -84,6 +84,29 @@ function matchImportToFile(importPath, fromFilePath, knownFileSet) {
 	return null;
 }
 
+/**
+ * Decide whether an upstream-added file (absent on disk) sits inside a directory
+ * tree the buyer intentionally DELETED, versus a brand-new tree upstream just
+ * introduced.
+ *
+ * Walks the file's ancestor directories shallow→deep. The first ancestor that is
+ * missing on disk is the boundary: if that directory HAD files in the old
+ * template baseline, the buyer removed a tree that used to exist → return it
+ * (don't silently recreate). If it never existed in the baseline, it's a
+ * legitimately new tree → return null (safe to auto-create).
+ */
+function deletedTreeAncestor(filePath, root, baselineFiles) {
+	const parts = filePath.split("/");
+	for (let i = 1; i < parts.length; i++) {
+		const dir = parts.slice(0, i).join("/");
+		if (fs.existsSync(path.join(root, dir))) continue;
+		// First missing ancestor. Did it exist in the old template?
+		const existedInTemplate = baselineFiles.some((f) => f === dir || f.startsWith(dir + "/"));
+		return existedInTemplate ? dir : null;
+	}
+	return null;
+}
+
 /**
  * Scan files for imports and build cross-dependency map between categories.
  */
@@ -96,6 +119,7 @@ function buildCrossDependencies(root, classification, stagingDir) {
 		...classification.unmodified,
 		...classification.modified,
 		...classification.new,
+		...classification.newInDeletedTree,
 		...classification.deleted,
 		...classification.removed,
 	]);
@@ -212,9 +236,12 @@ function main() {
 		modified: [],
 		deleted: [],
 		new: [],
+		newInDeletedTree: [],
 		removed: [],
 	};
 
+	const baselineFiles = Object.keys(baselineHashes);
+
 	// Classify modified files (upstream changed, check if user also changed)
 	for (const filePath of updateManifest.modified) {
 		const fullPath = path.join(root, filePath);
@@ -242,6 +269,10 @@ function main() {
 		const fullPath = path.join(root, filePath);
 		if (fs.existsSync(fullPath)) {
 			classification.modified.push(filePath);
+		} else if (deletedTreeAncestor(filePath, root, baselineFiles)) {
+			// Upstream added a file inside a directory tree the buyer deleted on
+			// purpose. Don't silently recreate the tree — surface for a decision.
+			classification.newInDeletedTree.push(filePath);
 		} else {
 			classification.new.push(filePath);
 		}
@@ -274,13 +305,22 @@ function main() {
 	console.log("File Classification Summary");
 	console.log("===========================");
 	console.log(`Target version: ${classification.targetVersion}`);
-	console.log(`  Unmodified (auto-update): ${classification.unmodified.length}`);
-	console.log(`  Modified (manual merge):  ${classification.modified.length}`);
-	console.log(`  Deleted by user (skip):   ${classification.deleted.length}`);
-	console.log(`  New files (auto-create):  ${classification.new.length}`);
-	console.log(`  Removed upstream:         ${classification.removed.length}`);
+	console.log(`  Unmodified (auto-update):   ${classification.unmodified.length}`);
+	console.log(`  Modified (manual merge):    ${classification.modified.length}`);
+	console.log(`  Deleted by user (skip):     ${classification.deleted.length}`);
+	console.log(`  New files (auto-create):    ${classification.new.length}`);
+	console.log(`  New in deleted tree (ask):  ${classification.newInDeletedTree.length}`);
+	console.log(`  Removed upstream:           ${classification.removed.length}`);
 	console.log("");
 
+	if (classification.newInDeletedTree.length > 0) {
+		console.log("New files inside trees you deleted (do NOT auto-create — ask the user):");
+		for (const f of classification.newInDeletedTree) {
+			console.log(`  - ${f}`);
+		}
+		console.log("");
+	}
+
 	if (classification.modified.length > 0) {
 		console.log("Files needing manual merge:");
 		for (const f of classification.modified) {

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

@@ -96,6 +96,23 @@ function main() {
 		console.log("Updating template directory from staging...");
 		const stagingFiles = new Set(walkDir(stagingDir, stagingDir));
 
+		// Validate held-back entries (non-fatal). A held-back file is supposed to be
+		// a real upstream change the user chose to skip — preserving its old template
+		// version so the next update re-surfaces the missed change. Warn on entries
+		// that can't be that: a path not in staging (nothing to hold back), or a file
+		// identical between old template and staging (no upstream change to preserve).
+		// A wrong held-back entry silently corrupts the next update's diff baseline.
+		for (const rel of heldBack) {
+			if (!stagingFiles.has(rel)) {
+				console.warn(`  Warning: held-back "${rel}" is not in staging — nothing to hold back. Check .generatesaas/held-back.json.`);
+				continue;
+			}
+			const oldTemplateFile = path.join(templateDir, rel);
+			if (fs.existsSync(oldTemplateFile) && hashFile(oldTemplateFile) === hashFile(path.join(stagingDir, rel))) {
+				console.warn(`  Warning: held-back "${rel}" is identical in the old template and staging — no upstream change to preserve.`);
+			}
+		}
+
 		// Copy staging files to template dir (skip held-back — old version stays)
 		let copied = 0;
 		let skipped = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "generatesaas",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "CLI for scaffolding and managing GenerateSaaS projects",
   "bin": {