create-ampless 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { spinner as spinner2, outro, log as log3 } from "@clack/prompts";
-import { existsSync as existsSync4 } from "fs";
+import { spinner as spinner2, outro as outro3, log as log5 } from "@clack/prompts";
+import { existsSync as existsSync7 } from "fs";
 import { basename as basename3, resolve as resolve5 } from "path";
 
 // src/prompts.ts
@@ -28,7 +28,10 @@ async function runPrompts(argProjectName) {
       // Multiple themes can ship side-by-side. The first selected is the
       // default active theme; admins can switch per-site at runtime. Add
       // / remove themes later by editing themes-registry.ts and
-      // themes/<name>/.
+      // themes/<name>/. Initial values pick every shipped theme so the
+      // shared `themes-registry.ts` placeholder (which imports all of
+      // them) compiles out of the box; deselect any the project won't
+      // need before confirming.
       themes: () => p.multiselect({
         message: "Themes to install (space to toggle)",
         options: [
@@ -39,7 +42,7 @@ async function runPrompts(argProjectName) {
           { value: "docs", label: "Docs \u2014 sidebar-led docs (tag-driven sections)" },
           { value: "dads", label: "DADS \u2014 Digital Agency Design System (Japanese government style)" }
         ],
-        initialValues: ["blog"],
+        initialValues: ["blog", "minimal", "landing", "corporate", "docs", "dads"],
         required: true
       }),
       plugins: () => p.multiselect({
@@ -83,8 +86,8 @@ async function runPrompts(argProjectName) {
 }
 
 // src/scaffold.ts
-import { cp, readFile, writeFile, readdir, mkdir, rm } from "fs/promises";
-import { join, extname, resolve as resolve2 } from "path";
+import { cp, readFile, writeFile, readdir as readdir2, mkdir, rm } from "fs/promises";
+import { join as join2, extname, resolve as resolve2 } from "path";
 
 // src/templates.ts
 import { existsSync } from "fs";
@@ -104,6 +107,100 @@ function templatePath(theme) {
   return resolve(templatesDir, theme);
 }
 
+// src/gitignore.ts
+var DEFAULT_GITIGNORE = `# Dependencies
+node_modules/
+
+# Next.js
+.next/
+next-env.d.ts
+
+# Amplify
+.amplify/
+amplify_outputs.json
+
+# TypeScript build artifacts
+*.tsbuildinfo
+
+# Env / OS noise
+.env
+.env.local
+.env.*.local
+.DS_Store
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor
+.vscode/
+.idea/
+`;
+
+// src/themes-registry.ts
+import { readdir } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join } from "path";
+var CUSTOM_THEME_PREFIX = "my-";
+function toIdentifier(themeName) {
+  if (!themeName.includes("-")) return themeName;
+  return themeName.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function isCustomTheme(themeName) {
+  return themeName.startsWith(CUSTOM_THEME_PREFIX);
+}
+async function discoverInstalledThemes(destDir) {
+  const themesDir = join(destDir, "themes");
+  if (!existsSync2(themesDir)) return [];
+  const entries = await readdir(themesDir, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+function buildRegistry(themes) {
+  const sorted = [...themes].sort((a, b) => {
+    const ca = isCustomTheme(a);
+    const cb = isCustomTheme(b);
+    if (ca !== cb) return ca ? 1 : -1;
+    return a.localeCompare(b);
+  });
+  const imports = sorted.map((t) => `import ${toIdentifier(t)} from '@/themes/${t}'`).join("\n");
+  const map = sorted.map((t) => {
+    const id = toIdentifier(t);
+    return id === t ? `  ${t},` : `  '${t}': ${id},`;
+  }).join("\n");
+  const fallback = sorted[0] ?? "blog";
+  return `// Generated by create-ampless. Lists every theme installed under
+// \`themes/<name>/\`. Auto-managed: \`create-ampless upgrade\` and
+// \`copy-theme\` regenerate this file from the directories present
+// under \`themes/\`. Edits made by hand will survive only until the
+// next upgrade.
+//
+// \`theme.active\` (per-site, in KvStore) picks which theme renders for
+// each request; everything listed here gets bundled so switching is
+// instant. Custom themes use the \`${CUSTOM_THEME_PREFIX}\` prefix and
+// are never touched by upgrade \u2014 clone an ampless default theme into
+// a \`${CUSTOM_THEME_PREFIX}<name>\` directory via \`copy-theme\` before
+// modifying it.
+
+${imports}
+
+export const themes = {
+${map}
+} as const
+
+export type ThemeName = keyof typeof themes
+
+export const themeList = Object.values(themes)
+
+/**
+ * Default theme used when a site has no \`theme.active\` override.
+ * Falls back to the first registered theme so an empty registry would
+ * still surface a clear runtime error rather than silent breakage.
+ */
+export const DEFAULT_THEME: ThemeName = (themeList[0]?.name as ThemeName) ?? '${fallback}'
+`;
+}
+
 // src/scaffold.ts
 var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".json",
@@ -131,10 +228,10 @@ async function substituteFile(filePath, vars) {
   if (replaced !== content) await writeFile(filePath, replaced, "utf-8");
 }
 async function substituteDir(dirPath, vars) {
-  const entries = await readdir(dirPath, { withFileTypes: true });
+  const entries = await readdir2(dirPath, { withFileTypes: true });
   await Promise.all(
     entries.map(async (entry) => {
-      const fullPath = join(dirPath, entry.name);
+      const fullPath = join2(dirPath, entry.name);
       if (entry.isDirectory()) {
         await substituteDir(fullPath, vars);
       } else {
@@ -143,30 +240,6 @@ async function substituteDir(dirPath, vars) {
     })
   );
 }
-function buildRegistry(themes) {
-  const imports = themes.map((t) => `import ${t} from '@/themes/${t}'`).join("\n");
-  const map = themes.map((t) => `  ${t},`).join("\n");
-  return `// Generated by create-ampless. Lists every theme installed under
-// \`themes/<name>/\`. Adding a theme = drop a directory under themes/,
-// add an import + map entry below, and redeploy.
-//
-// \`theme.active\` (per-site, in KvStore) picks which theme renders for
-// each request; everything listed here gets bundled so switching is
-// instant.
-
-${imports}
-
-export const themes = {
-${map}
-} as const
-
-export type ThemeName = keyof typeof themes
-
-export const themeList = Object.values(themes)
-
-export const DEFAULT_THEME: ThemeName = (themeList[0]?.name as ThemeName) ?? '${themes[0]}'
-`;
-}
 async function scaffold(sharedDir, themesRoot, destDir, opts) {
   await cp(sharedDir, destDir, { recursive: true });
   const destThemesDir = resolve2(destDir, "themes");
@@ -180,6 +253,8 @@ async function scaffold(sharedDir, themesRoot, destDir, opts) {
   void themesRoot;
   const registryPath = resolve2(destDir, "themes-registry.ts");
   await writeFile(registryPath, buildRegistry(opts.themes), "utf-8");
+  const gitignorePath = resolve2(destDir, ".gitignore");
+  await writeFile(gitignorePath, DEFAULT_GITIGNORE, "utf-8");
   const vars = {
     projectName: opts.projectName,
     siteName: opts.siteName,
@@ -209,6 +284,9 @@ var STRING_FLAGS = /* @__PURE__ */ new Set([
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "--deploy",
   "--mount",
+  "--upgrade",
+  "--dry-run",
+  "--no-install",
   "--github-private",
   "--create-iam-role",
   "--skip-confirm",
@@ -219,6 +297,10 @@ function parseDeployArgs(argv) {
   const out = {
     deploy: false,
     mount: false,
+    upgrade: false,
+    copyTheme: false,
+    dryRun: false,
+    noInstall: false,
     githubPrivate: false,
     createIamRole: false,
     skipConfirm: false,
@@ -242,6 +324,15 @@ function parseDeployArgs(argv) {
         case "--mount":
           out.mount = true;
           break;
+        case "--upgrade":
+          out.upgrade = true;
+          break;
+        case "--dry-run":
+          out.dryRun = true;
+          break;
+        case "--no-install":
+          out.noInstall = true;
+          break;
         case "--github-private":
           out.githubPrivate = true;
           break;
@@ -317,6 +408,22 @@ function parseDeployArgs(argv) {
       out.unknown.push(raw);
       continue;
     }
+    if (raw === "upgrade" && out.projectName === void 0) {
+      out.upgrade = true;
+      continue;
+    }
+    if (raw === "copy-theme" && out.projectName === void 0 && !out.copyTheme) {
+      out.copyTheme = true;
+      continue;
+    }
+    if (out.copyTheme && out.copyThemeSource === void 0) {
+      out.copyThemeSource = raw;
+      continue;
+    }
+    if (out.copyTheme && out.copyThemeTarget === void 0) {
+      out.copyThemeTarget = raw;
+      continue;
+    }
     if (out.projectName === void 0) {
       out.projectName = raw;
     } else {
@@ -330,6 +437,7 @@ var HELP_TEXT = `create-ampless \u2014 scaffold an ampless project
 Usage:
   npx create-ampless@alpha <project-name> [options]
   npx create-ampless@alpha --mount [options]    # in an existing project dir
+  npx create-ampless@alpha upgrade [options]    # in an existing project dir
 
 Options:
   --site-name <name>          Site display name (default: "My Blog")
@@ -365,6 +473,21 @@ Options:
   --skip-confirm              Skip all interactive prompts and use defaults /
                               flag values (for CI / automation)
   -h, --help                  Show this message
+
+upgrade  Sync ampless package files / deps to latest alpha.
+         Run inside an existing ampless project.
+
+  --dry-run                   Show what would change without writing any files
+  --no-install                Skip running pnpm/npm install after updating
+                              package.json
+
+copy-theme <source> <target>
+         Copy a theme so the original stays managed by ampless and
+         customisations live in the copy. Target must start with "my-"
+         (the convention that flags it as user-owned, so upgrade leaves
+         it alone). Run inside an existing ampless project.
+
+         Example: npx create-ampless@alpha copy-theme blog my-blog
 `;
 
 // src/deploy-prompts.ts
@@ -373,8 +496,8 @@ import { execa as execa3 } from "execa";
 
 // src/deploy.ts
 import { execa as execa2 } from "execa";
-import { existsSync as existsSync3 } from "fs";
-import { writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import { basename as basename2, resolve as resolve4 } from "path";
 import { spinner, log } from "@clack/prompts";
 import pc2 from "picocolors";
@@ -852,42 +975,21 @@ function printPreflightReport(problems) {
 }
 
 // src/mount.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync3 } from "fs";
 import { resolve as resolve3 } from "path";
 function validateMountableProject(destDir) {
   const required = ["package.json", "cms.config.ts"];
   for (const f of required) {
-    if (!existsSync2(resolve3(destDir, f))) {
+    if (!existsSync3(resolve3(destDir, f))) {
       return `Not an ampless project (missing ${f} in ${destDir})`;
     }
   }
   const amplifyFiles = ["amplify/backend.ts", "amplify/data/resource.ts"];
-  if (!amplifyFiles.some((f) => existsSync2(resolve3(destDir, f)))) {
+  if (!amplifyFiles.some((f) => existsSync3(resolve3(destDir, f)))) {
     return `Not an ampless project (missing amplify/ in ${destDir})`;
   }
   return null;
 }
-var MOUNT_DEFAULT_GITIGNORE = `# Dependencies
-node_modules/
-
-# Next.js
-.next/
-.amplify/
-
-# Amplify outputs (regenerated on every deploy / sandbox)
-amplify_outputs.json
-
-# Env / OS noise
-.env
-.env.local
-.env.*.local
-.DS_Store
-
-# Logs
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-`;
 function originPointsAt(origin, owner, name) {
   const candidates = [
     `https://github.com/${owner}/${name}`,
@@ -986,6 +1088,42 @@ function splitDomain(domain, subdomain) {
   const prefix = domain.slice(0, domain.length - registrable.length - 1);
   return { registrable, subdomain: prefix };
 }
+async function rewriteCmsConfigForDomain(projectDir, fullDomain) {
+  const path = resolve4(projectDir, "cms.config.ts");
+  if (!existsSync4(path)) {
+    return { urlRewritten: false, sitesInjected: false };
+  }
+  let content = await readFile2(path, "utf-8");
+  let urlRewritten = false;
+  let sitesInjected = false;
+  const urlRe = /url:\s*['"]http:\/\/localhost:3000['"]/;
+  if (urlRe.test(content)) {
+    content = content.replace(urlRe, `url: 'https://${fullDomain}'`);
+    urlRewritten = true;
+  }
+  const sitesActiveRe = /^\s*sites:\s*\{/m;
+  if (!sitesActiveRe.test(content)) {
+    const siteCloseRe = /(\n(\s*)site:\s*\{[\s\S]*?\n\2\},)/;
+    const m = siteCloseRe.exec(content);
+    if (m) {
+      const indent = m[2] ?? "  ";
+      const inner = indent + "  ";
+      const innermost = inner + "  ";
+      const inject = `
+${indent}sites: {
+${inner}default: {
+${innermost}domains: ['${fullDomain}'],
+${inner}},
+${indent}},`;
+      content = content.replace(siteCloseRe, `$1${inject}`);
+      sitesInjected = true;
+    }
+  }
+  if (urlRewritten || sitesInjected) {
+    await writeFile2(path, content, "utf-8");
+  }
+  return { urlRewritten, sitesInjected };
+}
 async function run(cmd, args, opts = {}) {
   const { step, ...execaOpts } = opts;
   try {
@@ -1026,8 +1164,8 @@ async function currentBranch(dir) {
 }
 async function ensureGitignore(dir) {
   const target = resolve4(dir, ".gitignore");
-  if (existsSync3(target)) return;
-  await writeFile2(target, MOUNT_DEFAULT_GITIGNORE, "utf-8");
+  if (existsSync4(target)) return;
+  await writeFile2(target, DEFAULT_GITIGNORE, "utf-8");
 }
 async function gitInitOrReuse(dir, mount) {
   const repo = await isGitRepo(dir);
@@ -1053,11 +1191,18 @@ function shortName2(opts) {
   return basename2(opts.projectDir);
 }
 async function ghRepoExists(name, token) {
-  const r = await execa2("gh", ["repo", "view", name], {
+  const r = await execa2("gh", ["repo", "view", name, "--json", "nameWithOwner"], {
     reject: false,
     env: { ...process.env, GH_TOKEN: token }
   });
-  return r.exitCode === 0;
+  if (r.exitCode !== 0) return false;
+  try {
+    const parsed = JSON.parse(r.stdout?.toString() ?? "{}");
+    const resolved = parsed.nameWithOwner?.toLowerCase();
+    return resolved === name.toLowerCase();
+  } catch {
+    return true;
+  }
 }
 async function getOriginUrl(dir) {
   const r = await execa2("git", ["remote", "get-url", "origin"], {
@@ -1354,6 +1499,17 @@ async function runDeploy(opts) {
     }
   }
   await writeFile2(resolve4(opts.projectDir, "amplify.yml"), AMPLIFY_BUILD_SPEC, "utf-8");
+  if (opts.domain) {
+    const { registrable, subdomain } = splitDomain(opts.domain, opts.subdomain);
+    const fullDomain = subdomain ? `${subdomain}.${registrable}` : registrable;
+    const mutations = await rewriteCmsConfigForDomain(opts.projectDir, fullDomain);
+    if (mutations.urlRewritten || mutations.sitesInjected) {
+      const parts = [];
+      if (mutations.urlRewritten) parts.push(`site.url \u2192 https://${fullDomain}`);
+      if (mutations.sitesInjected) parts.push(`sites.default.domains += ${fullDomain}`);
+      log.info(`cms.config.ts updated: ${parts.join(", ")}`);
+    }
+  }
   const created = {};
   const fail = (step, cause) => {
     const msg = cause instanceof Error ? cause.message : String(cause);
@@ -1490,7 +1646,7 @@ async function gatherDeployOptions(args, projectDir, projectName) {
     githubOwner = answer.trim();
   }
   let githubPrivate = args.githubPrivate;
-  if (!args.githubPrivate) {
+  if (!args.githubPrivate && !args.skipConfirm) {
     const choice = await p2.select({
       message: "Repository visibility",
       options: [
@@ -1598,15 +1754,388 @@ async function gatherDeployOptions(args, projectDir, projectName) {
   };
 }
 
-// src/index.ts
+// src/upgrade.ts
+import { cp as cp2, readFile as readFile3, writeFile as writeFile3, readdir as readdir3, mkdir as mkdir2, rm as rm2 } from "fs/promises";
+import { existsSync as existsSync5 } from "fs";
+import { join as join3, relative, extname as extname2, dirname } from "path";
+import { log as log3, outro } from "@clack/prompts";
 import pc3 from "picocolors";
+import { execa as execa4 } from "execa";
+var AMPLESS_PACKAGES = /* @__PURE__ */ new Set([
+  "ampless",
+  "@ampless/admin",
+  "@ampless/backend",
+  "@ampless/runtime",
+  "@ampless/plugin-seo",
+  "@ampless/plugin-rss",
+  "@ampless/plugin-webhook",
+  "@ampless/plugin-og-image"
+]);
+var AMPLESS_MANAGED_SCRIPTS = /* @__PURE__ */ new Set([
+  "sandbox",
+  "sandbox:dev",
+  "update-ampless",
+  "copy-theme"
+]);
+var PROTECTED_PATTERNS = [
+  /^cms\.config\.ts$/,
+  // `themes/` and `themes-registry.ts` are handled separately — see
+  // syncThemes() below. The themes directory is owned per-entry by
+  // either ampless (default themes, resynced on upgrade) or the user
+  // (`my-*` themes, preserved). The registry is regenerated to match
+  // whatever is on disk afterward.
+  /^\.env/,
+  /^node_modules(\/|$)/,
+  /^\.next(\/|$)/,
+  /^\.turbo(\/|$)/,
+  /^\.amplify(\/|$)/,
+  /^amplify_outputs\.json$/,
+  /^next-env\.d\.ts$/,
+  /^tsconfig\.tsbuildinfo$/,
+  /^pnpm-lock\.yaml$/,
+  /^package-lock\.json$/,
+  // Anything under themes/ is handled by syncThemes; the file-walk
+  // classifier must not double-process it.
+  /^themes(\/|$)/,
+  /^themes-registry\.ts$/
+];
+var SEED_IF_MISSING_PATTERN = /\.custom\.ts$/;
+var TEXT_EXTENSIONS2 = /* @__PURE__ */ new Set([
+  ".json",
+  ".md",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".html",
+  ".css",
+  ".env",
+  ".txt",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".gitignore"
+]);
+function isProtected(relPath) {
+  return PROTECTED_PATTERNS.some((re) => re.test(relPath));
+}
+async function listShippedThemes(templatesRoot) {
+  if (!existsSync5(templatesRoot)) return [];
+  const entries = await readdir3(templatesRoot, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory() && e.name !== "_shared").map((e) => e.name).sort();
+}
+var USER_OWNED_THEME_FILES = /* @__PURE__ */ new Set(["README.md", ".gitignore"]);
+function isUserOwnedThemeFile(path) {
+  const name = path.split(/[/\\]/).pop() ?? "";
+  return USER_OWNED_THEME_FILES.has(name);
+}
+async function captureUserOwnedFiles(dir) {
+  const out = /* @__PURE__ */ new Map();
+  if (!existsSync5(dir)) return out;
+  for (const name of USER_OWNED_THEME_FILES) {
+    const p3 = join3(dir, name);
+    if (existsSync5(p3)) {
+      out.set(name, await readFile3(p3));
+    }
+  }
+  return out;
+}
+async function restorePreservedFiles(dir, files) {
+  for (const [name, content] of files) {
+    await mkdir2(dir, { recursive: true });
+    await writeFile3(join3(dir, name), content);
+  }
+}
+async function syncThemes(destDir, templatesRoot) {
+  const shipped = await listShippedThemes(templatesRoot);
+  const themesDir = join3(destDir, "themes");
+  await mkdir2(themesDir, { recursive: true });
+  for (const name of shipped) {
+    const src = join3(templatesRoot, name);
+    const dst = join3(themesDir, name);
+    const preservedFiles = await captureUserOwnedFiles(dst);
+    await rm2(dst, { recursive: true, force: true });
+    await cp2(src, dst, {
+      recursive: true,
+      filter: (sourcePath) => !isUserOwnedThemeFile(sourcePath)
+    });
+    await restorePreservedFiles(dst, preservedFiles);
+  }
+  const installed = await discoverInstalledThemes(destDir);
+  const shippedSet = new Set(shipped);
+  const preserved = installed.filter((t) => !shippedSet.has(t));
+  const all = [...shipped, ...preserved];
+  await writeFile3(join3(destDir, "themes-registry.ts"), buildRegistry(all), "utf-8");
+  return { synced: shipped, preserved };
+}
+async function walkDir(dir, base, out) {
+  const entries = await readdir3(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join3(dir, entry.name);
+    const rel = relative(base, full);
+    if (entry.isDirectory()) {
+      await walkDir(full, base, out);
+    } else {
+      out.push(rel);
+    }
+  }
+}
+function substituteVars(content, vars) {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
+}
+async function copyWithSubstitution(src, dst, vars) {
+  const ext = extname2(src) || (src.endsWith(".gitignore") ? ".gitignore" : "");
+  await mkdir2(dirname(dst), { recursive: true });
+  if (TEXT_EXTENSIONS2.has(ext)) {
+    const content = await readFile3(src, "utf-8");
+    await writeFile3(dst, substituteVars(content, vars), "utf-8");
+  } else {
+    const buf = await readFile3(src);
+    await writeFile3(dst, buf);
+  }
+}
+function detectIndent(jsonStr) {
+  const m = jsonStr.match(/^{\n(\s+)/);
+  if (!m) return 2;
+  return m[1].length;
+}
+async function runUpgradeIn(destDir, sharedDir, opts = {}) {
+  const derivedRoot = opts.templatesRoot ?? join3(sharedDir, "..");
+  const themeSyncEnabled = existsSync5(join3(derivedRoot, "_shared"));
+  const templatesRoot = themeSyncEnabled ? derivedRoot : "";
+  const problem = validateMountableProject(destDir);
+  if (problem) {
+    throw new Error(problem);
+  }
+  const projectPkgPath = join3(destDir, "package.json");
+  const projectPkgRaw = await readFile3(projectPkgPath, "utf-8");
+  const projectPkg = JSON.parse(projectPkgRaw);
+  const projectName = typeof projectPkg.name === "string" && projectPkg.name ? projectPkg.name : "my-ampless-site";
+  const vars = { projectName };
+  const allRelPaths = [];
+  await walkDir(sharedDir, sharedDir, allRelPaths);
+  const classification = { replace: [], merge: [], seed: [], protected: [] };
+  for (const rel of allRelPaths) {
+    if (SEED_IF_MISSING_PATTERN.test(rel)) {
+      classification.seed.push(rel);
+    } else if (isProtected(rel)) {
+      classification.protected.push(rel);
+    } else if (rel === "package.json") {
+      classification.merge.push(rel);
+    } else {
+      classification.replace.push(rel);
+    }
+  }
+  const replaceNew = classification.replace.filter((r) => !existsSync5(join3(destDir, r)));
+  const replaceUpdate = classification.replace.filter((r) => existsSync5(join3(destDir, r)));
+  const seedNew = classification.seed.filter((r) => !existsSync5(join3(destDir, r)));
+  const seedSkipped = classification.seed.filter((r) => existsSync5(join3(destDir, r)));
+  const shippedThemes = themeSyncEnabled ? await listShippedThemes(templatesRoot) : [];
+  const existingThemes = themeSyncEnabled ? await discoverInstalledThemes(destDir) : [];
+  const preservedThemes = existingThemes.filter((t) => !shippedThemes.includes(t));
+  log3.info(
+    `replace: ${pc3.green(`\u8FFD\u52A0 ${replaceNew.length}`)} / ${pc3.yellow(`\u66F4\u65B0 ${replaceUpdate.length}`)}`
+  );
+  log3.info(`merge:   ${pc3.cyan("package.json: ampless deps / managed scripts \u3092\u30C6\u30F3\u30D7\u30EC\u5074\u306B\u5408\u308F\u305B\u308B")}`);
+  if (classification.seed.length > 0) {
+    log3.info(
+      `seed:    ${pc3.green(`\u8FFD\u52A0 ${seedNew.length}`)} / ${pc3.dim(`\u65E2\u5B58\u30D5\u30A1\u30A4\u30EB\u306F\u4E0A\u66F8\u304D\u3057\u306A\u3044: ${seedSkipped.length}`)} (*.custom.ts)`
+    );
+  }
+  if (themeSyncEnabled) {
+    log3.info(
+      `themes:  ${pc3.cyan(`\u30C7\u30D5\u30A9\u30EB\u30C8\u30C6\u30FC\u30DE\u3092\u540C\u671F: ${shippedThemes.length}`)} / ${pc3.dim(`\u30AB\u30B9\u30BF\u30E0\u30C6\u30FC\u30DE (my-*) \u3092\u4FDD\u6301: ${preservedThemes.length}`)}`
+    );
+  }
+  log3.info(`protected: ${pc3.dim(`\u30C6\u30F3\u30D7\u30EC\u306B\u5B58\u5728\u3059\u308B\u304C\u89E6\u3089\u306A\u3044: ${classification.protected.length} \u500B`)}`);
+  if (opts.dryRun) {
+    return {
+      added: replaceNew,
+      updated: replaceUpdate,
+      seeded: seedNew,
+      protected: classification.protected,
+      themesSynced: shippedThemes,
+      themesPreserved: preservedThemes,
+      packageJsonMerged: false
+    };
+  }
+  for (const rel of classification.replace) {
+    const src = join3(sharedDir, rel);
+    const dst = join3(destDir, rel);
+    await copyWithSubstitution(src, dst, vars);
+  }
+  for (const rel of seedNew) {
+    const src = join3(sharedDir, rel);
+    const dst = join3(destDir, rel);
+    await copyWithSubstitution(src, dst, vars);
+  }
+  const themeResult = themeSyncEnabled ? await syncThemes(destDir, templatesRoot) : { synced: [], preserved: [] };
+  const templatePkgRaw = await readFile3(join3(sharedDir, "package.json"), "utf-8");
+  const templatePkg = JSON.parse(templatePkgRaw);
+  const indent = detectIndent(projectPkgRaw);
+  for (const section of ["dependencies", "devDependencies"]) {
+    const templateDeps = templatePkg[section] ?? {};
+    const projectDeps = projectPkg[section] ?? {};
+    for (const [name, version] of Object.entries(templateDeps)) {
+      if (!AMPLESS_PACKAGES.has(name)) continue;
+      projectDeps[name] = version;
+    }
+    if (Object.keys(projectDeps).length > 0) {
+      projectPkg[section] = projectDeps;
+    }
+  }
+  const templateScripts = templatePkg["scripts"] ?? {};
+  const projectScripts = projectPkg["scripts"] ?? {};
+  for (const [name, body] of Object.entries(templateScripts)) {
+    if (!AMPLESS_MANAGED_SCRIPTS.has(name)) continue;
+    projectScripts[name] = body;
+  }
+  if (Object.keys(projectScripts).length > 0) {
+    projectPkg["scripts"] = projectScripts;
+  }
+  await writeFile3(projectPkgPath, JSON.stringify(projectPkg, null, indent) + "\n", "utf-8");
+  if (!opts.noInstall) {
+    const usePnpm = existsSync5(join3(destDir, "pnpm-lock.yaml"));
+    const pm = usePnpm ? "pnpm" : "npm";
+    await execa4(pm, ["install"], { cwd: destDir, stdio: "inherit" });
+  }
+  return {
+    added: replaceNew,
+    updated: replaceUpdate,
+    seeded: seedNew,
+    protected: classification.protected,
+    themesSynced: themeResult.synced,
+    themesPreserved: themeResult.preserved,
+    packageJsonMerged: true
+  };
+}
+async function runUpgrade(args) {
+  const destDir = process.cwd();
+  try {
+    await runUpgradeIn(destDir, sharedTemplateDir(), {
+      dryRun: args.dryRun,
+      noInstall: args.noInstall
+    });
+  } catch (err) {
+    log3.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  if (args.dryRun) {
+    outro(`${pc3.dim("(dry-run) No files were changed.")}`);
+    return;
+  }
+  outro(
+    `${pc3.green("\u2714")} Upgrade complete
+
+  Next steps:
+    ${pc3.cyan("git diff")}              ${pc3.dim("# review changes")}
+    ${pc3.cyan("git commit && git push")}  ${pc3.dim("# deploy via Amplify Hosting")}`
+  );
+}
+
+// src/copy-theme.ts
+import { cp as cp3, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { existsSync as existsSync6 } from "fs";
+import { join as join4 } from "path";
+import { log as log4, outro as outro2 } from "@clack/prompts";
+import pc4 from "picocolors";
+async function runCopyThemeIn(destDir, source, target) {
+  const problem = validateMountableProject(destDir);
+  if (problem) {
+    throw new Error(problem);
+  }
+  if (!isCustomTheme(target)) {
+    throw new Error(
+      `Target theme name must start with "${CUSTOM_THEME_PREFIX}" (got "${target}"). This prefix marks the theme as user-owned so create-ampless upgrade leaves it alone.`
+    );
+  }
+  if (source === target) {
+    throw new Error(`Source and target are identical (${source}).`);
+  }
+  const themesDir = join4(destDir, "themes");
+  const sourceDir = join4(themesDir, source);
+  const targetDir = join4(themesDir, target);
+  if (!existsSync6(sourceDir)) {
+    throw new Error(`Source theme not found: themes/${source}/`);
+  }
+  if (existsSync6(targetDir)) {
+    throw new Error(`Target theme already exists: themes/${target}/`);
+  }
+  await cp3(sourceDir, targetDir, { recursive: true });
+  const filesRewritten = await rewriteThemeName(targetDir, source, target);
+  const installed = await discoverInstalledThemes(destDir);
+  await writeFile4(join4(destDir, "themes-registry.ts"), buildRegistry(installed), "utf-8");
+  return { source, target, filesRewritten };
+}
+async function rewriteThemeName(targetDir, source, target) {
+  const touched = [];
+  await rewriteFile(
+    join4(targetDir, "index.ts"),
+    (s) => s.replace(new RegExp(`name:\\s*'${escapeRegex(source)}'`), `name: '${target}'`).replace(new RegExp(`name:\\s*"${escapeRegex(source)}"`), `name: "${target}"`),
+    touched
+  );
+  await rewriteFile(
+    join4(targetDir, "manifest.ts"),
+    (s) => s.replace(new RegExp(`name:\\s*'${escapeRegex(source)}'`), `name: '${target}'`).replace(new RegExp(`name:\\s*"${escapeRegex(source)}"`), `name: "${target}"`),
+    touched
+  );
+  await rewriteFile(
+    join4(targetDir, "tokens.css"),
+    (s) => s.replace(new RegExp(`\\[data-theme='${escapeRegex(source)}'\\]`, "g"), `[data-theme='${target}']`).replace(new RegExp(`\\[data-theme="${escapeRegex(source)}"\\]`, "g"), `[data-theme="${target}"]`),
+    touched
+  );
+  return touched;
+}
+async function rewriteFile(path, transform, touched) {
+  if (!existsSync6(path)) return;
+  const before = await readFile4(path, "utf-8");
+  const after = transform(before);
+  if (after === before) return;
+  await writeFile4(path, after, "utf-8");
+  touched.push(path);
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+async function runCopyTheme(args) {
+  const destDir = process.cwd();
+  const source = args.copyThemeSource;
+  const target = args.copyThemeTarget;
+  if (!source || !target) {
+    log4.error("Usage: npx create-ampless@alpha copy-theme <source> <target>");
+    log4.info("Example: npx create-ampless@alpha copy-theme blog my-blog");
+    process.exit(1);
+  }
+  try {
+    const result = await runCopyThemeIn(destDir, source, target);
+    outro2(
+      `${pc4.green("\u2714")} Copied themes/${result.source}/ \u2192 themes/${result.target}/
+
+  Files rewritten:
+` + result.filesRewritten.map((f) => `    ${pc4.dim(f)}`).join("\n") + `
+
+  themes-registry.ts updated. Next:
+    ${pc4.cyan(`Open themes/${result.target}/ and start customising`)}
+    ${pc4.cyan(`Activate via /admin/sites/<siteId>/theme`)}`
+    );
+  } catch (err) {
+    log4.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+import pc5 from "picocolors";
+var DEFAULT_THEMES = VALID_THEMES;
 function buildNonInteractiveOpts(args) {
   const projectName = args.projectName ?? (() => {
     const b = basename3(process.cwd());
     return b && b !== "/" ? b : "my-ampless-site";
   })();
   const siteName = args.siteName ?? "My Blog";
-  const themes = args.themes ?? ["blog"];
+  const themes = args.themes ?? [...DEFAULT_THEMES];
   const plugins = args.plugins ?? ["seo"];
   return {
     projectName,
@@ -1623,7 +2152,7 @@ function warnIgnoredScaffoldFlags(args) {
   if (args.plugins) ignored.push("--plugins");
   if (args.projectName) ignored.push("<project-name> positional");
   if (ignored.length > 0) {
-    log3.warn(`--mount mode ignores: ${ignored.join(", ")}`);
+    log5.warn(`--mount mode ignores: ${ignored.join(", ")}`);
   }
 }
 async function runMount(args) {
@@ -1632,8 +2161,8 @@ async function runMount(args) {
   warnIgnoredScaffoldFlags(args);
   const problem = validateMountableProject(destDir);
   if (problem) {
-    log3.error(problem);
-    log3.info(
+    log5.error(problem);
+    log5.info(
       "Run `npx create-ampless@alpha <name>` first to scaffold, or `cd` into a scaffolded project before passing --mount."
     );
     process.exit(1);
@@ -1647,23 +2176,23 @@ async function runMount(args) {
     if (err instanceof PreflightError) {
       process.exit(1);
     }
-    log3.error(err instanceof Error ? err.message : String(err));
+    log5.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
 }
 function printDeployResult(result) {
   const lines = [
-    `${pc3.green("\u2714")} Project deployed`,
+    `${pc5.green("\u2714")} Project deployed`,
     ``,
-    `  GitHub:        ${pc3.cyan(result.githubRepoUrl)}`,
-    `  Amplify app:   ${pc3.cyan(result.amplifyAppId)}`,
-    `  Amplify URL:   ${pc3.cyan(result.amplifyAppUrl)}`
+    `  GitHub:        ${pc5.cyan(result.githubRepoUrl)}`,
+    `  Amplify app:   ${pc5.cyan(result.amplifyAppId)}`,
+    `  Amplify URL:   ${pc5.cyan(result.amplifyAppUrl)}`
   ];
   if (result.domainUrl) {
-    lines.push(`  Custom domain: ${pc3.cyan(result.domainUrl)}`);
+    lines.push(`  Custom domain: ${pc5.cyan(result.domainUrl)}`);
   }
   if (result.domainVerification && result.domainVerification.length > 0) {
-    lines.push("", `  ${pc3.bold("Add these DNS records to verify the domain:")}`);
+    lines.push("", `  ${pc5.bold("Add these DNS records to verify the domain:")}`);
     for (const v of result.domainVerification) {
       lines.push(`    ${v.cname}  CNAME  ${v.target}`);
     }
@@ -1671,9 +2200,9 @@ function printDeployResult(result) {
   lines.push(
     "",
     `  First build is now running in Amplify Hosting.`,
-    `  Watch it at ${pc3.cyan(`https://console.aws.amazon.com/amplify/home#/${result.amplifyAppId}`)}`
+    `  Watch it at ${pc5.cyan(`https://console.aws.amazon.com/amplify/home#/${result.amplifyAppId}`)}`
   );
-  outro(lines.join("\n"));
+  outro3(lines.join("\n"));
 }
 async function main() {
   const args = parseDeployArgs(process.argv.slice(2));
@@ -1682,7 +2211,15 @@ async function main() {
     return;
   }
   for (const flag of args.unknown) {
-    log3.warn(`Unknown argument ignored: ${flag}`);
+    log5.warn(`Unknown argument ignored: ${flag}`);
+  }
+  if (args.upgrade) {
+    await runUpgrade(args);
+    return;
+  }
+  if (args.copyTheme) {
+    await runCopyTheme(args);
+    return;
   }
   if (args.mount) {
     await runMount(args);
@@ -1696,8 +2233,8 @@ async function main() {
   }
   if (!opts) return;
   const destDir = resolve5(process.cwd(), opts.projectName);
-  if (existsSync4(destDir)) {
-    log3.error(`Directory already exists: ${destDir}`);
+  if (existsSync7(destDir)) {
+    log5.error(`Directory already exists: ${destDir}`);
     process.exit(1);
   }
   const sharedDir = sharedTemplateDir();
@@ -1708,7 +2245,7 @@ async function main() {
     s.stop("Done!");
   } catch (err) {
     s.stop("Failed.");
-    log3.error(String(err));
+    log5.error(String(err));
     process.exit(1);
   }
   if (args.deploy) {
@@ -1721,19 +2258,19 @@ async function main() {
       if (err instanceof PreflightError) {
         process.exit(1);
       }
-      log3.error(err instanceof Error ? err.message : String(err));
+      log5.error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
     return;
   }
-  outro(
-    `${pc3.green("\u2714")} Project created at ${pc3.bold(opts.projectName)}
+  outro3(
+    `${pc5.green("\u2714")} Project created at ${pc5.bold(opts.projectName)}
 
   Next steps:
-    ${pc3.cyan("cd")} ${opts.projectName}
-    ${pc3.cyan("npm install")}
-    ${pc3.cyan("npx ampx sandbox")}   ${pc3.dim("# start Amplify backend")}
-    ${pc3.cyan("npm run dev")}         ${pc3.dim("# start Next.js")}`
+    ${pc5.cyan("cd")} ${opts.projectName}
+    ${pc5.cyan("npm install")}
+    ${pc5.cyan("npx ampx sandbox")}   ${pc5.dim("# start Amplify backend")}
+    ${pc5.cyan("npm run dev")}         ${pc5.dim("# start Next.js")}`
   );
 }
 main().catch((err) => {

package/dist/templates/_shared/amplify/backend.custom.ts

@@ -0,0 +1,41 @@
+import type { AmplessBackend } from '@ampless/backend'
+
+// Custom backend extensions for this project.
+//
+// `amplify/backend.ts` calls `customizeBackend(backend)` right after
+// ampless's baseline wiring. Mutate the passed `backend` instance to
+// add Lambda permissions, attach event sources, register custom CDK
+// constructs, etc.
+//
+// This file is NEVER overwritten by `create-ampless upgrade` —
+// `amplify/backend.ts` is, so keep your customizations here.
+//
+// (Function-export rather than side-effect import on purpose: a
+// top-level `import { backend } from './backend.js'` would create an
+// ESM circular dependency, leaving `backend` in its TDZ at evaluation
+// time. The factory pattern sidesteps that.)
+//
+// Example: granting an existing ampless Lambda extra IAM permissions:
+//
+//   import { Effect, PolicyStatement } from 'aws-cdk-lib/aws-iam'
+//
+//   export function customizeBackend(backend: AmplessBackend): void {
+//     backend.processorTrusted.resources.lambda.addToRolePolicy(
+//       new PolicyStatement({
+//         effect: Effect.ALLOW,
+//         actions: ['ses:SendEmail'],
+//         resources: ['*'],
+//       })
+//     )
+//   }
+//
+// Example: adding your own Lambda function — define it in
+// `amplify/functions/<name>/resource.ts`, import it here, and attach
+// it inside `customizeBackend` via `backend.createStack(...)` or by
+// granting it permissions on existing resources.
+//
+// If you don't need any extensions, leave the body empty.
+
+export function customizeBackend(_backend: AmplessBackend): void {
+  // No-op by default.
+}

package/dist/templates/_shared/amplify/backend.ts

@@ -8,13 +8,16 @@ import { eventDispatcher } from './events/dispatcher/resource.js'
 import { processorTrusted } from './events/processor-trusted/resource.js'
 import { processorUntrusted } from './events/processor-untrusted/resource.js'
 import { apiKeyRenewer } from './functions/api-key-renewer/resource.js'
+import { userAdmin } from './functions/user-admin/resource.js'
+import { customizeBackend } from './backend.custom.js'
 
 // `defineAmplessBackend` provisions auth, data, storage, the event
 // system (DynamoDB Streams → SQS-trusted / SQS-untrusted → trust_level
 // Lambdas), the AppSync API key renewer, and every IAM / CORS /
 // password policy override. Add custom CDK constructs / IAM policies
-// below by mutating the returned `backend` — `defineAmplessBackend`
-// returns the same object Amplify Gen 2's `defineBackend` does.
+// in `amplify/backend.custom.ts` by mutating the `backend` instance —
+// `defineAmplessBackend` returns the same object Amplify Gen 2's
+// `defineBackend` does.
 const backend = defineAmplessBackend({
   auth,
   data,
@@ -24,6 +27,11 @@ const backend = defineAmplessBackend({
   processorTrusted,
   processorUntrusted,
   apiKeyRenewer,
+  userAdmin,
 })
 
+// Run user-defined customizations after baseline wiring. `backend.custom.ts`
+// is never overwritten by `create-ampless upgrade`.
+customizeBackend(backend)
+
 export default backend

package/dist/templates/_shared/amplify/data/resource.custom.ts

@@ -0,0 +1,33 @@
+// Custom data schema models for this project.
+//
+// `amplify/data/resource.ts` calls `customSchemaModels(a)` and spreads
+// the result alongside ampless's built-in models in the same
+// `a.schema({...})` call, which is the only way Amplify Gen 2's
+// `ClientSchema<typeof schema>` inference picks up extra models.
+//
+// This file is NEVER overwritten by `create-ampless upgrade` —
+// `amplify/data/resource.ts` is, so keep your custom models here.
+//
+// Example:
+//
+//   export function customSchemaModels(a: any) {
+//     return {
+//       Bookmark: a
+//         .model({
+//           siteId: a.string().required(),
+//           bookmarkId: a.id().required(),
+//           url: a.string().required(),
+//           title: a.string(),
+//         })
+//         .identifier(['siteId', 'bookmarkId'])
+//         .authorization((allow: any) => [allow.groups(['ampless-admin', 'ampless-editor'])]),
+//     }
+//   }
+//
+// `a` is the Amplify Gen 2 schema builder; see Amplify Data docs for
+// the full DSL. Return an empty object if no customizations are needed.
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function customSchemaModels(_a: any): Record<string, unknown> {
+  return {}
+}

package/dist/templates/_shared/amplify/data/resource.ts

@@ -2,6 +2,8 @@ import { fileURLToPath } from 'node:url'
 import { dirname, resolve } from 'node:path'
 import { a, defineData, type ClientSchema } from '@aws-amplify/backend'
 import { amplessSchemaModels, defaultAuthorizationModes } from '@ampless/backend'
+import { userAdmin } from '../functions/user-admin/resource.js'
+import { customSchemaModels } from './resource.custom.js'
 
 // AppSync's `a.handler.custom({ entry })` paths are resolved by CDK
 // relative to the file that called `a.handler.custom`. When the call
@@ -16,15 +18,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 // KvStore) plus the three public-read custom queries
 // (listPublishedPosts / getPublishedPost / listPostsByTag).
 //
-// Add project-specific models alongside the spread:
-//
-//   const schema = a.schema({
-//     ...amplessSchemaModels(a, { resolverPaths }),
-//     MyCustomModel: a
-//       .model({ siteId: a.string().required(), foo: a.string() })
-//       .identifier(['siteId', 'foo'])
-//       .authorization((allow) => [allow.groups(['ampless-admin'])]),
-//   })
+// Add project-specific models in `amplify/data/resource.custom.ts` —
+// that file is never overwritten by `create-ampless upgrade`.
 const resolverPaths = {
   listPublishedPosts: resolve(__dirname, 'list-published-posts.js'),
   getPublishedPost: resolve(__dirname, 'get-published-post.js'),
@@ -32,7 +27,8 @@ const resolverPaths = {
 }
 
 const schema = a.schema({
-  ...amplessSchemaModels(a, { resolverPaths }),
+  ...amplessSchemaModels(a, { resolverPaths, userAdminFunction: userAdmin }),
+  ...customSchemaModels(a),
 })
 
 export type Schema = ClientSchema<typeof schema>

package/dist/templates/_shared/amplify/functions/user-admin/handler.ts

@@ -0,0 +1,4 @@
+// Re-exported from @ampless/backend so the package can ship Lambda
+// handler updates via `npm update`. Amplify's esbuild follows this
+// import and bundles the real handler into the Lambda artifact.
+export { handler } from '@ampless/backend/auth/user-admin'

package/dist/templates/_shared/amplify/functions/user-admin/resource.ts

@@ -0,0 +1,6 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const userAdmin = defineFunction({
+  name: 'user-admin',
+  entry: './handler.ts',
+})

package/dist/templates/_shared/app/(admin)/admin/users/page.tsx

@@ -0,0 +1,5 @@
+import { admin } from '@/lib/admin'
+import { createUsersListPage } from '@ampless/admin/pages'
+
+export const dynamic = 'force-dynamic'
+export default createUsersListPage(admin)

package/dist/templates/_shared/package.json

@@ -8,7 +8,10 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "sandbox": "ampx sandbox"
+    "sandbox": "ampx sandbox",
+    "sandbox:dev": "ampx sandbox --once && next dev",
+    "update-ampless": "npx create-ampless@alpha upgrade",
+    "copy-theme": "npx create-ampless@alpha copy-theme"
   },
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.6.0",
@@ -20,15 +23,15 @@
     "@tiptap/pm": "^3.23.4",
     "@tiptap/react": "^3.23.4",
     "@tiptap/starter-kit": "^3.23.4",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.1",
-    "@ampless/plugin-rss": "^0.2.0-alpha.1",
-    "@ampless/plugin-seo": "^0.2.0-alpha.1",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.1",
-    "@ampless/admin": "^0.2.0-alpha.6",
-    "@ampless/backend": "^0.2.0-alpha.2",
-    "@ampless/runtime": "^0.2.0-alpha.3",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.2",
+    "@ampless/plugin-rss": "^0.2.0-alpha.2",
+    "@ampless/plugin-seo": "^0.2.0-alpha.2",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.2",
+    "@ampless/admin": "^0.2.0-alpha.7",
+    "@ampless/backend": "^0.2.0-alpha.3",
+    "@ampless/runtime": "^0.2.0-alpha.4",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^0.2.0-alpha.1",
+    "ampless": "^0.2.0-alpha.2",
     "aws-amplify": "^6.10.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "0.2.0-alpha.7",
+  "version": "0.2.0-alpha.9",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",