create-meith 0.30.0 → 0.31.0

package/dist/bin.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { execFile } from "node:child_process";
-import { mkdir, readdir, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import { promisify } from "node:util";
+import { execFile as execFile2 } from "node:child_process";
+import { mkdir as mkdir2, readdir, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname2, join as join2, resolve } from "node:path";
+import { promisify as promisify2 } from "node:util";
 
 // src/scaffold.ts
 var DEFAULT_REPOSITORY_URL = "https://github.com/meith-dev/meith";
@@ -125,6 +125,18 @@ var ENV_SMTP_MAIL_BLOCK = `# Mail. Leave these alone and the installer asks for
 # MAIL_SMTP_USERNAME=
 # MAIL_SMTP_PASSWORD=
 # MAIL_FROM=noreply@yourdomain.com`;
+var ENV_BACKUP_BLOCK = `# The off-site backup destination: an S3-compatible bucket \`meith backup\`
+# ships every bundle to, pruned there to the newest --keep (7 unless set).
+# All four required together \u2014 a partial set fails the backup, never the board.
+# BACKUP_S3_ENDPOINT is for anything S3-compatible (R2, MinIO, Spaces;
+# BACKUP_S3_REGION=auto for R2); BACKUP_S3_PREFIX shares one bucket between
+# boards. Use a bucket of its own, never the bucket the uploads live in.
+# BACKUP_S3_BUCKET=
+# BACKUP_S3_REGION=
+# BACKUP_S3_ACCESS_KEY_ID=
+# BACKUP_S3_SECRET_ACCESS_KEY=
+# BACKUP_S3_ENDPOINT=
+# BACKUP_S3_PREFIX=`;
 function selfHostEnvExample(name) {
   return `# ${name} \u2014 environment.
 #
@@ -155,6 +167,8 @@ APP_URL=
 
 ${ENV_SMTP_MAIL_BLOCK}
 
+${ENV_BACKUP_BLOCK}
+
 `;
 }
 function vercelEnvExample(name) {
@@ -323,7 +337,6 @@ function envExample(name, target) {
 }
 var SELF_HOST_DEPLOY_KIT = [
   ".dockerignore",
-  ".github/dependabot.yml",
   ".github/workflows/build.yml",
   "Dockerfile",
   "Dockerfile.prebuilt",
@@ -508,9 +521,10 @@ export function installedPluginDefinitions() {
   files.set(
     ".github/dependabot.yml",
     `# Keeps this board's GitHub Actions current: one weekly pull request that
-# bumps the actions pinned in .github/workflows. Upgrading Meith itself is
-# separate and deliberate \u2014 see README.md, "Upgrading" \u2014 because the board's
-# \`next\` pin has to move together with \`@meith/web\` rather than on its own.
+# bumps the actions pinned in .github/workflows. Meith itself is updated
+# separately, by .github/workflows/update.yml \u2014 see README.md, "Upgrading" \u2014
+# because the board's \`next\` pin has to move together with \`@meith/web\`
+# rather than on its own.
 version: 2
 updates:
   - package-ecosystem: github-actions
@@ -520,6 +534,82 @@ updates:
     groups:
       actions:
         patterns: ['*']
+`
+  );
+  files.set(
+    ".github/workflows/update.yml",
+    `# Opens a pull request whenever a new Meith release is out \u2014 see README.md,
+# "Upgrading". Once a week, and on the Run workflow button, it runs the same
+# updater you can run by hand, \`npx create-meith@latest update\`: every
+# @meith/* pin and next moved together in package.json, and the deploy files
+# the scaffold owns rewritten to the new release's shape. A file you have
+# edited yourself is never rewritten; the run's log names any it left alone.
+#
+# One-time setup: under Settings \u2192 Actions \u2192 General, enable "Allow GitHub
+# Actions to create and approve pull requests" \u2014 without it the last step
+# fails, saying GitHub Actions is not permitted to create pull requests.
+#
+# Merging is still an upgrade, not a formality: read the release notes the
+# pull request links, take a backup first, and once the new version serves,
+# run \`meith upgrade\` against it. Migrations are forward-only \u2014 the backup
+# is the rollback.
+name: Meith update
+
+on:
+  schedule:
+    - cron: '30 4 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    name: Update Meith
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - name: Run the updater
+        run: npx --yes create-meith@latest update
+
+      - name: Open a pull request
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "Already up to date."
+            exit 0
+          fi
+          VERSION=$(node -p "require('./package.json').dependencies['@meith/web']")
+          BODY="$RUNNER_TEMP/meith-update-body.md"
+          {
+            echo "Updates this board to Meith $VERSION \u2014 every @meith/* package and"
+            echo "next moved together, and the scaffold-owned deploy files rewritten"
+            echo "to this release's shape. Files with local edits were left alone;"
+            echo "this workflow run's log names any it skipped."
+            echo
+            echo "Before merging and deploying:"
+            echo
+            echo "1. Read the release notes \u2014 their Migrations line says what this"
+            echo "   release does to the schema:"
+            echo "   https://github.com/meith-dev/meith/releases/tag/v$VERSION"
+            echo "2. Take a backup. Migrations are forward-only; the backup is the"
+            echo "   rollback."
+            echo
+            echo "After the new version deploys, run 'meith upgrade' once against the"
+            echo "board \u2014 the admin panel shows a notice until it has run. See"
+            echo "README.md, \\"Upgrading\\"."
+          } > "$BODY"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -B meith-update
+          git add -A
+          git commit -m "Update Meith to $VERSION"
+          git push -f origin meith-update
+          gh pr create --title "Update Meith to $VERSION" --body-file "$BODY" \\
+            || gh pr edit meith-update --title "Update Meith to $VERSION" --body-file "$BODY"
 `
   );
   files.set(
@@ -934,8 +1024,24 @@ services:
       - MAIL_SMTP_USERNAME=\${MAIL_SMTP_USERNAME:-}
       - MAIL_SMTP_PASSWORD=\${MAIL_SMTP_PASSWORD:-}
       - MAIL_FROM=\${MAIL_FROM:-}
+      # The off-site backup destination, unset until the four required values
+      # are filled in on the Coolify resource. Coolify only hands a compose
+      # service the variables the file names, so a Scheduled Task running
+      # \`meith backup\` in this container would never see them without these
+      # lines \u2014 see the meith repository's
+      # docs/getting-started/deployment/coolify.md, "Set up backups".
+      - BACKUP_S3_BUCKET=\${BACKUP_S3_BUCKET:-}
+      - BACKUP_S3_REGION=\${BACKUP_S3_REGION:-}
+      - BACKUP_S3_ACCESS_KEY_ID=\${BACKUP_S3_ACCESS_KEY_ID:-}
+      - BACKUP_S3_SECRET_ACCESS_KEY=\${BACKUP_S3_SECRET_ACCESS_KEY:-}
+      - BACKUP_S3_ENDPOINT=\${BACKUP_S3_ENDPOINT:-}
+      - BACKUP_S3_PREFIX=\${BACKUP_S3_PREFIX:-}
     volumes:
       - uploads:/app/.uploads
+      # Where \`meith backup --dir /backups\` writes its ring of bundles. A
+      # named volume rather than the container filesystem, so the ring survives
+      # every redeploy.
+      - backups:/backups
     depends_on:
       postgres:
         condition: service_healthy
@@ -971,6 +1077,7 @@ services:
 volumes:
   pgdata:
   uploads:
+  backups:
 `
   );
   files.set(
@@ -1066,8 +1173,24 @@ services:
       - MAIL_SMTP_USERNAME=\${MAIL_SMTP_USERNAME:-}
       - MAIL_SMTP_PASSWORD=\${MAIL_SMTP_PASSWORD:-}
       - MAIL_FROM=\${MAIL_FROM:-}
+      # The off-site backup destination, unset until the four required values
+      # are filled in on the Coolify resource. Coolify only hands a compose
+      # service the variables the file names, so a Scheduled Task running
+      # \`meith backup\` in this container would never see them without these
+      # lines \u2014 see the meith repository's
+      # docs/getting-started/deployment/coolify.md, "Set up backups".
+      - BACKUP_S3_BUCKET=\${BACKUP_S3_BUCKET:-}
+      - BACKUP_S3_REGION=\${BACKUP_S3_REGION:-}
+      - BACKUP_S3_ACCESS_KEY_ID=\${BACKUP_S3_ACCESS_KEY_ID:-}
+      - BACKUP_S3_SECRET_ACCESS_KEY=\${BACKUP_S3_SECRET_ACCESS_KEY:-}
+      - BACKUP_S3_ENDPOINT=\${BACKUP_S3_ENDPOINT:-}
+      - BACKUP_S3_PREFIX=\${BACKUP_S3_PREFIX:-}
     volumes:
       - uploads:/app/.uploads
+      # Where \`meith backup --dir /backups\` writes its ring of bundles. A
+      # named volume rather than the container filesystem, so the ring survives
+      # every redeploy.
+      - backups:/backups
     depends_on:
       postgres:
         condition: service_healthy
@@ -1103,6 +1226,7 @@ services:
 volumes:
   pgdata:
   uploads:
+  backups:
 `
   );
   files.set(
@@ -1288,27 +1412,52 @@ for the full guide.
 
 ## Upgrading
 
+\`.github/workflows/update.yml\` does this for you: once a week \u2014 and
+whenever you press **Run workflow** on the Actions tab \u2014 it checks for a new
+Meith release and opens a pull request that moves every \`@meith/*\` package
+and \`next\` together, and rewrites the deploy files this scaffold owns
+(\`Dockerfile\`, the compose files, the workflows) to the new release's
+shape. A file you have edited yourself is never rewritten; the run's log
+names any it left for you. One-time setup: under
+**Settings \u2192 Actions \u2192 General**, enable **Allow GitHub Actions to create
+and approve pull requests**, or the workflow cannot open one.
+
+Merging that pull request is still an upgrade, not a formality: read the
+release notes it links, take a backup first, and press **Redeploy** in
+Coolify after the merge \u2014 pushing alone does not rebuild. Once the new
+version serves, run \`npm run meith -- upgrade\` against it for the plugin
+migrations.
+
+The same update, by hand and without waiting for the schedule:
+
+\`\`\`sh
+npx create-meith@latest update
+git commit -am "Update Meith"
+git push
+\`\`\`
+
+Under the hood, the version move is these two commands, plus the deploy-file
+rewrite neither of them can do:
+
 \`\`\`sh
 npm install --save-exact @meith/web@latest @meith/cli@latest @meith/theme-default@latest
 npm install --save-exact next@$(node -p "require('./node_modules/@meith/web/package.json').dependencies.next")
-git commit -am "Upgrade Meith and the Next.js version it builds with"
-git push
 \`\`\`
 
 The second command is not optional. This board pins \`next\` itself, and
-nothing bumps it for you: upgrading only the \`@meith/*\` packages leaves the
-board's own pin on the old Next while \`@meith/web\` depends on the new one,
-which npm resolves by installing both \u2014 the build then runs on one version
-while everything reading \`package.json\` sees the other. Reading the version
-out of the freshly installed \`@meith/web\` is what keeps the two the same
-without anybody having to know the number.
-
-This upgrade is deliberate and manual for that reason: \`next\` and
-\`@meith/web\` move together or not at all. What *is* kept current for you is
-this repository's own GitHub Actions \u2014 \`.github/dependabot.yml\` opens a
-weekly pull request bumping the actions pinned in
-\`.github/workflows/build.yml\`, which is a safe, independent update the two
-commands above never touch.
+the npm commands alone never bump it: upgrading only the \`@meith/*\` packages
+leaves the board's own pin on the old Next while \`@meith/web\` depends on the
+new one, which npm resolves by installing both \u2014 the build then runs on one
+version while everything reading \`package.json\` sees the other. Reading the
+version out of the freshly installed \`@meith/web\` is what keeps the two the
+same without anybody having to know the number.
+
+\`next\` and \`@meith/web\` move together or not at all, which is why one
+updater owns the whole move and no dependency bot bumps either on its own.
+What Dependabot *does* keep current is this repository's own GitHub Actions \u2014
+\`.github/dependabot.yml\` opens a weekly pull request bumping the actions
+pinned under \`.github/workflows\`, a safe, independent update the updater
+leaves to it.
 
 On the quick-start path there is no version to keep in sync by hand:
 \`Dockerfile\` runs \`npm install\` straight from this \`package.json\` on every
@@ -1542,20 +1691,38 @@ each retry into another attempt against whatever it is failing against.
 
 ## Upgrading
 
+\`.github/workflows/update.yml\` does this for you: once a week \u2014 and
+whenever you press **Run workflow** on the Actions tab \u2014 it checks for a new
+Meith release and opens a pull request that moves every \`@meith/*\` package
+and \`next\` together. A file you have edited yourself is never rewritten; the
+run's log names any it left for you. One-time setup: under
+**Settings \u2192 Actions \u2192 General**, enable **Allow GitHub Actions to create and
+approve pull requests**, or the workflow cannot open one. Read the release
+notes the pull request links and take a backup before merging; Vercel
+rebuilds on the merge, and the build command applies the new migrations
+before it builds.
+
+The same update, by hand and without waiting for the schedule:
+
+\`\`\`sh
+npx create-meith@latest update
+git commit -am "Update Meith"
+git push
+\`\`\`
+
+Under the hood, the version move is these two commands:
+
 \`\`\`sh
 npm install --save-exact @meith/web@latest @meith/cli@latest @meith/theme-default@latest
 npm install --save-exact next@$(node -p "require('./node_modules/@meith/web/package.json').dependencies.next")
-git commit -am "Upgrade Meith and the Next.js version it builds with"
-git push
 \`\`\`
 
-Vercel rebuilds on the push, and the build command applies the new migrations
-before it builds. \`--save-exact\` matters and \`.npmrc\` already sets it for
-everything else installed here.
+\`--save-exact\` matters and \`.npmrc\` already sets it for everything else
+installed here.
 
 The second command is not optional. This board pins \`next\` itself \u2014 Vercel
-reads that pin to pick its Next.js builder \u2014 and nothing bumps it for you.
-Upgrading only the \`@meith/*\` packages leaves two versions of Next
+reads that pin to pick its Next.js builder \u2014 and the npm commands alone never
+bump it. Upgrading only the \`@meith/*\` packages leaves two versions of Next
 installed, the board built with one and the platform configured for the
 other. Reading the version out of the freshly installed \`@meith/web\` keeps
 them the same without anybody having to know the number.
@@ -2098,8 +2265,369 @@ function extensionNextSteps(name) {
   return [`cd ${name}`, "npm install", "npm test"];
 }
 
-// src/cli.ts
+// src/update.ts
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { gunzipSync } from "node:zlib";
 var execFileAsync = promisify(execFile);
+var TEMPLATE_BOARD_NAME = "meith-board";
+var TEMPLATE_REPOSITORIES = {
+  "self-host": "meith-dev/template",
+  vercel: "meith-dev/vercel-template"
+};
+var RELEASE_NOTES_URL = "https://github.com/meith-dev/meith/releases/tag";
+function templateTarballUrl(target, version) {
+  return `https://codeload.github.com/${TEMPLATE_REPOSITORIES[target]}/tar.gz/refs/tags/v${version}`;
+}
+function parseExactVersion(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (match === null) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareExactVersions(left, right) {
+  const a = parseExactVersion(left);
+  const b = parseExactVersion(right);
+  if (a === null || b === null) return 0;
+  for (let part = 0; part < 3; part++) {
+    if (a[part] !== b[part])
+      return a[part] - b[part];
+  }
+  return 0;
+}
+function substituteBoardName(content, name) {
+  if (name === TEMPLATE_BOARD_NAME) return content;
+  return content.split(TEMPLATE_BOARD_NAME).join(name);
+}
+function normalizeActionPins(content) {
+  return content.split("\n").map((line) => /^\s*(- )?uses:\s/.test(line) ? line.replace(/@\S+(\s*#.*)?$/, "@pin") : line).join("\n");
+}
+function comparable(path, content) {
+  return path.startsWith(".github/workflows/") ? normalizeActionPins(content) : content;
+}
+function tarText(block, start, length) {
+  const slice = block.subarray(start, start + length);
+  const end = slice.indexOf(0);
+  return new TextDecoder().decode(end === -1 ? slice : slice.subarray(0, end));
+}
+function unpackTemplateTarball(data, name) {
+  const tar = gunzipSync(data);
+  const files = /* @__PURE__ */ new Map();
+  for (let at = 0; at + 512 <= tar.length; ) {
+    const header = tar.subarray(at, at + 512);
+    at += 512;
+    if (header.every((byte) => byte === 0)) break;
+    const size = Number.parseInt(tarText(header, 124, 12).trim() || "0", 8);
+    const type = header[156] ?? 0;
+    const prefix = tarText(header, 345, 155);
+    const path = prefix === "" ? tarText(header, 0, 100) : `${prefix}/${tarText(header, 0, 100)}`;
+    if (type === 48 || type === 0) {
+      const relative = path.split("/").slice(1).join("/");
+      if (relative !== "") {
+        const content = new TextDecoder().decode(tar.subarray(at, at + size));
+        files.set(relative, substituteBoardName(content, name));
+      }
+    }
+    at += Math.ceil(size / 512) * 512;
+  }
+  return files;
+}
+async function fetchPreviousTree(target, version, name) {
+  try {
+    const response = await fetch(templateTarballUrl(target, version), {
+      redirect: "follow",
+      signal: AbortSignal.timeout(3e4)
+    });
+    if (!response.ok) return null;
+    return unpackTemplateTarball(new Uint8Array(await response.arrayBuffer()), name);
+  } catch {
+    return null;
+  }
+}
+function mergeDependencies(current, next, newVersion) {
+  const merged = {};
+  for (const [name, range] of Object.entries(current)) {
+    merged[name] = next[name] ?? (name.startsWith("@meith/") ? newVersion : range);
+  }
+  for (const [name, range] of Object.entries(next)) {
+    if (!(name in merged)) merged[name] = range;
+  }
+  return merged;
+}
+function mergeScripts(current, previous, next, degraded) {
+  const merged = { ...current ?? {} };
+  for (const [key, value] of Object.entries(next)) {
+    const held = current?.[key];
+    if (held === void 0) {
+      if (degraded || previous?.[key] === void 0) merged[key] = value;
+      continue;
+    }
+    if (held === value || held === previous?.[key]) merged[key] = value;
+  }
+  return merged;
+}
+function mergeManifest(currentText, previousText, nextText, newVersion) {
+  const current = JSON.parse(currentText);
+  const previous = previousText === null ? null : JSON.parse(previousText);
+  const next = JSON.parse(nextText);
+  const merged = { ...current };
+  merged.dependencies = mergeDependencies(
+    current.dependencies ?? {},
+    next.dependencies ?? {},
+    newVersion
+  );
+  if (current.devDependencies !== void 0) {
+    merged.devDependencies = mergeDependencies(current.devDependencies, {}, newVersion);
+  }
+  if (next.scripts !== void 0) {
+    merged.scripts = mergeScripts(
+      current.scripts,
+      previous?.scripts,
+      next.scripts,
+      previous === null
+    );
+  }
+  for (const field of ["type", "engines"]) {
+    if (!(field in next)) continue;
+    const untouched = previous !== null && JSON.stringify(current[field]) === JSON.stringify(previous[field]);
+    if (!(field in current) || untouched) merged[field] = next[field];
+  }
+  return `${JSON.stringify(merged, null, 2)}
+`;
+}
+function planUpdate({ current, previous, next, newVersion }) {
+  const writes = /* @__PURE__ */ new Map();
+  const deletes = [];
+  const created = [];
+  const updated = [];
+  const skipped = [];
+  const review = [];
+  const currentManifest = current.get("package.json");
+  const nextManifest = next.get("package.json");
+  if (currentManifest !== void 0 && nextManifest !== void 0) {
+    const merged = mergeManifest(
+      currentManifest,
+      previous?.get("package.json") ?? null,
+      nextManifest,
+      newVersion
+    );
+    if (merged !== currentManifest) {
+      writes.set("package.json", merged);
+      updated.push("package.json");
+    }
+  }
+  if (previous === null) {
+    for (const [path, content] of next) {
+      if (path === "package.json") continue;
+      if (current.get(path) !== content) review.push(path);
+    }
+    return { writes, deletes, created, updated, skipped, review: review.sort() };
+  }
+  const paths = /* @__PURE__ */ new Set([...next.keys(), ...previous.keys()]);
+  paths.delete("package.json");
+  for (const path of [...paths].sort()) {
+    const held = current.get(path);
+    const before = previous.get(path);
+    const after = next.get(path);
+    if (after !== void 0) {
+      if (held === void 0) {
+        if (before === void 0) {
+          writes.set(path, after);
+          created.push(path);
+        }
+        continue;
+      }
+      if (held === after) continue;
+      if (before !== void 0 && comparable(path, held) === comparable(path, before)) {
+        writes.set(path, after);
+        updated.push(path);
+      } else {
+        skipped.push(path);
+      }
+      continue;
+    }
+    if (held === void 0 || before === void 0) continue;
+    if (comparable(path, held) === comparable(path, before)) deletes.push(path);
+    else skipped.push(path);
+  }
+  return { writes, deletes, created, updated, skipped: skipped.sort(), review };
+}
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readIfPresent(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function refreshNpmLockfile(cwd) {
+  try {
+    await execFileAsync(
+      "npm",
+      ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"],
+      { cwd }
+    );
+    return null;
+  } catch {
+    return "package-lock.json could not be refreshed \u2014 run `npm install` here to bring it up to date.";
+  }
+}
+async function runUpdate(newVersion, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const manifestText = await readIfPresent(join(cwd, "package.json"));
+  if (manifestText === null) {
+    return {
+      code: 1,
+      lines: [
+        "create-meith update: no package.json here.",
+        "Run this inside the board directory \u2014 the one `npx create-meith` scaffolded,",
+        "or the clone of your board repository."
+      ]
+    };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestText);
+  } catch {
+    return { code: 1, lines: ["create-meith update: package.json here is not valid JSON."] };
+  }
+  const currentVersion = manifest.dependencies?.["@meith/web"];
+  if (currentVersion === void 0) {
+    return {
+      code: 1,
+      lines: [
+        "create-meith update: this package.json does not depend on @meith/web,",
+        "so this does not look like a Meith board."
+      ]
+    };
+  }
+  const parsedCurrent = parseExactVersion(currentVersion);
+  if (parsedCurrent === null) {
+    return {
+      code: 1,
+      lines: [
+        `create-meith update: @meith/web is pinned to '${currentVersion}', not an exact X.Y.Z version.`,
+        "Pin it first \u2014 `npm install --save-exact @meith/web@<version>` \u2014 so the updater",
+        "can tell which release this board is on."
+      ]
+    };
+  }
+  const parsedNew = parseExactVersion(newVersion);
+  if (parsedNew === null) {
+    return {
+      code: 1,
+      lines: [`create-meith update: cannot update to '${newVersion}' \u2014 not an exact version.`]
+    };
+  }
+  if (compareExactVersions(currentVersion, newVersion) === 0) {
+    return { code: 0, lines: [`Already at ${newVersion} \u2014 nothing to update.`] };
+  }
+  if (compareExactVersions(currentVersion, newVersion) > 0) {
+    return {
+      code: 1,
+      lines: [
+        `create-meith update: this board is on ${currentVersion}, newer than ${newVersion}.`,
+        "Downgrades are refused \u2014 migrations are forward-only. To update, run the",
+        "newest updater: `npx create-meith@latest update`."
+      ]
+    };
+  }
+  if (parsedNew[0] - parsedCurrent[0] > 2) {
+    const stage = parsedCurrent[0] + 2;
+    return {
+      code: 1,
+      lines: [
+        `create-meith update: ${currentVersion} to ${newVersion} jumps more than two majors,`,
+        "which is further than upgrades are tested to span. Update in stages instead \u2014",
+        `\`npx create-meith@${stage} update\` first, deploy and run \`meith upgrade\`,`,
+        "then come back to `npx create-meith@latest update`."
+      ]
+    };
+  }
+  const name = typeof manifest.name === "string" && manifest.name !== "" ? manifest.name : TEMPLATE_BOARD_NAME;
+  const target = await exists(join(cwd, "vercel.json")) ? "vercel" : "self-host";
+  const next = scaffold({
+    name,
+    version: newVersion,
+    repositoryUrl: DEFAULT_REPOSITORY_URL,
+    target
+  });
+  const previous = await (options.loadPrevious ?? fetchPreviousTree)(target, currentVersion, name);
+  const paths = /* @__PURE__ */ new Set(["package.json", ...next.keys(), ...previous?.keys() ?? []]);
+  const current = /* @__PURE__ */ new Map();
+  for (const path of paths) {
+    const content = await readIfPresent(join(cwd, path));
+    if (content !== null) current.set(path, content);
+  }
+  const plan = planUpdate({ current, previous, next, newVersion });
+  for (const [path, content] of plan.writes) {
+    const absolute = join(cwd, path);
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, content, "utf8");
+  }
+  for (const path of plan.deletes) {
+    await rm(join(cwd, path), { force: true });
+  }
+  const lockfileWarning = plan.writes.size > 0 && await exists(join(cwd, "package-lock.json")) ? await (options.refreshLockfile ?? refreshNpmLockfile)(cwd) : null;
+  const templateUrl = `https://github.com/${TEMPLATE_REPOSITORIES[target]}`;
+  const nextManifest = JSON.parse(next.get("package.json") ?? "{}");
+  const nextPin = nextManifest.dependencies?.next;
+  const lines = [];
+  const changed = plan.writes.size + plan.deletes.length;
+  if (changed === 0) {
+    lines.push(`Nothing to write \u2014 every file already matches ${newVersion}.`);
+  } else {
+    lines.push(
+      `Updated ${name} from ${currentVersion} to ${newVersion} \u2014 ${changed} file${changed === 1 ? "" : "s"} changed.`,
+      ""
+    );
+  }
+  for (const path of plan.updated) {
+    lines.push(
+      path === "package.json" ? `  updated package.json \u2014 every @meith/* pin to ${newVersion}${nextPin === void 0 ? "" : `, next to ${nextPin}`}` : `  updated ${path}`
+    );
+  }
+  for (const path of plan.created) lines.push(`  added   ${path}`);
+  for (const path of plan.deletes) lines.push(`  removed ${path} \u2014 this release no longer ships it`);
+  for (const path of plan.skipped) {
+    lines.push(
+      `  kept    ${path} \u2014 it differs from the ${currentVersion} scaffold; compare it with ${templateUrl} at v${newVersion}`
+    );
+  }
+  if (previous === null) {
+    lines.push(
+      "",
+      `Could not read the v${currentVersion} template from ${templateUrl}, so only`,
+      "package.json was updated. Review these files against that repository at",
+      `v${newVersion} \u2014 this release may have changed them:`,
+      ...plan.review.map((path) => `  ${path}`)
+    );
+  }
+  if (lockfileWarning !== null) lines.push("", lockfileWarning);
+  if (changed > 0) {
+    lines.push(
+      "",
+      "Next:",
+      "  1. Review the diff, commit, and push.",
+      "  2. Take a backup, then deploy. The release notes name the migrations:",
+      `     ${RELEASE_NOTES_URL}/v${newVersion}`,
+      "  3. Once the new version serves, run `meith upgrade` against the board \u2014",
+      "     the admin panel shows a notice until it has run."
+    );
+  }
+  return { code: 0, lines };
+}
+
+// src/cli.ts
+var execFileAsync2 = promisify2(execFile2);
 async function isSafeTarget(target) {
   try {
     return (await readdir(target)).length === 0;
@@ -2109,14 +2637,14 @@ async function isSafeTarget(target) {
 }
 async function initGit(target) {
   try {
-    await execFileAsync("git", ["init", "-q", "-b", "main"], { cwd: target });
-    await execFileAsync("git", ["add", "-A"], { cwd: target });
+    await execFileAsync2("git", ["init", "-q", "-b", "main"], { cwd: target });
+    await execFileAsync2("git", ["add", "-A"], { cwd: target });
     return true;
   } catch {
     return false;
   }
 }
-async function run(argv, version) {
+async function run(argv, version, updateOptions = {}) {
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -2131,21 +2659,30 @@ async function run(argv, version) {
     return {
       code: 0,
       lines: [
-        "create-meith \u2014 scaffold a forum project, a plugin or a theme.",
+        "create-meith \u2014 scaffold a forum project, a plugin or a theme, or update one.",
         "",
         "  npx create-meith <name> [--repo <url>] [--no-git]",
         "  npx create-meith --plugin <name> [--repo <url>] [--no-git]",
         "  npx create-meith --theme <name> [--repo <url>] [--no-git]",
+        "  npx create-meith@latest update",
         "",
         "The first form writes a deployable board into ./<name>, then tells you",
         "what to run. --plugin and --theme write an extension workspace instead:",
         "source and a passing test copied from the meith repository\u2019s worked",
         "examples, plus a README and a marketplace listing.json.",
         "",
+        "`update`, run inside a board, moves it to this release: every @meith/*",
+        "pin and next together in package.json, and the deploy files the scaffold",
+        "owns rewritten to the new shape \u2014 files you have edited are left alone",
+        "and named. `update` is a reserved word, so a board cannot take it as a name.",
+        "",
         "--no-git skips initializing a git repository in the new directory."
       ]
     };
   }
+  if (name === "update") {
+    return await runUpdate(version, updateOptions);
+  }
   const wantsPlugin = argv.includes("--plugin");
   const wantsTheme = argv.includes("--theme");
   if (wantsPlugin && wantsTheme) {
@@ -2178,9 +2715,9 @@ async function run(argv, version) {
     repositoryUrl: repoIndex === -1 ? void 0 : repositoryUrl
   });
   for (const [relative, contents] of files) {
-    const path = join(target, relative);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, contents, "utf8");
+    const path = join2(target, relative);
+    await mkdir2(dirname2(path), { recursive: true });
+    await writeFile2(path, contents, "utf8");
   }
   const gitReady = argv.includes("--no-git") ? false : await initGit(target);
   return {
@@ -2219,7 +2756,7 @@ async function run(argv, version) {
 }
 
 // src/bin.ts
-var result = await run(process.argv.slice(2), "0.30.0");
+var result = await run(process.argv.slice(2), "0.31.0");
 for (const line of result.lines) {
   if (result.code === 0) console.log(line);
   else console.error(line);