generatesaas 1.9.3 → 1.11.0

package/dist/skill/content/SKILL.md

@@ -105,15 +105,22 @@ Creates:
   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
+- `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)
 
 ### Step 2: Present Changelog
 
-Read `references/changelog.md`. It may be one of two shapes:
+Read `references/changelog.md`. When the update spans multiple releases, it contains one `# vX.Y.Z` section per release, oldest first - read ALL of them, not just the last; a breaking change can sit in any intermediate release. A `[BREAKING]` marker on a section header is authoritative (it comes from the version index: a major bump or release notes flagged BREAKING) - always call those releases out explicitly.
+
+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** - 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.
 
+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.
+
 Present a clear, organized summary:
 
 > ## What's New in v{targetVersion}
@@ -276,6 +283,12 @@ If `.generatesaas/template/<path>` does not exist (backward compat), fall back t
 
 #### For Removed Files
 
+**Check for renames first.** Look up the file in `renamed` in `references/update-manifest.json`. If it is the `from` of a rename, the same upstream content now lives at the `to` path (auto-created in Step 6). Present it as a rename, not an unrelated removal:
+
+- If the user never modified the old file: delete it and note the rename - nothing is lost.
+- If the user **modified** the old file: their customizations exist nowhere in the new version. Port them to the `to` path (show the proposed result) before deleting the old file. Never let a rename silently drop customizations.
+- Imports of the old path elsewhere in the project must be updated to the new path - run the import search below for the old path either way.
+
 Before presenting each removed file, **search the entire project** for imports of it. Use grep to find `import ... from` or `require(...)` statements referencing the file's path (check relative paths, aliases, and package paths). This is critical - the classification script only scans files in the update, not user-created files that may also depend on the removed file.
 
 ```
@@ -377,6 +390,13 @@ After all files are processed:
 
 If no files were held back, skip creating this file.
 
+> Note: the completion script runs a safety net that auto-holds-back upstream
+> changes which were demonstrably never applied (the file was not touched during
+> the entire update). Do NOT rely on it - it cannot detect a file you edited
+> during a merge or that the user customized between updates - always write
+> held-back.json yourself. Treat its warnings as a signal that your bookkeeping
+> missed something.
+
 2. **Run the completion script:**
 
 ```bash

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

@@ -39,14 +39,17 @@ function hashFile(filePath) {
 
 // ── File Walking ──
 
-// Broader than strictly needed, but aligned with the CLI's exclusions.ts to ensure
-// hash consistency across update cycles. The staging tarball is pre-filtered by
-// exclusions.ts, so most of these only matter when walking the live project root.
+// MUST stay in sync with the CLI's template/exclusions.ts: exactly
+// EXCLUDED_NAMES + SNAPSHOT_EXCLUDED_NAMES plus the two project-root extras
+// ("data", INTERNAL_DIR). A drift silently corrupts classification - a path the
+// CLI stages but this walker skips never gets diffed or hashed. The
+// exclusions-parity test in the CLI repo asserts this set equality.
 const WALK_EXCLUSIONS = new Set([
 	".git", "node_modules", ".pnpm-store", ".env", ".env.test",
 	".turbo", ".nuxt", ".output", ".data", "dist", "data",
 	".next", ".svelte-kit", ".wrangler",
 	".devcontainer", "playwright-report", "test-results",
+	"pnpm-lock.yaml",
 	INTERNAL_DIR,
 ]);
 
@@ -86,6 +89,8 @@ module.exports = {
 	ensureDir,
 	hashFile,
 	walkDir,
+	shouldExcludeWalk,
+	WALK_EXCLUSIONS,
 	INTERNAL_DIR,
 	MANIFEST_FILE,
 	HASHES_FILE,

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

@@ -15,43 +15,43 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { findProjectRoot, hashFile, walkDir, ensureDir, MANIFEST_FILE, HASHES_FILE, TEMPLATE_HASHES_FILE, TEMPLATE_DIR, STAGING_DIR, STAGING_META_FILE, INTERNAL_DIR } = require("./_helpers.js");
 
-const HASH_EXCLUSIONS = new Set([
-	".git", "node_modules", ".pnpm-store", ".env", ".env.test",
-	".turbo", ".nuxt", ".output", ".data", "dist", "data",
-	".next", ".svelte-kit", ".wrangler",
-	".devcontainer", "playwright-report", "test-results",
-	INTERNAL_DIR,
-]);
-
-/** Check if a relative path should be excluded from hashing. */
-function shouldExcludeFromHash(relativePath) {
-	const parts = relativePath.split("/");
-	for (const part of parts) {
-		if (HASH_EXCLUSIONS.has(part)) return true;
-		if (part.startsWith(".env") && !part.includes("example")) return true;
-	}
-	return false;
-}
-
-/** Recursively collect all file paths for project hashing. */
-function collectProjectFiles(dir, baseDir) {
-	const files = [];
-	const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-	for (const entry of entries) {
-		const fullPath = path.join(dir, entry.name);
-		const rel = path.relative(baseDir, fullPath);
-
-		if (shouldExcludeFromHash(rel)) continue;
-
-		if (entry.isDirectory()) {
-			files.push(...collectProjectFiles(fullPath, baseDir));
-		} else if (entry.isFile()) {
-			files.push(fullPath);
-		}
+/**
+ * Safety net for the held-back list. An upstream change was demonstrably never
+ * applied when the file (a) really changed upstream (old template hash differs
+ * from staging), (b) still exists on disk, and (c) was not touched during the
+ * entire update (its disk hash still equals the previous hashes.json entry).
+ * Such files MUST be held back - otherwise the template baseline advances past
+ * a change the project never received and the next update's diff silently
+ * drops it. Returns the detected paths (sorted) and adds them to `heldBack`.
+ *
+ * This is a net, not a replacement for the AI-written held-back.json: a file
+ * the user customized since the last update and then kept during this one
+ * cannot be distinguished from a merged file by hashes alone.
+ */
+function applyHeldBackSafetyNet(root, stagingDir, stagingFiles, heldBack) {
+	const templateHashesPath = path.join(root, TEMPLATE_HASHES_FILE);
+	const hashesPath = path.join(root, HASHES_FILE);
+	const oldTemplateHashes = fs.existsSync(templateHashesPath)
+		? JSON.parse(fs.readFileSync(templateHashesPath, "utf-8"))
+		: {};
+	const prevProjectHashes = fs.existsSync(hashesPath)
+		? JSON.parse(fs.readFileSync(hashesPath, "utf-8"))
+		: {};
+
+	const netted = [];
+	for (const rel of stagingFiles) {
+		if (heldBack.has(rel)) continue;
+		const oldHash = oldTemplateHashes[rel];
+		const prevHash = prevProjectHashes[rel];
+		if (!oldHash || !prevHash) continue;
+		const diskPath = path.join(root, rel);
+		if (!fs.existsSync(diskPath)) continue;
+		if (hashFile(path.join(stagingDir, rel)) === oldHash) continue;
+		if (hashFile(diskPath) !== prevHash) continue;
+		heldBack.add(rel);
+		netted.push(rel);
 	}
-
-	return files;
+	return netted.sort();
 }
 
 /**
@@ -133,6 +133,15 @@ function main() {
 		console.log("Updating template directory from staging...");
 		const stagingFiles = new Set(walkDir(stagingDir, stagingDir));
 
+		// Safety net: auto-hold-back upstream changes that were demonstrably
+		// never applied but are missing from held-back.json.
+		const netted = applyHeldBackSafetyNet(root, stagingDir, stagingFiles, heldBack);
+		if (netted.length > 0) {
+			console.warn(`Safety net: ${netted.length} upstream change(s) were never applied and were missing from held-back.json.`);
+			console.warn("Holding them back so the next update re-surfaces them:");
+			for (const rel of netted) console.warn(`  - ${rel}`);
+		}
+
 		// 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
@@ -219,11 +228,10 @@ function main() {
 
 	// Re-hash all project files
 	console.log("Hashing project files...");
-	const files = collectProjectFiles(root, root);
+	const files = walkDir(root, root);
 	const fileHashes = {};
-	for (const file of files.sort()) {
-		const rel = path.relative(root, file);
-		fileHashes[rel] = hashFile(file);
+	for (const rel of files.sort()) {
+		fileHashes[rel] = hashFile(path.join(root, rel));
 	}
 
 	// Update version in manifest

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

@@ -9,7 +9,15 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { execFileSync } = require("node:child_process");
-const { findProjectRoot, ensureDir, hashFile, walkDir, TEMPLATE_HASHES_FILE, TEMPLATE_DIR, STAGING_DIR, STAGING_META_FILE } = require("./_helpers.js");
+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.
+const SENSITIVE_PATTERNS = [
+	/^packages\/database\/src\/db\//,
+	/(^|\/)\.env\.example$/,
+];
 
 function main() {
 	const root = findProjectRoot();
@@ -36,11 +44,17 @@ function main() {
 
 	console.log(`Preparing update: ${currentVersion} → ${targetVersion}`);
 
-	// Read old template hashes
+	// Read old template hashes. Entries that are no longer part of the template
+	// universe (e.g. pnpm-lock.yaml after an exclusions update) are dropped so
+	// they don't surface as phantom "removed upstream" files.
 	const templateHashesPath = path.join(root, TEMPLATE_HASHES_FILE);
-	const oldHashes = fs.existsSync(templateHashesPath)
+	const oldHashesRaw = fs.existsSync(templateHashesPath)
 		? JSON.parse(fs.readFileSync(templateHashesPath, "utf-8"))
 		: {};
+	const oldHashes = {};
+	for (const [filePath, hash] of Object.entries(oldHashesRaw)) {
+		if (!shouldExcludeWalk(filePath)) oldHashes[filePath] = hash;
+	}
 
 	// Walk staging dir and compute new template hashes
 	const stagingFiles = walkDir(stagingDir, stagingDir);
@@ -74,7 +88,25 @@ function main() {
 	modified.sort();
 	removed.sort();
 
+	// Detect upstream renames: a removed file whose baseline content reappears
+	// verbatim at exactly one added path (and vice versa). Surfaced so user
+	// customizations on the old path can be ported before it is deleted -
+	// otherwise a rename reads as an unrelated add + remove and customizations
+	// on the old path are silently lost.
+	const renamed = detectRenames(oldHashes, newHashes, added, removed);
+
+	// Flag changes that always carry follow-up work (migrations, new env vars).
+	const sensitive = [...modified, ...added]
+		.filter((filePath) => SENSITIVE_PATTERNS.some((pattern) => pattern.test(filePath)))
+		.sort();
+
 	console.log(`  Added: ${added.length}, Modified: ${modified.length}, Removed: ${removed.length}`);
+	if (renamed.length > 0) {
+		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}`);
+	}
 
 	// Determine output directory
 	const scriptDir = __dirname;
@@ -124,13 +156,15 @@ function main() {
 	}
 	console.log(`Written: ${diffCount} diff files`);
 
-	// Write update manifest (same format as before)
+	// Write update manifest (same format as before, plus renamed + sensitive)
 	const updateManifest = {
 		currentVersion,
 		targetVersion,
 		added,
 		modified,
 		removed,
+		renamed,
+		sensitive,
 	};
 	fs.writeFileSync(
 		path.join(refsDir, "update-manifest.json"),
@@ -142,6 +176,35 @@ function main() {
 	console.log("\nNext: Review references/changelog.md, then run classify-files.js");
 }
 
+/**
+ * Detect upstream renames by exact content hash: a removed path whose baseline
+ * hash matches exactly one added path's staging hash (1:1 both ways - ambiguous
+ * matches are skipped). Returns [{ from, to }] sorted by old path.
+ */
+function detectRenames(oldHashes, newHashes, added, removed) {
+	if (added.length === 0 || removed.length === 0) return [];
+
+	const addedByHash = new Map();
+	for (const filePath of added) {
+		const hash = newHashes[filePath];
+		addedByHash.set(hash, (addedByHash.get(hash) || []).concat(filePath));
+	}
+	const removedByHash = new Map();
+	for (const filePath of removed) {
+		const hash = oldHashes[filePath];
+		removedByHash.set(hash, (removedByHash.get(hash) || []).concat(filePath));
+	}
+
+	const renamed = [];
+	for (const [hash, fromPaths] of removedByHash) {
+		const toPaths = addedByHash.get(hash);
+		if (fromPaths.length === 1 && toPaths && toPaths.length === 1) {
+			renamed.push({ from: fromPaths[0], to: toPaths[0] });
+		}
+	}
+	return renamed.sort((a, b) => a.from.localeCompare(b.from));
+}
+
 /** Generate a unified diff between two files. Returns null if diff is unavailable. */
 function generateDiff(userFile, stagingFile, relativePath) {
 	try {

package/package.json

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