@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/src/vendor/provider-kit/src/apply.js

@@ -0,0 +1,207 @@
+'use strict'
+
+/**
+ * The apply ORCHESTRATION — the ordering, stamping and accounting shared by
+ * every provider's `spec-sync apply`, with the tracker calls themselves left
+ * to provider `ops` (deferred to this shape until two providers existed to
+ * validate it: one folds workflow state into its create/update payloads, the
+ * other must move status by a separate transition call — so state application
+ * lives inside the ops, and the skeleton owns only what is identical).
+ *
+ * What the skeleton owns, in order:
+ *
+ *   1. resolve every workflow state BEFORE the first write, so a bad
+ *      `config.states` value cannot strand the spec mid-apply;
+ *   2. the twin-mint guard: an EXACT-title issue held by no spec is a positive
+ *      signal the issue already exists — refuse to mint a second (a fuzzy
+ *      match must never count: being wrong here blocks a legitimate push);
+ *   3. mint-or-update the spec issue, stamping the identifier the moment the
+ *      create lands — an interrupt after that point must not mint a twin;
+ *   4. sub-issue creates, each STAMPED AS IT LANDS, then updates (keyed by
+ *      ref, never by id — the read-back matches by ref);
+ *   5. read back what the tracker stored and run the same check `verify` runs;
+ *   6. record the snapshot from the now-stamped files, so the next push is
+ *      empty.
+ *
+ * Orphan accounting rides the whole way: `created` is what the tracker holds,
+ * `stamped` what the repo recorded, and the one case a re-run makes WORSE is a
+ * create whose stamp could not be written — the identifiers travel out on the
+ * error so the caller can name them.
+ *
+ * @param {object} ops the provider's tracker calls:
+ *   - `prevalidateStates(buckets)`          throw early on a bad state name
+ *   - `mintIssue({ title, issue })`         → `{ id, identifier, url }`
+ *   - `updateIssue(existing, issue)`        apply `plan.issue` to a live issue
+ *   - `mintSubIssue(parentId, sub)`         → `{ id, identifier }`
+ *   - `updateSubIssue(sub)`                 apply a sub-issue update
+ *   - `remoteEditedLine(identifier)`        the someone-else-edited warning
+ *   - `twinAdvice(twin, title, specName)`   the refusal message for a twin
+ */
+
+const path = require('node:path')
+
+const {
+  readSnapshot,
+  readBase,
+  projectionOf,
+  recordPush,
+  writeFrontmatter,
+  stampSubIssueId,
+  fieldsOf,
+  remoteDescriptionEdited,
+  remoteSubIssueEdited,
+  listPhaseFiles,
+} = require('../../sync-core')
+const { makeSpecHelpers } = require('./specs.js')
+
+/**
+ * The outer accounting wrapper: run the inner apply, and on ANY throw attach
+ * what had been stamped versus created by the time it happened.
+ */
+async function applySpecPlan(args) {
+  const progress = {}
+  try {
+    return await applyInner({ ...args, progress })
+  } catch (error) {
+    const r = progress.result
+    if (error && typeof error === 'object' && error.stamped === undefined) {
+      error.stamped = r ? (r.issue ? 1 : 0) + Object.keys(r.subIssues || {}).length : 0
+      error.created = progress.created || []
+      error.orphans = error.created.slice(error.stamped)
+    }
+    throw error
+  }
+}
+
+async function applyInner({ dir, config, snapshotDir, plan, adapter, ops, progress, forceNew = false, program = 'spec-sync' }) {
+  const fields = fieldsOf(config)
+  const helpers = makeSpecHelpers({ program })
+  const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+  const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
+  const lines = []
+  const result = { issue: null, subIssues: {} }
+  // Handed out immediately, so a throw from anywhere below still reports what
+  // had been stamped by the time it happened.
+  if (progress) progress.result = result
+
+  // 1. Every state resolved BEFORE the first write.
+  const wanted = new Set()
+  if (plan.issue && plan.issue.state) wanted.add(plan.issue.state)
+  for (const s of (plan.subIssues && plan.subIssues.create) || []) if (s.state) wanted.add(s.state)
+  for (const s of (plan.subIssues && plan.subIssues.update) || []) if (s.state) wanted.add(s.state)
+  ops.prevalidateStates([...wanted])
+
+  let parentId = null
+  if (!identifier) {
+    // 2. REFUSE TO MINT A TWIN. An EXACT match held by no spec is a positive
+    // signal that the issue already exists; a near-match must never count —
+    // being wrong here blocks a legitimate push, and a renamed spec is
+    // answered by adopting the issue, not by fuzz.
+    if (!forceNew && adapter.searchIssues) {
+      const title = String(plan.title || readSnapshot(snapshotDir, config).title || '').trim()
+      if (title) {
+        let found = []
+        try {
+          found = (await ops.searchTwin(title)) || []
+        } catch {
+          // A search we could not run is not evidence of an orphan. Carry on
+          // and mint — the cannot-tell case goes to the harmless branch, which
+          // here is the one that does the work the caller asked for.
+          found = []
+        }
+        const claimed = new Set(helpers.listSpecs(dir, config).map((sp) => sp.identifier).filter(Boolean))
+        const twin = found.find(
+          (i) => i && i.identifier && !claimed.has(i.identifier) && String(i.title || '').trim() === title,
+        )
+        if (twin) throw new Error(ops.twinAdvice(twin, title, path.basename(snapshotDir)))
+      }
+    }
+    // 3. Mint, then stamp IMMEDIATELY: noted before it is stamped, so a stamp
+    // that cannot be written can still name the identifier it strands.
+    const created = await ops.mintIssue({ title: readSnapshot(snapshotDir, config).title, issue: plan.issue })
+    parentId = created.id
+    if (progress) (progress.created = progress.created || []).push(created.identifier)
+    writeFrontmatter(snapshotDir, config, {
+      [fields.identifier]: created.identifier,
+      [fields.url]: created.url,
+    })
+    result.issue = { id: created.id, identifier: created.identifier, url: created.url }
+    lines.push(`  issue created: ${created.identifier}`)
+  } else {
+    const existing = await adapter.readIssue(identifier)
+    if (!existing || !existing.id) throw new Error(ops.missingIssueMessage(identifier))
+    parentId = existing.id
+    result.issue = { id: existing.id, identifier: existing.identifier, url: existing.url }
+
+    // SOMEONE ELSE EDITED THE DESCRIPTION SINCE THE LAST PUSH, and this write
+    // replaces it. A WARNING AND NEVER A REFUSAL: one-way sync means the repo
+    // wins; what was wrong was winning silently.
+    if (remoteDescriptionEdited(readBase(dir, identifier, config), existing, config) === true) {
+      lines.push(ops.remoteEditedLine(identifier))
+    }
+    if (plan.issue) {
+      await ops.updateIssue(existing, plan.issue)
+      lines.push(`  issue updated: ${identifier}`)
+    }
+  }
+
+  // 4. Sub-issue creates — each stamped as it lands, for the same reason.
+  for (const sub of (plan.subIssues && plan.subIssues.create) || []) {
+    const created = await ops.mintSubIssue(parentId, sub)
+    if (progress) (progress.created = progress.created || []).push(created.identifier)
+    const file = resolvePhaseFileIn(snapshotDir, sub.ref)
+    if (!file) throw new Error(`no phase file for ref ${sub.ref}`)
+    stampSubIssueId(snapshotDir, file, created.identifier, config)
+    result.subIssues[sub.ref] = created.identifier
+    lines.push(`  sub-issue created: ${sub.ref} → ${created.identifier}`)
+  }
+
+  // 5. Sub-issue updates — keyed by REF, never by id: the read-back matches
+  // sub-issues to phases by ref, and a plan written before updates carried a
+  // ref still resolves — by id, off the projection.
+  const refById = new Map()
+  for (const s of projectionOf(snapshotDir, config).subIssues || []) {
+    if (s.id != null) refById.set(String(s.id), s.ref)
+  }
+  // A phase body edited on the tracker gets the same warning as the spec
+  // issue. The read is spent only where the snapshot recorded something to
+  // compare against, so an old snapshot costs no extra calls.
+  const base = readBase(dir, identifier, config)
+  for (const sub of (plan.subIssues && plan.subIssues.update) || []) {
+    const streams = base && base.subIssueStreams
+    if (sub.goal != null && streams && streams[String(sub.id)]) {
+      const before = await adapter.readIssue(sub.id)
+      if (remoteSubIssueEdited(base, sub.id, before, config) === true) lines.push(ops.remoteEditedLine(sub.id))
+    }
+    await ops.updateSubIssue(sub)
+    result.subIssues[sub.ref || refById.get(String(sub.id)) || sub.id] = sub.id
+    lines.push(`  sub-issue updated: ${sub.id}`)
+  }
+
+  // 6. Read back what the tracker stored and run the SAME check verify runs.
+  const stored = { issue: undefined, subIssues: {} }
+  if (result.issue) {
+    const back = await adapter.readIssue(result.issue.id)
+    if (back && typeof back.description === 'string') stored.issue = back.description
+  }
+  for (const [ref, id] of Object.entries(result.subIssues)) {
+    const back = await adapter.readIssue(id)
+    if (back && typeof back.description === 'string') stored.subIssues[ref] = back.description
+  }
+  const verify = helpers.verifyLines(snapshotDir, config, stored, result.issue ? result.issue.identifier : identifier)
+  lines.push(...verify.map((l) => `  ${l}`))
+  const lost = verify.some((l) => l.includes('!!') || l.includes('??'))
+
+  // 7. Record the snapshot from the now-stamped files, so the next push is empty.
+  const file = recordPush({ dir, snapshotDir, identifier: helpers.specIdentifier(snapshotDir, config), config })
+  lines.push(`  snapshot: ${path.relative(dir, file)}`)
+  return { result, lines, lost }
+}
+
+// The phase file a sub-issue ref names — the ref is the phase-file basename.
+function resolvePhaseFileIn(snapshotDir, ref) {
+  const want = String(ref).replace(/\.md$/, '')
+  return listPhaseFiles(snapshotDir).find((f) => f.replace(/\.md$/, '') === want) || null
+}
+
+module.exports = { applySpecPlan }

package/src/vendor/provider-kit/src/args.js

@@ -0,0 +1,68 @@
+'use strict'
+
+/**
+ * A table-driven flag parser for a provider CLI, carrying the one discipline
+ * the first provider learned the hard way: an UNKNOWN `--flag` is a refusal,
+ * never a silent positional. (A renamed flag once parsed as a no-op — the
+ * repair invocation ran the wrong command, ignored the flag, and exited 0.)
+ *
+ * The table maps `--flag` → spec:
+ *   - `{ kind: 'boolean' }`            sets `flags[name] = true`
+ *   - `{ kind: 'value' }`              takes the next token verbatim
+ *   - `{ kind: 'string' }`             takes the next token, trimmed ('' kept)
+ *   - `{ kind: 'number' }`             Number(next token)
+ *   - `{ kind: 'path' }`               path.resolve(next token)
+ *   - `{ kind: 'list' }`               repeatable; pushes trimmed tokens
+ *   - `{ kind: 'custom', take, handle }` `handle(flags, value, context)`;
+ *                                      `take: false` consumes no token
+ *   - any spec may set `name` (defaults to the camelCased flag)
+ *
+ * A spec name never starts with `--`, so the refusal cannot swallow a real
+ * argument. `renamed` maps an old flag to advice lines appended to the refusal,
+ * so a rename hands off instead of leaving the caller to guess.
+ */
+
+const path = require('node:path')
+
+const camel = (flag) => flag.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+
+function parseFlags(args, table, { defaults = {}, renamed = {}, context = {} } = {}) {
+  const flags = { ...defaults }
+  const positional = []
+  const unknown = []
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i]
+    const spec = table[token]
+    if (!spec) {
+      if (String(token).startsWith('--')) unknown.push(token)
+      else positional.push(token)
+      continue
+    }
+    const name = spec.name || camel(token)
+    const kind = spec.kind || 'boolean'
+    if (kind === 'boolean') flags[name] = true
+    else if (kind === 'value') flags[name] = args[++i]
+    else if (kind === 'string') flags[name] = String(args[++i] || '').trim()
+    else if (kind === 'number') flags[name] = Number(args[++i])
+    else if (kind === 'path') flags[name] = path.resolve(args[++i])
+    else if (kind === 'list') (flags[name] = flags[name] || []).push(String(args[++i] || '').trim())
+    else if (kind === 'custom') {
+      const value = spec.take === false ? undefined : args[++i]
+      spec.handle(flags, value, context)
+    } else throw new Error(`parseFlags: unknown kind "${kind}" for ${token}`)
+  }
+  return { flags, positional, unknown }
+}
+
+// The refusal, phrased once. Returns the lines to print (the caller owns the
+// stream and the exit code).
+function unknownFlagLines(program, unknown, renamed = {}) {
+  const lines = [`${program}: unknown flag ${unknown.join(', ')}`]
+  for (const flag of unknown) {
+    if (renamed[flag]) for (const advice of [].concat(renamed[flag])) lines.push(`  ${advice}`)
+  }
+  lines.push(`  run \`${program}\` for the full usage.`)
+  return lines
+}
+
+module.exports = { parseFlags, unknownFlagLines }

package/src/vendor/provider-kit/src/assignment.js

@@ -0,0 +1,277 @@
+'use strict'
+
+/**
+ * Assignment — who is building a spec, mirrored to the tracker's assignee.
+ *
+ * Three commands every provider with assignment shares, hoisted from the
+ * Linear provider when GitHub became the second consumer:
+ *
+ *   - `assign <spec> --to <id> [--name <n>] | --release` stamps (or clears) the
+ *     assignee fields in the overview frontmatter. It writes the REPO and
+ *     nothing else; the next push carries it, like any other field.
+ *   - `whoami [--set <id> [--name <n>]] [--unset]` reports — and caches — who
+ *     the operator is in the tracker, which is the fact assignment rests on.
+ *   - `users [<query>]` finds a person to hand a spec to.
+ *
+ * Everything tracker-shaped arrives as a hook (`makeAssignmentCommands`): the
+ * tracker's name for messages, the frontmatter fields, the store scope, how a
+ * credential resolves and how an adapter is made. The behaviour is the Linear
+ * provider's, unchanged — its tests still pin every message.
+ */
+
+const path = require('node:path')
+
+const { ownsField, writeFrontmatter, deleteFrontmatter, fieldsOf } = require('../../sync-core')
+const { resolveTransport } = require('./transport.js')
+const { makeSpecHelpers } = require('./specs.js')
+
+/**
+ * @param {object} p
+ *   - `tracker`         the tracker's name in messages ("Linear", "GitHub")
+ *   - `configFile`      the provider config path, for refusals
+ *   - `bin`             the command a person types (for the hints)
+ *   - `idHint`          how a user id is described ("<linear-user-id>", "<login>")
+ *   - `scopeOf(config)` → `{ id, label }` the credentials-store scope, or `{ id: '' , missing }` with
+ *                         `missing` the refusal text when the config cannot name one
+ *   - `storePath(env)`, `writeUser(file, scope, user)`, `removeUser(file, scope)`
+ *   - `resolveIdentity(config, env, deps)` the provider's identity binding
+ *   - `resolveCredential(config, env)` → `{ ok, error? }`
+ *   - `makeAdapter(config, credential, flags)` → an adapter with `searchUsers`
+ *   - `displayNameOf(user)`
+ *   - `validateAssignee(config, id, flags)` OPTIONAL — async, resolves to a
+ *     refusal string or null. Absent means "do not check", which is the Linear
+ *     provider's behaviour.
+ *   - `usersOverMcp` the hint printed when users must be searched over MCP
+ *   - `unknownHint` OPTIONAL extra lines for the unknown-identity whoami report
+ */
+function makeAssignmentCommands(p) {
+  const helpers = makeSpecHelpers({ program: 'spec-sync' })
+
+  async function assign(dir, config, specArg, flags, out) {
+    const snapshotDir = helpers.resolveOrExit(specArg, dir, out)
+    if (!snapshotDir) return 1
+    const fields = fieldsOf(config)
+
+    const overviewFile = (config.snapshot && config.snapshot.overviewFile) || '00-overview.md'
+    const identifier = helpers.linkedIdentifier(path.join(snapshotDir, overviewFile), config)
+    const rel = path.relative(dir, snapshotDir)
+
+    const problems = []
+    if (flags.release && flags.to) problems.push('--release and --to are opposites — pass one')
+    if (!flags.release && !flags.to) problems.push('nothing to do — pass --to <user-id> or --release')
+    // An unlinked spec has no issue to assign. Refusing beats stamping a field
+    // that would sit in the file doing nothing until someone noticed.
+    if (!identifier) problems.push(`${rel} is not linked to ${p.tracker} — /spec-push it first`)
+    // AND THE SAME REASONING FOR THE FIELD ITSELF. A field the repo does not own
+    // is dropped from the projection, so a stamp written here would never reach
+    // the tracker — while the success line says `next: push it`. That is not a
+    // silent skip, it is an untrue assertion. Applies to `--release` too.
+    if (!ownsField(config, 'assignee')) {
+      problems.push(
+        'this repo does not own the assignee field — set sync.fieldOwnership.assignee ' +
+          `to "push" in ${p.configFile}`,
+      )
+    }
+    // A POSITIVE refusal only: the hook answers "this id cannot be assigned"
+    // or null, and every cannot-tell inside it must be null.
+    if (!problems.length && flags.to && p.validateAssignee) {
+      const refusal = await p.validateAssignee(config, flags.to, flags)
+      if (refusal) problems.push(refusal)
+    }
+
+    if (problems.length) {
+      out.write(
+        ['spec-sync assign: refusing to write — nothing was changed', ...problems.map((x) => `  ${x}`)].join('\n') + '\n',
+      )
+      return 1
+    }
+
+    if (flags.release) {
+      const removed = deleteFrontmatter(snapshotDir, config, [fields.assigneeId, fields.assigneeName].filter(Boolean))
+      if (flags.json) {
+        out.write(JSON.stringify({ spec: rel, issue: identifier, released: removed.length > 0 }, null, 2) + '\n')
+        return 0
+      }
+      out.write(
+        (removed.length
+          ? `spec-sync assign: ${rel} released (${identifier})\n`
+          : `spec-sync assign: ${rel} records no assignee — nothing to release\n`) +
+          `  next: push it, so ${p.tracker} is unassigned too\n`,
+      )
+      return 0
+    }
+
+    writeFrontmatter(snapshotDir, config, {
+      [fields.assigneeId]: flags.to,
+      // Display only — the projection never sends it. It exists so a reader (and
+      // `/spec-claim`) can name the person without a tracker round trip.
+      ...(fields.assigneeName ? { [fields.assigneeName]: flags.name || null } : {}),
+    })
+    if (flags.json) {
+      out.write(JSON.stringify({ spec: rel, issue: identifier, id: flags.to, name: flags.name || null }, null, 2) + '\n')
+      return 0
+    }
+    const who = flags.name ? `${flags.name} (${flags.to})` : flags.to
+    out.write(`spec-sync assign: ${rel} assigned to ${who} (${identifier})\n  next: push it, so ${p.tracker} agrees\n`)
+    return 0
+  }
+
+  /**
+   * Exit 0 even when the answer is "unknown": this answers a question, and
+   * "nobody is identified here" is a valid answer — a shared key, an offline
+   * machine. A successful DERIVE is cached; a cache read is not re-written, and
+   * the caching lives here so that asking never has a side effect.
+   */
+  async function whoami(dir, config, flags, out) {
+    const env = flags.env || process.env
+    const file = p.storePath(env)
+    const scope = p.scopeOf(config)
+
+    // The store is keyed by scope, so without one there is nowhere to read from
+    // or write to. That IS a broken config, so it exits non-zero.
+    if (!scope.id) {
+      out.write(scope.missing + '\n')
+      return 1
+    }
+    const label = scope.label || scope.id
+
+    if (flags.unset) {
+      const r = p.removeUser(file, scope.id, {})
+      if (!r.ok) {
+        out.write(`spec-sync whoami: ${r.reason}\n`)
+        return 1
+      }
+      out.write(
+        r.removed
+          ? `spec-sync whoami: forgot the identity for ${label} (the ${p.credentialNoun || 'API key'} is untouched)\n`
+          : `spec-sync whoami: no identity stored for ${label} — nothing to forget\n`,
+      )
+      return 0
+    }
+
+    if (flags.set) {
+      const r = p.writeUser(file, scope.id, { id: flags.set, name: flags.name }, {})
+      if (!r.ok) {
+        out.write(`spec-sync whoami: ${r.reason}\n`)
+        return 1
+      }
+      if (flags.json) {
+        out.write(JSON.stringify({ id: flags.set, name: flags.name || null, source: 'set', store: r.path }, null, 2) + '\n')
+        return 0
+      }
+      const shown = flags.name ? `${flags.name} (${flags.set})` : flags.set
+      out.write(`spec-sync whoami: identity for ${label} set to ${shown} in ${r.path} (600)\n`)
+      return 0
+    }
+
+    const identity = await p.resolveIdentity(config, env, { adapter: flags.adapter, fetch: flags.fetch })
+
+    if (identity.ok && identity.source === 'viewer') {
+      // A failed write is not fatal: we HAVE the answer, and re-deriving it next
+      // time is a slower success, not a wrong one.
+      const cached = p.writeUser(file, scope.id, { id: identity.id, name: identity.name }, {})
+      if (!cached.ok) identity.cacheWarning = cached.reason
+    }
+
+    if (flags.json) {
+      out.write(
+        JSON.stringify(
+          {
+            [p.scopeJsonKey || 'team']: label,
+            store: file,
+            ok: identity.ok,
+            id: identity.id || null,
+            name: identity.name || null,
+            source: identity.source,
+            reason: identity.ok ? null : identity.reason || null,
+          },
+          null,
+          2,
+        ) + '\n',
+      )
+      return 0
+    }
+
+    if (!identity.ok) {
+      out.write(
+        [
+          'spec-sync whoami: unknown — no identity for this workspace',
+          `  ${identity.reason}`,
+          '  Set one by hand:',
+          `    ${p.bin} spec-sync whoami --set ${p.idHint} --name "<your name>"`,
+          `  Find the id with: ${p.bin} spec-sync users <name-or-email>`,
+        ].join('\n') + '\n',
+      )
+      return 0
+    }
+
+    const where = identity.source === 'store' ? `cached in ${file}` : `derived from the ${p.credentialNoun || 'API key'}`
+    const lines = [
+      `spec-sync whoami: ${identity.name || '(unnamed)'} <${identity.id}>`,
+      `  ${(p.scopeLineLabel || 'team:').padEnd(7)} ${label}`,
+      `  source: ${where}`,
+    ]
+    if (identity.cacheWarning) lines.push(`  note:   not cached — ${identity.cacheWarning}`)
+    out.write(lines.join('\n') + '\n')
+    return 0
+  }
+
+  /**
+   * The engine answers on the API path and steps aside on the MCP path — the
+   * same contract `states` follows.
+   */
+  async function users(dir, config, query, flags, out) {
+    const cred = p.resolveCredential(config, flags.env || process.env)
+    const transport = resolveTransport(flags, config, cred.ok || !!flags.adapter)
+
+    if (transport === 'mcp') {
+      if (flags.json) {
+        out.write(JSON.stringify({ transport: 'mcp', reason: cred.ok ? 'requested' : cred.error, users: null }, null, 2) + '\n')
+        return 0
+      }
+      out.write(
+        ['spec-sync users: transport = mcp', `  ${cred.ok ? '--via mcp was requested' : cred.error}`, `  ${p.usersOverMcp}`].join('\n') +
+          '\n',
+      )
+      return 0
+    }
+    if (!cred.ok && !flags.adapter) {
+      out.write(`spec-sync users: refusing — ${cred.error}\n`)
+      return 1
+    }
+
+    const adapter = flags.adapter || p.makeAdapter(config, cred, flags)
+    let page
+    try {
+      page = await adapter.searchUsers(query || '', { limit: flags.limit || 50, cursor: flags.cursor || null })
+    } catch (error) {
+      out.write(`spec-sync users: ${error.message}\n`)
+      return 1
+    }
+
+    const list = (page && page.users) || []
+    if (flags.json) {
+      out.write(JSON.stringify({ transport: 'api', users: list, nextCursor: (page && page.nextCursor) || null }, null, 2) + '\n')
+      return 0
+    }
+    if (!list.length) {
+      out.write(`spec-sync users: no match for ${JSON.stringify(query || '')}\n`)
+      return 0
+    }
+    const lines = [`spec-sync users: ${list.length} match(es)`]
+    for (const u of list) {
+      // A deactivated user still resolves by id and can still be assigned, so
+      // the marker is the difference between a valid pick and a silently dead one.
+      const inactive = u && u.active === false ? '  [deactivated]' : ''
+      const email = u && u.email ? `  ${u.email}` : ''
+      lines.push(`  ${p.displayNameOf(u) || '(unnamed)'} <${u && u.id}>${email}${inactive}`)
+    }
+    if (page && page.nextCursor) lines.push(`  … more — re-run with --cursor ${page.nextCursor}`)
+    out.write(lines.join('\n') + '\n')
+    return 0
+  }
+
+  return { assign, whoami, users }
+}
+
+module.exports = { makeAssignmentCommands }