@meith/cli 0.16.0

package/src/board-eject.ts

@@ -0,0 +1,180 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { DEFAULT_REPOSITORY_URL, scaffold, validateName } from 'create-meith'
+
+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.
+ */
+const ROOT = fileURLToPath(new URL('../../../', import.meta.url))
+const DEFAULT_MANIFEST_PATH = join(ROOT, 'boards/stock/board.plugins.json')
+
+interface ManifestEntry {
+  readonly key: string
+  readonly package: string
+  readonly enabled?: boolean
+}
+
+interface Manifest {
+  readonly plugins: readonly ManifestEntry[]
+}
+
+function manifestPath(): string {
+  return process.env.BOARD_PLUGINS_MANIFEST ?? DEFAULT_MANIFEST_PATH
+}
+
+/**
+ * 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
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new ValidationError(
+        `board:eject could not find this build's plugin manifest at ${path}. This command ` +
+          'runs inside the official image (docker compose run --rm web community board:eject ' +
+          '<dir>), where it is baked in — or, in this repository, against boards/stock. It is ' +
+          'not meant to run against a workspace board:eject already produced.',
+      )
+    }
+    throw error
+  }
+
+  const parsed = JSON.parse(raw) as Partial<Manifest>
+  if (!Array.isArray(parsed.plugins)) {
+    throw new ValidationError(`${path} must have a "plugins" array.`)
+  }
+  return { plugins: parsed.plugins }
+}
+
+async function isEmptyOrMissing(target: string): Promise<boolean> {
+  try {
+    return (await readdir(target)).length === 0
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return true
+    throw error
+  }
+}
+
+function toIdentifier(key: string): string {
+  return key.replace(/-([a-z0-9])/g, (_match, char) => char.toUpperCase())
+}
+
+/**
+ * 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)
+    return `import { messages as ${name}Messages, plugin as ${name}Plugin } from '${entry.package}'`
+  })
+  const entryLines = plugins.map((entry) => {
+    const name = toIdentifier(entry.key)
+    const enabled = entry.enabled === false ? 'false' : 'true'
+    return (
+      `  { key: '${entry.key}', enabled: ${enabled}, ` +
+      `plugin: ${name}Plugin, messages: ${name}Messages },`
+    )
+  })
+  const body = entryLines.length > 0 ? `\n${entryLines.join('\n')}\n` : ''
+
+  return `${
+    importLines.length > 0 ? `${importLines.join('\n')}\n\n` : ''
+  }import type { InstalledPlugin } from '@meith/web/config'
+
+export const INSTALLED_PLUGINS: readonly InstalledPlugin[] = [${body}]
+
+export function installedPluginDefinitions() {
+  return INSTALLED_PLUGINS.filter(
+    (entry) => entry.enabled !== false && entry.plugin !== undefined,
+  ).map((entry) => entry.plugin)
+}
+`
+}
+
+export async function boardEject(args: readonly string[]): Promise<number> {
+  const positional = args.filter((arg) => !arg.startsWith('-'))
+  const [dir] = positional
+
+  if (dir === undefined || positional.length > 1) {
+    throw new ValidationError('Usage: community board:eject <dir>')
+  }
+
+  const target = resolve(process.cwd(), dir)
+  const name = basename(target)
+
+  const invalidName = validateName(name)
+  if (invalidName !== null) {
+    throw new ValidationError(
+      `board:eject: "${name}" (from ${target}) is not a usable project name — ${invalidName} ` +
+        'Pick a target directory whose name is a valid npm package name.',
+    )
+  }
+
+  if (!(await isEmptyOrMissing(target))) {
+    throw new ValidationError(`${target} already exists and is not empty. Pick an empty target.`)
+  }
+
+  const manifest = await readManifest()
+
+  const files = new Map(
+    scaffold({ name, version: CODE_VERSION, repositoryUrl: DEFAULT_REPOSITORY_URL }),
+  )
+  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')
+  }
+
+  console.log(`Ejected ${files.size} files to ${target}, pinned to meith ${CODE_VERSION}.`)
+  console.log('')
+  console.log(
+    "What doesn't move: the database, the uploads volume and every environment variable " +
+      'stay exactly where they are — only where the image comes from changes.',
+  )
+  console.log('')
+  console.log('Next:')
+  console.log(`  cd ${target}`)
+  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('  # 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.')
+
+  return 0
+}

package/src/commands.ts

@@ -0,0 +1,269 @@
+import { clearSecondFactor, foldIdentifier } from '@meith/accounts'
+import { ValidationError } from '@meith/core'
+import { FORUM_TYPES, type ForumType } from '@meith/forums'
+import {
+  SETTING_DEFINITION_BY_KEY,
+  type SettingDefinition,
+  type SettingKey,
+  SettingsSnapshot,
+  saveSettings,
+} from '@meith/settings'
+
+import { type Flags, integer, optional, parseFlags, required } from './args'
+import { type CliContext, createContext } from './context'
+
+async function readPassword(flags: Flags): Promise<string> {
+  const inline = optional(flags, 'password')
+  if (inline !== undefined) {
+    console.warn(
+      'warning: --password is visible in shell history and to `ps`. ' +
+        'Prefer:  echo "secret" | community user:create --username u --email e@x.com',
+    )
+    return inline
+  }
+
+  if (process.stdin.isTTY) {
+    throw new ValidationError(
+      'No password supplied. Pipe one in:\n' +
+        '  echo "correct horse battery staple" | community user:create --username u --email u@example.com',
+    )
+  }
+
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer)
+  const password = Buffer.concat(chunks)
+    .toString('utf8')
+    .replace(/\r?\n$/, '')
+
+  if (password === '') throw new ValidationError('The password read from stdin was empty.')
+  return password
+}
+
+async function findUser(ctx: CliContext, reference: string) {
+  const user = await ctx.admin.findUser(reference, foldIdentifier(reference))
+  if (!user) throw new ValidationError(`No such user: ${reference}`)
+  return user
+}
+
+async function findGroup(ctx: CliContext, reference: string) {
+  const group = await ctx.admin.findGroup(reference)
+  if (!group) {
+    const keys = await ctx.admin.listGroupKeys()
+    throw new ValidationError(`No such group: ${reference}. Available: ${keys.join(', ')}`)
+  }
+  return group
+}
+
+export async function userCreate(args: readonly string[]): Promise<number> {
+  const { flags } = parseFlags(args)
+  const username = required(flags, 'username')
+  const email = required(flags, 'email')
+  const password = await readPassword(flags)
+
+  const ctx = await createContext()
+  const result = await ctx.identity.register({ username, email, password })
+
+  const groupRef = optional(flags, 'group')
+  if (groupRef !== undefined) {
+    const group = await findGroup(ctx, groupRef)
+    await ctx.admin.setPrimaryGroup(result.account.id, group.id)
+    console.log(`Created user ${username} (id ${result.account.id}) in group ${group.key}.`)
+  } else {
+    console.log(`Created user ${username} (id ${result.account.id}).`)
+  }
+
+  return 0
+}
+
+export async function userPromote(args: readonly string[]): Promise<number> {
+  const { flags } = parseFlags(args)
+  const userRef = required(flags, 'user')
+  const groupRef = required(flags, 'group')
+
+  const ctx = await createContext()
+  const user = await findUser(ctx, userRef)
+  const group = await findGroup(ctx, groupRef)
+
+  if (user.primaryGroupId === group.id) {
+    console.log(`${user.username} is already in ${group.key}. Nothing to do.`)
+    return 0
+  }
+
+  await ctx.admin.setPrimaryGroup(user.id, group.id)
+  console.log(`${user.username} is now in ${group.key} (${group.title}).`)
+  return 0
+}
+
+export async function userClearSecondFactor(args: readonly string[]): Promise<number> {
+  const { flags } = parseFlags(args)
+  const userRef = required(flags, 'user')
+
+  const ctx = await createContext()
+  const user = await findUser(ctx, userRef)
+
+  const removed = await clearSecondFactor(ctx.accounts, user.id)
+
+  if (!removed) {
+    console.log(`${user.username} holds no second factor. Nothing to do.`)
+    return 0
+  }
+
+  await ctx.accounts.sessions.revokeAllForUser(user.id)
+  await ctx.accounts.authEvents.record({
+    userId: user.id,
+    kind: 'second_factor_cleared',
+    detail: { by: 'cli' },
+    at: new Date(),
+  })
+
+  console.log(
+    `Cleared the second factor on ${user.username} and signed every session out. ` +
+      'They sign in with their password alone until they set one up again.',
+  )
+  return 0
+}
+
+export async function forumCreate(args: readonly string[]): Promise<number> {
+  const { flags } = parseFlags(args)
+
+  const rawType = optional(flags, 'type') ?? 'forum'
+  if (!(FORUM_TYPES as readonly string[]).includes(rawType)) {
+    throw new ValidationError(`--type must be one of ${FORUM_TYPES.join(', ')}, got "${rawType}".`)
+  }
+
+  const input = {
+    type: rawType as ForumType,
+    title: required(flags, 'title'),
+    slug: required(flags, 'slug'),
+    description: optional(flags, 'description'),
+    parentId: integer(flags, 'parent') ?? null,
+    linkUrl: optional(flags, 'link-url'),
+  }
+
+  const ctx = await createContext()
+  const created = await ctx.forums.create(input)
+
+  console.log(
+    `Created ${created.type} "${created.title}" (id ${created.id}, path ${created.path}).`,
+  )
+  return 0
+}
+
+export function settingDisplayValue(definition: SettingDefinition, value: unknown): string {
+  if (definition.secret) {
+    return Object.is(value, definition.default) ? '<unset>' : '<set>'
+  }
+  return JSON.stringify(value)
+}
+
+export async function settingsGet(args: readonly string[]): Promise<number> {
+  const { positional } = parseFlags(args)
+  const key = positional[0]
+  if (key === undefined) throw new ValidationError('Usage: community settings:get <key>')
+
+  const definition = SETTING_DEFINITION_BY_KEY.get(key)
+  if (!definition) throw new ValidationError(`Unknown setting "${key}".`)
+
+  const ctx = await createContext()
+  const snapshot = SettingsSnapshot.fromOverrides(await ctx.settings.loadAll())
+  const value = snapshot.get(key as SettingKey)
+  const isDefault = Object.is(value, definition.default)
+  console.log(`${key} = ${settingDisplayValue(definition, value)}${isDefault ? '  (default)' : ''}`)
+  return 0
+}
+
+interface SecretInput {
+  readonly isTTY?: boolean
+  [Symbol.asyncIterator](): AsyncIterator<Buffer | string>
+}
+
+export async function readSecretSettingValue(
+  flags: Flags,
+  input: SecretInput,
+  environment: NodeJS.ProcessEnv,
+): Promise<string> {
+  const environmentName = flags.get('from-env')
+  if (environmentName !== undefined) {
+    if (environmentName.trim() === '' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(environmentName)) {
+      throw new ValidationError('--from-env needs a valid environment variable name.')
+    }
+    const value = environment[environmentName]
+    if (value === undefined) {
+      throw new ValidationError(`Environment variable ${environmentName} is not set.`)
+    }
+    return value
+  }
+
+  if (input.isTTY) {
+    throw new ValidationError('No secret supplied. Pipe it on stdin or use --from-env <name>.')
+  }
+
+  const chunks: Buffer[] = []
+  for await (const chunk of input) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+  }
+  return Buffer.concat(chunks)
+    .toString('utf8')
+    .replace(/\r?\n$/, '')
+}
+
+export async function settingsSet(args: readonly string[]): Promise<number> {
+  const { flags, positional } = parseFlags(args)
+  const [key, positionalValue, ...extra] = positional
+  if (key === undefined || extra.length > 0) {
+    throw new ValidationError(
+      'Usage: community settings:set <key> <value>\n' +
+        '       community settings:set <secret-key> --from-env <name>\n' +
+        '       printf %s "$SECRET" | community settings:set <secret-key>',
+    )
+  }
+
+  const definition = SETTING_DEFINITION_BY_KEY.get(key)
+  if (!definition) throw new ValidationError(`Unknown setting "${key}".`)
+
+  let raw: string
+  if (definition.secret) {
+    if (positionalValue !== undefined) {
+      throw new ValidationError(
+        'Secret settings cannot be supplied as arguments. Pipe the value on stdin or use --from-env <name>.',
+      )
+    }
+    raw = await readSecretSettingValue(flags, process.stdin, process.env)
+  } else {
+    if (flags.has('from-env')) {
+      throw new ValidationError('--from-env is only available for secret settings.')
+    }
+    if (positionalValue === undefined) {
+      throw new ValidationError('Usage: community settings:set <key> <value>')
+    }
+    raw = positionalValue
+  }
+
+  const ctx = await createContext()
+  const snapshot = SettingsSnapshot.fromOverrides(await ctx.settings.loadAll())
+  const value = definition.secret ? raw : coerce(raw, definition)
+  const result = await saveSettings(ctx.settings, { [key]: value }, snapshot)
+  const displayed = definition.secret ? settingDisplayValue(definition, value) : raw
+
+  console.log(
+    result.changed.length === 0
+      ? `${key} was already ${displayed}. Nothing written.`
+      : `${key} = ${displayed}`,
+  )
+  return 0
+}
+
+function coerce(raw: string, definition: SettingDefinition): unknown {
+  const type = typeof definition.default
+  if (type === 'boolean') {
+    if (['1', 'true', 'yes', 'on'].includes(raw.toLowerCase())) return true
+    if (['0', 'false', 'no', 'off'].includes(raw.toLowerCase())) return false
+    throw new ValidationError(`Expected a boolean, got "${raw}".`)
+  }
+  if (type === 'number') {
+    const value = Number(raw)
+    if (Number.isNaN(value)) throw new ValidationError(`Expected a number, got "${raw}".`)
+    return value
+  }
+  return raw
+}

package/src/context.ts

@@ -0,0 +1,77 @@
+import {
+  type AccountStore,
+  type AuthConfig,
+  DEFAULT_AUTH_POLICY,
+  IdentityService,
+  resolveAuthPolicy,
+} from '@meith/accounts'
+import { ConfigurationError, env } from '@meith/core'
+import {
+  createPostgresAccountStore,
+  type Database,
+  getDb,
+  PostgresAdminRepository,
+  PostgresForumRepository,
+  PostgresSettingsRepository,
+} from '@meith/db'
+import { SettingsSnapshot } from '@meith/settings'
+
+export interface CliContext {
+  readonly db: Database
+  readonly accounts: AccountStore
+  readonly identity: IdentityService
+  readonly forums: PostgresForumRepository
+  readonly settings: PostgresSettingsRepository
+  readonly admin: PostgresAdminRepository
+}
+
+export function requirePostgres(): void {
+  if (env.DATA_SOURCE !== 'postgres') {
+    throw new ConfigurationError(
+      'This command needs a database: DATA_SOURCE is "fixture".\n' +
+        'Set DATABASE_URL (see .env.example) and run `community migrate` first.',
+    )
+  }
+}
+
+export async function defaultMemberGroupId(admin: PostgresAdminRepository): Promise<number> {
+  const id = await admin.registeredGroupId()
+  if (id === null) {
+    throw new ConfigurationError(
+      'No "registered" usergroup found. Run `community migrate` to seed the group ladder.',
+    )
+  }
+  return id
+}
+
+export async function createContext(): Promise<CliContext> {
+  requirePostgres()
+  const db = getDb()
+  const admin = new PostgresAdminRepository(db)
+
+  const settings = new PostgresSettingsRepository(db)
+
+  const stored = SettingsSnapshot.fromOverrides(await settings.loadAll())
+
+  const config: AuthConfig = {
+    ...DEFAULT_AUTH_POLICY,
+    ...resolveAuthPolicy((key) => stored.get(key as never), {
+      ...DEFAULT_AUTH_POLICY,
+      activationMethod: 'none',
+    }),
+    registrationEnabled: true,
+    activationMethod: 'none',
+    defaultMemberGroupId: await defaultMemberGroupId(admin),
+  }
+
+  const store = createPostgresAccountStore(db)
+
+  return {
+    db,
+    accounts: store,
+    identity: new IdentityService({ store, config }),
+    forums: new PostgresForumRepository(db),
+    settings,
+    admin,
+  }
+}

package/src/demo.ts

@@ -0,0 +1,61 @@
+import { ConfigurationError, env } from '@meith/core'
+import { getDb } from '@meith/db'
+import { resetDemoBoard, seedDemoBoard } from '@meith/demo'
+import type { PluginDefinition } from '@meith/plugin-kit'
+
+import { requirePostgres } from './context'
+
+function requireDemoMode(): void {
+  if (!env.DEMO_MODE) {
+    throw new ConfigurationError(
+      'DEMO_MODE is not set, and this command destroys the board it is pointed ' +
+        'at. If this really is a demo, set DEMO_MODE=1 in the environment; if it ' +
+        'is not, you have the wrong DATABASE_URL.',
+    )
+  }
+}
+
+async function plugins(): Promise<readonly PluginDefinition[]> {
+  const { installedPluginDefinitions } = await import('@board/plugins')
+  return installedPluginDefinitions()
+}
+
+export async function demoSeed(): Promise<number> {
+  requirePostgres()
+  requireDemoMode()
+
+  const summary = await seedDemoBoard(getDb(), new Date(), { plugins: await plugins() })
+
+  console.log(
+    `Seeded ${summary.members} member(s), ${summary.forums} forum(s), ` +
+      `${summary.threads} thread(s) and ${summary.posts} post(s).`,
+  )
+  if (summary.plugins.length > 0) {
+    console.log(`Furnished plugin(s): ${summary.plugins.join(', ')}.`)
+  }
+  return 0
+}
+
+export async function demoReset(args: readonly string[]): Promise<number> {
+  requirePostgres()
+  requireDemoMode()
+
+  if (!args.includes('--yes')) {
+    console.error(
+      'This drops every table in the database and writes the demo board back.\n' +
+        'Nothing survives it. Re-run with --yes if that is what you want.',
+    )
+    return 1
+  }
+
+  const result = await resetDemoBoard({ db: getDb(), plugins: await plugins() })
+
+  console.log(
+    `Reset in ${Math.round(result.elapsedMs / 1000)}s: ` +
+      `${result.migrationsApplied} migration(s), ${result.members} member(s), ` +
+      `${result.forums} forum(s), ${result.threads} thread(s), ${result.posts} post(s)` +
+      `${result.plugins.length === 0 ? '' : `, plugin(s) ${result.plugins.join(', ')}`}.`,
+  )
+  console.log('Uploaded files are untouched — the web container clears those on its own reset.')
+  return 0
+}