@meith/cli 0.16.0

package/src/index.ts

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+import process from 'node:process'
+
+import { type LoadedEnvFiles, loadEnvFiles } from '@meith/core/env-files'
+
+import { backupCommand, restoreCommand } from './backup'
+import {
+  forumCreate,
+  settingDisplayValue,
+  settingsGet,
+  settingsSet,
+  userClearSecondFactor,
+  userCreate,
+  userPromote,
+} from './commands'
+import { demoReset, demoSeed } from './demo'
+import { importCommand } from './import'
+import { profileFieldAdd, profileFieldList, profileFieldRemove } from './profile-fields'
+import { pushKeys } from './push'
+import { SECRET_ENV_KEYS } from './redaction'
+import { searchReindex } from './search'
+import { taskList, taskRun } from './tasks'
+
+interface Command {
+  readonly name: string
+  readonly summary: string
+  readonly usage?: string
+  run(args: readonly string[]): Promise<number>
+}
+
+function usage(commands: readonly Command[]): string {
+  const width = Math.max(...commands.map((c) => c.name.length))
+  const lines = commands.map((c) => `  ${c.name.padEnd(width)}  ${c.summary}`)
+  return [
+    'community — operator CLI',
+    '',
+    'Usage: community <command> [options]',
+    '',
+    'Commands:',
+    ...lines,
+    '',
+  ].join('\n')
+}
+
+const commands: Command[] = [
+  {
+    name: 'env:check',
+    summary: 'Validate environment variables and print the resolved config.',
+    async run() {
+      const { assertEnv } = await import('@meith/core')
+
+      let env: ReturnType<typeof assertEnv>
+      try {
+        env = assertEnv()
+      } catch (error) {
+        console.error('Environment is invalid:\n')
+        console.error(error instanceof Error ? error.message : String(error))
+        return 1
+      }
+
+      const rows = Object.entries(env)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => [k, SECRET_ENV_KEYS.has(k) ? '<set>' : String(v)] as const)
+        .sort(([a], [b]) => a.localeCompare(b))
+
+      const width = Math.max(...rows.map(([k]) => k.length))
+      for (const [k, v] of rows) console.log(`${k.padEnd(width)}  ${v}`)
+
+      console.log('\nEnvironment is valid.')
+      console.log(
+        envFiles.loaded.length > 0
+          ? `Loaded ${envFiles.loaded.join(', ')} from ${envFiles.root}.`
+          : envFiles.root === undefined
+            ? 'No workspace root found — configuration came from the environment.'
+            : `No .env files at ${envFiles.root} — configuration came from the environment.`,
+      )
+      if (env.DATA_SOURCE === 'fixture') {
+        console.log('DATA_SOURCE=fixture — in-memory sample data. Set DATABASE_URL for Postgres.')
+      }
+      return 0
+    },
+  },
+
+  {
+    name: 'migrate',
+    summary: 'Apply pending database migrations.',
+    async run() {
+      const { assertEnv } = await import('@meith/core')
+      const env = assertEnv()
+
+      if (env.DATA_SOURCE !== 'postgres') {
+        console.error('Nothing to migrate: DATA_SOURCE is "fixture". Set DATABASE_URL first.')
+        return 1
+      }
+
+      const { runMigrations } = await import('@meith/db')
+      const applied = await runMigrations()
+      console.log(applied === 0 ? 'Already up to date.' : `Applied ${applied} migration(s).`)
+      return 0
+    },
+  },
+
+  {
+    name: 'import',
+    summary: 'Import a MyBB or phpBB board. Resumable — run it again to continue.',
+    usage:
+      'IMPORT_SOURCE_PASSWORD=… forum import --host H --user U --database D ' +
+      '[--source mybb|phpbb] [--prefix mybb_] [--uploads-dir /path/to/uploads] ' +
+      '[--port 3306] [--charset utf8mb4] [--ssl] ' +
+      '[--budget 20000] [--page-size 200]',
+    async run(args: readonly string[]) {
+      const { assertEnv } = await import('@meith/core')
+      const env = assertEnv()
+
+      if (env.DATA_SOURCE !== 'postgres') {
+        console.error('Nothing to import into: DATA_SOURCE is "fixture". Set DATABASE_URL first.')
+        return 1
+      }
+
+      return importCommand(args)
+    },
+  },
+
+  {
+    name: 'upgrade',
+    summary: 'Apply core and plugin migrations, then record the version.',
+    usage: 'community upgrade [--dry-run]',
+    async run(args: readonly string[]) {
+      const { assertEnv } = await import('@meith/core')
+      const env = assertEnv()
+
+      if (env.DATA_SOURCE !== 'postgres') {
+        console.error('Nothing to upgrade: DATA_SOURCE is "fixture". Set DATABASE_URL first.')
+        return 1
+      }
+
+      const { upgrade } = await import('./upgrade')
+      const { installedPluginDefinitions } = await import('@board/plugins')
+      return upgrade({
+        dryRun: args.includes('--dry-run'),
+        plugins: installedPluginDefinitions(),
+        log: (line) => console.log(line),
+      })
+    },
+  },
+
+  {
+    name: 'backup',
+    summary: 'Dump the database and the uploads into one restorable bundle.',
+    usage: 'community backup [--out <path>] [--uploads include|skip]',
+    run: backupCommand,
+  },
+
+  {
+    name: 'restore',
+    summary: 'Restore a backup bundle into a new, empty database.',
+    usage:
+      'RESTORE_DATABASE_URL=<postgres://…> community restore <bundle.tar.gz> ' +
+      '[--uploads-dir <dir>] [--skip-uploads]',
+    run: restoreCommand,
+  },
+
+  {
+    name: 'plugin:purge',
+    summary: 'Run a plugin’s onUninstall and remove its data. Do this before removing the code.',
+    usage: 'community plugin:purge <key> [--yes]',
+    async run(args: readonly string[]) {
+      const { assertEnv } = await import('@meith/core')
+      const env = assertEnv()
+
+      if (env.DATA_SOURCE !== 'postgres') {
+        console.error('Nothing to purge: DATA_SOURCE is "fixture". Set DATABASE_URL first.')
+        return 1
+      }
+
+      const key = args.find((arg) => !arg.startsWith('--'))
+      if (key === undefined) {
+        console.error('Usage: community plugin:purge <key> [--yes]')
+        return 1
+      }
+
+      const { purge } = await import('./plugins')
+      const { installedPluginDefinitions } = await import('@board/plugins')
+      return purge({
+        key,
+        plugins: installedPluginDefinitions(),
+        confirmed: args.includes('--yes'),
+        log: (line) => console.log(line),
+      })
+    },
+  },
+
+  {
+    name: 'plugin:add',
+    summary: 'Add a package to board.plugins.json and regenerate community.plugins.ts.',
+    usage: 'community plugin:add <package> [--key <key>] [--disabled]',
+    async run(args: readonly string[]) {
+      const { pluginAdd } = await import('./plugin-manifest')
+      return pluginAdd(args)
+    },
+  },
+
+  {
+    name: 'plugin:remove',
+    summary: 'Remove a plugin from board.plugins.json and regenerate community.plugins.ts.',
+    usage: 'community plugin:remove <key>',
+    async run(args: readonly string[]) {
+      const { pluginRemove } = await import('./plugin-manifest')
+      return pluginRemove(args)
+    },
+  },
+
+  {
+    name: 'board:eject',
+    summary:
+      'Write this build as a standalone workspace — the first step of graduating off the stock image.',
+    usage: 'community board:eject <dir>',
+    async run(args: readonly string[]) {
+      const { boardEject } = await import('./board-eject')
+      return boardEject(args)
+    },
+  },
+
+  {
+    name: 'settings:list',
+    summary: 'Print the setting registry with default values.',
+    async run() {
+      const { SETTING_DEFINITIONS } = await import('@meith/settings')
+
+      const width = Math.max(...SETTING_DEFINITIONS.map((d) => d.key.length))
+      let group = ''
+
+      for (const d of SETTING_DEFINITIONS) {
+        if (d.group !== group) {
+          group = d.group
+          console.log(`\n[${group}]`)
+        }
+        console.log(`  ${d.key.padEnd(width)}  ${settingDisplayValue(d, d.default)}`)
+      }
+      console.log()
+      return 0
+    },
+  },
+
+  {
+    name: 'user:create',
+    summary: 'Create a user account. Pipe the password in on stdin.',
+    usage:
+      'echo "<password>" | community user:create --username <name> --email <addr> [--group <key>]',
+    run: userCreate,
+  },
+
+  {
+    name: 'user:promote',
+    summary: "Change a user's primary group.",
+    usage: 'community user:promote --user <id|username> --group <key|id>',
+    run: userPromote,
+  },
+
+  {
+    name: 'user:2fa-clear',
+    summary: "Clear a user's second factor when they have lost it, and sign them out.",
+    usage: 'community user:2fa-clear --user <id|username>',
+    run: userClearSecondFactor,
+  },
+
+  {
+    name: 'forum:create',
+    summary: 'Create a category, forum or link.',
+    usage:
+      'community forum:create --title <title> --slug <slug> [--parent <id>] ' +
+      '[--type category|forum|link] [--description <text>] [--link-url <url>]',
+    run: forumCreate,
+  },
+
+  {
+    name: 'settings:get',
+    summary: 'Print one resolved setting value.',
+    usage: 'community settings:get <key>',
+    run: settingsGet,
+  },
+
+  {
+    name: 'settings:set',
+    summary: 'Set one setting, validated by the registry.',
+    usage:
+      'community settings:set <key> <value>\n' +
+      'community settings:set <secret-key> --from-env <name>\n' +
+      'printf %s "$SECRET" | community settings:set <secret-key>',
+    run: settingsSet,
+  },
+
+  {
+    name: 'profile-field:list',
+    summary: 'List the custom profile fields this board defines.',
+    run: profileFieldList,
+  },
+
+  {
+    name: 'profile-field:add',
+    summary: 'Define a custom profile field.',
+    usage:
+      'community profile-field:add --key <key> --label <label> ' +
+      '--type text|textarea|select|checkbox|url|number ' +
+      '[--options a,b,c] [--required] [--postbit] [--order <n>]',
+    run: profileFieldAdd,
+  },
+
+  {
+    name: 'profile-field:remove',
+    summary: "Delete a custom profile field and every member's answer to it.",
+    usage: 'community profile-field:remove <key>',
+    run: profileFieldRemove,
+  },
+
+  {
+    name: 'push:keys',
+    summary: 'Generate a VAPID key pair for web push. --save writes it to the board.',
+    usage: 'community push:keys [--save]',
+    run: pushKeys,
+  },
+
+  {
+    name: 'task:list',
+    summary: 'List the scheduled tasks this build registers.',
+    run: taskList,
+  },
+
+  {
+    name: 'task:run',
+    summary: 'Run every task that is due now, or one named task if it is due.',
+    usage: 'community task:run [<task-id>]',
+    run: taskRun,
+  },
+
+  {
+    name: 'search:reindex',
+    summary: 'Build the full-text index for posts that have none. Resumable.',
+    run: searchReindex,
+  },
+
+  {
+    name: 'demo:seed',
+    summary: 'Write the demo board into an empty database. Needs DEMO_MODE.',
+    run: demoSeed,
+  },
+
+  {
+    name: 'demo:reset',
+    summary: 'Drop everything and rebuild the demo board. Needs DEMO_MODE.',
+    usage: 'community demo:reset --yes',
+    run: demoReset,
+  },
+]
+
+let envFiles: LoadedEnvFiles = { root: undefined, loaded: [] }
+
+async function main(): Promise<number> {
+  envFiles = loadEnvFiles()
+
+  const [name, ...rest] = process.argv.slice(2)
+
+  if (!name || name === '--help' || name === '-h') {
+    console.log(usage(commands))
+    return name ? 0 : 1
+  }
+
+  const command = commands.find((c) => c.name === name)
+  if (!command) {
+    console.error(`Unknown command: ${name}\n`)
+    console.error(usage(commands))
+    return 1
+  }
+
+  if (rest.includes('--help')) {
+    console.log(command.usage ?? `community ${command.name}`)
+    return 0
+  }
+
+  return command.run(rest)
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch(async (error: unknown) => {
+    const { isAppError } = await import('@meith/core')
+
+    if (isAppError(error)) {
+      console.error(error.message)
+    } else {
+      console.error(error instanceof Error ? error.stack : String(error))
+    }
+    process.exit(1)
+  })

package/src/plugin-manifest.ts

@@ -0,0 +1,176 @@
+import { execFileSync } from 'node:child_process'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ValidationError } from '@meith/core'
+
+import { optional, parseFlags } from './args'
+
+/**
+ * apps/cli/src/plugin-manifest.ts and scripts/board-plugins-gen.mjs are the same
+ * 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')
+
+interface ManifestEntry {
+  readonly key: string
+  readonly package: string
+  readonly enabled?: boolean
+}
+
+interface Manifest {
+  readonly plugins: readonly ManifestEntry[]
+}
+
+/**
+ * `plugin:add`/`plugin:remove` edit source files and rebuild output that only exists in
+ * a checkout — unlike `plugin:purge`, which acts on a running board's database and is the
+ * 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.
+ */
+async function readManifest(): Promise<Manifest> {
+  let raw: string
+  try {
+    raw = await readFile(MANIFEST_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.',
+      )
+    }
+    throw error
+  }
+
+  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.')
+  }
+  return { plugins: parsed.plugins }
+}
+
+async function writeManifest(manifest: Manifest): Promise<void> {
+  await writeFile(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+}
+
+interface GeneratorResult {
+  readonly ok: boolean
+  readonly output: string
+}
+
+/**
+ * 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.
+ */
+function runGenerator(): GeneratorResult {
+  try {
+    const output = execFileSync(process.execPath, [GENERATOR_SCRIPT], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    })
+    return { ok: true, output }
+  } catch (error) {
+    const failure = error as { stdout?: string; stderr?: string; message: string }
+    const output = [failure.stdout, failure.stderr].filter(Boolean).join('\n').trim()
+    return { ok: false, output: output === '' ? failure.message : output }
+  }
+}
+
+const PACKAGE_KEY_PATTERN = /^@[^/]+\/plugin-([a-z][a-z0-9-]*)$/
+
+/** `@scope/plugin-<key>` is the only shape a key can be read from without asking. */
+export function inferKey(packageName: string): string | undefined {
+  return PACKAGE_KEY_PATTERN.exec(packageName)?.[1]
+}
+
+const ADD_FLAGS = new Set(['key', 'disabled'])
+
+export async function pluginAdd(args: readonly string[]): Promise<number> {
+  const { flags, positional } = parseFlags(args)
+  const [packageName, ...extraPositional] = positional
+
+  if (packageName === undefined || extraPositional.length > 0) {
+    throw new ValidationError('Usage: community plugin:add <package> [--key <key>] [--disabled]')
+  }
+
+  const configFlags = [...flags.keys()].filter((name) => !ADD_FLAGS.has(name))
+  if (configFlags.length > 0) {
+    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 ' +
+        'zero-argument plugin and add it with just its package name.',
+    )
+  }
+
+  const key = optional(flags, 'key') ?? inferKey(packageName)
+  if (key === undefined) {
+    throw new ValidationError(
+      `Can't infer a plugin key from "${packageName}". Pass --key <key> — it must be the same ` +
+        "key the package's plugin declares, or defineForumConfig refuses it at build time.",
+    )
+  }
+
+  const manifest = await readManifest()
+  if (manifest.plugins.some((entry) => entry.key === key)) {
+    throw new ValidationError(`"${key}" is already in board.plugins.json.`)
+  }
+
+  const entry: ManifestEntry = { key, package: packageName, enabled: !flags.has('disabled') }
+  await writeManifest({ plugins: [...manifest.plugins, entry] })
+
+  const result = runGenerator()
+  if (!result.ok) {
+    await writeManifest(manifest)
+    throw new ValidationError(`Could not add "${key}":\n\n${result.output}`)
+  }
+
+  console.log(
+    `Added "${key}" (${packageName}${entry.enabled ? '' : ', disabled'}) to board.plugins.json ` +
+      'and regenerated community.plugins.ts.',
+  )
+  console.log('Rebuild and redeploy for it to take effect.')
+  return 0
+}
+
+export async function pluginRemove(args: readonly string[]): Promise<number> {
+  const { positional } = parseFlags(args)
+  const [key, ...extraPositional] = positional
+
+  if (key === undefined || extraPositional.length > 0) {
+    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(', ')}.`,
+    )
+  }
+
+  await writeManifest({ plugins: manifest.plugins.filter((entry) => entry.key !== key) })
+
+  const result = runGenerator()
+  if (!result.ok) {
+    await writeManifest(manifest)
+    throw new ValidationError(`Could not remove "${key}":\n\n${result.output}`)
+  }
+
+  console.log(`Removed "${key}" from board.plugins.json and regenerated community.plugins.ts.`)
+  console.log('Rebuild and redeploy for it to take effect.')
+  return 0
+}

package/src/plugins.ts

@@ -0,0 +1,65 @@
+import { getDb, pluginOwnedTables, purgePlugin } from '@meith/db'
+import type { PluginDefinition } from '@meith/plugin-kit'
+import { runPluginLifecycle } from '@meith/runtime'
+
+export interface PurgeOptions {
+  readonly key: string
+  readonly plugins: readonly PluginDefinition[]
+  readonly confirmed: boolean
+  readonly log: (line: string) => void
+}
+
+/**
+ * The one moment `onUninstall` can run: the operator has decided the plugin is
+ * going, and its code is still in the build. Afterwards there is nothing left
+ * to call — removing a plugin is `pnpm remove`, a line out of
+ * `community.plugins.ts` and a redeploy, and by then the function is gone.
+ */
+export async function purge(options: PurgeOptions): Promise<number> {
+  const definition = options.plugins.find((plugin) => plugin.key === options.key)
+
+  if (definition === undefined) {
+    options.log(`No plugin named "${options.key}" is in this build.`)
+    options.log('')
+    options.log('Purging runs the plugin’s own onUninstall before dropping its data, so it')
+    options.log('has to happen while the code is still installed. Put the plugin back into')
+    options.log('community.plugins.ts, deploy, purge, and then remove it.')
+    return 1
+  }
+
+  const db = getDb()
+  const tables = await pluginOwnedTables(db, options.key)
+
+  if (!options.confirmed) {
+    options.log(`Would purge "${options.key}":`)
+    options.log(
+      definition.onUninstall === undefined
+        ? '  - it declares no onUninstall'
+        : '  - run its onUninstall',
+    )
+    options.log(tables.length === 0 ? '  - no tables of its own' : `  - drop ${tables.join(', ')}`)
+    options.log('  - delete its settings, migration records, navigation items and health row')
+    options.log('')
+    options.log('This cannot be undone. Run again with --yes to do it.')
+    return 0
+  }
+
+  const { ran } = await runPluginLifecycle({ db, plugin: definition, phase: 'uninstall' })
+  if (ran) options.log(`${options.key}: onUninstall.`)
+
+  const result = await purgePlugin(db, options.key)
+
+  options.log(
+    result.tables.length === 0
+      ? `Purged "${options.key}": it had no tables of its own.`
+      : `Purged "${options.key}": dropped ${result.tables.join(', ')}.`,
+  )
+  options.log(
+    `Removed ${result.settings} setting(s), ${result.migrations} migration record(s), ` +
+      `${result.navigation} navigation item(s).`,
+  )
+  options.log('')
+  options.log('Now take it out of community.plugins.ts, pnpm remove it, and redeploy.')
+
+  return 0
+}