@littlebearapps/platform-admin-sdk 1.0.0 → 1.1.0

package/README.md

@@ -97,9 +97,67 @@ npx wrangler d1 migrations apply my-platform-metrics --remote
 npx wrangler deploy -c wrangler.my-platform-usage.jsonc
 ```
 
+## Updating Your Platform
+
+Starting with v1.1.0, the Admin SDK writes a `.platform-scaffold.json` manifest that tracks what was generated. This enables safe, incremental upgrades.
+
+### Upgrade an existing project
+
+```bash
+cd my-platform
+npx @littlebearapps/platform-admin-sdk upgrade
+```
+
+The upgrade command:
+- **Creates** new files added in the SDK update
+- **Updates** files you haven't modified (compares content hashes)
+- **Skips** files you've customised (with a warning)
+- **Renumbers** new migrations to avoid conflicts with your own
+
+Preview changes without writing:
+
+```bash
+npx @littlebearapps/platform-admin-sdk upgrade --dry-run
+```
+
+Upgrade to a higher tier:
+
+```bash
+npx @littlebearapps/platform-admin-sdk upgrade --tier standard
+```
+
+### Adopt a pre-v1.1.0 project
+
+Projects scaffolded before v1.1.0 don't have a manifest. Run `adopt` first:
+
+```bash
+npx @littlebearapps/platform-admin-sdk adopt . --tier minimal --project-name my-platform --skip-prompts
+```
+
+This hashes your existing files as a baseline and writes `.platform-scaffold.json`. You can then run `upgrade` normally.
+
+## Data Safety
+
+- The scaffolder **refuses to overwrite** existing directories
+- All generated migrations are **idempotent** (`ON CONFLICT DO NOTHING`)
+- The scaffolder **never modifies** existing Cloudflare resources (D1, KV, Queues)
+- Re-applying migrations to an existing database is safe
+
+## What's Not Included
+
+The scaffolder generates core infrastructure only. It does **not** create:
+
+- Dashboards or admin UIs
+- Email workers or notification templates
+- Data connectors (Stripe, GA4, Plausible, etc.)
+- Test suites
+- CI/CD workflows
+
+These are project-specific — build them as you need them.
+
 ## Consumer SDK
 
-The generated workers use `@littlebearapps/platform-consumer-sdk` — the Consumer SDK. Install it in your application workers:
+The generated workers use `@littlebearapps/platform-consumer-sdk` — the Consumer SDK. Install it in your application workers to send telemetry to the platform backend:
 
 ```bash
 npm install @littlebearapps/platform-consumer-sdk

package/dist/adopt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Adopt an existing scaffold that was created before the manifest system.
+ *
+ * Hashes all files on disk as a baseline and writes `.platform-scaffold.json`
+ * so the project can be upgraded in future.
+ */
+import type { Tier } from './prompts.js';
+export interface AdoptOptions {
+    projectName: string;
+    projectSlug: string;
+    githubOrg: string;
+    tier: Tier;
+    gatusUrl: string;
+    defaultAssignee: string;
+    /** SDK version that originally generated the scaffold (defaults to current). */
+    fromVersion?: string;
+}
+export declare function adopt(projectDir: string, options: AdoptOptions): void;

package/dist/adopt.js

@@ -0,0 +1,64 @@
+/**
+ * Adopt an existing scaffold that was created before the manifest system.
+ *
+ * Hashes all files on disk as a baseline and writes `.platform-scaffold.json`
+ * so the project can be upgraded in future.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import pc from 'picocolors';
+import { getFilesForTier, SDK_VERSION, isMigrationFile } from './templates.js';
+import { hashContent, writeManifest, buildManifest, readManifest, MANIFEST_FILENAME } from './manifest.js';
+import { getMigrationNumber } from './migrations.js';
+export function adopt(projectDir, options) {
+    if (!existsSync(projectDir)) {
+        throw new Error(`Directory does not exist: ${projectDir}`);
+    }
+    if (readManifest(projectDir) !== null) {
+        throw new Error(`${projectDir} already has a ${MANIFEST_FILENAME}. ` +
+            `Use \`platform-admin-sdk upgrade\` instead.`);
+    }
+    const files = getFilesForTier(options.tier);
+    // Build context for path rendering
+    const context = {
+        projectName: options.projectName,
+        projectSlug: options.projectSlug,
+    };
+    // Hash all files that exist on disk
+    const fileHashes = {};
+    let matched = 0;
+    for (const file of files) {
+        let destRelative = file.dest;
+        for (const [key, value] of Object.entries(context)) {
+            destRelative = destRelative.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+        }
+        const destPath = join(projectDir, destRelative);
+        if (existsSync(destPath)) {
+            const content = readFileSync(destPath, 'utf-8');
+            fileHashes[destRelative] = hashContent(content);
+            matched++;
+        }
+    }
+    // highestScaffoldMigration is the highest migration the SDK owns for this tier,
+    // NOT the highest migration on disk (which includes user-created migrations)
+    let highestScaffoldMigration = 0;
+    for (const file of files.filter(isMigrationFile)) {
+        const num = getMigrationNumber(file.dest);
+        if (num !== null && num > highestScaffoldMigration) {
+            highestScaffoldMigration = num;
+        }
+    }
+    const sdkVersion = options.fromVersion ?? SDK_VERSION;
+    const manifest = buildManifest(sdkVersion, options.tier, {
+        projectName: options.projectName,
+        projectSlug: options.projectSlug,
+        githubOrg: options.githubOrg,
+        gatusUrl: options.gatusUrl,
+        defaultAssignee: options.defaultAssignee,
+    }, fileHashes, highestScaffoldMigration);
+    writeManifest(projectDir, manifest);
+    console.log(`  ${pc.green('create')} ${MANIFEST_FILENAME}`);
+    console.log(`  ${pc.dim(`Matched ${matched} of ${files.length} expected files.`)}`);
+    console.log(`  ${pc.dim(`SDK migrations: up to ${highestScaffoldMigration || 'none'}`)}`);
+    console.log(`  ${pc.dim(`Tier: ${options.tier}, SDK: ${sdkVersion}`)}`);
+}

package/dist/index.d.ts

@@ -2,15 +2,19 @@
 /**
  * @littlebearapps/platform-admin-sdk
  *
- * Scaffolds a Cloudflare Workers platform with SDK integration,
+ * Scaffolds and upgrades a Cloudflare Workers platform with SDK integration,
  * circuit breakers, and cost protection.
  *
  * Usage:
  *   npx @littlebearapps/platform-admin-sdk [project-name] [options]
+ *   npx @littlebearapps/platform-admin-sdk upgrade [project-dir] [options]
+ *   npx @littlebearapps/platform-admin-sdk adopt [project-dir] [options]
  *
  * Examples:
  *   npx @littlebearapps/platform-admin-sdk my-project
  *   npx @littlebearapps/platform-admin-sdk my-project --tier full --github-org myorg
- *   npx @littlebearapps/platform-admin-sdk my-project --tier minimal --skip-prompts
+ *   npx @littlebearapps/platform-admin-sdk upgrade ./my-project
+ *   npx @littlebearapps/platform-admin-sdk upgrade ./my-project --tier standard --dry-run
+ *   npx @littlebearapps/platform-admin-sdk adopt ./my-project --tier minimal --skip-prompts
  */
 export {};

package/dist/index.js

@@ -2,53 +2,54 @@
 /**
  * @littlebearapps/platform-admin-sdk
  *
- * Scaffolds a Cloudflare Workers platform with SDK integration,
+ * Scaffolds and upgrades a Cloudflare Workers platform with SDK integration,
  * circuit breakers, and cost protection.
  *
  * Usage:
  *   npx @littlebearapps/platform-admin-sdk [project-name] [options]
+ *   npx @littlebearapps/platform-admin-sdk upgrade [project-dir] [options]
+ *   npx @littlebearapps/platform-admin-sdk adopt [project-dir] [options]
  *
  * Examples:
  *   npx @littlebearapps/platform-admin-sdk my-project
  *   npx @littlebearapps/platform-admin-sdk my-project --tier full --github-org myorg
- *   npx @littlebearapps/platform-admin-sdk my-project --tier minimal --skip-prompts
+ *   npx @littlebearapps/platform-admin-sdk upgrade ./my-project
+ *   npx @littlebearapps/platform-admin-sdk upgrade ./my-project --tier standard --dry-run
+ *   npx @littlebearapps/platform-admin-sdk adopt ./my-project --tier minimal --skip-prompts
  */
 import { resolve } from 'node:path';
 import { Command } from 'commander';
 import pc from 'picocolors';
 import { collectOptions, isValidTier } from './prompts.js';
 import { scaffold } from './scaffold.js';
+import { upgrade } from './upgrade.js';
+import { adopt } from './adopt.js';
+import { SDK_VERSION } from './templates.js';
 const BANNER = `
   ${pc.bold(pc.cyan('Platform Admin SDK'))} — Cloudflare Cost Protection
   ${pc.dim('Scaffold backend infrastructure: circuit breakers, budget enforcement, error collection')}
 `;
-const program = new Command()
-    .name('platform-admin-sdk')
-    .description('Scaffold a Cloudflare Workers platform with SDK integration')
-    .version('1.0.0')
+// --- Scaffold command (default) ---
+const scaffoldCmd = new Command('scaffold')
+    .description('Scaffold a new platform project (default)')
     .argument('[project-name]', 'Name of the project to create')
     .option('--tier <tier>', 'Infrastructure tier (minimal, standard, full)')
     .option('--github-org <org>', 'GitHub organisation for error issue creation')
     .option('--gatus-url <url>', 'Gatus status page URL for heartbeat monitoring')
     .option('--default-assignee <user>', 'Default GitHub assignee for error issues')
-    .option('--skip-prompts', 'Non-interactive mode — fail if required flags are missing');
-async function main() {
-    console.log(BANNER);
-    program.parse();
-    const opts = program.opts();
-    const [projectNameArg] = program.args;
-    // Validate tier if provided
-    if (opts.tier && !isValidTier(opts.tier)) {
-        console.error(pc.red(`  Error: Invalid tier "${opts.tier}". Must be one of: minimal, standard, full`));
+    .option('--skip-prompts', 'Non-interactive mode — fail if required flags are missing')
+    .action(async (projectNameArg, cmdOpts) => {
+    if (cmdOpts.tier && !isValidTier(cmdOpts.tier)) {
+        console.error(pc.red(`  Error: Invalid tier "${cmdOpts.tier}". Must be one of: minimal, standard, full`));
         process.exit(1);
     }
     const options = await collectOptions({
         projectName: projectNameArg,
-        tier: opts.tier,
-        githubOrg: opts.githubOrg,
-        gatusUrl: opts.gatusUrl,
-        defaultAssignee: opts.defaultAssignee,
-        skipPrompts: opts.skipPrompts,
+        tier: cmdOpts.tier,
+        githubOrg: cmdOpts.githubOrg,
+        gatusUrl: cmdOpts.gatusUrl,
+        defaultAssignee: cmdOpts.defaultAssignee,
+        skipPrompts: cmdOpts.skipPrompts,
     });
     const outputDir = resolve(process.cwd(), options.projectName);
     console.log();
@@ -82,6 +83,115 @@ async function main() {
     console.log(`  ${pc.dim('# In your consumer projects:')}`);
     console.log(`  ${pc.cyan('npm install @littlebearapps/platform-consumer-sdk')}`);
     console.log();
+});
+// --- Upgrade command ---
+const upgradeCmd = new Command('upgrade')
+    .description('Upgrade an existing scaffolded project to the latest SDK version')
+    .argument('[project-dir]', 'Path to the project directory', '.')
+    .option('--tier <tier>', 'Upgrade to a higher tier (minimal → standard → full)')
+    .option('--dry-run', 'Show what would change without writing files')
+    .action(async (projectDirArg, cmdOpts) => {
+    if (cmdOpts.tier && !isValidTier(cmdOpts.tier)) {
+        console.error(pc.red(`  Error: Invalid tier "${cmdOpts.tier}". Must be one of: minimal, standard, full`));
+        process.exit(1);
+    }
+    const projectDir = resolve(process.cwd(), projectDirArg);
+    console.log();
+    console.log(`  ${pc.bold('Upgrading')}: ${projectDir}`);
+    if (cmdOpts.tier)
+        console.log(`  ${pc.bold('Target tier')}: ${cmdOpts.tier}`);
+    if (cmdOpts.dryRun)
+        console.log(`  ${pc.yellow('DRY RUN')} — no files will be written`);
+    console.log();
+    const result = await upgrade(projectDir, {
+        tier: cmdOpts.tier,
+        dryRun: cmdOpts.dryRun,
+    });
+    console.log();
+    const total = result.created.length + result.updated.length + result.migrations.length;
+    if (total === 0 && result.skipped.length === 0) {
+        console.log(pc.green('  Already up to date.'));
+    }
+    else {
+        console.log(`  ${pc.green(`${result.created.length} created`)}, ${pc.cyan(`${result.updated.length} updated`)}, ${pc.yellow(`${result.skipped.length} skipped`)}, ${pc.green(`${result.migrations.length} migrations`)}`);
+    }
+    if (result.removed.length > 0) {
+        console.log(`  ${pc.yellow(`${result.removed.length} files removed from SDK (kept on disk)`)}`);
+    }
+    console.log();
+    if (result.migrations.length > 0 && !cmdOpts.dryRun) {
+        console.log(`  ${pc.bold('Run migrations:')}`);
+        console.log(`  ${pc.cyan('npx wrangler d1 migrations apply')} YOUR_DB --remote`);
+        console.log();
+    }
+});
+// --- Adopt command ---
+const adoptCmd = new Command('adopt')
+    .description('Add upgrade support to a project scaffolded before v1.1.0')
+    .argument('[project-dir]', 'Path to the project directory', '.')
+    .option('--tier <tier>', 'Infrastructure tier (minimal, standard, full)')
+    .option('--project-name <name>', 'Project name (as used during scaffold)')
+    .option('--project-slug <slug>', 'Project slug (for resource naming)')
+    .option('--github-org <org>', 'GitHub organisation')
+    .option('--gatus-url <url>', 'Gatus status page URL')
+    .option('--default-assignee <user>', 'Default GitHub assignee')
+    .option('--from-version <version>', 'SDK version that originally generated the scaffold')
+    .option('--skip-prompts', 'Non-interactive mode — fail if required flags are missing')
+    .action(async (projectDirArg, cmdOpts) => {
+    if (cmdOpts.tier && !isValidTier(cmdOpts.tier)) {
+        console.error(pc.red(`  Error: Invalid tier "${cmdOpts.tier}". Must be one of: minimal, standard, full`));
+        process.exit(1);
+    }
+    const projectDir = resolve(process.cwd(), projectDirArg);
+    // Collect options — reuse the prompt system for adopt
+    const options = await collectOptions({
+        projectName: cmdOpts.projectName,
+        tier: cmdOpts.tier,
+        githubOrg: cmdOpts.githubOrg,
+        gatusUrl: cmdOpts.gatusUrl,
+        defaultAssignee: cmdOpts.defaultAssignee,
+        skipPrompts: cmdOpts.skipPrompts,
+    });
+    console.log();
+    console.log(`  ${pc.bold('Adopting')}: ${projectDir}`);
+    console.log(`  ${pc.bold('Tier')}: ${options.tier}`);
+    console.log();
+    adopt(projectDir, {
+        projectName: options.projectName,
+        projectSlug: options.projectSlug,
+        githubOrg: options.githubOrg,
+        tier: options.tier,
+        gatusUrl: options.gatusUrl,
+        defaultAssignee: options.defaultAssignee,
+        fromVersion: cmdOpts.fromVersion,
+    });
+    console.log();
+    console.log(pc.green(pc.bold('  Done!')));
+    console.log(`  ${pc.dim('You can now run:')} ${pc.cyan('platform-admin-sdk upgrade')}`);
+    console.log();
+});
+// --- Main program ---
+const program = new Command()
+    .name('platform-admin-sdk')
+    .description('Scaffold and upgrade Cloudflare Workers platform infrastructure')
+    .version(SDK_VERSION)
+    .addCommand(scaffoldCmd)
+    .addCommand(upgradeCmd)
+    .addCommand(adoptCmd);
+async function main() {
+    console.log(BANNER);
+    // Backward compat: if first arg isn't a known subcommand, treat it as `scaffold <arg>`
+    const args = process.argv.slice(2);
+    const subcommands = ['scaffold', 'upgrade', 'adopt', 'help', '--help', '-h', '--version', '-V'];
+    if (args.length > 0 && !subcommands.includes(args[0])) {
+        // Inject 'scaffold' as the subcommand
+        process.argv.splice(2, 0, 'scaffold');
+    }
+    else if (args.length === 0) {
+        // No args at all — default to scaffold (which will prompt interactively)
+        process.argv.splice(2, 0, 'scaffold');
+    }
+    await program.parseAsync();
 }
 main().catch((error) => {
     console.error(pc.red('Error:'), error instanceof Error ? error.message : String(error));

package/dist/manifest.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Scaffold manifest — tracks what was generated so upgrades can detect changes.
+ *
+ * Written to `.platform-scaffold.json` in the project root.
+ */
+import type { Tier } from './prompts.js';
+export declare const MANIFEST_FILENAME = ".platform-scaffold.json";
+export declare const MANIFEST_VERSION = 1;
+export interface ManifestContext {
+    projectName: string;
+    projectSlug: string;
+    githubOrg: string;
+    gatusUrl: string;
+    defaultAssignee: string;
+}
+export interface ScaffoldManifest {
+    /** Manifest format version (for future-proofing). */
+    manifestVersion: number;
+    /** Admin SDK version that generated this scaffold. */
+    sdkVersion: string;
+    /** ISO 8601 timestamp of scaffold or last upgrade. */
+    generatedAt: string;
+    /** Infrastructure tier. */
+    tier: Tier;
+    /** Persisted context variables for re-rendering templates. */
+    context: ManifestContext;
+    /** Map of relative output path to SHA-256 hash of the content as-generated. */
+    files: Record<string, string>;
+    /** Highest migration number owned by the scaffolder (user migrations are higher). */
+    highestScaffoldMigration: number;
+}
+/** SHA-256 hash of file content. */
+export declare function hashContent(content: string): string;
+/** Read manifest from a project directory. Returns null if not found. */
+export declare function readManifest(projectDir: string): ScaffoldManifest | null;
+/** Write manifest to a project directory. */
+export declare function writeManifest(projectDir: string, manifest: ScaffoldManifest): void;
+/** Build a new manifest from components. */
+export declare function buildManifest(sdkVersion: string, tier: Tier, context: ManifestContext, fileHashes: Record<string, string>, highestScaffoldMigration: number): ScaffoldManifest;

package/dist/manifest.js

@@ -0,0 +1,44 @@
+/**
+ * Scaffold manifest — tracks what was generated so upgrades can detect changes.
+ *
+ * Written to `.platform-scaffold.json` in the project root.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const MANIFEST_FILENAME = '.platform-scaffold.json';
+export const MANIFEST_VERSION = 1;
+/** SHA-256 hash of file content. */
+export function hashContent(content) {
+    return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+/** Read manifest from a project directory. Returns null if not found. */
+export function readManifest(projectDir) {
+    const manifestPath = join(projectDir, MANIFEST_FILENAME);
+    if (!existsSync(manifestPath))
+        return null;
+    const raw = readFileSync(manifestPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed.manifestVersion !== MANIFEST_VERSION) {
+        throw new Error(`Manifest version ${parsed.manifestVersion} is not supported ` +
+            `(expected ${MANIFEST_VERSION}). Please upgrade the Admin SDK.`);
+    }
+    return parsed;
+}
+/** Write manifest to a project directory. */
+export function writeManifest(projectDir, manifest) {
+    const manifestPath = join(projectDir, MANIFEST_FILENAME);
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+}
+/** Build a new manifest from components. */
+export function buildManifest(sdkVersion, tier, context, fileHashes, highestScaffoldMigration) {
+    return {
+        manifestVersion: MANIFEST_VERSION,
+        sdkVersion,
+        generatedAt: new Date().toISOString(),
+        tier,
+        context,
+        files: fileHashes,
+        highestScaffoldMigration,
+    };
+}

package/dist/migrations.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Migration numbering utilities for safe upgrades.
+ *
+ * Handles renumbering scaffold-owned migrations so they don't conflict
+ * with user-created migrations.
+ */
+/** Parse the highest NNN_ migration number from a directory. Returns 0 if empty. */
+export declare function findHighestMigration(migrationsDir: string): number;
+/** Extract the NNN migration number from a path like `storage/d1/migrations/005_error.sql`. */
+export declare function getMigrationNumber(destPath: string): number | null;
+/** Renumber a migration filename: `005_error.sql` with nextNumber=12 → `012_error.sql`. */
+export declare function renumberMigration(filename: string, nextNumber: number): string;
+export interface PlannedMigration {
+    /** New destination path (renumbered). */
+    dest: string;
+    /** File content (unchanged). */
+    content: string;
+    /** Original scaffold destination path (before renumbering). */
+    originalDest: string;
+}
+/**
+ * Plan which migrations are new and what numbers they should get.
+ *
+ * Filters to migrations with numbers > lastAppliedScaffoldMigration,
+ * then renumbers sequentially starting after the user's highest migration.
+ */
+export declare function planMigrations(scaffoldMigrations: Array<{
+    originalDest: string;
+    content: string;
+}>, lastAppliedScaffoldMigration: number, userHighestMigration: number): PlannedMigration[];

package/dist/migrations.js

@@ -0,0 +1,67 @@
+/**
+ * Migration numbering utilities for safe upgrades.
+ *
+ * Handles renumbering scaffold-owned migrations so they don't conflict
+ * with user-created migrations.
+ */
+import { readdirSync } from 'node:fs';
+/** Parse the highest NNN_ migration number from a directory. Returns 0 if empty. */
+export function findHighestMigration(migrationsDir) {
+    let files;
+    try {
+        files = readdirSync(migrationsDir);
+    }
+    catch {
+        return 0;
+    }
+    let highest = 0;
+    for (const file of files) {
+        const match = file.match(/^(\d{3})_/);
+        if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > highest)
+                highest = num;
+        }
+    }
+    return highest;
+}
+/** Extract the NNN migration number from a path like `storage/d1/migrations/005_error.sql`. */
+export function getMigrationNumber(destPath) {
+    const match = destPath.match(/(\d{3})_[^/]+\.sql$/);
+    return match ? parseInt(match[1], 10) : null;
+}
+/** Renumber a migration filename: `005_error.sql` with nextNumber=12 → `012_error.sql`. */
+export function renumberMigration(filename, nextNumber) {
+    return filename.replace(/^\d{3}_/, `${String(nextNumber).padStart(3, '0')}_`);
+}
+/**
+ * Plan which migrations are new and what numbers they should get.
+ *
+ * Filters to migrations with numbers > lastAppliedScaffoldMigration,
+ * then renumbers sequentially starting after the user's highest migration.
+ */
+export function planMigrations(scaffoldMigrations, lastAppliedScaffoldMigration, userHighestMigration) {
+    // Filter to only new scaffold migrations
+    const newMigrations = scaffoldMigrations.filter((m) => {
+        const num = getMigrationNumber(m.originalDest);
+        return num !== null && num > lastAppliedScaffoldMigration;
+    });
+    // Sort by original number
+    newMigrations.sort((a, b) => {
+        const aNum = getMigrationNumber(a.originalDest) ?? 0;
+        const bNum = getMigrationNumber(b.originalDest) ?? 0;
+        return aNum - bNum;
+    });
+    // Renumber sequentially after user's highest
+    let nextNum = userHighestMigration + 1;
+    return newMigrations.map((m) => {
+        const originalFilename = m.originalDest.split('/').pop();
+        const newFilename = renumberMigration(originalFilename, nextNum++);
+        const dir = m.originalDest.substring(0, m.originalDest.lastIndexOf('/'));
+        return {
+            dest: `${dir}/${newFilename}`,
+            content: m.content,
+            originalDest: m.originalDest,
+        };
+    });
+}

package/dist/scaffold.js

@@ -6,7 +6,9 @@ import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import pc from 'picocolors';
-import { getFilesForTier } from './templates.js';
+import { getFilesForTier, SDK_VERSION } from './templates.js';
+import { hashContent, buildManifest, writeManifest, MANIFEST_FILENAME } from './manifest.js';
+import { findHighestMigration } from './migrations.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 function getTemplatesDir() {
@@ -27,6 +29,10 @@ function renderString(template, context) {
 }
 export async function scaffold(options, outputDir) {
     if (existsSync(outputDir)) {
+        if (existsSync(join(outputDir, MANIFEST_FILENAME))) {
+            throw new Error(`${outputDir} is an existing scaffold. Use:\n` +
+                `  platform-admin-sdk upgrade ${outputDir}`);
+        }
         throw new Error(`Directory already exists: ${outputDir}`);
     }
     const templatesDir = getTemplatesDir();
@@ -38,9 +44,10 @@ export async function scaffold(options, outputDir) {
         tier: options.tier,
         gatusUrl: options.gatusUrl,
         defaultAssignee: options.defaultAssignee,
-        sdkVersion: '0.2.0',
+        sdkVersion: SDK_VERSION,
     };
     mkdirSync(outputDir, { recursive: true });
+    const fileHashes = {};
     for (const file of files) {
         const srcPath = join(templatesDir, file.src);
         const destPath = join(outputDir, renderString(file.dest, context));
@@ -51,15 +58,29 @@ export async function scaffold(options, outputDir) {
             continue;
         }
         const raw = readFileSync(srcPath, 'utf-8');
+        let content;
         if (file.template) {
             const compiled = Handlebars.compile(raw, { noEscape: true });
-            const rendered = compiled(context);
-            writeFileSync(destPath, rendered);
+            content = compiled(context);
         }
         else {
-            writeFileSync(destPath, raw);
+            content = raw;
         }
+        writeFileSync(destPath, content);
         const relDest = destPath.replace(outputDir + '/', '');
+        fileHashes[relDest] = hashContent(content);
         console.log(`  ${pc.green('create')} ${relDest}`);
     }
+    // Write manifest for future upgrades
+    const migrationsDir = join(outputDir, 'storage/d1/migrations');
+    const highestMigration = findHighestMigration(migrationsDir);
+    const manifest = buildManifest(SDK_VERSION, options.tier, {
+        projectName: options.projectName,
+        projectSlug: options.projectSlug,
+        githubOrg: options.githubOrg,
+        gatusUrl: options.gatusUrl,
+        defaultAssignee: options.defaultAssignee,
+    }, fileHashes, highestMigration);
+    writeManifest(outputDir, manifest);
+    console.log(`  ${pc.green('create')} ${MANIFEST_FILENAME}`);
 }

package/dist/templates.d.ts

@@ -5,6 +5,12 @@
  * All other files are copied verbatim.
  */
 import type { Tier } from './prompts.js';
+/** Single source of truth for the SDK version. */
+export declare const SDK_VERSION = "1.1.0";
+/** Returns true if `to` is the same or higher tier than `from`. */
+export declare function isTierUpgradeOrSame(from: Tier, to: Tier): boolean;
+/** Check if a template file is a numbered migration (not seed.sql). */
+export declare function isMigrationFile(file: TemplateFile): boolean;
 export interface TemplateFile {
     /** Path relative to the templates/ directory */
     src: string;

package/dist/templates.js

@@ -4,6 +4,18 @@
  * Files ending in .hbs are rendered through Handlebars.
  * All other files are copied verbatim.
  */
+/** Single source of truth for the SDK version. */
+export const SDK_VERSION = '1.1.0';
+/** Tier ordering for upgrade validation. */
+const TIER_ORDER = { minimal: 0, standard: 1, full: 2 };
+/** Returns true if `to` is the same or higher tier than `from`. */
+export function isTierUpgradeOrSame(from, to) {
+    return TIER_ORDER[to] >= TIER_ORDER[from];
+}
+/** Check if a template file is a numbered migration (not seed.sql). */
+export function isMigrationFile(file) {
+    return /migrations\/\d{3}_[^/]+\.sql$/.test(file.dest);
+}
 const SHARED_FILES = [
     // Config
     { src: 'shared/config/services.yaml.hbs', dest: 'platform/config/services.yaml', template: true },

package/dist/upgrade.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Upgrade an existing scaffolded project to a newer SDK version.
+ *
+ * For each file:
+ *   - New file (not on disk) → create it
+ *   - Unchanged by user (disk hash == manifest hash) → overwrite with new version
+ *   - Modified by user (disk hash != manifest hash) → skip with warning
+ *   - Removed from SDK (in manifest, not in new template list) → warn, don't delete
+ *
+ * Migrations are renumbered to avoid conflicts with user-created migrations.
+ */
+import type { Tier } from './prompts.js';
+export interface UpgradeOptions {
+    tier?: Tier;
+    dryRun?: boolean;
+}
+export interface UpgradeResult {
+    created: string[];
+    updated: string[];
+    skipped: string[];
+    removed: string[];
+    migrations: string[];
+}
+export declare function upgrade(projectDir: string, options?: UpgradeOptions): Promise<UpgradeResult>;

package/dist/upgrade.js

@@ -0,0 +1,180 @@
+/**
+ * Upgrade an existing scaffolded project to a newer SDK version.
+ *
+ * For each file:
+ *   - New file (not on disk) → create it
+ *   - Unchanged by user (disk hash == manifest hash) → overwrite with new version
+ *   - Modified by user (disk hash != manifest hash) → skip with warning
+ *   - Removed from SDK (in manifest, not in new template list) → warn, don't delete
+ *
+ * Migrations are renumbered to avoid conflicts with user-created migrations.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Handlebars from 'handlebars';
+import pc from 'picocolors';
+import { getFilesForTier, SDK_VERSION, isMigrationFile, isTierUpgradeOrSame } from './templates.js';
+import { readManifest, writeManifest, buildManifest, hashContent, MANIFEST_FILENAME, } from './manifest.js';
+import { findHighestMigration, getMigrationNumber, planMigrations } from './migrations.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function getTemplatesDir() {
+    const devPath = resolve(__dirname, '..', 'templates');
+    if (existsSync(devPath))
+        return devPath;
+    return resolve(__dirname, '..', '..', 'templates');
+}
+function renderString(template, context) {
+    let result = template;
+    for (const [key, value] of Object.entries(context)) {
+        result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), value);
+    }
+    return result;
+}
+export async function upgrade(projectDir, options = {}) {
+    const manifest = readManifest(projectDir);
+    if (!manifest) {
+        throw new Error(`No ${MANIFEST_FILENAME} found in ${projectDir}.\n` +
+            `If this project was scaffolded before v1.1.0, run:\n` +
+            `  platform-admin-sdk adopt ${projectDir}`);
+    }
+    const targetTier = options.tier ?? manifest.tier;
+    if (!isTierUpgradeOrSame(manifest.tier, targetTier)) {
+        throw new Error(`Cannot downgrade from "${manifest.tier}" to "${targetTier}". ` +
+            `Tier changes must be upgrades (minimal → standard → full).`);
+    }
+    if (manifest.sdkVersion === SDK_VERSION && manifest.tier === targetTier) {
+        console.log(pc.green(`  Already up to date (SDK ${SDK_VERSION}, tier ${targetTier}).`));
+        return { created: [], updated: [], skipped: [], removed: [], migrations: [] };
+    }
+    const templatesDir = getTemplatesDir();
+    const files = getFilesForTier(targetTier);
+    const context = {
+        projectName: manifest.context.projectName,
+        projectSlug: manifest.context.projectSlug,
+        githubOrg: manifest.context.githubOrg,
+        tier: targetTier,
+        gatusUrl: manifest.context.gatusUrl,
+        defaultAssignee: manifest.context.defaultAssignee,
+        sdkVersion: SDK_VERSION,
+    };
+    const result = {
+        created: [],
+        updated: [],
+        skipped: [],
+        removed: [],
+        migrations: [],
+    };
+    // Separate regular files from migrations
+    const regularFiles = files.filter((f) => !isMigrationFile(f));
+    const migrationFiles = files.filter((f) => isMigrationFile(f));
+    const newFileHashes = {};
+    // --- Process regular files ---
+    for (const file of regularFiles) {
+        const srcPath = join(templatesDir, file.src);
+        const destRelative = renderString(file.dest, context);
+        const destPath = join(projectDir, destRelative);
+        if (!existsSync(srcPath))
+            continue;
+        const raw = readFileSync(srcPath, 'utf-8');
+        let content;
+        if (file.template) {
+            const compiled = Handlebars.compile(raw, { noEscape: true });
+            content = compiled(context);
+        }
+        else {
+            content = raw;
+        }
+        const newHash = hashContent(content);
+        newFileHashes[destRelative] = newHash;
+        if (!existsSync(destPath)) {
+            // New file — create it
+            if (!options.dryRun) {
+                mkdirSync(dirname(destPath), { recursive: true });
+                writeFileSync(destPath, content);
+            }
+            console.log(`  ${pc.green('create')} ${destRelative}`);
+            result.created.push(destRelative);
+        }
+        else {
+            const diskContent = readFileSync(destPath, 'utf-8');
+            const diskHash = hashContent(diskContent);
+            const manifestHash = manifest.files[destRelative];
+            if (diskHash === manifestHash) {
+                // Unmodified by user — safe to overwrite
+                if (newHash !== diskHash) {
+                    if (!options.dryRun) {
+                        writeFileSync(destPath, content);
+                    }
+                    console.log(`  ${pc.cyan('update')} ${destRelative}`);
+                    result.updated.push(destRelative);
+                }
+                // else: identical content, nothing to do
+            }
+            else {
+                // User has modified this file — skip
+                console.log(`  ${pc.yellow('skip')}   ${destRelative} ${pc.dim('(user modified)')}`);
+                result.skipped.push(destRelative);
+                // Preserve the user's version in the new manifest
+                newFileHashes[destRelative] = diskHash;
+            }
+        }
+    }
+    // --- Process migrations ---
+    const scaffoldMigrations = [];
+    for (const file of migrationFiles) {
+        const srcPath = join(templatesDir, file.src);
+        if (!existsSync(srcPath))
+            continue;
+        const content = readFileSync(srcPath, 'utf-8');
+        scaffoldMigrations.push({ originalDest: file.dest, content });
+    }
+    const migrationsDir = join(projectDir, 'storage/d1/migrations');
+    const userHighest = findHighestMigration(migrationsDir);
+    const planned = planMigrations(scaffoldMigrations, manifest.highestScaffoldMigration, userHighest);
+    for (const migration of planned) {
+        const destPath = join(projectDir, migration.dest);
+        if (!options.dryRun) {
+            mkdirSync(dirname(destPath), { recursive: true });
+            writeFileSync(destPath, migration.content);
+        }
+        console.log(`  ${pc.green('create')} ${migration.dest} ${pc.dim(`(from ${migration.originalDest.split('/').pop()})`)}`);
+        result.migrations.push(migration.dest);
+        newFileHashes[migration.dest] = hashContent(migration.content);
+    }
+    // Carry forward hashes for existing migrations that weren't re-planned
+    for (const [path, hash] of Object.entries(manifest.files)) {
+        if (path.includes('migrations/') && !newFileHashes[path]) {
+            newFileHashes[path] = hash;
+        }
+    }
+    // --- Check for removed files ---
+    const newDestSet = new Set([
+        ...regularFiles.map((f) => renderString(f.dest, context)),
+        ...migrationFiles.map((f) => f.dest),
+    ]);
+    for (const oldPath of Object.keys(manifest.files)) {
+        // Skip migrations from the removed check (they get renumbered)
+        if (oldPath.includes('migrations/'))
+            continue;
+        if (!newDestSet.has(oldPath)) {
+            console.log(`  ${pc.yellow('warn')}   ${oldPath} ${pc.dim('(removed from SDK, keeping on disk)')}`);
+            result.removed.push(oldPath);
+        }
+    }
+    // --- Compute new highestScaffoldMigration ---
+    let highestScaffoldMig = manifest.highestScaffoldMigration;
+    for (const file of migrationFiles) {
+        const num = getMigrationNumber(file.dest);
+        if (num !== null && num > highestScaffoldMig) {
+            highestScaffoldMig = num;
+        }
+    }
+    // --- Write updated manifest ---
+    if (!options.dryRun) {
+        const newManifest = buildManifest(SDK_VERSION, targetTier, manifest.context, newFileHashes, highestScaffoldMig);
+        writeManifest(projectDir, newManifest);
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/platform-admin-sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Platform Admin SDK — scaffold backend infrastructure with workers, circuit breakers, and cost protection for Cloudflare",
   "type": "module",
   "bin": {