@crombolo/cli 0.14.4 → 0.16.0

package/src/commands/types/sync.ts

@@ -0,0 +1,66 @@
+import { bootstrapDatabase, syncSchemaDirectory } from '@crombolo/server'
+import { Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeProblem, describeSync, printProblems } from '../../support/describe.ts'
+import { siteConfig } from '../../support/site.ts'
+import { needSchemaDir } from '../../support/types.ts'
+
+export default class TypesSync extends BaseCommand {
+  static override summary = 'apply schema/ to the database'
+  static override aliases = ['schema:sync']
+  static override deprecateAliases = true
+  static override flags = {
+    'force-retire-types': Flags.boolean({
+      summary: 'retire a type the files no longer have even though content uses it',
+    }),
+  }
+  static override audit = { category: 'schema', action: 'Sync', entityType: 'Schema' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      {
+        name: 'action',
+        type: 'string',
+        enum: ['applied', 'would-apply', 'skipped-same', 'skipped-older', 'refused'],
+      },
+      { name: 'changed', type: 'boolean' },
+      { name: 'summary', type: 'string' },
+      { name: 'problems', type: 'array', items: { type: 'string' } },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(TypesSync)
+    const config = await siteConfig()
+    needSchemaDir(config)
+    const { db } = await bootstrapDatabase(config)
+    try {
+      const report = await syncSchemaDirectory(
+        db,
+        config,
+        { nodeId: config.nodeId, revision: config.schemaRevision },
+        { forceRetireTypes: flags['force-retire-types'] },
+      )
+      if (report.problems.length > 0) printProblems(this, report.problems)
+      const summary = describeSync(report)
+      if (report.action === 'refused')
+        this.fail(
+          'refused',
+          `The schema was not applied: ${summary}.`,
+          undefined,
+          report.problems.map(describeProblem),
+        )
+      this.say(summary)
+      return {
+        action: report.action,
+        changed: report.action === 'applied',
+        summary,
+        problems: report.problems.map(describeProblem),
+      }
+    } finally {
+      await db.close()
+    }
+  }
+}

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/users/disable.ts

@@ -0,0 +1,54 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import {
+  checkStatus,
+  describeUser,
+  OBSERVER,
+  OPERATOR,
+  openPeople,
+  userNamed,
+} from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersDisable extends BaseCommand {
+  static override summary = 'stop a user signing in, and end their sessions'
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = { category: 'user', action: 'Disable', entityType: 'User' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'state', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersDisable)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const snapshot = async () => {
+        const found = await people.users.get(OBSERVER, user.key)
+        return found.status === 'Success'
+          ? { state: found.value.state, failed: found.value.failedLoginAttempts }
+          : { state: 'unknown', failed: 0 }
+      }
+      const before = await snapshot()
+      checkStatus(await people.users.setApproved(OPERATOR, [user.key], false))
+      const after = await snapshot()
+      const state = after.state
+      const changed = before.state !== after.state || before.failed !== after.failed
+      this.say(`  disabled  ${describeUser(user)}${changed ? '' : ' (no change)'}`)
+      return { id: user.key, email: user.email, state, changed }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/enable.ts

@@ -0,0 +1,54 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import {
+  checkStatus,
+  describeUser,
+  OBSERVER,
+  OPERATOR,
+  openPeople,
+  userNamed,
+} from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersEnable extends BaseCommand {
+  static override summary = 'let a disabled user sign in again'
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = { category: 'user', action: 'Enable', entityType: 'User' } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'state', type: 'string' },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found', 'refused'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersEnable)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const snapshot = async () => {
+        const found = await people.users.get(OBSERVER, user.key)
+        return found.status === 'Success'
+          ? { state: found.value.state, failed: found.value.failedLoginAttempts }
+          : { state: 'unknown', failed: 0 }
+      }
+      const before = await snapshot()
+      checkStatus(await people.users.setApproved(OPERATOR, [user.key], true))
+      const after = await snapshot()
+      const state = after.state
+      const changed = before.state !== after.state || before.failed !== after.failed
+      this.say(`  enabled   ${describeUser(user)}${changed ? '' : ' (no change)'}`)
+      return { id: user.key, email: user.email, state, changed }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/invite.ts

@@ -0,0 +1,82 @@
+import { UserGroupRepository } from '@crombolo/data'
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { many } from '../../support/flags.ts'
+import { checkStatus, OPERATOR, openPeople } from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersInvite extends BaseCommand {
+  static override summary = 'create a user and print the link they set their password with'
+  static override description =
+    'The link is printed rather than e-mailed, so it works on a site with no e-mail delivery. It is used once, and expires as an invitation does.'
+  static override examples = [
+    '<%= config.bin %> users invite editor@example.com --group editor --name "Ada Lovelace"',
+  ]
+  static override args = {
+    email: Args.string({ required: true, description: 'their e-mail address' }),
+  }
+  static override flags = {
+    group: many('a user group, by alias; repeatable', '<alias>'),
+    name: Flags.string({ summary: 'their name; the address when not given', helpValue: '<name>' }),
+  }
+  static override audit = { category: 'user', action: 'Invite', entityType: 'User' } as const
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'groups', type: 'array', items: { type: 'string' } },
+      { name: 'link', type: 'string' },
+    ],
+    errors: ['usage', 'not_found', 'conflict', 'refused'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(UsersInvite)
+    if (flags.group.length === 0)
+      this.fail('usage', 'An invited user needs at least one group.', 'Pass --group <alias>.')
+    const config = await siteConfig()
+    const people = await openPeople(config)
+    try {
+      const repository = new UserGroupRepository(people.db)
+      const groupKeys: string[] = []
+      for (const alias of flags.group) {
+        const group = await repository.byAlias(alias)
+        if (!group)
+          this.fail(
+            'not_found',
+            `There is no user group "${alias}".`,
+            `It has: ${(await repository.all()).map((g) => g.alias).join(', ')}.`,
+          )
+        groupKeys.push(group.key)
+      }
+      const result = await people.users.invite(
+        OPERATOR,
+        {
+          kind: 'Default',
+          email: args.email,
+          userName: args.email,
+          name: flags.name ?? args.email,
+          groupKeys,
+        },
+        null,
+      )
+      checkStatus(result.status)
+      const id = result.status === 'Success' ? result.value : ''
+      this.auditKey = id
+      const captured = people.lastLink() ?? ''
+      // Without an application URL the link is relative: it is the path on the site's own address.
+      const link = config.applicationUrl ? captured : captured.replace(/^[^/]*/, '')
+      this.say(`  invited  ${args.email} to ${flags.group.join(', ')}`)
+      this.say(link)
+      if (!config.applicationUrl)
+        this.warning(
+          '  note     the link is a path on the site: set CROMBOLO_APPLICATION_URL to print the whole address',
+        )
+      return { id, email: args.email, groups: flags.group, link }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/list.ts

@@ -0,0 +1,62 @@
+import { UserGroupRepository } from '@crombolo/data'
+import { BaseCommand } from '../../base.ts'
+import { page, pageFlags, pagination } from '../../support/flags.ts'
+import { OBSERVER, openPeople } from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersList extends BaseCommand {
+  static override summary = 'the back-office users: who, their groups, their state and last sign-in'
+  static override flags = { ...pageFlags(50) }
+  static override spec = {
+    effects: 'read_only',
+    cardinality: 'unbounded',
+    pagination,
+    fieldsArg: '--fields',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'name', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'userName', type: 'string' },
+      { name: 'kind', type: 'string', enum: ['Default', 'Api'] },
+      { name: 'state', type: 'string' },
+      { name: 'groups', type: 'array', items: { type: 'string' } },
+      { name: 'failedLoginAttempts', type: 'integer' },
+      { name: 'lastLoginDate', type: 'string', nullable: true },
+    ],
+  } as const
+
+  async run() {
+    const { flags } = await this.parse(UsersList)
+    const people = await openPeople(await siteConfig())
+    try {
+      const found = await people.users.list(OBSERVER, flags.offset, flags.limit)
+      const groups = new Map(
+        (await new UserGroupRepository(people.db).all()).map((g) => [g.key, g.alias]),
+      )
+      const items = found.items.map((user) => ({
+        id: user.id,
+        name: user.name,
+        email: user.email,
+        userName: user.userName,
+        kind: user.kind,
+        state: user.state,
+        groups: user.userGroupIds.map((g) => groups.get(g.id) ?? g.id),
+        failedLoginAttempts: user.failedLoginAttempts,
+        lastLoginDate: user.lastLoginDate ?? null,
+      }))
+      if (items.length === 0) this.say('No users.')
+      for (const user of items)
+        this.say(
+          `  ${user.state.padEnd(9)} ${user.name} <${user.email || user.userName}>  ${user.groups.join(', ') || 'no groups'}` +
+            `${user.lastLoginDate ? `  last in ${user.lastLoginDate}` : '  never signed in'}`,
+        )
+      if (flags.offset + items.length < found.total)
+        this.say(
+          `  … ${found.total - flags.offset - items.length} more: --offset ${flags.offset + items.length}`,
+        )
+      return page(items, found.total, flags)
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/reset-2fa.ts

@@ -0,0 +1,48 @@
+import { Args } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { describeUser, openPeople, userNamed } from '../../support/people.ts'
+import { siteConfig } from '../../support/site.ts'
+
+/** For someone who has lost their authenticator: their next sign-in enrols again. */
+export default class UsersReset2fa extends BaseCommand {
+  static override summary =
+    "remove a user's second factors, so their next sign-in sets one up again"
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = {
+    category: 'user',
+    action: 'ResetTwoFactor',
+    entityType: 'User',
+  } as const
+  static override spec = {
+    effects: 'idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      { name: 'removed', type: 'array', items: { type: 'string' } },
+      { name: 'changed', type: 'boolean' },
+    ],
+    errors: ['not_found'],
+  } as const
+
+  async run() {
+    const { args } = await this.parse(UsersReset2fa)
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      const removed = await people.twoFactor.providers(user.key)
+      await people.twoFactor.reset(user.key)
+      this.say(
+        removed.length > 0
+          ? `  removed  ${removed.join(', ')} from ${describeUser(user)}`
+          : `  ${describeUser(user)} has no second factor; nothing changed`,
+      )
+      return { id: user.key, email: user.email, removed, changed: removed.length > 0 }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/commands/users/reset-password.ts

@@ -0,0 +1,58 @@
+import { Args, Flags } from '@oclif/core'
+import { BaseCommand } from '../../base.ts'
+import { checkStatus, describeUser, OPERATOR, openPeople, userNamed } from '../../support/people.ts'
+import { readStdin } from '../../support/prompt.ts'
+import { siteConfig } from '../../support/site.ts'
+
+export default class UsersResetPassword extends BaseCommand {
+  static override summary = 'give a user a new password, and end their sessions'
+  static override description =
+    "A new one is generated and printed, unless --stdin gives it. `admin reset-password` does the same for the site's own administrator."
+  static override examples = [
+    '<%= config.bin %> users reset-password editor@example.com',
+    'printf %s "$PASSWORD" | <%= config.bin %> users reset-password editor@example.com --stdin',
+  ]
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override flags = { stdin: Flags.boolean({ summary: 'read the new password from stdin' }) }
+  static override audit = { category: 'user', action: 'ResetPassword', entityType: 'User' } as const
+  static override spec = {
+    effects: 'non_idempotent',
+    cardinality: 'single',
+    outputFields: [
+      { name: 'id', type: 'string' },
+      { name: 'email', type: 'string' },
+      {
+        name: 'password',
+        type: 'string',
+        nullable: true,
+        description: 'the generated one; null when given',
+      },
+    ],
+    errors: ['not_found', 'usage', 'refused'],
+  } as const
+
+  async run() {
+    const { args, flags } = await this.parse(UsersResetPassword)
+    const given = flags.stdin ? await readStdin() : undefined
+    if (flags.stdin && !given) this.fail('usage', 'Nothing came on stdin to use as the password.')
+    const people = await openPeople(await siteConfig())
+    try {
+      const user = await userNamed(people, args.user)
+      this.auditKey = user.key
+      let password: string | null = null
+      if (given) checkStatus(await people.users.changePassword(OPERATOR, user.key, given, null))
+      else {
+        const result = await people.users.resetPassword(OPERATOR, user.key)
+        checkStatus(result.status)
+        password = result.status === 'Success' ? result.value : null
+      }
+      this.say(`  reset    ${describeUser(user)}; their sessions are ended`)
+      if (password) this.say(password)
+      return { id: user.key, email: user.email, password }
+    } finally {
+      await people.db.close()
+    }
+  }
+}