@meith/cli 0.21.1 → 0.22.0

package/bin/community.mjs

@@ -1,28 +1,4 @@
 #!/usr/bin/env node
-/**
- * `community` — the bin that makes `@meith/cli` runnable against an external
- * board workspace, on the same footing as `forum-web` (see
- * apps/community/bin/forum-web.mjs and docs/development.md).
- *
- * `apps/cli/src/index.ts` reaches the board-config seam with a *dynamic*
- * `await import('@board/plugins')` (never a static one — see
- * docs/architecture.md), so unlike the release image's own bundled CLI —
- * which bakes in whichever board it was built next to — this one resolves
- * that seam at the moment it actually runs, against whichever workspace it
- * was invoked from. So the same materialize-then-run trick as `forum-web`
- * applies, with `tsx` standing in for `next`: this package ships TypeScript
- * source with no build step, `tsx` is already how it runs inside this
- * monorepo (`pnpm community` is `tsx src/index.ts`), and a tsconfig it reads
- * from the nearest ancestor directory is a mechanism it already has, so
- * pointing that tsconfig's `@board/config` / `@board/plugins` at the
- * invoking workspace's own files is the same seam-resolution mechanism
- * `forum-web` uses for the Next app, applied through the tool this package
- * already runs through.
- *
- * Unlike `forum-web`, this does not change the working directory: the CLI's
- * own `.env` loading is relative to wherever the operator invoked it from,
- * and that should stay the workspace root.
- */
 import { spawn } from 'node:child_process'
 import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -92,12 +68,6 @@ 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() {
   const require = createRequire(join(packageRoot, 'package.json'))
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/cli",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "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": "MIT",
   "repository": {
@@ -23,18 +23,18 @@
   },
   "dependencies": {
     "tsx": "^4.23.12",
-    "@meith/accounts": "0.21.1",
-    "@meith/core": "0.21.1",
-    "@meith/db": "0.21.1",
-    "@meith/demo": "0.21.1",
-    "@meith/drivers": "0.21.1",
-    "@meith/forums": "0.21.1",
-    "@meith/plugin-kit": "0.21.1",
-    "@meith/profile-fields": "0.21.1",
-    "@meith/settings": "0.21.1",
-    "@meith/tasks": "0.21.1",
-    "create-meith": "0.21.1",
-    "@meith/runtime": "0.21.1"
+    "@meith/accounts": "0.22.0",
+    "@meith/core": "0.22.0",
+    "@meith/demo": "0.22.0",
+    "@meith/db": "0.22.0",
+    "@meith/drivers": "0.22.0",
+    "@meith/plugin-kit": "0.22.0",
+    "@meith/profile-fields": "0.22.0",
+    "@meith/forums": "0.22.0",
+    "@meith/runtime": "0.22.0",
+    "@meith/settings": "0.22.0",
+    "@meith/tasks": "0.22.0",
+    "create-meith": "0.22.0"
   },
   "devDependencies": {
     "esbuild": "^0.28.2"

package/src/backup.ts

@@ -16,7 +16,7 @@ import path from 'node:path'
 
 import { ConfigurationError, env, type FileStore, ValidationError } from '@meith/core'
 import { migrationUrl, runMigrations } from '@meith/db'
-import { BlobFileStore, S3FileStore } from '@meith/drivers'
+import { BlobFileStore, S3FileStore, unusableKeyReason } from '@meith/drivers'
 
 import { optional, parseFlags } from './args'
 import { requirePostgres } from './context'
@@ -33,8 +33,11 @@ export interface BackupManifest {
   readonly filestore: FilestoreDriver
   readonly uploads: 'included' | 'skipped'
   readonly bucket?: string
+  readonly skippedKeys?: readonly string[]
 }
 
+const INCOMPLETE_BUNDLE_EXIT_CODE = 2
+
 export function resolveUploadsMode(driver: FilestoreDriver, flag: string | undefined): UploadsMode {
   if (flag === undefined) return driver === 's3' ? 'skip' : 'include'
   if (flag === 'include' || flag === 'skip') return flag
@@ -77,6 +80,14 @@ export function parseManifest(raw: string): BackupManifest {
     throw new ValidationError('The bundle manifest does not name a known file driver.')
   }
 
+  const skippedKeys = manifest.skippedKeys
+  if (
+    skippedKeys !== undefined &&
+    (!Array.isArray(skippedKeys) || skippedKeys.some((key) => typeof key !== 'string'))
+  ) {
+    throw new ValidationError('The bundle manifest lists skipped objects in a form it cannot read.')
+  }
+
   return {
     format: 1,
     createdAt: manifest.createdAt,
@@ -84,6 +95,7 @@ export function parseManifest(raw: string): BackupManifest {
     filestore: manifest.filestore,
     uploads: manifest.uploads,
     ...(typeof manifest.bucket === 'string' ? { bucket: manifest.bucket } : {}),
+    ...(skippedKeys === undefined || skippedKeys.length === 0 ? {} : { skippedKeys }),
   }
 }
 
@@ -370,18 +382,35 @@ export async function reserveBackupDestination(destination: string): Promise<voi
   await file.close()
 }
 
-async function stageLocalUploads(stage: string): Promise<'included' | 'skipped'> {
+interface StagedUploads {
+  readonly uploads: 'included' | 'skipped'
+  readonly skippedKeys: readonly string[]
+}
+
+const SKIPPED_KEYS_LISTED = 10
+
+export function skippedKeyLines(keys: readonly string[]): readonly string[] {
+  const shown = keys.slice(0, SKIPPED_KEYS_LISTED)
+  return [
+    ...shown.map((key) => `  ${JSON.stringify(key)}`),
+    ...(keys.length > shown.length
+      ? [`  …and ${keys.length - shown.length} more, listed in the bundle's manifest.json.`]
+      : []),
+  ]
+}
+
+async function stageLocalUploads(stage: string): Promise<StagedUploads> {
   const exists = await stat(env.UPLOADS_DIR).then(
     (info) => info.isDirectory(),
     () => false,
   )
   if (!exists) {
     console.log(`No uploads directory at ${env.UPLOADS_DIR}; the bundle carries none.`)
-    return 'skipped'
+    return { uploads: 'skipped', skippedKeys: [] }
   }
 
   await run('tar', ['czf', path.join(stage, 'uploads.tar.gz'), '-C', env.UPLOADS_DIR, '.'])
-  return 'included'
+  return { uploads: 'included', skippedKeys: [] }
 }
 
 export interface ListableStore {
@@ -389,13 +418,29 @@ export interface ListableStore {
   get(key: string): Promise<Uint8Array | undefined>
 }
 
-export async function drainStoreToDirectory(store: ListableStore, dir: string): Promise<number> {
+export interface DrainedStore {
+  readonly pulled: number
+  readonly skipped: readonly string[]
+}
+
+export async function drainStoreToDirectory(
+  store: ListableStore,
+  dir: string,
+): Promise<DrainedStore> {
   let pulled = 0
+  const skipped: string[] = []
 
   for await (const key of store.listKeys()) {
     const target = path.resolve(dir, key)
     if (target !== dir && !target.startsWith(dir + path.sep)) {
-      console.warn(`Skipping object with an unsafe key: ${key}`)
+      console.warn(`Skipping the object at ${JSON.stringify(key)}: its key escapes ${dir}.`)
+      skipped.push(key)
+      continue
+    }
+    const unusable = unusableKeyReason(key)
+    if (unusable !== undefined) {
+      console.warn(`Skipping the object at ${JSON.stringify(key)}: its key ${unusable}.`)
+      skipped.push(key)
       continue
     }
     const body = await store.get(key)
@@ -405,7 +450,7 @@ export async function drainStoreToDirectory(store: ListableStore, dir: string):
     pulled++
   }
 
-  return pulled
+  return { pulled, skipped }
 }
 
 export async function uploadDirectoryToStore(
@@ -430,26 +475,26 @@ async function stageObjectStoreUploads(
   stage: string,
   store: ListableStore,
   origin: string,
-): Promise<'included' | 'skipped'> {
+): Promise<StagedUploads> {
   const dir = path.join(stage, 'uploads')
   await mkdir(dir, { recursive: true })
 
-  const pulled = await drainStoreToDirectory(store, dir)
+  const { pulled, skipped } = await drainStoreToDirectory(store, dir)
 
   if (pulled === 0) {
     console.log(`Found no objects in ${origin}; the bundle carries no uploads.`)
     await rm(dir, { recursive: true, force: true })
-    return 'skipped'
+    return { uploads: 'skipped', skippedKeys: skipped }
   }
 
   await run('tar', ['czf', path.join(stage, 'uploads.tar.gz'), '-C', dir, '.'])
   await rm(dir, { recursive: true, force: true })
   console.log(`Pulled ${pulled} object(s) from ${origin}.`)
-  return 'included'
+  return { uploads: 'included', skippedKeys: skipped }
 }
 
-async function stageUploads(stage: string, mode: UploadsMode): Promise<'included' | 'skipped'> {
-  if (mode === 'skip') return 'skipped'
+async function stageUploads(stage: string, mode: UploadsMode): Promise<StagedUploads> {
+  if (mode === 'skip') return { uploads: 'skipped', skippedKeys: [] }
 
   switch (env.FILESTORE_DRIVER) {
     case 's3':
@@ -490,7 +535,7 @@ export async function backupCommand(args: readonly string[]): Promise<number> {
       databaseEnvironment,
     )
 
-    const uploads = await stageUploads(stage, mode)
+    const { uploads, skippedKeys } = await stageUploads(stage, mode)
 
     const manifest: BackupManifest = {
       format: 1,
@@ -499,6 +544,7 @@ export async function backupCommand(args: readonly string[]): Promise<number> {
       filestore: env.FILESTORE_DRIVER,
       uploads,
       ...(env.S3_BUCKET === undefined ? {} : { bucket: env.S3_BUCKET }),
+      ...(skippedKeys.length === 0 ? {} : { skippedKeys }),
     }
     await writeFile(path.join(stage, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
 
@@ -529,7 +575,19 @@ export async function backupCommand(args: readonly string[]): Promise<number> {
         'thing most likely to fail.',
     )
     destinationCreated = false
-    return 0
+    if (skippedKeys.length === 0) return 0
+
+    console.warn(
+      `\nThis bundle is missing ${skippedKeys.length} object(s) whose keys nothing can read:`,
+    )
+    for (const line of skippedKeyLines(skippedKeys)) console.warn(line)
+    console.warn(
+      'The bundle itself is sound and restores normally — posts referring to those ' +
+        'objects will have broken images. The manifest carries the list, so the ' +
+        `restore says so too. Exiting ${INCOMPLETE_BUNDLE_EXIT_CODE} rather than 0 so a ` +
+        'scheduled backup does not record this run as a clean one.',
+    )
+    return INCOMPLETE_BUNDLE_EXIT_CODE
   } finally {
     if (destinationCreated) await rm(out, { force: true })
     await rm(stage, { recursive: true, force: true })
@@ -719,6 +777,18 @@ export async function restoreCommand(args: readonly string[]): Promise<number> {
       )
     }
 
+    if (manifest.skippedKeys !== undefined) {
+      console.warn(
+        `\nThe backup that made this bundle could not read ${manifest.skippedKeys.length} ` +
+          'object(s), so they are not here:',
+      )
+      for (const line of skippedKeyLines(manifest.skippedKeys)) console.warn(line)
+      console.warn(
+        'Posts referring to them have broken images. Those keys were unusable in the ' +
+          'source store, so another backup of the same board would skip them again.',
+      )
+    }
+
     console.log(
       'Point a staging deployment at the restored database, sign in as an ' +
         'administrator, and open a thread with attachments before trusting it.',

package/src/board-eject.ts

@@ -8,15 +8,6 @@ import { ValidationError } from '@meith/core'
 
 import { CODE_VERSION } from './upgrade'
 
-/**
- * apps/cli/src/plugin-manifest.ts and this file are the same distance from
- * the repository root (apps/cli/{src,dist}/<file> either way) — see that
- * file's own comment. This default is only reached from *this* checkout
- * (`pnpm community board:eject`, tests): the deployed image sets
- * `BOARD_PLUGINS_MANIFEST` explicitly (see docker/Dockerfile), because a
- * bundled `dist/cli.cjs` does not sit at that same distance — Docker's own
- * `COPY apps/cli/dist/ ./apps/cli/` drops the `dist` segment.
- */
 function defaultManifestPath(): string {
   return join(
     fileURLToPath(new URL('../../../', import.meta.url)),
@@ -38,22 +29,10 @@ function manifestPath(): string {
   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>()
@@ -112,14 +91,6 @@ export function validateEjectManifest(plugins: readonly ManifestEntry[], path: s
   }
 }
 
-/**
- * The manifest this build actually compiled in. Unlike
- * apps/cli/src/plugin-manifest.ts's readManifest — which is written for a
- * checkout and refuses to run against a deployed image — this one is meant
- * to run *only* against a deployed image (or this checkout's own
- * boards/stock, standing in for one), so a missing file is the real failure
- * this command exists to report, not an expected outcome.
- */
 async function readManifest(): Promise<Manifest> {
   const path = manifestPath()
   let raw: string
@@ -163,14 +134,6 @@ interface EjectedPackageJson {
   [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) {
@@ -181,20 +144,6 @@ function mergePluginDependencies(packageJson: string, plugins: readonly Manifest
   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
- * packages/create-meith/src/scaffold.ts), extended with one entry per
- * manifest plugin. Never the showcase-wired shape scripts/board-plugins.mjs
- * generates for apps/community and boards/stock: `./community.demo.plugins`
- * is this monorepo's own demo/test scaffolding and does not exist in a
- * workspace outside it — the same reason scaffold.ts's own template omits
- * it. In practice the manifest a real stock image compiles in is always
- * empty (plugin:add refuses to run against a deployed image — see
- * plugin-manifest.ts — so a running stock image can never have grown one),
- * but this reads the real file rather than assuming that, so a future
- * default plugin would still be captured correctly.
- */
 function renderInstalledPluginsModule(plugins: readonly ManifestEntry[]): string {
   const importLines = plugins.map((entry) => {
     const name = toIdentifier(entry.key)
@@ -229,19 +178,13 @@ function isFsPermissionError(error: unknown): error is NodeJS.ErrnoException {
   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, ' +
+        '(or writable by) that same account before eject runs. See docs/customization/marketplace.md, ' +
         '"Moving to a custom board", for the exact invocation.',
     )
   }
@@ -309,7 +252,9 @@ export async function boardEject(args: readonly string[]): Promise<number> {
   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.')
+  console.log(
+    'See docs/customization/marketplace.md, "Moving to a custom board", for the full walkthrough.',
+  )
 
   return 0
 }

package/src/plugin-manifest.ts

@@ -8,11 +8,6 @@ import { ValidationError } from '@meith/core'
 import BOARDS_JSON from '../../../scripts/boards.json'
 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.
- */
 function repoRoot(): string {
   return fileURLToPath(new URL('../../../', import.meta.url))
 }
@@ -21,12 +16,6 @@ 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
@@ -51,14 +40,6 @@ 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 a manifest is where that shows up first, so this is where it is named.
- */
 async function readManifestFor(board: Board): Promise<Manifest> {
   const path = join(boardsRoot(), board.manifestFile)
   let raw: string
@@ -105,14 +86,6 @@ interface GeneratorResult {
   readonly output: string
 }
 
-/**
- * The one thing this file trusts to know whether a manifest edit is valid: the same
- * 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, [generatorScript()], {
@@ -129,7 +102,6 @@ function runGenerator(): GeneratorResult {
 
 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]
 }

package/src/plugins.ts

@@ -9,12 +9,6 @@ export interface PurgeOptions {
   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)
 

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.21.1'
+export const CODE_VERSION = '0.22.0'
 
 export function pluginUpgrades(plugins: readonly PluginDefinition[]): readonly PluginUpgrade[] {
   return plugins.map((plugin) => ({
@@ -90,12 +90,6 @@ export async function upgrade(options: UpgradeOptions): Promise<number> {
       const ran = await applyPluginMigration(db, plugin.key, migration.id, migration.statements)
       if (ran) options.log(`${plugin.key}: applied ${migration.id}.`)
     }
-    /*
-     * onInstall runs after this plugin's migrations, so its tables exist, and
-     * before the version row that will stop it running again. A throw here
-     * stops the upgrade: a plugin that could not finish installing is one the
-     * board should not start serving.
-     */
     if (fresh.includes(plugin.key) && definition !== undefined) {
       const { ran } = await runPluginLifecycle({ db, plugin: definition, phase: 'install' })
       if (ran) options.log(`${plugin.key}: onInstall.`)