@crombolo/cli 0.15.0 → 0.16.0

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()
+    }
+  }
+}

package/src/commands/users/unlock.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 UsersUnlock extends BaseCommand {
+  static override summary = "clear a user's lockout and failed sign-ins"
+  static override args = {
+    user: Args.string({ required: true, description: 'their e-mail address or username' }),
+  }
+  static override audit = { category: 'user', action: 'Unlock', 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(UsersUnlock)
+    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.unlock(OPERATOR, [user.key]))
+      const after = await snapshot()
+      const state = after.state
+      const changed = before.state !== after.state || before.failed !== after.failed
+      this.say(`  unlocked  ${describeUser(user)}${changed ? '' : ' (no change)'}`)
+      return { id: user.key, email: user.email, state, changed }
+    } finally {
+      await people.db.close()
+    }
+  }
+}

package/src/load.ts

@@ -0,0 +1,59 @@
+/**
+ * The CLI's commands, with the optional plugins found beside it (story 158).
+ *
+ * oclif loads a plugin only when the CLI's own `package.json` depends on it,
+ * and warns when one is missing; an optional plugin is neither. So each name in
+ * `oclif.optionalPlugins` is looked for here — in the site's `node_modules`,
+ * then beside the CLI, as a global install puts it — loaded when it is found,
+ * and passed over in silence when it is not.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { Config, Plugin } from '@oclif/core'
+import { CLI_DIR } from './manifest.ts'
+
+/** The directory a package is installed in, looked for from each of `from` upward. */
+export function findInstalled(name: string, from: readonly string[]): string | undefined {
+  for (const start of from) {
+    let dir = start
+    for (;;) {
+      const candidate = join(dir, 'node_modules', name)
+      if (existsSync(join(candidate, 'package.json'))) return candidate
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  }
+  return undefined
+}
+
+export function optionalPlugins(): string[] {
+  const pjson = JSON.parse(readFileSync(join(CLI_DIR, 'package.json'), 'utf8')) as {
+    oclif?: { optionalPlugins?: string[] }
+  }
+  return pjson.oclif?.optionalPlugins ?? []
+}
+
+export interface LoadedCli {
+  config: Config
+  /** The optional plugins that are not installed. */
+  missing: string[]
+}
+
+export async function loadCli(cwd: string = process.cwd()): Promise<LoadedCli> {
+  const root = new Plugin({ root: CLI_DIR, isRoot: true, type: 'core' })
+  await root.load()
+  const plugins = new Map<string, Plugin>([[root.name, root]])
+  const missing: string[] = []
+  for (const name of optionalPlugins()) {
+    const dir = findInstalled(name, [cwd, CLI_DIR])
+    if (!dir) {
+      missing.push(name)
+      continue
+    }
+    const plugin = new Plugin({ root: dir, name, type: 'core' })
+    await plugin.load()
+    plugins.set(plugin.name, plugin)
+  }
+  return { config: await Config.load({ root: CLI_DIR, plugins }), missing }
+}

package/src/main.ts

@@ -5,15 +5,33 @@
  */
 import { Errors, flush, run } from '@oclif/core'
 import { wantsJson } from './base.ts'
-import { classify, reportFailure } from './classify.ts'
-import { exitCodeOf } from './errors.ts'
+import { CliError, exitCodeOf } from './errors.ts'
+import { loadCli } from './load.ts'
 
-export async function main(dir: string, argv: string[] = process.argv.slice(2)): Promise<void> {
+/** The topic each optional plugin brings, and how to add it. */
+const PLUGIN_TOPICS: Record<string, { topic: string; what: string }> = {
+  '@crombolo/cloud': { topic: 'cloud', what: 'Crombolo Cloud' },
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
   try {
-    await run(argv, dir)
+    const { config, missing } = await loadCli()
+    const absent = missing
+      .map((name) => ({ name, ...PLUGIN_TOPICS[name] }))
+      .find((plugin) => plugin.topic && argv[0] === plugin.topic)
+    if (absent)
+      throw new CliError(
+        'usage',
+        `\`crombolo ${absent.topic}\` comes with the ${absent.what} plugin, which is not installed.`,
+        {
+          hint: `Add it to the site: bun add -d ${absent.name}`,
+        },
+      )
+    await run(argv, config)
     await flush()
   } catch (error) {
     if (error instanceof Errors.ExitError) process.exit(error.oclif.exit ?? 0)
+    const { classify, reportFailure } = await import('./classify.ts')
     const failure = classify(error)
     if (failure.kind === 'usage' && !failure.hint)
       Object.assign(failure, { hint: '`crombolo --help` lists the commands.' })

package/src/manifest.ts

@@ -18,3 +18,13 @@ export async function buildManifest(): Promise<Interfaces.Manifest> {
   // 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
 }
+
+/** The manifest's shape for any loaded config: the CLI's commands and its plugins'. */
+export function manifestOf(config: Config): Interfaces.Manifest {
+  const commands = Object.fromEntries(
+    config.commands
+      .map((command) => [command.id, command] as const)
+      .sort(([a], [b]) => a.localeCompare(b)),
+  )
+  return JSON.parse(JSON.stringify({ commands, version: config.version })) as Interfaces.Manifest
+}

package/src/plugin.ts

@@ -0,0 +1,38 @@
+/**
+ * `@crombolo/cli/plugin`: what a plugin's commands are built from (story 158),
+ * so that they behave like the CLI's own — the global flags, the JSON envelope,
+ * the exit codes, an entry in `crombolo schema` — and sign in where `crombolo
+ * login` does. Covered by semver like the main entry. It loads none of the
+ * CLI's commands, and none of the site packages until a command fails.
+ *
+ *   import { Args, BaseCommand, Flags } from '@crombolo/cli/plugin'
+ *
+ *   export default class CloudStatus extends BaseCommand {
+ *     static override summary = 'what the platform says about this site'
+ *     static override spec = { effects: 'read_only', cardinality: 'single', outputFields: [...] } as const
+ *     async run() { … return result }
+ *   }
+ */
+export { Args, Flags } from '@oclif/core'
+export type { AuditSpec, CommandSpec, OutputField } from './base.ts'
+export { BaseCommand } from './base.ts'
+export {
+  CliError,
+  ERROR_KINDS,
+  type ErrorKind,
+  exitCodeOf,
+  OUTCOMES,
+  type OutcomeName,
+} from './errors.ts'
+export {
+  type Discovery,
+  discover,
+  type Job,
+  problemOf,
+  RemoteClient,
+  RemoteError,
+  signIn,
+  TimedOut,
+} from './remote/client.ts'
+export { keychain, openInBrowser } from './support/remote.ts'
+export type { Io } from './support/site.ts'

package/src/remote/client.ts

@@ -6,7 +6,12 @@
  */
 import { createHash } from 'node:crypto'
 import { createWriteStream } from 'node:fs'
-import { freshAccessToken, type Keychain, readSignIn, saveSignIn } from '@crombolo/server'
+import {
+  freshAccessToken,
+  type Keychain,
+  readSignIn,
+  saveSignIn,
+} from '@crombolo/server/remote-credentials'
 
 export const PROTOCOL_VERSION = '1'
 

package/src/remote/remotes-file.ts

@@ -8,7 +8,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { writeFileAtomic } from '@crombolo/server'
+import { writeFileAtomic } from '@crombolo/server/atomic-write'
 
 export const REMOTES_FILE = 'remotes.toml'
 

package/src/support/media-tree.ts

@@ -0,0 +1,72 @@
+/**
+ * The media tree, for the bulk commands (story 153): its folders by name, what
+ * a file's extension makes it, and the repository and file store an upload
+ * goes through, so an imported file is placed exactly as the back office
+ * places one.
+ */
+import { ObjectTypes, SystemNodes } from '@crombolo/core'
+import {
+  currentSchemaState,
+  type Db,
+  DocumentRepository,
+  describeRefFailure,
+  NodeRepository,
+  type NodeRow,
+  resolveNodeRef,
+} from '@crombolo/data'
+import {
+  type CromboloConfig,
+  createFileIntake,
+  createMediaPort,
+  MediaFileStore,
+  mediaStoreFor,
+} from '@crombolo/server'
+import { CliError } from '../errors.ts'
+
+export async function openMedia(db: Db, config: CromboloConfig) {
+  const files = new MediaFileStore(await mediaStoreFor(config))
+  const state = await currentSchemaState(db)
+  const options = {
+    nodeState: { version: state.version, revision: state.revision },
+    nodeId: `cli:${config.nodeId}`,
+  }
+  return {
+    files,
+    nodes: new NodeRepository(db),
+    repo: new DocumentRepository(db, {
+      ...options,
+      kind: 'media',
+      valueIntake: createFileIntake(files),
+    }),
+    // For the rules alone — which type takes which file — not for writing: a
+    // write through the port tells the cluster once per item.
+    port: createMediaPort(db, files, options),
+  }
+}
+
+export type MediaTree = Awaited<ReturnType<typeof openMedia>>
+
+/** The node a `--under` names, or the root. */
+export async function mediaParent(db: Db, ref: string | undefined): Promise<NodeRow | null> {
+  if (!ref) return null
+  const resolved = await resolveNodeRef(db, [ObjectTypes.Media], ref)
+  if (!resolved.ok) throw new CliError('not_found', describeRefFailure(ref, resolved))
+  return resolved.node
+}
+
+/** The media directly under a node, by name. */
+export async function childrenByName(
+  tree: MediaTree,
+  parent: NodeRow | null,
+): Promise<Map<string, NodeRow>> {
+  const page = await tree.nodes.children(
+    parent?.id ?? SystemNodes.Root,
+    ObjectTypes.Media,
+    0,
+    Number.MAX_SAFE_INTEGER,
+  )
+  return new Map(page.items.map((node) => [node.text ?? '', node]))
+}
+
+export const sha256 = (bytes: Uint8Array): string =>
+  new Bun.CryptoHasher('sha256').update(bytes).digest('hex')

package/src/support/people.ts

@@ -0,0 +1,134 @@
+/**
+ * Back-office users from the command line (story 151), through the same user
+ * port the Management API uses, so a rule the back office keeps — who may act
+ * on an admin, what an invite is — is the rule here too. It opens the site's
+ * database directly, not through the server, so it works when the site will not
+ * boot; in a container it runs through `docker exec`.
+ */
+import type { Principal, UserPort, UserStatus } from '@crombolo/api-management'
+import { AuthStore } from '@crombolo/auth'
+import { type Db, SUPER_USER_KEY, UserRepository } from '@crombolo/data'
+import {
+  bootstrapDatabase,
+  type CromboloConfig,
+  createNodeLookup,
+  createUserPorts,
+  MediaFileStore,
+  mediaStoreFor,
+  TwoFactorService,
+} from '@crombolo/server'
+import { CliError, type ErrorKind } from '../errors.ts'
+
+/** The operator: an administrator who is nobody in particular, so no rule about acting on oneself applies. */
+const CLI_PRINCIPAL_ID = '00000000-0000-4000-8000-0000000c1c1e'
+
+const principal = (id: string): Principal =>
+  ({
+    id,
+    userName: 'crombolo',
+    name: 'The command line',
+    email: '',
+    isAdmin: true,
+    languageIsoCode: undefined,
+    avatarUrls: [],
+    allowedSections: [],
+    permissions: [],
+    groupKeys: [],
+    hasAccessToAllLanguages: true,
+    languages: [],
+  }) as unknown as Principal
+
+/** Sees every user, the built-in administrator included, as only that administrator may. */
+export const OBSERVER = principal(SUPER_USER_KEY)
+/** Acts on any user, the built-in administrator included. */
+export const OPERATOR = principal(CLI_PRINCIPAL_ID)
+
+export interface People {
+  config: CromboloConfig
+  db: Db
+  users: UserPort
+  repository: UserRepository
+  twoFactor: TwoFactorService
+  /** The link the last invite would have e-mailed. */
+  lastLink(): string | undefined
+}
+
+export async function openPeople(config: CromboloConfig): Promise<People> {
+  const { db } = await bootstrapDatabase(config)
+  const store = new AuthStore(db)
+  let link: string | undefined
+  const { users } = createUserPorts(db, {
+    config: {
+      ...config,
+      // Captured, not sent: the command prints it, for a site with no e-mail.
+      sendUserLink: async (message) => {
+        link = message.link
+      },
+    },
+    mediaFiles: new MediaFileStore(await mediaStoreFor(config)),
+    nodes: createNodeLookup(db),
+    endSessions: async (userId) => {
+      await store.endAllSessionsForUser(userId)
+    },
+  })
+  return {
+    config,
+    db,
+    users,
+    repository: new UserRepository(db),
+    twoFactor: new TwoFactorService(db, { secretKey: config.secretKey, issuer: config.siteName }),
+    lastLink: () => link,
+  }
+}
+
+/** A user by e-mail or username, whatever the casing; `not_found` otherwise. */
+export async function userNamed(people: People, who: string) {
+  const wanted = who.trim().toLowerCase()
+  const rows = await people.db.query<{ key: string }>(
+    'SELECT key FROM user_account WHERE LOWER(email) = ? OR LOWER(user_name) = ?',
+    [wanted, wanted],
+  )
+  const key = rows[0]?.key
+  const user = key ? await people.repository.byKey(String(key)) : undefined
+  if (!user)
+    throw new CliError('not_found', `No user "${who}".`, {
+      hint: '`crombolo users list` lists them.',
+    })
+  return user
+}
+
+const STATUS_KINDS: Partial<Record<UserStatus, ErrorKind>> = {
+  UserNotFound: 'not_found',
+  MissingUserGroup: 'not_found',
+  DuplicateUserName: 'conflict',
+  DuplicateEmail: 'conflict',
+  InvalidEmail: 'usage',
+  InvalidUserName: 'usage',
+  UserNameIsNotEmail: 'usage',
+  InvalidPassword: 'usage',
+  NoUserGroup: 'usage',
+}
+
+const STATUS_MESSAGES: Partial<Record<UserStatus, string>> = {
+  CannotDisableInvitedUser: 'An invited user cannot be disabled; delete the invitation instead.',
+  CannotInvite: 'The invitation could not be made.',
+  InvalidPassword: "That password does not meet this site's password rules.",
+  DuplicateEmail: 'Another user has that e-mail address.',
+  DuplicateUserName: 'Another user has that username.',
+  MissingUserGroup: 'There is no group with that alias.',
+}
+
+/** A user port status other than `Success`, as a failure. */
+export function checkStatus(status: UserStatus): void {
+  if (status === 'Success') return
+  throw new CliError(STATUS_KINDS[status] ?? 'refused', STATUS_MESSAGES[status] ?? status)
+}
+
+export function describeUser(user: {
+  key: string
+  name: string
+  email: string
+  userName: string
+}): string {
+  return `${user.name} <${user.email || user.userName}>`
+}

package/src/support/remote.ts

@@ -1,9 +1,8 @@
 /** What the remote commands share: the remote a command names, and the browser it opens. */
-import { osKeychain } from '@crombolo/server'
+import { osKeychain } from '@crombolo/server/remote-credentials'
 import { CliError } from '../errors.ts'
 import { discover, RemoteClient } from '../remote/client.ts'
 import { pickRemote, readRemotes } from '../remote/remotes-file.ts'
-import { cwd } from './site.ts'
 
 export const keychain = () => osKeychain()
 
@@ -24,9 +23,9 @@ export function openInBrowser(url: string, disabled: boolean): void {
 
 /** The remote a command names, signed in or not, with the environment it goes to. */
 export async function connectRemote(name: string | undefined, env: string | undefined) {
-  const entry = pickRemote(cwd(), name)
+  const entry = pickRemote(process.cwd(), name)
   if (!entry) {
-    const known = readRemotes(cwd())
+    const known = readRemotes(process.cwd())
     if (known.length === 0)
       throw new CliError('not_found', 'No remotes yet.', {
         hint: '`crombolo remote add <name> <url>` adds one.',

package/templates/basic/bundle/package.json

@@ -6,7 +6,7 @@
     "content"
   ],
   "peerDependencies": {
-    "@crombolo/crombolo": ">=0.15.0"
+    "@crombolo/crombolo": ">=0.16.0"
   },
   "crombolo": {
     "id": "basic",

package/templates/demo/harbourstone/bundle/package.json

@@ -6,7 +6,7 @@
     "content"
   ],
   "peerDependencies": {
-    "@crombolo/crombolo": ">=0.15.0"
+    "@crombolo/crombolo": ">=0.16.0"
   },
   "crombolo": {
     "id": "demo-harbourstone",

package/templates/starter/bundle/package.json

@@ -6,7 +6,7 @@
     "content"
   ],
   "peerDependencies": {
-    "@crombolo/crombolo": ">=0.15.0"
+    "@crombolo/crombolo": ">=0.16.0"
   },
   "crombolo": {
     "id": "starter",