@crombolo/cli 0.14.4 → 0.15.0

package/src/commands/upgrade/check.ts

@@ -0,0 +1,69 @@
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { findingsOf, printFindings } from '../../support/describe.ts'
+import { backupTaken, many } from '../../support/flags.ts'
+import { siteConfig } from '../../support/site.ts'
+import { parseSet, upgradeCheck } from '../../support/types.ts'
+
+export default class UpgradeCheck extends BaseCommand {
+  static override summary = "what the deployed schema/ would do to this database's data"
+  static override description = [
+    'Exits 21 when a finding needs a person first.',
+    '--fix backs up, then applies the additive part and every conversion early, so the cut-over is short.',
+  ].join('\n\n')
+  static override flags = {
+    fix: Flags.boolean({
+      summary: 'back up, then apply the additive part and every conversion early',
+    }),
+    set: many('a value for a new mandatory property: <type>.<property>=<value>', '<t.p=v>'),
+    'backup-taken': backupTaken,
+  }
+  static override audit = { category: 'system', action: 'UpgradeFix' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'classification', type: 'string' },
+      { name: 'findings', type: 'array', items: { type: 'object' } },
+      { name: 'blocking', type: 'boolean' },
+      { name: 'applied', type: 'array', items: { type: 'string' } },
+      { name: 'backup', type: 'string', nullable: true },
+    ],
+    outcomes: ['blocked'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(UpgradeCheck)
+    const config = await siteConfig()
+    const set = parseSet(flags.set)
+    if (!flags.fix) {
+      this.changedNothing = true
+      const report = await upgradeCheck(this, config, set)
+      if (report.blocking) this.outcome = 'blocked'
+      return {
+        classification: report.classification,
+        findings: findingsOf(report.findings),
+        blocking: report.blocking,
+        applied: [],
+        backup: null,
+      }
+    }
+    const fix = await ops.upgradeFix(config, { set, backupTaken: flags['backup-taken'] })
+    if (fix.backup.path) this.progress(`  backup   ${fix.backup.path}`)
+    this.say(
+      `  sync     ${fix.sync.action}${fix.sync.deferred.length > 0 ? ` (deferred to the cut-over: ${fix.sync.deferred.join(', ')})` : ''}`,
+    )
+    for (const name of fix.applied) this.say(`  applied  ${name}`)
+    if (fix.skipped > 0)
+      this.say(`  skipped  ${fix.skipped} value(s) a converter refused; see the findings`)
+    printFindings(this, fix)
+    return {
+      classification: fix.classification,
+      findings: findingsOf(fix.findings),
+      blocking: fix.findings.some((f) => f.kind === 'blocking'),
+      applied: fix.applied,
+      backup: fix.backup.path ?? null,
+    }
+  }
+}

package/src/commands/upgrade/index.ts

@@ -0,0 +1,120 @@
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import * as ops from '../../operations/commands.ts'
+import { findingsOf } from '../../support/describe.ts'
+import { backupTaken, many } from '../../support/flags.ts'
+import { siteConfig } from '../../support/site.ts'
+import { parseSet } from '../../support/types.ts'
+
+export default class Upgrade extends BaseCommand {
+  static override summary = 'back up, apply pending framework migrations, cut over, and record them'
+  static override description = [
+    'Re-checks first, and refuses while a finding is outstanding; `upgrade check --fix` resolves what it can early.',
+    '--plan prints the DDL each pending migration would run, and changes nothing.',
+  ].join('\n\n')
+  static override flags = {
+    plan: Flags.boolean({
+      summary: 'print the DDL pending framework migrations would run, and stop',
+    }),
+    force: Flags.string({
+      summary: 'go on over outstanding findings, saying why',
+      helpValue: '<reason>',
+    }),
+    set: many('a value for a new mandatory property: <type>.<property>=<value>', '<t.p=v>'),
+    'backup-taken': backupTaken,
+  }
+  static override audit = { category: 'system', action: 'Upgrade' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'action', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+      { name: 'backup', type: 'string', nullable: true },
+      { name: 'frameworkApplied', type: 'array', items: { type: 'string' } },
+      { name: 'bundlesApplied', type: 'array', items: { type: 'object' } },
+      { name: 'schema', type: 'object', nullable: true },
+      { name: 'plan', type: 'object', nullable: true },
+    ],
+    errors: ['refused'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(Upgrade)
+    const config = await siteConfig()
+    if (flags.plan) {
+      this.changedNothing = true
+      const plan = await ops.upgradePlan(config)
+      if (plan.steps.length === 0) this.say('No framework migration is pending.')
+      const printStep = (step: ops.PlannedStepResult, indent = '') => {
+        this.say(
+          `\n${indent}== ${step.name} (${step.kind}${step.release ? `, release ${step.release}` : ''})`,
+        )
+        if (step.unplannable) this.say(`${indent}  unplannable: ${step.unplannable}`)
+        for (const sql of step.statements) this.say(`${indent}  ${sql};`)
+      }
+      for (const step of plan.steps) printStep(step)
+      // After core's, in the order `bundles` lists them, because that is the order they run.
+      for (const bundle of plan.bundles) {
+        this.say(
+          `\nbundle ${bundle.id} (${bundle.name}): ${bundle.steps.length === 0 ? 'nothing pending' : `${bundle.steps.length} step(s)`}`,
+        )
+        for (const step of bundle.steps) printStep(step, '  ')
+      }
+      this.say(
+        plan.site.checked
+          ? `\nsite schema: ${plan.site.action} (${plan.site.classification})`
+          : '\nsite schema: checked once the framework migrations have run',
+      )
+      return {
+        action: 'plan',
+        changed: false,
+        backup: null,
+        frameworkApplied: [],
+        bundlesApplied: [],
+        schema: null,
+        plan,
+      }
+    }
+    const result = await ops.upgradeRun(config, {
+      force: flags.force,
+      set: parseSet(flags.set),
+      backupTaken: flags['backup-taken'],
+    })
+    if (result.backup.path) this.progress(`  backup   ${result.backup.path}`)
+    if (result.action === 'refused')
+      this.fail(
+        'refused',
+        `upgrade refused: ${result.reasons.length} outstanding finding(s).`,
+        'Run `crombolo upgrade check --fix`, resolve what needs a person, and try again.',
+        findingsOf(result.reasons),
+      )
+    if (result.action === 'nothing') {
+      this.say('Nothing to upgrade: the database is at this version.')
+      return {
+        action: result.action,
+        changed: false,
+        backup: result.backup.path ?? null,
+        frameworkApplied: [],
+        bundlesApplied: [],
+        schema: null,
+        plan: null,
+      }
+    }
+    for (const name of result.frameworkApplied) this.say(`  applied  ${name}`)
+    for (const bundle of result.bundlesApplied)
+      for (const name of bundle.applied) this.say(`  applied  [${bundle.id}] ${name}`)
+    this.say(
+      `  schema   ${result.schema?.action} ${result.schema?.version ?? ''}+${result.schema?.revision ?? ''}`,
+    )
+    return {
+      action: result.action,
+      changed: true,
+      backup: result.backup.path ?? null,
+      frameworkApplied: result.frameworkApplied,
+      bundlesApplied: result.bundlesApplied,
+      schema: result.schema ?? null,
+      plan: null,
+    }
+  }
+}

package/src/commands/upgrade/ledger.ts

@@ -0,0 +1,55 @@
+import { connect, readLedger } from '@crombolo/data'
+import { BaseCommand } from '../../base.ts'
+import { page, pageFlags, pagination } from '../../support/flags.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UpgradeLedger extends BaseCommand {
+  static override summary = 'print migration_history: every migration, sync and import applied here'
+  static override flags = { ...pageFlags(1000) }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'unbounded',
+    pagination,
+    fieldsArg: '--fields',
+    outputFields: [
+      { name: 'id', type: 'integer' },
+      { name: 'name', type: 'string' },
+      { name: 'kind', type: 'string' },
+      { name: 'appliedAt', type: 'string' },
+      { name: 'durationMs', type: 'integer' },
+      { name: 'appliedBy', type: 'string', nullable: true },
+      { name: 'bundle', type: 'string', nullable: true },
+      { name: 'note', type: 'string', nullable: true },
+    ],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(UpgradeLedger)
+    const config = await siteConfig()
+    const db = await connect({ file: config.sqliteFile })
+    try {
+      const rows = await readLedger(db)
+      const items = rows.slice(flags.offset, flags.offset + flags.limit).map((row) => ({
+        id: row.id,
+        name: row.name,
+        kind: row.kind,
+        appliedAt: row.appliedAt,
+        durationMs: row.durationMs,
+        appliedBy: row.appliedBy ?? null,
+        bundle: row.bundle ?? null,
+        note: row.note ?? null,
+      }))
+      for (const row of items)
+        this.say(
+          `  ${row.appliedAt}  ${row.kind.padEnd(8)} ${row.bundle ? `[${row.bundle}] ` : ''}${row.name}  ${row.durationMs}ms${row.appliedBy ? `  by ${row.appliedBy}` : ''}${row.note ? `  (${row.note})` : ''}`,
+        )
+      if (flags.offset + items.length < rows.length)
+        this.say(
+          `  … ${rows.length - flags.offset - items.length} more: --offset ${flags.offset + items.length}`,
+        )
+      return page(items, rows.length, flags)
+    } finally {
+      await db.close()
+    }
+  }
+}

package/src/commands/whoami.ts

@@ -0,0 +1,41 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../base.ts'
+import { problemOf } from '../remote/client.ts'
+import { connectRemote } from '../support/remote.ts'
+
+export default class Whoami extends BaseCommand {
+  static override summary = 'who you are signed in as at a remote, and what you may do there'
+  static override args = {
+    remote: Args.string({ description: 'the remote; the only one, when there is one' }),
+  }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'name', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'remote', type: 'string' },
+      { name: 'environments', type: 'array', items: { type: 'object' } },
+    ],
+    errors: ['not_found', 'auth', 'unavailable'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(Whoami)
+    const { entry, client, discovery } = await connectRemote(args.remote, undefined)
+    const response = await client.call(
+      `${new URL(discovery.api).origin}/umbraco/management/api/v1/user/current`,
+    )
+    if (!response.ok) throw await problemOf(response)
+    const me = (await response.json()) as { name: string; email: string }
+    this.say(`  ${me.name} <${me.email}> on ${entry.name}`)
+    const environments = await client.environments()
+    for (const env of environments) {
+      const may = [env.may.pull && 'pull', env.may.pullFull && 'full pull', env.may.push && 'push']
+        .filter(Boolean)
+        .join(', ')
+      this.say(`  ${env.id.padEnd(12)} ${may || 'nothing'}${env.protected ? '  (protected)' : ''}`)
+    }
+    return { name: me.name, email: me.email, remote: entry.name, environments }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,90 @@
+/**
+ * How a command fails, and what it exits with (story 150). Every failure is a
+ * kind with one exit code, so a script can branch on `$?` and a machine can read
+ * the envelope; an outcome is a finding the command was asked to look for, which
+ * exits non-zero with no envelope.
+ */
+
+/** Each kind's exit code. The table in `docs/operations.md` § Exit codes is this one. */
+export const ERROR_KINDS = {
+  internal: { exitCode: 1, description: 'Something unexpected went wrong.' },
+  usage: {
+    exitCode: 2,
+    description: 'The arguments are wrong: an unknown command or flag, or one missing.',
+  },
+  timeout: {
+    exitCode: 3,
+    description: 'Gave up waiting. A remote job carries on at the remote.',
+    retryable: true,
+  },
+  auth: {
+    exitCode: 4,
+    description: 'Not signed in, the sign-in has lapsed, or a passphrase is missing or wrong.',
+  },
+  not_found: {
+    exitCode: 5,
+    description: 'No such remote, environment, page, run, bundle, file or account.',
+  },
+  conflict: {
+    exitCode: 6,
+    description: 'Someone else is changing it, or it exists with a different value.',
+    retryable: true,
+  },
+  confirmation_required: {
+    exitCode: 7,
+    description: 'It would have asked first, and there is no terminal to ask on.',
+  },
+  refused: {
+    exitCode: 8,
+    description:
+      'The site or the remote said no: findings outstanding, a permission, a protected environment.',
+  },
+  unavailable: {
+    exitCode: 9,
+    description: 'The database or the remote could not be reached.',
+    retryable: true,
+  },
+  io: { exitCode: 10, description: 'A file could not be read or written.' },
+  interrupted: { exitCode: 130, description: 'Stopped by a signal.' },
+} as const satisfies Record<string, { exitCode: number; description: string; retryable?: boolean }>
+
+export type ErrorKind = keyof typeof ERROR_KINDS
+
+/** Findings a command was asked to look for. Their details are the command's normal output. */
+export const OUTCOMES = {
+  problems_found: {
+    code: 20,
+    description: 'The check found problems: `status`, `types check`, `components check`.',
+  },
+  blocked: {
+    code: 21,
+    description:
+      'Something must be resolved by a person first: `content check`, `upgrade check`, `import umbraco report`.',
+  },
+} as const
+
+export type OutcomeName = keyof typeof OUTCOMES
+
+/** A failure with a kind, a sentence, and what to do about it. */
+export class CliError extends Error {
+  readonly hint?: string
+  readonly details?: unknown
+  constructor(
+    readonly kind: ErrorKind,
+    message: string,
+    options: { hint?: string; details?: unknown } = {},
+  ) {
+    super(message)
+    this.hint = options.hint
+    this.details = options.details
+  }
+}
+
+/** The command finished, and found what it reports: exit with the outcome's code, no envelope. */
+export class Outcome extends Error {
+  constructor(readonly outcome: OutcomeName) {
+    super(outcome)
+  }
+}
+
+export const exitCodeOf = (kind: ErrorKind): number => ERROR_KINDS[kind].exitCode

package/src/main.ts

@@ -0,0 +1,23 @@
+/**
+ * Runs the CLI. A failure inside a command is reported by the command
+ * (`BaseCommand.catch`); one before any command runs — an unknown command —
+ * is reported here the same way, so every failure has a kind and an exit code.
+ */
+import { Errors, flush, run } from '@oclif/core'
+import { wantsJson } from './base.ts'
+import { classify, reportFailure } from './classify.ts'
+import { exitCodeOf } from './errors.ts'
+
+export async function main(dir: string, argv: string[] = process.argv.slice(2)): Promise<void> {
+  try {
+    await run(argv, dir)
+    await flush()
+  } catch (error) {
+    if (error instanceof Errors.ExitError) process.exit(error.oclif.exit ?? 0)
+    const failure = classify(error)
+    if (failure.kind === 'usage' && !failure.hint)
+      Object.assign(failure, { hint: '`crombolo --help` lists the commands.' })
+    reportFailure(failure, wantsJson(argv))
+    process.exit(exitCodeOf(failure.kind))
+  }
+}

package/src/manifest.ts

@@ -0,0 +1,20 @@
+/**
+ * The CLI's `oclif.manifest.json`: every command's args, flags and clispec
+ * `spec`, cached so a start reads one file rather than importing every command.
+ */
+import { join } from 'node:path'
+import { Config, type Interfaces } from '@oclif/core'
+
+export const CLI_DIR = join(import.meta.dir, '..')
+export const MANIFEST_FILE = join(CLI_DIR, 'oclif.manifest.json')
+
+export async function buildManifest(): Promise<Interfaces.Manifest> {
+  const config = await Config.load(CLI_DIR)
+  const commands = Object.fromEntries(
+    config.commands
+      .map((command) => [command.id, command] as const)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  )
+  // Through JSON, as oclif reads it back: each command's `load` is dropped.
+  return JSON.parse(JSON.stringify({ commands, version: config.version })) as Interfaces.Manifest
+}

package/src/reference.ts

@@ -0,0 +1,118 @@
+/**
+ * The command line reference as HTML, for the product site's developer pages:
+ * built from the CLI manifest's data, through the same clispec description
+ * `crombolo schema` prints, so the page cannot say anything the CLI does not.
+ */
+import type { Interfaces } from '@oclif/core'
+import { clispecDocument } from './clispec.ts'
+
+const escapeHtml = (text: string): string =>
+  text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+
+const code = (text: string) => `<code>${escapeHtml(text)}</code>`
+
+interface Arg {
+  name: string
+  type: string
+  short?: string
+  required?: boolean
+  default?: unknown
+  enum?: unknown[]
+  description?: string
+}
+
+function usage(name: string, args: Arg[]): string {
+  const words = args.map((arg) => {
+    if (!arg.name.startsWith('--')) return arg.required ? `<${arg.name}>` : `[<${arg.name}>]`
+    const flag = arg.type === 'boolean' ? arg.name : `${arg.name} <${arg.name.slice(2)}>`
+    return arg.required ? flag : `[${flag}]`
+  })
+  return ['crombolo', name, ...words].join(' ')
+}
+
+/** A summary written for `--help` — "apply schema/ to the database" — as a sentence. */
+const sentence = (text: string): string => {
+  const trimmed = text.trim()
+  if (!trimmed) return ''
+  const capital = `${trimmed.charAt(0).toUpperCase()}${trimmed.slice(1)}`
+  return /[.!?]$/.test(capital) ? capital : `${capital}.`
+}
+
+function argRow(arg: Arg): string {
+  const name = [arg.short, arg.name].filter(Boolean).join(', ')
+  const notes = [
+    arg.description ? escapeHtml(sentence(arg.description)) : '',
+    arg.enum ? `One of ${arg.enum.map((v) => code(String(v))).join(', ')}.` : '',
+    arg.default !== undefined ? `Default ${code(String(arg.default))}.` : '',
+    arg.required ? 'Required.' : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+  return `<tr><td>${code(name)}</td><td>${notes}</td></tr>`
+}
+
+const EFFECTS: Record<string, string> = {
+  read_only: 'Changes nothing.',
+  idempotent: 'Safe to run again: a second run changes nothing more.',
+  non_idempotent: 'Each run acts again.',
+}
+
+/** The reference, grouped by the first word of each command. */
+export function cliReferenceHtml(manifest: Interfaces.Manifest): string {
+  const document = clispecDocument({
+    bin: 'crombolo',
+    version: manifest.version,
+    commands: Object.values(manifest.commands),
+  })
+  const groups = new Map<string, typeof document.commands>()
+  for (const command of document.commands) {
+    const group = String(command.name).split(' ')[0] as string
+    groups.set(group, [...(groups.get(group) ?? []), command])
+  }
+  const parts: string[] = [
+    '<p>Every command, generated from the CLI itself. Each takes ' +
+      `${code('--help')} for this page's entry, and ${code('-o json')} for a result a script can read. ` +
+      `${code('crombolo schema')} prints the same description for a machine, as a ` +
+      '<a href="https://clispec.dev">clispec</a> document.</p>',
+  ]
+  for (const [group, commands] of groups) {
+    parts.push(`<h2 id="${escapeHtml(group)}">${escapeHtml(group)}</h2>`)
+    for (const command of commands) {
+      const name = String(command.name)
+      const args = ((command.args as Arg[] | undefined) ?? []).slice()
+      parts.push(
+        `<h3 id="${escapeHtml(name.replaceAll(' ', '-'))}">${code(`crombolo ${name}`)}</h3>`,
+      )
+      parts.push(
+        `<p>${escapeHtml(sentence(String(command.description)))} ${EFFECTS[String(command.effects)] ?? ''}</p>`,
+      )
+      parts.push(`<pre><code>${escapeHtml(usage(name, args))}</code></pre>`)
+      if (args.length > 0)
+        parts.push(
+          `<table><thead><tr><th>Argument</th><th>What it is</th></tr></thead><tbody>${args.map(argRow).join('')}</tbody></table>`,
+        )
+    }
+  }
+  parts.push('<h2 id="exit-codes">Exit codes</h2>')
+  parts.push(
+    `<p>A failure exits with its kind's code; with ${code('-o json')}, or whenever stderr is not a terminal, ` +
+      "the last line of stderr is a JSON envelope naming the kind. A check that finds what it looks for exits with an outcome's code, and its findings are its output.</p>",
+  )
+  const rows = [
+    ...document.errors.map((e) => [String(e.exit_code), e.kind, e.description] as const),
+    ...document.outcomes.map((o) => [String(o.code), o.name, o.description] as const),
+  ].sort((a, b) => Number(a[0]) - Number(b[0]))
+  parts.push(
+    `<table><thead><tr><th>Code</th><th>Kind</th><th>When</th></tr></thead><tbody>${rows
+      .map(
+        ([codeNumber, kind, description]) =>
+          `<tr><td>${codeNumber}</td><td>${code(kind)}</td><td>${escapeHtml(description).replaceAll(/`([^`]+)`/g, '<code>$1</code>')}</td></tr>`,
+      )
+      .join('')}</tbody></table>`,
+  )
+  return parts.join('\n')
+}

package/src/remote/client.ts

@@ -55,19 +55,28 @@ export async function discover(url: string, http: typeof fetch = fetch): Promise
   try {
     response = await http(`${origin}/.well-known/crombolo-remote`)
   } catch (error) {
-    throw new Error(
-      `${origin} could not be reached: ${error instanceof Error ? error.message : error}`,
-    )
+    throw new RemoteError({
+      status: 0,
+      code: 'unreachable',
+      title: `${origin} could not be reached: ${error instanceof Error ? error.message : error}`,
+    })
   }
-  if (response.status === 404) throw new Error(`${origin} is not a crombolo remote.`)
-  if (!response.ok)
-    throw new Error(`${origin} answered ${response.status} for its discovery document.`)
+  const notARemote = () =>
+    new RemoteError({
+      status: 404,
+      code: 'not-a-remote',
+      title: `${origin} is not a crombolo remote.`,
+    })
+  if (response.status === 404) throw notARemote()
+  if (!response.ok) throw await problemOf(response)
   const body = (await response.json()) as Discovery
-  if (body.protocol !== 'crombolo-remote') throw new Error(`${origin} is not a crombolo remote.`)
+  if (body.protocol !== 'crombolo-remote') throw notARemote()
   if (!body.versions?.includes(PROTOCOL_VERSION))
-    throw new Error(
-      `${origin} speaks protocol ${body.versions?.join(', ') || 'none'}; this crombolo speaks ${PROTOCOL_VERSION}.`,
-    )
+    throw new RemoteError({
+      status: 0,
+      code: 'protocol-version',
+      title: `${origin} speaks protocol ${body.versions?.join(', ') || 'none'}; this crombolo speaks ${PROTOCOL_VERSION}.`,
+    })
   return body
 }
 

package/src/remote/remotes-file.ts

@@ -6,8 +6,9 @@
  *   url = "https://example.com"
  *   environment = "production"
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { writeFileAtomic } from '@crombolo/server'
 
 export const REMOTES_FILE = 'remotes.toml'
 
@@ -50,7 +51,7 @@ export function writeRemotes(siteDir: string, remotes: readonly RemoteEntry[]):
     lines.push('', `[remotes.${remote.name}]`, `url = ${quote(remote.url)}`)
     if (remote.environment) lines.push(`environment = ${quote(remote.environment)}`)
   }
-  writeFileSync(join(siteDir, REMOTES_FILE), `${lines.join('\n')}\n`)
+  writeFileAtomic(join(siteDir, REMOTES_FILE), `${lines.join('\n')}\n`)
 }
 
 /** Adds or replaces one, refusing a name that would not survive as a TOML key. */