generatesaas 0.1.0

package/dist/skill/content/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: generatesaas-update
+description: Update GenerateSaaS project to latest boilerplate version. Handles version checks, file classification, generates an update plan for user review, and applies changes while preserving user customizations.
+---
+
+# GenerateSaaS Update
+
+Update your project to the latest GenerateSaaS boilerplate version while preserving all your customizations.
+
+## Core Principles
+
+1. **User changes always come first** — Every update must preserve the user's functionality, business logic, and intentional modifications. If an upstream change conflicts with something the user built, the user's version wins.
+2. **Never break user code** — If applying an upstream change would break the user's customizations or doesn't make sense in the context of their modifications, skip it and document why.
+3. **Plan before acting** — Generate a full update plan. The user reviews and approves before anything is applied.
+4. **Track everything** — Every change is tracked in a checklist. Mark items as completed, skipped, or failed so the user knows exactly what happened.
+
+## Workflow
+
+### Step 1: Prepare Update Data
+
+```bash
+node .claude/skills/generatesaas-update/scripts/prepare-update.js
+```
+
+Reads the staged update from `.generatesaas/staging/` and computes local diffs. Creates:
+- `references/changelog.md` — what changed and why
+- `references/diffs/*.diff` — unified diffs for each modified file
+- `references/update-manifest.json` — lists of added, modified, and removed files
+
+### Step 2: Review Changelog
+
+Read `references/changelog.md` to understand:
+- Breaking changes that need attention
+- New features being added
+- Bug fixes included
+- Migration steps if any
+
+### Step 3: Classify Files
+
+```bash
+node .claude/skills/generatesaas-update/scripts/classify-files.js
+```
+
+Compares local file hashes (from `.generatesaas/hashes.json`) against current files to determine which the user has customized. Outputs `references/classification.json` with categories:
+
+- **unmodified** — file matches the original hash, safe to auto-update
+- **modified** — user has customized this file, needs careful merge
+- **deleted** — user deleted this file, skip update
+- **new** — file doesn't exist locally, safe to create
+- **removed** — file was removed upstream, review before deleting
+
+### Step 4: Generate Update Plan
+
+**This is a critical step.** After classification, generate the update plan file at:
+
+```
+.generatesaas/updates/update-{currentVersion}-to-{targetVersion}.md
+```
+
+The plan must follow this format:
+
+```markdown
+# Update: {currentVersion} → {targetVersion}
+
+Date: {YYYY-MM-DD}
+
+## Summary
+
+{Brief description of what this update includes based on the changelog}
+
+## Auto-Updates (Unmodified Files)
+
+These files haven't been modified and will be updated automatically:
+
+- [x] `path/to/file.ts` — {brief description of change}
+- [x] `path/to/other.ts` — {brief description of change}
+
+## New Files
+
+These files are new in this version and will be created:
+
+- [x] `path/to/new-file.ts` — {what this file does}
+
+## Manual Merges (Modified Files)
+
+These files have been customized. Changes will be merged preserving your modifications:
+
+- [ ] `path/to/modified.ts` — {what upstream changed vs what you changed}
+- [ ] `path/to/config.ts` — {description}
+
+## Removed Upstream
+
+These files were removed in the new version. Review before deleting:
+
+- [ ] `path/to/old-file.ts` — {why it was removed}
+
+## Skipped
+
+Changes that were not applied (with reasons):
+
+{empty until items are skipped during execution}
+```
+
+**Present this plan to the user.** Explain the key changes and ask if they want to exclude anything. Wait for confirmation before proceeding.
+
+If the user wants to exclude items, move them to the **Skipped** section with the reason "Excluded by user".
+
+### Step 5: Apply Auto-Updates
+
+```bash
+node .claude/skills/generatesaas-update/scripts/apply-auto.js
+```
+
+Automatically updates `unmodified` files and creates `new` files. These are safe because:
+- Unmodified files have no user changes to preserve
+- New files don't conflict with anything
+
+After this completes, mark all auto-update and new file items as `[x]` in the plan.
+
+### Step 6: Manual Merge (Modified Files)
+
+For each file in the `modified` category, work through the plan checklist one by one:
+
+1. Read the corresponding diff at `references/diffs/<path>.diff`
+2. Read the current local file
+3. Understand what the user changed and why
+4. Apply upstream changes that are compatible with the user's modifications
+5. **Skip changes that would break user functionality** — move to Skipped section with explanation
+6. Mark the item as `[x]` in the plan when done
+
+For `removed` files:
+1. Check if the user depends on the file
+2. If the user modified it or other files import it, move to Skipped with explanation
+3. If truly unused, delete it and mark as `[x]`
+
+**After each file, update the plan file** so progress is tracked in real-time.
+
+### Step 7: Complete Update
+
+After all items are processed:
+
+1. Review the plan — verify every item is either `[x]` (completed) or listed in Skipped with a reason
+2. If any items are still unchecked, address them or move to Skipped with explanation
+3. Run the completion script:
+
+```bash
+node .claude/skills/generatesaas-update/scripts/complete-update.js
+```
+
+This regenerates `.generatesaas/hashes.json` with fresh file hashes and updates the version in `.generatesaas/manifest.json`. Cleans up the `references/` directory.
+
+4. Add a final status to the plan file:
+
+```markdown
+## Result
+
+- **Status**: Completed
+- **Files updated**: {count}
+- **Files created**: {count}
+- **Files merged**: {count}
+- **Items skipped**: {count}
+- **Post-update steps**: {e.g., "Run pnpm install", "Run migrations", etc.}
+```
+
+## Merge Strategies
+
+### Config Files (`*.config.ts`, `config/index.ts`, `config/pricing.ts`)
+
+Config files are the most commonly customized. The upstream diff usually adds new options or changes defaults.
+
+- Preserve all user-set values
+- Add new config keys with their default values
+- If a key was renamed upstream, migrate the user's value to the new key
+- Keep user's formatting preferences if they differ
+
+### Components (`.vue`, `.tsx`)
+
+- Preserve user-added props, slots, and event handlers
+- Apply upstream structural changes (new elements, changed layouts)
+- Keep user's custom CSS classes and styles
+- If the component was significantly restructured upstream, present both versions and ask
+
+### API Routes (`routes/*.ts`)
+
+- Preserve user-added endpoints and middleware
+- Apply upstream changes to existing endpoints (bug fixes, new validations)
+- Keep user-added business logic intact
+- Watch for new imports or dependency changes
+
+### Database (schema, migrations)
+
+- NEVER auto-merge schema files — always present changes for review
+- New migration files can be added directly
+- Schema changes may require new migrations the user needs to create
+
+### Package Dependencies (`package.json`)
+
+- Add new dependencies from upstream
+- Update version ranges for existing dependencies only if the upstream change is intentional (security fix, breaking change requirement)
+- Preserve user-added dependencies
+- Never modify `pnpm-lock.yaml` — user runs `pnpm install` after
+
+### Translation Files (`en.json`)
+
+- Add new translation keys from upstream
+- Preserve user-modified translation values
+- Remove keys that were deleted upstream (they're unused)
+- Maintain alphabetical ordering within sections
+
+### Environment Files (`.env.example`)
+
+- Add new environment variables with their example values
+- Preserve user-added variables
+- Update comments for changed variables
+- Never touch actual `.env` files
+
+## When to Skip a Change
+
+Move the item to the **Skipped** section of the plan with a clear reason when:
+
+- The upstream change modifies code the user has significantly rewritten — applying it would undo their work
+- The upstream fix addresses a bug the user already fixed differently
+- A new feature conflicts with the user's custom implementation of the same thing
+- Applying the change would create invalid code, type errors, or runtime failures
+- The user explicitly asked to exclude it
+
+When skipping, always explain:
+- What the upstream change was trying to do
+- Why it was skipped
+- Whether the user should manually review it later
+
+## When to Ask the User
+
+- Schema changes that might need migrations
+- Removed files or features the user might depend on
+- Config changes where the user's value conflicts with a new required format
+- Component restructures where preserving user changes is ambiguous
+- Any change where applying both upstream and user modifications would create invalid code
+- When you're unsure whether a user's modification was intentional
+
+## Examples
+
+### Config merge
+
+Upstream diff adds a new `analytics` field:
+```diff
+ export default {
+   siteName: "My SaaS",
++  analytics: {
++    enabled: true,
++    provider: "plausible",
++  },
+   billing: {
+     scope: "organization",
+   },
+ };
+```
+
+User has customized `siteName` and `billing.scope`. Result:
+```typescript
+export default {
+  siteName: "Acme Corp",        // user's value preserved
+  analytics: {                   // new field added with defaults
+    enabled: true,
+    provider: "plausible",
+  },
+  billing: {
+    scope: "user",              // user's value preserved
+  },
+};
+```
+
+### Translation merge
+
+Upstream diff:
+```diff
+ {
+   "dashboard": {
+     "title": "Dashboard",
+-    "old_metric": "Old Metric",
++    "new_metric": "New Metric",
++    "analytics": "Analytics"
+   }
+ }
+```
+
+User changed `dashboard.title` to `"Control Panel"`. Result:
+```json
+{
+  "dashboard": {
+    "title": "Control Panel",
+    "new_metric": "New Metric",
+    "analytics": "Analytics"
+  }
+}
+```
+`old_metric` removed (upstream deleted it), `title` preserved (user customized it), new keys added.
+
+### Skipped change example
+
+Plan entry:
+```markdown
+## Skipped
+
+- `app/components/PricingTable.vue` — Upstream restructured the pricing grid layout from CSS Grid to Flexbox. User has heavily customized this component with custom tier cards and comparison features. Applying the layout change would break the custom tier rendering. **User should review the diff manually if they want the new layout.**
+```

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

@@ -0,0 +1,85 @@
+/**
+ * Shared helpers for update scripts.
+ * CommonJS module — used by prepare-update.js, apply-auto.js, classify-files.js, complete-update.js.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const INTERNAL_DIR = ".generatesaas";
+const MANIFEST_FILE = path.join(INTERNAL_DIR, "manifest.json");
+const HASHES_FILE = path.join(INTERNAL_DIR, "hashes.json");
+const TEMPLATE_HASHES_FILE = path.join(INTERNAL_DIR, "template-hashes.json");
+const STAGING_DIR = path.join(INTERNAL_DIR, "staging");
+const STAGING_META_FILE = path.join(INTERNAL_DIR, "staging.json");
+
+// ── Shared Utilities ──
+
+/** Walk up from cwd to find .generatesaas/manifest.json. */
+function findProjectRoot() {
+	let dir = process.cwd();
+	while (dir !== path.dirname(dir)) {
+		if (fs.existsSync(path.join(dir, MANIFEST_FILE))) return dir;
+		dir = path.dirname(dir);
+	}
+	return null;
+}
+
+/** Ensure a directory exists. */
+function ensureDir(dir) {
+	fs.mkdirSync(dir, { recursive: true });
+}
+
+/** Compute SHA-256 hash of a file. */
+function hashFile(filePath) {
+	const content = fs.readFileSync(filePath);
+	return require("node:crypto").createHash("sha256").update(content).digest("hex");
+}
+
+// ── File Walking ──
+
+const WALK_EXCLUSIONS = new Set([".git", "node_modules", ".pnpm-store", ".env", INTERNAL_DIR]);
+
+/** Check if a relative path should be excluded from walking. */
+function shouldExcludeWalk(relativePath) {
+	const parts = relativePath.split("/");
+	for (const part of parts) {
+		if (WALK_EXCLUSIONS.has(part)) return true;
+		if (part.startsWith(".env") && !part.includes("example")) return true;
+	}
+	return false;
+}
+
+/** Recursively collect all file paths in a directory. Returns relative paths. */
+function walkDir(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 (shouldExcludeWalk(rel)) continue;
+
+		if (entry.isDirectory()) {
+			files.push(...walkDir(fullPath, baseDir));
+		} else if (entry.isFile()) {
+			files.push(rel);
+		}
+	}
+
+	return files;
+}
+
+module.exports = {
+	findProjectRoot,
+	ensureDir,
+	hashFile,
+	walkDir,
+	INTERNAL_DIR,
+	MANIFEST_FILE,
+	HASHES_FILE,
+	TEMPLATE_HASHES_FILE,
+	STAGING_DIR,
+	STAGING_META_FILE,
+};

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+/**
+ * Auto-apply safe updates.
+ * Copies unmodified and new files from the staging directory to the project.
+ * Uses fs.copyFileSync for binary-safe file operations.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { findProjectRoot, ensureDir, STAGING_DIR } = require("./_helpers.js");
+
+function main() {
+	const root = findProjectRoot();
+	if (!root) {
+		console.error("Error: .generatesaas/manifest.json not found. Run this from a GenerateSaaS project.");
+		process.exit(1);
+	}
+
+	// Determine the skill root
+	const scriptDir = __dirname;
+	const skillDir = path.dirname(scriptDir);
+	const refsDir = path.join(skillDir, "references");
+
+	const classificationPath = path.join(refsDir, "classification.json");
+	if (!fs.existsSync(classificationPath)) {
+		console.error("Error: references/classification.json not found. Run classify-files.js first.");
+		process.exit(1);
+	}
+
+	const classification = JSON.parse(fs.readFileSync(classificationPath, "utf-8"));
+	const stagingDir = path.join(root, STAGING_DIR);
+
+	if (!fs.existsSync(stagingDir)) {
+		console.error("Error: Staging directory not found. Run 'generatesaas update' first.");
+		process.exit(1);
+	}
+
+	const filesToCopy = [...classification.unmodified, ...classification.new];
+
+	if (filesToCopy.length === 0) {
+		console.log("No files to auto-update. All changed files need manual merge.");
+		return;
+	}
+
+	console.log(`Copying ${filesToCopy.length} files from staging...`);
+
+	const unmodifiedSet = new Set(classification.unmodified);
+	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 {
+			created++;
+		}
+	}
+
+	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.");
+	}
+
+	if (classification.removed.length > 0) {
+		console.log(`\n${classification.removed.length} files were removed upstream. Review before deleting:`);
+		for (const f of classification.removed) {
+			console.log(`  - ${f}`);
+		}
+	}
+
+	console.log("\nAfter merging all files, run complete-update.js to finalize.");
+}
+
+try {
+	main();
+} catch (err) {
+	console.error("Error:", err.message);
+	process.exit(1);
+}

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * Classify project files for update.
+ * Compares local file hashes against the manifest to determine which files
+ * the user has customized and which are safe to auto-update.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { findProjectRoot, hashFile, HASHES_FILE } = require("./_helpers.js");
+
+function main() {
+	const root = findProjectRoot();
+	if (!root) {
+		console.error("Error: .generatesaas/manifest.json not found. Run this from a GenerateSaaS project.");
+		process.exit(1);
+	}
+
+	// Determine the skill root
+	const scriptDir = __dirname;
+	const skillDir = path.dirname(scriptDir);
+	const refsDir = path.join(skillDir, "references");
+
+	const manifestPath = path.join(refsDir, "update-manifest.json");
+	if (!fs.existsSync(manifestPath)) {
+		console.error("Error: references/update-manifest.json not found. Run prepare-update.js first.");
+		process.exit(1);
+	}
+
+	const updateManifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+	const hashesPath = path.join(root, HASHES_FILE);
+	const fileHashes = fs.existsSync(hashesPath)
+		? JSON.parse(fs.readFileSync(hashesPath, "utf-8"))
+		: {};
+
+	const classification = {
+		targetVersion: updateManifest.targetVersion,
+		unmodified: [],
+		modified: [],
+		deleted: [],
+		new: [],
+		removed: [],
+	};
+
+	// Classify modified files (upstream changed, check if user also changed)
+	for (const filePath of updateManifest.modified) {
+		const fullPath = path.join(root, filePath);
+		const originalHash = fileHashes[filePath];
+
+		if (!fs.existsSync(fullPath)) {
+			// User deleted this file
+			classification.deleted.push(filePath);
+		} else if (!originalHash) {
+			// No original hash — treat as modified to be safe
+			classification.modified.push(filePath);
+		} else {
+			const currentHash = hashFile(fullPath);
+			if (currentHash === originalHash) {
+				// File unchanged by user — safe to auto-update
+				classification.unmodified.push(filePath);
+			} else {
+				// User has customized this file — needs manual merge
+				classification.modified.push(filePath);
+			}
+		}
+	}
+
+	// Classify added files (new in upstream)
+	for (const filePath of updateManifest.added) {
+		const fullPath = path.join(root, filePath);
+		if (fs.existsSync(fullPath)) {
+			// File already exists locally — treat as modified for safety
+			classification.modified.push(filePath);
+		} else {
+			classification.new.push(filePath);
+		}
+	}
+
+	// Classify removed files (deleted in upstream)
+	for (const filePath of updateManifest.removed) {
+		const fullPath = path.join(root, filePath);
+		if (fs.existsSync(fullPath)) {
+			classification.removed.push(filePath);
+		}
+		// If already gone locally, nothing to do
+	}
+
+	// Write classification
+	fs.writeFileSync(
+		path.join(refsDir, "classification.json"),
+		JSON.stringify(classification, null, "\t") + "\n",
+		"utf-8"
+	);
+
+	// Print summary
+	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("");
+
+	if (classification.modified.length > 0) {
+		console.log("Files needing manual merge:");
+		for (const f of classification.modified) {
+			console.log(`  - ${f}`);
+		}
+		console.log("");
+	}
+
+	if (classification.removed.length > 0) {
+		console.log("Files removed upstream (review before deleting):");
+		for (const f of classification.removed) {
+			console.log(`  - ${f}`);
+		}
+		console.log("");
+	}
+
+	console.log("Next: Run apply-auto.js to update safe files, then manually merge modified files.");
+}
+
+try {
+	main();
+} catch (err) {
+	console.error("Error:", err.message);
+	process.exit(1);
+}