@meith/cli 0.17.0 → 0.17.2

package/bin/community.mjs

@@ -92,11 +92,13 @@ function materialize() {
   return join(srcTarget, 'index.ts')
 }
 
+/**
+ * Resolved from this package's own directory — `tsx` is `@meith/cli`'s
+ * dependency, found either hoisted to the workspace root or nested under
+ * this package's own `node_modules`, the same reasoning as forum-web's
+ * `resolveNextBin()`.
+ */
 function resolveTsx() {
-  // Resolved from this package's own directory — `tsx` is @meith/cli's
-  // dependency, found either hoisted to the workspace root or nested under
-  // this package's own node_modules, the same reasoning as forum-web's
-  // resolveNextBin().
   const require = createRequire(join(packageRoot, 'package.json'))
   try {
     return require.resolve('tsx/cli')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/cli",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "The operator CLI: migrations, backup and restore, imports, users and settings — and the community bin that runs it against an external board workspace.",
   "license": "LGPL-3.0-or-later",
   "repository": {
@@ -23,18 +23,18 @@
   },
   "dependencies": {
     "tsx": "^4.23.12",
-    "@meith/core": "0.17.0",
-    "@meith/accounts": "0.17.0",
-    "@meith/forums": "0.17.0",
-    "@meith/db": "0.17.0",
-    "@meith/demo": "0.17.0",
-    "@meith/drivers": "0.17.0",
-    "@meith/plugin-kit": "0.17.0",
-    "@meith/profile-fields": "0.17.0",
-    "@meith/runtime": "0.17.0",
-    "@meith/settings": "0.17.0",
-    "create-meith": "0.17.0",
-    "@meith/tasks": "0.17.0"
+    "@meith/accounts": "0.17.2",
+    "@meith/db": "0.17.2",
+    "@meith/drivers": "0.17.2",
+    "@meith/demo": "0.17.2",
+    "@meith/forums": "0.17.2",
+    "@meith/core": "0.17.2",
+    "@meith/plugin-kit": "0.17.2",
+    "@meith/profile-fields": "0.17.2",
+    "@meith/tasks": "0.17.2",
+    "@meith/runtime": "0.17.2",
+    "@meith/settings": "0.17.2",
+    "create-meith": "0.17.2"
   },
   "devDependencies": {
     "esbuild": "^0.28.2"

package/src/board-eject.ts

@@ -17,8 +17,12 @@ import { CODE_VERSION } from './upgrade'
  * bundled `dist/cli.cjs` does not sit at that same distance — Docker's own
  * `COPY apps/cli/dist/ ./apps/cli/` drops the `dist` segment.
  */
-const ROOT = fileURLToPath(new URL('../../../', import.meta.url))
-const DEFAULT_MANIFEST_PATH = join(ROOT, 'boards/stock/board.plugins.json')
+function defaultManifestPath(): string {
+  return join(
+    fileURLToPath(new URL('../../../', import.meta.url)),
+    'boards/stock/board.plugins.json',
+  )
+}
 
 interface ManifestEntry {
   readonly key: string
@@ -31,7 +35,81 @@ interface Manifest {
 }
 
 function manifestPath(): string {
-  return process.env.BOARD_PLUGINS_MANIFEST ?? DEFAULT_MANIFEST_PATH
+  return process.env.BOARD_PLUGINS_MANIFEST ?? defaultManifestPath()
+}
+
+/**
+ * Duplicated from scripts/board-plugins.mjs's own PLUGIN_KEY_PATTERN, IDENTIFIER_PATTERN
+ * and NPM_PACKAGE_NAME_PATTERN rather than imported — see docs/plugin-api.md, "The board
+ * plugin manifests" — and pinned to agree with it by board-eject.test.ts.
+ */
+const PLUGIN_KEY_PATTERN = /^[a-z][a-z0-9-]{1,39}$/
+const IDENTIFIER_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+const NPM_PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+
+/**
+ * The same shape of refusal scripts/board-plugins.mjs's validateManifest makes for
+ * apps/community and boards/stock, minus the dependency check — a deployed image
+ * carries no package.json listing what it was actually built with. A manifest that
+ * gets this far already passed that check once, when plugin:add wrote it; this is
+ * defense against a manifest hand-edited after the fact, not the primary gate.
+ */
+export function validateEjectManifest(plugins: readonly ManifestEntry[], path: string): void {
+  const seen = new Set<string>()
+  const identifiers = new Map<string, string>()
+
+  for (const entry of plugins) {
+    if (typeof entry.key !== 'string' || typeof entry.package !== 'string') {
+      throw new ValidationError(
+        `${path}: every entry needs a string "key" and "package". Got ${JSON.stringify(entry)}.`,
+      )
+    }
+
+    if (seen.has(entry.key)) {
+      throw new ValidationError(`${path}: "${entry.key}" is listed twice.`)
+    }
+    seen.add(entry.key)
+
+    if (!PLUGIN_KEY_PATTERN.test(entry.key)) {
+      throw new ValidationError(
+        `${path}: "${entry.key}" is not a valid plugin key. definePlugin requires lower-case ` +
+          'letters, digits and hyphens, starting with a letter, 2-40 characters long.',
+      )
+    }
+
+    if (entry.enabled !== undefined && typeof entry.enabled !== 'boolean') {
+      throw new ValidationError(
+        `${path}: "${entry.key}" has a non-boolean "enabled" (${JSON.stringify(entry.enabled)}). ` +
+          'Omit the field to enable the plugin, or set it to true or false.',
+      )
+    }
+
+    if (!NPM_PACKAGE_NAME_PATTERN.test(entry.package) || entry.package.length > 214) {
+      throw new ValidationError(
+        `${path}: "${entry.package}" (key "${entry.key}") is not a valid npm package name.`,
+      )
+    }
+
+    const identifier = toIdentifier(entry.key)
+    if (!IDENTIFIER_PATTERN.test(identifier)) {
+      throw new ValidationError(
+        `${path}: "${entry.key}" is a valid plugin key, but the identifier ` +
+          `community.plugins.ts would bind for it, "${identifier}", is not a valid TypeScript ` +
+          'identifier. Each hyphen must be followed by exactly one lower-case letter or digit, ' +
+          'and a key cannot end in a hyphen.',
+      )
+    }
+
+    const collidingKey = identifiers.get(identifier)
+    if (collidingKey !== undefined) {
+      throw new ValidationError(
+        `${path}: "${entry.key}" and "${collidingKey}" both generate the identifier ` +
+          `"${identifier}" for community.plugins.ts. Rename one of the keys so the generated ` +
+          'imports do not collide.',
+      )
+    }
+    identifiers.set(identifier, entry.key)
+  }
 }
 
 /**
@@ -63,6 +141,7 @@ async function readManifest(): Promise<Manifest> {
   if (!Array.isArray(parsed.plugins)) {
     throw new ValidationError(`${path} must have a "plugins" array.`)
   }
+  validateEjectManifest(parsed.plugins, path)
   return { plugins: parsed.plugins }
 }
 
@@ -75,10 +154,33 @@ async function isEmptyOrMissing(target: string): Promise<boolean> {
   }
 }
 
-function toIdentifier(key: string): string {
+export function toIdentifier(key: string): string {
   return key.replace(/-([a-z0-9])/g, (_match, char) => char.toUpperCase())
 }
 
+interface EjectedPackageJson {
+  dependencies: Record<string, string>
+  [key: string]: unknown
+}
+
+/**
+ * Every manifest entry's package pinned into the scaffolded package.json's
+ * dependencies, at this exact running version — see docs/marketplace.md,
+ * "1. Eject", for why never `latest`, and for the collision policy this
+ * implements: a package scaffold() already pins is left exactly where it
+ * is, never duplicated or reordered, because both pins are always this
+ * same CODE_VERSION.
+ */
+function mergePluginDependencies(packageJson: string, plugins: readonly ManifestEntry[]): string {
+  const parsed = JSON.parse(packageJson) as EjectedPackageJson
+  for (const entry of plugins) {
+    if (!(entry.package in parsed.dependencies)) {
+      parsed.dependencies[entry.package] = CODE_VERSION
+    }
+  }
+  return `${JSON.stringify(parsed, null, 2)}\n`
+}
+
 /**
  * The ejected workspace's own community.plugins.ts — the same shape
  * create-meith's scaffold() writes for a plugin-free board (see
@@ -122,6 +224,30 @@ export function installedPluginDefinitions() {
 `
 }
 
+function isFsPermissionError(error: unknown): error is NodeJS.ErrnoException {
+  const code = (error as NodeJS.ErrnoException | undefined)?.code
+  return code === 'EACCES' || code === 'EPERM'
+}
+
+/**
+ * Turns an EACCES/EPERM from the write loop below into this instead of a
+ * bare Node stack trace — see docs/marketplace.md, "1. Eject", for the
+ * bind-mount ownership rule this message is naming. Anything else passes
+ * through unchanged.
+ */
+function translateWriteError(error: unknown, target: string, path: string): never {
+  if (isFsPermissionError(error)) {
+    throw new ValidationError(
+      `board:eject could not write to ${path}: permission denied. The account running this ` +
+        `command needs write access to ${target} — inside the official image that account is ` +
+        'a fixed, non-root user, so a bind-mounted target directory has to already be owned by ' +
+        '(or writable by) that same account before eject runs. See docs/marketplace.md, ' +
+        '"Moving to a custom board", for the exact invocation.',
+    )
+  }
+  throw error
+}
+
 export async function boardEject(args: readonly string[]): Promise<number> {
   const positional = args.filter((arg) => !arg.startsWith('-'))
   const [dir] = positional
@@ -150,13 +276,22 @@ export async function boardEject(args: readonly string[]): Promise<number> {
   const files = new Map(
     scaffold({ name, version: CODE_VERSION, repositoryUrl: DEFAULT_REPOSITORY_URL }),
   )
+  const packageJson = files.get('package.json')
+  if (packageJson === undefined) {
+    throw new Error('scaffold() did not emit package.json')
+  }
+  files.set('package.json', mergePluginDependencies(packageJson, manifest.plugins))
   files.set('board.plugins.json', `${JSON.stringify({ plugins: manifest.plugins }, null, 2)}\n`)
   files.set('community.plugins.ts', renderInstalledPluginsModule(manifest.plugins))
 
   for (const [relative, contents] of files) {
     const path = join(target, relative)
-    await mkdir(dirname(path), { recursive: true })
-    await writeFile(path, contents, 'utf8')
+    try {
+      await mkdir(dirname(path), { recursive: true })
+      await writeFile(path, contents, 'utf8')
+    } catch (error) {
+      translateWriteError(error, target, path)
+    }
   }
 
   console.log(`Ejected ${files.size} files to ${target}, pinned to meith ${CODE_VERSION}.`)
@@ -171,7 +306,7 @@ export async function boardEject(args: readonly string[]): Promise<number> {
   console.log('  git init && git add -A && git commit -m "Graduate from the stock image"')
   console.log('  # push it to a new GitHub repository')
   console.log('  # .github/workflows/build.yml builds and pushes the image on every push to main —')
-  console.log("  # point Coolify at this repository's compose.yml and set MEITH_IMAGE to it")
+  console.log('  # point Coolify at this repository and set MEITH_IMAGE to the pushed image')
   console.log('  # redeploy — same database, same uploads, same secrets, new image source')
   console.log('')
   console.log('See docs/marketplace.md, "Moving to a custom board", for the full walkthrough.')

package/src/plugin-manifest.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url'
 
 import { ValidationError } from '@meith/core'
 
+import BOARDS_JSON from '../../../scripts/boards.json'
 import { optional, parseFlags } from './args'
 
 /**
@@ -12,9 +13,33 @@ import { optional, parseFlags } from './args'
  * distance from the repository root (apps/cli/{src,dist}/<file> either way), so this
  * offset holds whether these commands run from source (tsx) or the built dist/cli.cjs.
  */
-const ROOT = fileURLToPath(new URL('../../../', import.meta.url))
-const MANIFEST_PATH = join(ROOT, 'apps/community/board.plugins.json')
-const GENERATOR_SCRIPT = join(ROOT, 'scripts/board-plugins-gen.mjs')
+function repoRoot(): string {
+  return fileURLToPath(new URL('../../../', import.meta.url))
+}
+
+function generatorScript(): string {
+  return join(repoRoot(), 'scripts/board-plugins-gen.mjs')
+}
+
+/**
+ * Every board's board.plugins.json is edited together, from the one list in
+ * scripts/boards.json that scripts/board-plugins-gen.mjs reads too. That file
+ * and the MEITH_BOARD_PLUGINS_ROOT override are described in
+ * docs/development.md, "The board plugin manifests".
+ */
+interface Board {
+  readonly manifestFile: string
+  readonly packageFile: string
+  readonly outputFile: string
+  readonly packageLabel: string
+  readonly filterName: string
+}
+
+const BOARDS = BOARDS_JSON as readonly Board[]
+
+function boardsRoot(): string {
+  return process.env.MEITH_BOARD_PLUGINS_ROOT ?? repoRoot()
+}
 
 interface ManifestEntry {
   readonly key: string
@@ -32,19 +57,21 @@ interface Manifest {
  * one meant to run as `docker compose run --rm web community plugin:purge`. The deployed
  * image is built `FROM node:26-alpine` with only `.next/standalone`, the worker and this
  * CLI's own bundle copied in (see docker/Dockerfile) — no `scripts/`, no `board.plugins.json`,
- * no Biome. Reading the manifest is where that shows up first, so this is where it is named.
+ * no Biome. Reading a manifest is where that shows up first, so this is where it is named.
  */
-async function readManifest(): Promise<Manifest> {
+async function readManifestFor(board: Board): Promise<Manifest> {
+  const path = join(boardsRoot(), board.manifestFile)
   let raw: string
   try {
-    raw = await readFile(MANIFEST_PATH, 'utf8')
+    raw = await readFile(path, 'utf8')
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
       throw new ValidationError(
-        `${MANIFEST_PATH} does not exist. This command edits source files and reruns the ` +
-          'generator, so it needs a checkout of the repository, not the deployed image — run ' +
-          'it where you would run `pnpm add`, commit board.plugins.json and ' +
-          'community.plugins.ts, then rebuild and redeploy.',
+        `${path} does not exist. This command edits source files for every board this ` +
+          'repository carries — apps/community and boards/stock — and reruns the generator, ' +
+          'so it needs a checkout of the repository, not the deployed image — run it where you ' +
+          'would run `pnpm add`, commit both board.plugins.json files and both ' +
+          'community.plugins.ts files, then rebuild and redeploy.',
       )
     }
     throw error
@@ -52,13 +79,25 @@ async function readManifest(): Promise<Manifest> {
 
   const parsed = JSON.parse(raw) as Partial<Manifest>
   if (!Array.isArray(parsed.plugins)) {
-    throw new ValidationError('apps/community/board.plugins.json must have a "plugins" array.')
+    throw new ValidationError(`${path} must have a "plugins" array.`)
   }
+
+  const extraFields = Object.keys(parsed).filter((field) => field !== 'plugins')
+  if (extraFields.length > 0) {
+    throw new ValidationError(
+      `${path} has ${extraFields.length === 1 ? 'a field' : 'fields'} plugin:add/plugin:remove ` +
+        `do not know how to carry forward: ${extraFields.join(', ')}. "plugins" is the ` +
+        "manifest's only field — remove the rest by hand, since rewriting the file here would " +
+        'otherwise drop them silently.',
+    )
+  }
+
   return { plugins: parsed.plugins }
 }
 
-async function writeManifest(manifest: Manifest): Promise<void> {
-  await writeFile(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+async function writeManifestFor(board: Board, manifest: Manifest): Promise<void> {
+  const path = join(boardsRoot(), board.manifestFile)
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
 }
 
 interface GeneratorResult {
@@ -68,14 +107,15 @@ interface GeneratorResult {
 
 /**
  * The one thing this file trusts to know whether a manifest edit is valid: the same
- * generator `pnpm board:gen` runs. Shelling out — rather than importing
- * scripts/board-plugins.mjs — keeps a plain script and a workspace TypeScript package
- * from needing to share a module; it also means a failed add or remove is reported in
- * exactly the words a person typing `pnpm board:gen` themselves would see.
+ * generator `pnpm board:gen` runs, for every board it carries. Shelling out — rather
+ * than importing scripts/board-plugins.mjs — keeps a plain script and a workspace
+ * TypeScript package from needing to share a module; it also means a failed add or
+ * remove is reported in exactly the words a person typing `pnpm board:gen` themselves
+ * would see, board by board.
  */
 function runGenerator(): GeneratorResult {
   try {
-    const output = execFileSync(process.execPath, [GENERATOR_SCRIPT], {
+    const output = execFileSync(process.execPath, [generatorScript()], {
       encoding: 'utf8',
       stdio: 'pipe',
     })
@@ -109,7 +149,7 @@ export async function pluginAdd(args: readonly string[]): Promise<number> {
     throw new ValidationError(
       `community plugin:add does not take plugin configuration (--${configFlags[0]}). The ` +
         "manifest has no field for it — a plugin's own settings are the only place its " +
-        'configuration lives now, the way plugins/dues moved its plans there. Export a ' +
+        "configuration lives now, the way MEI-74 moved plugins/dues's plans there. Export a " +
         'zero-argument plugin and add it with just its package name.',
     )
   }
@@ -122,23 +162,35 @@ export async function pluginAdd(args: readonly string[]): Promise<number> {
     )
   }
 
-  const manifest = await readManifest()
-  if (manifest.plugins.some((entry) => entry.key === key)) {
-    throw new ValidationError(`"${key}" is already in board.plugins.json.`)
-  }
+  const originals = await Promise.all(BOARDS.map((board) => readManifestFor(board)))
+
+  originals.forEach(({ plugins }, index) => {
+    if (plugins.some((entry) => entry.key === key)) {
+      throw new ValidationError(`"${key}" is already in ${BOARDS[index]?.manifestFile}.`)
+    }
+  })
 
   const entry: ManifestEntry = { key, package: packageName, enabled: !flags.has('disabled') }
-  await writeManifest({ plugins: [...manifest.plugins, entry] })
+
+  await Promise.all(
+    BOARDS.map((board, index) =>
+      writeManifestFor(board, { plugins: [...(originals[index]?.plugins ?? []), entry] }),
+    ),
+  )
 
   const result = runGenerator()
   if (!result.ok) {
-    await writeManifest(manifest)
+    await Promise.all(
+      BOARDS.map((board, index) => writeManifestFor(board, originals[index] ?? { plugins: [] })),
+    )
     throw new ValidationError(`Could not add "${key}":\n\n${result.output}`)
   }
 
+  const manifestFiles = BOARDS.map((board) => board.manifestFile).join(' and ')
+  const outputFiles = BOARDS.map((board) => board.outputFile).join(' and ')
   console.log(
-    `Added "${key}" (${packageName}${entry.enabled ? '' : ', disabled'}) to board.plugins.json ` +
-      'and regenerated community.plugins.ts.',
+    `Added "${key}" (${packageName}${entry.enabled ? '' : ', disabled'}) to ${manifestFiles} ` +
+      `and regenerated ${outputFiles}.`,
   )
   console.log('Rebuild and redeploy for it to take effect.')
   return 0
@@ -152,25 +204,38 @@ export async function pluginRemove(args: readonly string[]): Promise<number> {
     throw new ValidationError('Usage: community plugin:remove <key>')
   }
 
-  const manifest = await readManifest()
-  if (!manifest.plugins.some((entry) => entry.key === key)) {
-    const present = manifest.plugins.map((entry) => entry.key)
-    throw new ValidationError(
-      present.length === 0
-        ? `"${key}" is not in board.plugins.json — it lists no plugins.`
-        : `"${key}" is not in board.plugins.json. Present: ${present.join(', ')}.`,
-    )
-  }
+  const originals = await Promise.all(BOARDS.map((board) => readManifestFor(board)))
 
-  await writeManifest({ plugins: manifest.plugins.filter((entry) => entry.key !== key) })
+  originals.forEach(({ plugins }, index) => {
+    if (!plugins.some((entry) => entry.key === key)) {
+      const present = plugins.map((entry) => entry.key)
+      throw new ValidationError(
+        present.length === 0
+          ? `"${key}" is not in ${BOARDS[index]?.manifestFile} — it lists no plugins.`
+          : `"${key}" is not in ${BOARDS[index]?.manifestFile}. Present: ${present.join(', ')}.`,
+      )
+    }
+  })
+
+  await Promise.all(
+    BOARDS.map((board, index) =>
+      writeManifestFor(board, {
+        plugins: (originals[index]?.plugins ?? []).filter((entry) => entry.key !== key),
+      }),
+    ),
+  )
 
   const result = runGenerator()
   if (!result.ok) {
-    await writeManifest(manifest)
+    await Promise.all(
+      BOARDS.map((board, index) => writeManifestFor(board, originals[index] ?? { plugins: [] })),
+    )
     throw new ValidationError(`Could not remove "${key}":\n\n${result.output}`)
   }
 
-  console.log(`Removed "${key}" from board.plugins.json and regenerated community.plugins.ts.`)
+  const manifestFiles = BOARDS.map((board) => board.manifestFile).join(' and ')
+  const outputFiles = BOARDS.map((board) => board.outputFile).join(' and ')
+  console.log(`Removed "${key}" from ${manifestFiles} and regenerated ${outputFiles}.`)
   console.log('Rebuild and redeploy for it to take effect.')
   return 0
 }

package/src/upgrade.ts

@@ -11,7 +11,7 @@ import { type PluginDefinition, pluginNavigationPlacements } from '@meith/plugin
 import { runPluginLifecycle } from '@meith/runtime'
 import { type PluginUpgrade, planUpgrade, upgradeNotice } from '@meith/upgrade'
 
-export const CODE_VERSION = '0.17.0'
+export const CODE_VERSION = '0.17.2'
 
 export function pluginUpgrades(plugins: readonly PluginDefinition[]): readonly PluginUpgrade[] {
   return plugins.map((plugin) => ({