create-meith 0.30.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-meith",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "Scaffold a Meith board, plugin or theme — npx create-meith <name> writes a deployable board workspace; --plugin and --theme write extension workspaces built on the published kits.",
   "license": "MIT",
   "repository": {

package/src/bin.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { run } from './cli'
 
-const result = await run(process.argv.slice(2), '0.30.1')
+const result = await run(process.argv.slice(2), '0.32.0')
 for (const line of result.lines) {
   if (result.code === 0) console.log(line)
   else console.error(line)

package/src/cli.ts

@@ -10,6 +10,7 @@ import {
   scaffoldExtension,
   validateExtensionName,
 } from './scaffold-extension'
+import { type RunUpdateOptions, runUpdate } from './update'
 
 const execFileAsync = promisify(execFile)
 
@@ -36,7 +37,11 @@ async function initGit(target: string): Promise<boolean> {
   }
 }
 
-export async function run(argv: readonly string[], version: string): Promise<CliResult> {
+export async function run(
+  argv: readonly string[],
+  version: string,
+  updateOptions: RunUpdateOptions = {},
+): Promise<CliResult> {
   const positional: string[] = []
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i] as string
@@ -52,22 +57,32 @@ export async function run(argv: readonly string[], version: string): Promise<Cli
     return {
       code: 0,
       lines: [
-        'create-meith — scaffold a forum project, a plugin or a theme.',
+        'create-meith — 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’s 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 — 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) {

package/src/extension-templates.ts

@@ -5,7 +5,7 @@ export const PLUGIN_TEMPLATES: readonly ExtensionTemplate[] = [
   {
     path: 'src/plugin.tsx',
     contents:
-      "import { definePlugin } from '@meith/plugin-kit'\n\nexport const __MEITH_EXTENSION_CAMEL__Plugin = definePlugin({\n  key: '__MEITH_EXTENSION_KEY__',\n  name: '__MEITH_EXTENSION_TITLE__',\n  version: '0.1.0',\n  description:\n    'A plugin scaffolded by create-meith: a footer link, a greeting ' +\n    'on the board index, one setting, one migration, one task and an admin page.',\n  apiVersion: '0',\n\n  settings: [\n    {\n      key: 'greeting',\n      label: 'Greeting',\n      default: 'A greeting from the __MEITH_EXTENSION_TITLE__ plugin!',\n      description: 'Shown on the status page under Admin → Plugins → __MEITH_EXTENSION_TITLE__.',\n    },\n  ],\n\n  migrations: [\n    {\n      id: '0001_create_wave_table',\n      statements: [\n        `create table if not exists plugin___MEITH_EXTENSION_SNAKE___wave (\n           id integer generated by default as identity primary key,\n           waved_at timestamptz not null default now()\n         )`,\n      ],\n    },\n  ],\n\n  tasks: [\n    {\n      id: 'wave',\n      intervalSeconds: 3600,\n      run: (context) => {\n        context.logger.info('__MEITH_EXTENSION_KEY__ plugin: waving', {\n          greeting: context.settings.greeting,\n        })\n      },\n    },\n  ],\n\n  adminPages: [\n    {\n      path: 'status',\n      title: '__MEITH_EXTENSION_TITLE__ plugin',\n      render: (context) => (\n        <div className=\"flex flex-col gap-2 text-sm\">\n          <p>{String(context.settings.greeting)}</p>\n          <p className=\"text-muted-foreground\">\n            This page is rendered by the plugin itself. Edit the greeting on the plugin&rsquo;s\n            settings screen and reload to see the resolved value arrive in{' '}\n            <code className=\"text-xs\">context.settings</code>.\n          </p>\n        </div>\n      ),\n    },\n  ],\n\n  contributions: [\n    {\n      region: 'index.footer',\n      render: (context) => (\n        <p className=\"text-xs text-muted-foreground\" data-plugin=\"__MEITH_EXTENSION_KEY__\">\n          {context.viewer.isGuest\n            ? 'Greetings, guest — this line comes from the __MEITH_EXTENSION_TITLE__ plugin.'\n            : 'Greetings, member — this line comes from the __MEITH_EXTENSION_TITLE__ plugin.'}\n        </p>\n      ),\n    },\n  ],\n\n  hooks: {\n    'view.footer': (footer) => ({\n      ...footer,\n      links: [\n        ...footer.links,\n        {\n          label: '__MEITH_EXTENSION_TITLE__ plugin',\n          href: '__MEITH_EXTENSION_REPOSITORY__',\n        },\n      ],\n    }),\n\n    'post.created': () => {},\n  },\n})\n",
+      "import { definePlugin } from '@meith/plugin-kit'\n\nexport const __MEITH_EXTENSION_CAMEL__Plugin = definePlugin({\n  key: '__MEITH_EXTENSION_KEY__',\n  name: '__MEITH_EXTENSION_TITLE__',\n  version: '0.1.0',\n  description:\n    'A plugin scaffolded by create-meith: a footer link, a greeting ' +\n    'on the board index, one setting, one migration, one task and an admin page.',\n  apiVersion: '0',\n\n  settings: [\n    {\n      key: 'greeting',\n      label: 'Greeting',\n      default: 'A greeting from the __MEITH_EXTENSION_TITLE__ plugin!',\n      description: 'Shown on the status page under Admin → Plugins → __MEITH_EXTENSION_TITLE__.',\n    },\n  ],\n\n  migrations: [\n    {\n      id: '0001_create_wave_table',\n      statements: [\n        `create table if not exists plugin___MEITH_EXTENSION_SNAKE___wave (\n           id integer generated by default as identity primary key,\n           waved_at timestamptz not null default now()\n         )`,\n      ],\n    },\n  ],\n\n  tasks: [\n    {\n      id: 'wave',\n      intervalSeconds: 3600,\n      run: (context) => {\n        context.logger.info('__MEITH_EXTENSION_KEY__ plugin: waving', {\n          greeting: context.settings.greeting,\n        })\n      },\n    },\n  ],\n\n  adminPages: [\n    {\n      path: 'status',\n      title: '__MEITH_EXTENSION_TITLE__ plugin',\n      render: (context) => (\n        <div className=\"flex flex-col gap-2 text-sm\">\n          <p>{String(context.settings.greeting)}</p>\n          <p className=\"text-muted-foreground\">\n            This page is rendered by the plugin itself. Edit the greeting on the plugin&rsquo;s\n            settings screen and reload to see the resolved value arrive in{' '}\n            <code className=\"text-xs\">context.settings</code>.\n          </p>\n        </div>\n      ),\n    },\n  ],\n\n  contributions: [\n    {\n      region: 'index.footer',\n      render: (context) => {\n        const key = context.viewer.isGuest ? '__MEITH_EXTENSION_KEY__.footer.guest' : '__MEITH_EXTENSION_KEY__.footer.member'\n        const fallback = context.viewer.isGuest\n          ? 'Greetings, guest — this line comes from the __MEITH_EXTENSION_TITLE__ plugin.'\n          : 'Greetings, member — this line comes from the __MEITH_EXTENSION_TITLE__ plugin.'\n        return (\n          <p className=\"text-xs text-muted-foreground\" data-plugin=\"__MEITH_EXTENSION_KEY__\">\n            {context.t.has(key) ? context.t.t(key) : fallback}\n          </p>\n        )\n      },\n    },\n  ],\n\n  hooks: {\n    'view.footer': (footer) => ({\n      ...footer,\n      links: [\n        ...footer.links,\n        {\n          label: '__MEITH_EXTENSION_TITLE__ plugin',\n          href: '__MEITH_EXTENSION_REPOSITORY__',\n        },\n      ],\n    }),\n\n    'post.created': () => {},\n  },\n})\n",
   },
   {
     path: 'src/plugin.test.ts',

package/src/index.ts

@@ -26,3 +26,22 @@ export {
   scaffoldTheme,
   validateExtensionName,
 } from './scaffold-extension'
+export {
+  compareExactVersions,
+  fetchPreviousTree,
+  mergeManifest,
+  normalizeActionPins,
+  parseExactVersion,
+  planUpdate,
+  RELEASE_NOTES_URL,
+  type RunUpdateOptions,
+  runUpdate,
+  substituteBoardName,
+  TEMPLATE_BOARD_NAME,
+  TEMPLATE_REPOSITORIES,
+  templateTarballUrl,
+  type UpdateInputs,
+  type UpdatePlan,
+  type UpdateResult,
+  unpackTemplateTarball,
+} from './update'

package/src/scaffold.ts

@@ -149,6 +149,19 @@ const ENV_SMTP_MAIL_BLOCK = `# Mail. Leave these alone and the installer asks fo
 # MAIL_SMTP_PASSWORD=
 # MAIL_FROM=noreply@yourdomain.com`
 
+const 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 — 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: string): string {
   return `# ${name} — environment.
 #
@@ -179,6 +192,8 @@ APP_URL=
 
 ${ENV_SMTP_MAIL_BLOCK}
 
+${ENV_BACKUP_BLOCK}
+
 `
 }
 
@@ -350,7 +365,6 @@ function envExample(name: string, target: ScaffoldTarget): string {
 
 const SELF_HOST_DEPLOY_KIT = [
   '.dockerignore',
-  '.github/dependabot.yml',
   '.github/workflows/build.yml',
   'Dockerfile',
   'Dockerfile.prebuilt',
@@ -547,9 +561,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 — see README.md, "Upgrading" — 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 — see README.md, "Upgrading" —
+# 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
@@ -562,6 +577,83 @@ updates:
 `,
   )
 
+  files.set(
+    '.github/workflows/update.yml',
+    `# Opens a pull request whenever a new Meith release is out — 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 → Actions → General, enable "Allow GitHub
+# Actions to create and approve pull requests" — 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 — 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 — 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 — 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 — 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(
     'Dockerfile',
     `# syntax=docker/dockerfile:1.7-labs
@@ -980,8 +1072,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 — 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
@@ -1017,6 +1125,7 @@ services:
 volumes:
   pgdata:
   uploads:
+  backups:
 `,
   )
 
@@ -1113,8 +1222,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 — 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
@@ -1150,6 +1275,7 @@ services:
 volumes:
   pgdata:
   uploads:
+  backups:
 `,
   )
 
@@ -1336,27 +1462,52 @@ for the full guide.
 
 ## Upgrading
 
+\`.github/workflows/update.yml\` does this for you: once a week — and
+whenever you press **Run workflow** on the Actions tab — 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 → Actions → 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 — 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 — 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 — \`.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 — 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 —
+\`.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
@@ -1607,20 +1758,38 @@ each retry into another attempt against whatever it is failing against.
 
 ## Upgrading
 
+\`.github/workflows/update.yml\` does this for you: once a week — and
+whenever you press **Run workflow** on the Actions tab — 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 → Actions → 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 — Vercel
-reads that pin to pick its Next.js builder — 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 — 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.