create-meith 0.21.2 → 0.22.0

package/dist/bin.mjs

@@ -99,8 +99,12 @@ var ENV_AUTH_SECRET_PROSE = `# Session and token signing. No default, deliberate
 var ENV_TICK_SECRET_PROSE = `# The shared secret the tick caller presents to GET /api/system/tick. Generate
 # it the same way. Without it the tick is unauthenticated, and the tick is how
 # bans expire and digests send.`;
-var ENV_DATA_SOURCE_PROSE = `# fixture = deterministic in-memory sample data, no database needed. This is
-# what \`npm run build\` uses, and what a checkout with no database falls back to.`;
+var ENV_DATA_SOURCE_PROSE = `# Derived, and left commented out on purpose: with no DATABASE_URL the board
+# serves \`fixture\` \u2014 deterministic in-memory sample data, no database needed,
+# which is what \`npm run build\` uses and what \`npm run dev\` falls back to \u2014 and
+# with one it serves \`postgres\`. Setting it to postgres while DATABASE_URL is
+# still blank is refused at boot, so uncomment it only to override the
+# derivation.`;
 var ENV_APP_URL_PROSE = `# Absolute, no trailing slash. Used in mail, feeds and canonical URLs \u2014 every
 # place a relative URL cannot work because there is no request to be relative to.
 #
@@ -144,7 +148,7 @@ TICK_SECRET=
 ${ENV_OPTIONAL_HEADING}
 
 ${ENV_DATA_SOURCE_PROSE}
-DATA_SOURCE=postgres
+# DATA_SOURCE=postgres
 
 ${ENV_APP_URL_PROSE}
 APP_URL=
@@ -432,7 +436,7 @@ save-exact=true
  *
  * Adding a theme is: \`npm install\` it, add a line here, redeploy. Adding a
  * plugin is the same, through board.plugins.json and community.plugins.ts \u2014
- * see docs/plugin-api.md.
+ * see docs/customization/plugins.md.
  */
 import { defineForumConfig } from '@meith/web/config'
 import {
@@ -470,7 +474,7 @@ export default defineForumConfig({
  * The board's installed-plugin list.
  *
  * Inside the Meith monorepo this file is generated from board.plugins.json
- * by \`pnpm board:gen\` (see docs/plugin-api.md) \u2014 that generator is
+ * by \`pnpm board:gen\` (see docs/customization/plugins.md) \u2014 that generator is
  * repository tooling, not something this workspace carries, so this file
  * starts as a plain, valid file with the same shape instead. Add a plugin by
  * importing its \`plugin\`/\`messages\` exports and adding an entry:
@@ -517,7 +521,7 @@ export function installedPluginDefinitions() {
 #
 # FROM the published framework base image \u2014 deps + framework layers only,
 # locked to this exact release (see the meith repository's
-# docs/self-hosting.md, "Custom boards", and docker/Dockerfile.base for what
+# docs/getting-started/deployment/docker-compose.md, "Custom boards", and docker/Dockerfile.base for what
 # it is and is not). This board's own Dockerfile only ever installs its own
 # delta on top of it \u2014 a new plugin's own dependency, typically nothing more
 # \u2014 which is what keeps a rebuild after \`npm install some-plugin\` a matter
@@ -527,12 +531,12 @@ export function installedPluginDefinitions() {
 # to Next's own standalone output. The migrate role below runs \`community
 # migrate\`, and \`community\` materializes @meith/cli's sources and runs them
 # with tsx at the moment it runs (see the meith repository's
-# docs/development.md, "Consuming the board from a workspace") \u2014 it needs
+# docs/contributing/development.md, "Consuming the board from a workspace") \u2014 it needs
 # the full, un-pruned node_modules tree this board installed, not what Next
 # traced as reachable from the web server alone. The tick itself is driven
 # by docker-compose.yml's own \`worker\` service \u2014 a lightweight loop against
 # /api/system/tick, not a compiled worker process, because @meith/worker is
-# not published (see the meith repository's docs/release.md).
+# not published (see the meith repository's docs/contributing/release.md).
 ARG MEITH_VERSION
 FROM ghcr.io/meith-dev/meith-base:\${MEITH_VERSION} AS deps
 WORKDIR /board
@@ -557,7 +561,7 @@ ENV NODE_ENV=production
 # persists into every container started from this image afterward, and this
 # Dockerfile has no later stage to reset it in (see "Two stages, not three"
 # above). The build needs neither a database nor a production secret (see
-# the meith repository's docs/development.md, "Fixture mode"), but baking
+# the meith repository's docs/contributing/development.md, "Fixture mode"), but baking
 # DATA_SOURCE=fixture into the image itself would silently force fixture
 # mode \u2014 and with it the in-memory queue driver \u2014 at runtime too, no matter
 # what DATABASE_URL an operator supplies to \`docker run\`.
@@ -794,9 +798,9 @@ services:
         condition: service_completed_successfully
 
   # @meith/worker is not published (see the meith repository's
-  # docs/release.md), so there is no compiled worker binary a scaffolded
+  # docs/contributing/release.md), so there is no compiled worker binary a scaffolded
   # board can run \u2014 this drives the tick the alternative way the meith
-  # repository documents in docs/self-hosting.md, "Running the tick without
+  # repository documents in docs/getting-started/deployment/docker-compose.md, "Running the tick without
   # a second set of credentials": a small loop calling /api/system/tick.
   worker:
     image: alpine:3.24@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b
@@ -866,7 +870,7 @@ one value only you know:
 
 3. **Deploy, then \`/install\` on your own domain.** Coolify issues the
    certificate; the installer from there is the one
-   [docs/quickstart.md](${repositoryUrl}/blob/main/docs/quickstart.md#4-run-the-installer)
+   [docs/getting-started/deployment/coolify.md](${repositoryUrl}/blob/main/docs/getting-started/deployment/coolify.md#4-run-the-installer)
    walks through, screen for screen. It seals itself when it finishes, and
    \`/install\` answers 404 from then on \u2014 run it **against the database you
    are going to keep**. Every push to \`main\` after this rebuilds the
@@ -884,7 +888,7 @@ rather not use GitHub Actions for the build \u2014 push the result wherever
 docker build --build-arg MEITH_VERSION=$(node -p "require('./package.json').dependencies['@meith/web']") -t ${name} .
 \`\`\`
 
-**Without a panel**: [docs/self-hosting.md](${repositoryUrl}/blob/main/docs/self-hosting.md)
+**Without a panel**: [docs/getting-started/deployment/docker-compose.md](${repositoryUrl}/blob/main/docs/getting-started/deployment/docker-compose.md)
 is the same four containers by hand \u2014 your own \`.env\`, a reverse proxy you
 already run, no Coolify. \`Dockerfile\` and \`docker-compose.yml\` here are this
 board's own version of exactly that shape.
@@ -904,12 +908,15 @@ Two things nothing configures for you:
 
 \`\`\`sh
 npm install
-cp .env.example .env.local
 npm run dev
 \`\`\`
 
-With no \`DATABASE_URL\`, the board runs on deterministic in-memory sample data \u2014
-enough to click through every reading surface. Posting needs a database:
+No environment file, no database: with no \`DATABASE_URL\` the board serves
+deterministic in-memory sample data, which is enough to click through every
+reading surface.
+
+Posting needs Postgres. Copy \`.env.example\` to \`.env.local\`, set
+\`DATABASE_URL\` and the two secrets in it, then:
 
 \`\`\`sh
 npm run community -- migrate
@@ -957,7 +964,7 @@ project's own \`.npmrc\` sets \`save-exact=true\` for the same reason, so an
 build workflow also refuses to build from anything but an exact version, as
 a second line of defense. Once the rebuilt image is deployed, run
 \`npm run community -- upgrade\` against it for the plugin migrations \u2014 see
-[the operator CLI](${repositoryUrl}/blob/main/docs/operating.md#the-operator-cli)
+[the operator CLI](${repositoryUrl}/blob/main/docs/guides/operations/operating.md#the-operator-cli)
 for running it against this deployment.
 
 Migrations are forward-only. Recovery is by restore, so take a backup first \u2014
@@ -1130,7 +1137,7 @@ the board's name and address and for the first administrator's username, email
 and password, creates the board and that account, and then **seals itself**:
 \`/install\` answers 404 from then on. Run it against the database you intend to
 keep \u2014 the screens are the ones
-[docs/quickstart.md](${repositoryUrl}/blob/main/docs/quickstart.md#4-run-the-installer)
+[docs/getting-started/deployment/docker-compose.md](${repositoryUrl}/blob/main/docs/getting-started/deployment/docker-compose.md#6-install-it)
 walks through.
 
 ## The tick
@@ -1246,16 +1253,486 @@ one.
 ## Somewhere other than Vercel
 
 Everything above is one deployment shape.
-[docs/self-hosting.md](${repositoryUrl}/blob/main/docs/self-hosting.md) is the
+[docs/getting-started/deployment/docker-compose.md](${repositoryUrl}/blob/main/docs/getting-started/deployment/docker-compose.md) is the
 same board as containers you run yourself, and \`npx create-meith <name>\`
 scaffolds that shape instead \u2014 a Dockerfile, a compose file and a workflow that
-builds the image. [docs/scaling.md](${repositoryUrl}/blob/main/docs/scaling.md)
+builds the image. [docs/guides/operations/scaling.md](${repositoryUrl}/blob/main/docs/guides/operations/scaling.md)
 explains why the drivers above are what they are, and why an S3-compatible
 bucket is the portable choice for uploads everywhere but here.
 `;
 }
 function nextSteps(name) {
-  return [`cd ${name}`, "npm install", "cp .env.example .env.local", "npm run dev"];
+  return [`cd ${name}`, "npm install", "npm run dev"];
+}
+
+// src/extension-templates.ts
+var PLUGIN_TEMPLATES = [
+  {
+    path: "src/plugin.tsx",
+    contents: `import { definePlugin } from '@meith/plugin-kit'
+
+export const __MEITH_EXTENSION_CAMEL__Plugin = definePlugin({
+  key: '__MEITH_EXTENSION_KEY__',
+  name: '__MEITH_EXTENSION_TITLE__',
+  version: '0.1.0',
+  description:
+    'A plugin scaffolded by create-meith: a footer link, a greeting ' +
+    'on the board index, one setting, one migration, one task and an admin page.',
+  apiVersion: '0',
+
+  settings: [
+    {
+      key: 'greeting',
+      label: 'Greeting',
+      default: 'A greeting from the __MEITH_EXTENSION_TITLE__ plugin!',
+      description: 'Shown on the status page under Admin \u2192 Plugins \u2192 __MEITH_EXTENSION_TITLE__.',
+    },
+  ],
+
+  migrations: [
+    {
+      id: '0001_create_wave_table',
+      statements: [
+        \`create table if not exists plugin___MEITH_EXTENSION_SNAKE___wave (
+           id integer generated by default as identity primary key,
+           waved_at timestamptz not null default now()
+         )\`,
+      ],
+    },
+  ],
+
+  tasks: [
+    {
+      id: 'wave',
+      intervalSeconds: 3600,
+      run: (context) => {
+        context.logger.info('__MEITH_EXTENSION_KEY__ plugin: waving', {
+          greeting: context.settings.greeting,
+        })
+      },
+    },
+  ],
+
+  adminPages: [
+    {
+      path: 'status',
+      title: '__MEITH_EXTENSION_TITLE__ plugin',
+      render: (context) => (
+        <div className="flex flex-col gap-2 text-sm">
+          <p>{String(context.settings.greeting)}</p>
+          <p className="text-muted-foreground">
+            This page is rendered by the plugin itself. Edit the greeting on the plugin&rsquo;s
+            settings screen and reload to see the resolved value arrive in{' '}
+            <code className="text-xs">context.settings</code>.
+          </p>
+        </div>
+      ),
+    },
+  ],
+
+  contributions: [
+    {
+      region: 'index.footer',
+      render: (context) => (
+        <p className="text-xs text-muted-foreground" data-plugin="__MEITH_EXTENSION_KEY__">
+          {context.viewer.isGuest
+            ? 'Greetings, guest \u2014 this line comes from the __MEITH_EXTENSION_TITLE__ plugin.'
+            : 'Greetings, member \u2014 this line comes from the __MEITH_EXTENSION_TITLE__ plugin.'}
+        </p>
+      ),
+    },
+  ],
+
+  hooks: {
+    'view.footer': (footer) => ({
+      ...footer,
+      links: [
+        ...footer.links,
+        {
+          label: '__MEITH_EXTENSION_TITLE__ plugin',
+          href: '__MEITH_EXTENSION_REPOSITORY__',
+        },
+      ],
+    }),
+
+    'post.created': () => {},
+  },
+})
+`
+  },
+  {
+    path: "src/plugin.test.ts",
+    contents: "import { describe, expect, it } from 'vitest'\n\nimport { type FilterHandler, unavailableHookRuntime } from '@meith/plugin-kit'\n\nimport { __MEITH_EXTENSION_CAMEL__Plugin } from './plugin'\n\ndescribe('the __MEITH_EXTENSION_KEY__ plugin', () => {\n  it('has a validated manifest (definePlugin threw at import time otherwise)', () => {\n    expect(__MEITH_EXTENSION_CAMEL__Plugin.key).toBe('__MEITH_EXTENSION_KEY__')\n    expect(__MEITH_EXTENSION_CAMEL__Plugin.version).toBe('0.1.0')\n  })\n\n  it('appends its footer link without disturbing the board\u2019s own', () => {\n    const filter = __MEITH_EXTENSION_CAMEL__Plugin.hooks?.['view.footer'] as FilterHandler<'view.footer'>\n    const footer = {\n      boardTitle: 'A board',\n      links: [{ label: 'Contact', href: '/contact' }],\n      timezoneLabel: 'Europe/Dublin',\n    }\n\n    const filtered = filter(\n      footer,\n      { userId: null, isGuest: true, requestId: null },\n      unavailableHookRuntime('this test drives the filter directly'),\n    )\n\n    expect(filtered).toMatchObject({\n      boardTitle: 'A board',\n      links: [\n        { label: 'Contact', href: '/contact' },\n        { label: '__MEITH_EXTENSION_TITLE__ plugin', href: expect.stringContaining('__MEITH_EXTENSION_REPOSITORY__') },\n      ],\n    })\n    expect(footer.links).toHaveLength(1)\n  })\n})\n"
+  }
+];
+var THEME_TEMPLATES = [
+  {
+    path: "src/index.ts",
+    contents: "export { __MEITH_EXTENSION_CAMEL__Theme } from './theme'\nexport { BROWSER_THEME_COLOR, DARK_TOKENS, LIGHT_TOKENS } from './tokens'\n"
+  },
+  {
+    path: "src/theme.ts",
+    contents: "import { defaultTheme } from '@meith/theme-default'\nimport { defineTheme } from '@meith/theme-kit'\n\nimport { Footer } from './slots/footer'\n\nexport const __MEITH_EXTENSION_CAMEL__Theme = defineTheme({\n  key: '__MEITH_EXTENSION_KEY__',\n  title: '__MEITH_EXTENSION_TITLE__',\n  extends: defaultTheme,\n  slots: { Footer },\n})\n"
+  },
+  {
+    path: "src/tokens.ts",
+    contents: "import { DARK_TOKENS as DEFAULT_DARK, LIGHT_TOKENS as DEFAULT_LIGHT } from '@meith/theme-default'\n\nexport const LIGHT_TOKENS: Record<string, string> = {\n  ...DEFAULT_LIGHT,\n  primary: 'oklch(0.49 0.19 300)',\n  'primary-hover': 'oklch(0.42 0.17 300)',\n  ring: 'oklch(0.49 0.19 300)',\n}\n\nexport const DARK_TOKENS: Record<string, string> = {\n  ...DEFAULT_DARK,\n  primary: 'oklch(0.78 0.12 300)',\n  'primary-foreground': 'oklch(0.18 0.03 300)',\n  'primary-hover': 'oklch(0.84 0.11 300)',\n  ring: 'oklch(0.78 0.12 300)',\n}\n\nexport { BROWSER_THEME_COLOR } from '@meith/theme-default'\n"
+  },
+  {
+    path: "src/slots/footer.tsx",
+    contents: `import type { FooterModel } from '@meith/theme-kit'
+
+export function Footer({ boardTitle, links, timezoneLabel, poweredBy }: FooterModel) {
+  return (
+    <footer className="mt-auto border-t-2 border-primary bg-card">
+      <div className="mx-auto flex w-full max-w-5xl flex-col items-center gap-2 px-4 py-6 text-center text-xs text-muted-foreground">
+        <span className="font-semibold uppercase tracking-widest text-foreground">
+          {boardTitle}
+        </span>
+
+        {links.length > 0 && (
+          <nav aria-label="Footer" className="flex flex-wrap justify-center gap-x-4 gap-y-1">
+            {links.map((link) => (
+              <a
+                key={link.href}
+                href={link.href}
+                className="underline decoration-primary underline-offset-2 hover:text-foreground"
+              >
+                {link.label}
+              </a>
+            ))}
+          </nav>
+        )}
+
+        <span>
+          Times are shown in {timezoneLabel}
+          {poweredBy && (
+            <>
+              {' \u2014 '}
+              <a
+                href={poweredBy.href}
+                className="underline decoration-primary underline-offset-2 hover:text-foreground"
+              >
+                {poweredBy.label}
+              </a>
+            </>
+          )}
+        </span>
+      </div>
+    </footer>
+  )
+}
+`
+  },
+  {
+    path: "src/theme.test.ts",
+    contents: "import { describe, expect, it } from 'vitest'\n\nimport { defaultTheme, TOKEN_NAMES } from '@meith/theme-default'\nimport { assertThemeContract, resolveTheme } from '@meith/theme-kit'\n\nimport { __MEITH_EXTENSION_CAMEL__Theme } from './theme'\nimport { DARK_TOKENS, LIGHT_TOKENS } from './tokens'\n\ndescribe('the __MEITH_EXTENSION_KEY__ theme', () => {\n  it('satisfies the theme-kit contract', () => {\n    expect(assertThemeContract(resolveTheme(__MEITH_EXTENSION_CAMEL__Theme)).missing).toEqual([])\n  })\n\n  it('inherits from the default theme rather than copying it', () => {\n    expect(resolveTheme(__MEITH_EXTENSION_CAMEL__Theme).chain).toEqual(['__MEITH_EXTENSION_KEY__', 'default'])\n  })\n\n  it('overrides exactly one slot: the footer', () => {\n    expect(Object.keys(__MEITH_EXTENSION_CAMEL__Theme.slots)).toEqual(['Footer'])\n    expect(__MEITH_EXTENSION_CAMEL__Theme.slots.Footer).not.toBe(defaultTheme.slots.Footer)\n  })\n\n  it('declares a value for every token the theme layer names', () => {\n    for (const name of TOKEN_NAMES) {\n      expect(LIGHT_TOKENS[name], `light ${name}`).toBeDefined()\n      expect(DARK_TOKENS[name], `dark ${name}`).toBeDefined()\n    }\n  })\n\n  it('recolours the brand group and nothing greyscale', () => {\n    expect(LIGHT_TOKENS.primary).not.toBe(DARK_TOKENS.primary)\n    expect(LIGHT_TOKENS.background).toBe('oklch(0.968 0 0)')\n    expect(DARK_TOKENS.background).toBe('oklch(0.15 0 0)')\n  })\n})\n"
+  }
+];
+
+// src/scaffold-extension.ts
+var EXTENSION_KEY_PATTERN = /^[a-z][a-z0-9-]{1,39}$/;
+function validateExtensionName(name) {
+  if (name === "") return "An extension name is required.";
+  if (!EXTENSION_KEY_PATTERN.test(name)) {
+    return "Use lower-case letters, digits and hyphens, starting with a letter, 2 to 40 characters \u2014 the name becomes the definePlugin/defineTheme key and the npm package name.";
+  }
+  return null;
+}
+function extensionTitle(name) {
+  return name.split("-").filter((word) => word !== "").map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`).join(" ");
+}
+function extensionCamel(name) {
+  const words = name.split("-").filter((word) => word !== "");
+  const [head, ...rest] = words;
+  return `${head ?? ""}${rest.map((word) => `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`).join("")}`;
+}
+function extensionSnake(name) {
+  return name.replace(/-/g, "_");
+}
+function defaultExtensionRepositoryUrl(name) {
+  return `https://github.com/your-name/${name}`;
+}
+function meithRange(version) {
+  const [major = "0", minor = "0"] = version.split(".");
+  return `>=${major}.${minor} <${Number(major) + 1}`;
+}
+function substitute(contents, values) {
+  return contents.replaceAll("__MEITH_EXTENSION_CAMEL__", values.camel).replaceAll("__MEITH_EXTENSION_SNAKE__", values.snake).replaceAll("__MEITH_EXTENSION_REPOSITORY__", values.repositoryUrl).replaceAll("__MEITH_EXTENSION_KEY__", values.key).replaceAll("__MEITH_EXTENSION_TITLE__", values.title);
+}
+function extensionManifest(options, repositoryUrl, description, dependencies) {
+  return `${JSON.stringify(
+    {
+      name: options.name,
+      version: "0.1.0",
+      description,
+      license: "MIT",
+      repository: { type: "git", url: repositoryUrl },
+      type: "module",
+      main: "./src/index.ts",
+      types: "./src/index.ts",
+      files: ["src", "!src/**/*.test.*"],
+      scripts: { test: "vitest run", typecheck: "tsc --noEmit" },
+      dependencies,
+      peerDependencies: { react: "^19.2.0" },
+      devDependencies: {
+        "@types/node": "^26.2.0",
+        "@types/react": "^19.2.18",
+        react: "^19.2.0",
+        typescript: "^7.0.2",
+        vitest: "^4.1.10"
+      },
+      publishConfig: { access: "public" }
+    },
+    null,
+    2
+  )}
+`;
+}
+function extensionTsconfig() {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        target: "es2022",
+        lib: ["es2022", "dom"],
+        module: "esnext",
+        moduleResolution: "bundler",
+        jsx: "react-jsx",
+        strict: true,
+        resolveJsonModule: true,
+        skipLibCheck: true,
+        noEmit: true
+      },
+      include: ["src"]
+    },
+    null,
+    2
+  )}
+`;
+}
+function extensionVitestConfig() {
+  return `import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: { environment: 'node' },
+})
+`;
+}
+function extensionGitignore() {
+  return `node_modules
+*.log
+.DS_Store
+`;
+}
+function listing(options, kind, repositoryUrl, description) {
+  return `${JSON.stringify(
+    {
+      key: options.name,
+      kind,
+      package: options.name,
+      name: extensionTitle(options.name),
+      description,
+      screenshots: [`${options.name}-light.png`],
+      version: "0.1.0",
+      apiVersion: 0,
+      meith: meithRange(options.version),
+      repository: repositoryUrl,
+      licence: "MIT"
+    },
+    null,
+    2
+  )}
+`;
+}
+function pluginReadme(options, camel, title) {
+  const { name } = options;
+  return `# ${title}
+
+A Meith plugin, scaffolded by \`create-meith\` from the meith repository's
+\`examples/hello-plugin\`: a footer link, a greeting on the board index, one
+setting, one migration, one task and an admin page \u2014 every extension point
+exercised once, each easy to delete.
+
+## Develop
+
+    npm install
+    npm test
+
+\`src/plugin.tsx\` is the plugin. What a plugin may and may not do is
+documented in the meith repository under \`docs/customization/plugins.md\`;
+every hook and payload is listed in \`docs/reference/plugin-hooks.md\`.
+
+## Run it inside a board
+
+Scaffold a board next to this directory if you do not have one
+(\`npx create-meith my-board\`), then install this workspace into it by path:
+
+    cd ../my-board
+    npm install ../${name}
+
+npm installs a local directory as a symlink, so edits here are picked up by
+the board's next build without reinstalling.
+
+Register the plugin in the board's \`community.plugins.ts\` \u2014 the comment at
+the top of that file shows the shape:
+
+    import { messages as ${camel}Messages, plugin as ${camel}Plugin } from '${name}'
+
+    export const INSTALLED_PLUGINS: readonly InstalledPlugin[] = [
+      { key: '${name}', enabled: true, plugin: ${camel}Plugin, messages: ${camel}Messages },
+    ]
+
+and add the matching entry to \`board.plugins.json\`:
+
+    { "plugins": [{ "key": "${name}", "package": "${name}", "enabled": true }] }
+
+Rebuild the board (\`npm run build\`) and, because this plugin ships a
+migration, run \`npx community migrate\`. The plugin then appears under
+**Admin \u2192 Plugins**.
+
+## Publish and list it
+
+\`npm publish\` ships \`src/\` as TypeScript source, the way every
+\`@meith/*\` package ships. To offer the plugin on the meith.dev marketplace,
+finish \`listing.json\` (its \`repository\` field starts as a placeholder),
+add the screenshot it names, and open a pull request against the meith
+repository \u2014 the submission process and the review bar are documented there
+in \`docs/customization/marketplace.md\`.
+`;
+}
+function themeReadme(options, camel, title) {
+  const { name } = options;
+  return `# ${title}
+
+A Meith theme, scaffolded by \`create-meith\` from the meith repository's
+\`examples/iris-theme\`: the default theme recoloured (one brand group of
+tokens) plus a single slot override, the footer.
+
+## Develop
+
+    npm install
+    npm test
+
+\`src/theme.ts\` declares the theme, \`src/tokens.ts\` carries the palette,
+and slots live in \`src/slots/\`. What a theme may and may not do is
+documented in the meith repository under \`docs/customization/themes.md\`;
+every slot and view model is listed in \`docs/reference/theme-slots.md\`.
+
+## Run it inside a board
+
+Scaffold a board next to this directory if you do not have one
+(\`npx create-meith my-board\`), then install this workspace into it by path:
+
+    cd ../my-board
+    npm install ../${name}
+
+npm installs a local directory as a symlink, so edits here are picked up by
+the board's next build without reinstalling.
+
+Register the theme in the board's \`community.config.ts\`, beside the
+default entry:
+
+    import { defaultMessages } from '@meith/theme-default'
+    import { BROWSER_THEME_COLOR, DARK_TOKENS, LIGHT_TOKENS, ${camel}Theme } from '${name}'
+
+    themes: {
+      '${name}': {
+        key: '${name}',
+        title: '${title}',
+        tokens: { light: LIGHT_TOKENS, dark: DARK_TOKENS },
+        browserThemeColor: BROWSER_THEME_COLOR,
+        theme: ${camel}Theme,
+        messages: defaultMessages,
+      },
+    },
+
+Rebuild the board (\`npm run build\`); the theme is then offered to members
+on the appearance screen and to administrators under **Admin \u2192 Themes**.
+
+## Publish and list it
+
+\`npm publish\` ships \`src/\` as TypeScript source, the way every
+\`@meith/*\` package ships. To offer the theme on the meith.dev marketplace,
+finish \`listing.json\` (its \`repository\` field starts as a placeholder),
+add the screenshot it names, and open a pull request against the meith
+repository \u2014 the submission process and the review bar are documented there
+in \`docs/customization/marketplace.md\`.
+`;
+}
+function scaffoldPlugin(options) {
+  const key = options.name;
+  const title = extensionTitle(key);
+  const camel = extensionCamel(key);
+  const snake = extensionSnake(key);
+  const repositoryUrl = options.repositoryUrl ?? defaultExtensionRepositoryUrl(key);
+  const description = `${title} \u2014 a Meith plugin.`;
+  const files = /* @__PURE__ */ new Map();
+  files.set(
+    "package.json",
+    extensionManifest(options, repositoryUrl, description, {
+      "@meith/plugin-kit": options.version
+    })
+  );
+  files.set("tsconfig.json", extensionTsconfig());
+  files.set("vitest.config.ts", extensionVitestConfig());
+  files.set(".gitignore", extensionGitignore());
+  files.set("README.md", pluginReadme(options, camel, title));
+  files.set("listing.json", listing(options, "plugin", repositoryUrl, description));
+  files.set(
+    "src/index.ts",
+    `export { ${camel}Plugin, ${camel}Plugin as plugin } from './plugin'
+export { ${camel}Messages, ${camel}Messages as messages } from './messages'
+`
+  );
+  files.set(
+    "src/messages/index.ts",
+    `import en from './en.json'
+
+export const ${camel}Messages = { en }
+`
+  );
+  files.set("src/messages/en.json", "{}\n");
+  for (const template of PLUGIN_TEMPLATES) {
+    files.set(
+      template.path,
+      substitute(template.contents, { key, title, camel, snake, repositoryUrl })
+    );
+  }
+  return files;
+}
+function scaffoldTheme(options) {
+  const key = options.name;
+  const title = extensionTitle(key);
+  const camel = extensionCamel(key);
+  const snake = extensionSnake(key);
+  const repositoryUrl = options.repositoryUrl ?? defaultExtensionRepositoryUrl(key);
+  const description = `${title} \u2014 a Meith theme.`;
+  const files = /* @__PURE__ */ new Map();
+  files.set(
+    "package.json",
+    extensionManifest(options, repositoryUrl, description, {
+      "@meith/theme-default": options.version,
+      "@meith/theme-kit": options.version
+    })
+  );
+  files.set("tsconfig.json", extensionTsconfig());
+  files.set("vitest.config.ts", extensionVitestConfig());
+  files.set(".gitignore", extensionGitignore());
+  files.set("README.md", themeReadme(options, camel, title));
+  files.set("listing.json", listing(options, "theme", repositoryUrl, description));
+  for (const template of THEME_TEMPLATES) {
+    files.set(
+      template.path,
+      substitute(template.contents, { key, title, camel, snake, repositoryUrl })
+    );
+  }
+  return files;
+}
+function scaffoldExtension(kind, options) {
+  return kind === "plugin" ? scaffoldPlugin(options) : scaffoldTheme(options);
+}
+function extensionNextSteps(name) {
+  return [`cd ${name}`, "npm install", "npm test"];
 }
 
 // src/cli.ts
@@ -1291,20 +1768,34 @@ async function run(argv, version) {
     return {
       code: 0,
       lines: [
-        "create-meith \u2014 scaffold a forum project.",
+        "create-meith \u2014 scaffold a forum project, a plugin or a theme.",
         "",
         "  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]",
         "",
-        "Writes package.json, community.config.ts, .env.example, .gitignore and",
-        "README.md into ./<name>, then tells you what to run.",
+        "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.",
         "",
         "--no-git skips initializing a git repository in the new directory."
       ]
     };
   }
-  const invalid = validateName(name);
+  const wantsPlugin = argv.includes("--plugin");
+  const wantsTheme = argv.includes("--theme");
+  if (wantsPlugin && wantsTheme) {
+    return {
+      code: 1,
+      lines: ["create-meith: --plugin and --theme are two different scaffolds \u2014 pass one."]
+    };
+  }
+  const kind = wantsPlugin ? "plugin" : wantsTheme ? "theme" : null;
+  const usage = kind === null ? "Usage: npx create-meith <name>" : `Usage: npx create-meith --${kind} <name>`;
+  const invalid = kind === null ? validateName(name) : validateExtensionName(name);
   if (invalid !== null) {
-    return { code: 1, lines: [`create-meith: ${invalid}`, "", "Usage: npx create-meith <name>"] };
+    return { code: 1, lines: [`create-meith: ${invalid}`, "", usage] };
   }
   const repoIndex = argv.indexOf("--repo");
   const repositoryUrl = repoIndex === -1 ? DEFAULT_REPOSITORY_URL : argv[repoIndex + 1] ?? DEFAULT_REPOSITORY_URL;
@@ -1318,7 +1809,11 @@ async function run(argv, version) {
       ]
     };
   }
-  const files = scaffold({ name, version, repositoryUrl });
+  const files = kind === null ? scaffold({ name, version, repositoryUrl }) : scaffoldExtension(kind, {
+    name,
+    version,
+    repositoryUrl: repoIndex === -1 ? void 0 : repositoryUrl
+  });
   for (const [relative, contents] of files) {
     const path = join(target, relative);
     await mkdir(dirname(path), { recursive: true });
@@ -1330,7 +1825,7 @@ async function run(argv, version) {
     lines: [
       `Created ${name} \u2014 ${files.size} files.`,
       "",
-      ...nextSteps(name).map((step) => `  ${step}`),
+      ...(kind === null ? nextSteps(name) : extensionNextSteps(name)).map((step) => `  ${step}`),
       "",
       ...gitReady ? [
         "Initialized a git repository here and staged every file. Commit it,",
@@ -1348,15 +1843,20 @@ async function run(argv, version) {
         "  git push -u origin main"
       ],
       "",
-      "Then set DATABASE_URL, AUTH_SECRET and TICK_SECRET and deploy.",
-      "Something must run the tick every minute \u2014 the worker process, or",
-      "`community task:run`. Without it nothing catches up, and nothing errors."
+      ...kind === null ? [
+        "Then set DATABASE_URL, AUTH_SECRET and TICK_SECRET and deploy.",
+        "Something must run the tick every minute \u2014 the worker process, or",
+        "`community task:run`. Without it nothing catches up, and nothing errors."
+      ] : [
+        `Then follow README.md \u2014 it walks through running the ${kind} inside a`,
+        "scaffolded board and submitting it to the meith.dev marketplace."
+      ]
     ]
   };
 }
 
 // src/bin.ts
-var result = await run(process.argv.slice(2), "0.21.2");
+var result = await run(process.argv.slice(2), "0.22.0");
 for (const line of result.lines) {
   if (result.code === 0) console.log(line);
   else console.error(line);