@skitterbyte/skitterspec-jira 1.0.0 → 2.0.0

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 }

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

@@ -98,52 +98,6 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
     }
   }
 
-  // Merge (and validate) `release.stages` — the project's deployment ladder.
-  //
-  // Loud on a malformed entry: this list names tracker states, and a tracker
-  // that silently ignores an unknown state would let a half-typed ladder push
-  // clean and move nothing — so a bad shape fails here, at load, rather than at
-  // the first deploy nobody is watching. An ABSENT `release` block is not an
-  // error: it is the opt-out, and the whole feature is unused without it.
-  function mergeReleaseStages(base, parsed) {
-    const value = parsed.stages
-    if (value === undefined) return
-    if (!Array.isArray(value)) {
-      throw new Error(
-        `Invalid ${configFile}: release.stages = ${JSON.stringify(value)} ` +
-          '(expected an array of { key, state })',
-      )
-    }
-    const stages = []
-    const seen = new Set()
-    value.forEach((entry, i) => {
-      if (!isObject(entry)) {
-        throw new Error(
-          `Invalid ${configFile}: release.stages[${i}] = ${JSON.stringify(entry)} ` +
-            '(expected { key, state })',
-        )
-      }
-      for (const field of ['key', 'state']) {
-        if (typeof entry[field] !== 'string' || !entry[field].trim()) {
-          throw new Error(
-            `Invalid ${configFile}: release.stages[${i}].${field} = ${JSON.stringify(entry[field])} ` +
-              '(expected a non-empty string)',
-          )
-        }
-      }
-      const key = entry.key.trim()
-      if (seen.has(key)) {
-        throw new Error(
-          `Invalid ${configFile}: release.stages[${i}].key = ${JSON.stringify(key)} is a duplicate ` +
-            '(a stage key is how CI names the rung, so it must be unique)',
-        )
-      }
-      seen.add(key)
-      stages.push({ key, state: entry.state.trim() })
-    })
-    base.stages = stages
-  }
-
   // Merge (and validate) release.ignorePaths — the path prefixes whose commits
   // are bookkeeping. Loud on anything but an array of non-empty strings: a bad
   // value that quietly fell back would let a project believe it had opted out
@@ -186,13 +140,112 @@ function makeMergeHelpers({ configFile, ownership, lifecycleBuckets, phaseMappin
     }
   }
 
+  // Merge (and validate) `states`. A bucket's value is a string — the one state
+  // push writes, exactly as it always was — or a non-empty array whose FIRST
+  // name is the one push writes and whose rest are read-only aliases: tracker
+  // states that also mean this bucket ("Blocked" for in-progress). The first
+  // name lands in `states[bucket]`, so every writer is unchanged; the rest go
+  // to `stateAliases[bucket]`, read only by code that interprets a remote state.
+  //
+  // An ALIAS in two buckets is refused: it would make a remote state mean two
+  // things, and which one won would be an accident of iteration order. Two
+  // buckets sharing one written name stays legal, as it always was — a tracker
+  // with no Cancelled state maps cancelled to "Done" — so only a name that an
+  // alias contributes is checked.
+  function mergeStates(base, parsed) {
+    const value = parsed.states
+    if (!isObject(value)) return
+    const aliases = {}
+    for (const bucket of Object.keys(base.states)) {
+      const entry = value[bucket]
+      if (entry === undefined) continue
+      if (typeof entry === 'string') {
+        if (entry.trim()) base.states[bucket] = entry.trim()
+        continue
+      }
+      if (!Array.isArray(entry) || !entry.length || entry.some((n) => typeof n !== 'string' || !n.trim())) {
+        throw new Error(
+          `Invalid ${configFile}: states.${bucket} = ${JSON.stringify(entry)} ` +
+            '(expected a state name, or a non-empty array of them — the first is what push writes)',
+        )
+      }
+      const names = entry.map((n) => n.trim())
+      base.states[bucket] = names[0]
+      aliases[bucket] = names.slice(1)
+    }
+    const owner = new Map()
+    for (const bucket of Object.keys(base.states)) {
+      const key = base.states[bucket].toLowerCase()
+      if (!owner.has(key)) owner.set(key, bucket)
+    }
+    for (const bucket of Object.keys(aliases)) {
+      for (const name of aliases[bucket]) {
+        const key = name.toLowerCase()
+        if (owner.has(key) && owner.get(key) !== bucket) {
+          throw new Error(
+            `Invalid ${configFile}: states name ${JSON.stringify(name)} is in both ` +
+              `${owner.get(key)} and ${bucket} (a tracker state can mean only one bucket)`,
+          )
+        }
+        owner.set(key, bucket)
+      }
+    }
+    base.stateAliases = aliases
+  }
+
   return {
+    mergeStates,
     mergeFieldOwnership,
     mergePhaseMapping,
-    mergeReleaseStages,
     mergeReleaseIgnorePaths,
     mergeKeyedFields,
   }
 }
 
-module.exports = { isObject, stringList, assign, makeMergeHelpers }
+// Keys no provider reads any more. The merge already ignores them, as it does
+// every unknown key — so a config still carrying one is a stale file, not a
+// broken one, and `doctor` says so as a `warn` without touching the exit code.
+//
+// WHAT WOULD FOOL THIS: it reads the committed file, so a key set only in a
+// working-tree edit is still reported — which is the file a person would edit.
+const RETIRED_KEYS = Object.freeze([
+  { path: ['releases'], name: 'releases' },
+  { path: ['release', 'stages'], name: 'release.stages' },
+])
+
+// The retired keys present in a parsed config. Not an object, or none present,
+// is `[]`: nothing to say is the safe answer to every cannot-tell.
+function retiredKeys(parsed) {
+  if (!isObject(parsed)) return []
+  return RETIRED_KEYS.filter(({ path }) => {
+    let node = parsed
+    for (const key of path) {
+      if (!isObject(node) || !(key in node)) return false
+      node = node[key]
+    }
+    return true
+  }).map((k) => k.name)
+}
+
+// A doctor row naming the retired keys in the config at `file`, or null when
+// there are none — or when the file cannot be read or parsed, which is the
+// loader's to report, not this row's.
+function retiredKeysRow(file, configFile, row) {
+  let parsed = null
+  try {
+    parsed = JSON.parse(require('node:fs').readFileSync(file, 'utf-8'))
+  } catch {
+    return null
+  }
+  const names = retiredKeys(parsed)
+  if (!names.length) return null
+  return row(
+    'retired',
+    'Retired config',
+    'warn',
+    `${names.join(', ')} in ${configFile} is no longer read — release and deploy state is the host project's to write (see \`spec-sync released --json\`)`,
+    `remove ${names.join(', ')} from ${configFile}`,
+  )
+}
+
+module.exports = { isObject, stringList, assign, makeMergeHelpers, retiredKeys, retiredKeysRow, RETIRED_KEYS }

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

@@ -14,31 +14,50 @@
 const MAX_RETRIES = 5
 const MAX_BACKOFF_MS = 60_000
 
-// How long to wait before retrying a 429.
-function retryDelay(res, attempt, maxBackoffMs = MAX_BACKOFF_MS) {
-  const header = res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null
+// How long to wait before retrying a rate-limited response: `Retry-After`
+// (seconds) first, then `X-RateLimit-Reset` (an epoch second — GitHub's
+// primary limit names the moment it lifts rather than a duration), then
+// exponential backoff. A reset already in the past falls through to backoff
+// rather than waiting zero and hammering.
+function retryDelay(res, attempt, maxBackoffMs = MAX_BACKOFF_MS, now = Date.now) {
+  const get = res.headers && typeof res.headers.get === 'function' ? (h) => res.headers.get(h) : () => null
+  const header = get('retry-after')
   const seconds = header != null ? Number(header) : NaN
   if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1000, maxBackoffMs)
+  const reset = Number(get('x-ratelimit-reset'))
+  if (Number.isFinite(reset) && reset > 0) {
+    const wait = reset * 1000 - now()
+    if (wait > 0) return Math.min(wait, maxBackoffMs)
+  }
   return Math.min(1000 * 2 ** attempt, maxBackoffMs)
 }
 
+// The default answer to "is this response a rate limit?": a 429. A provider
+// whose tracker also signals limits another way (GitHub: a 403 carrying
+// `Retry-After` or a zero `X-RateLimit-Remaining`) passes its own `isLimited`.
+const isTooManyRequests = (res) => res.status === 429
+
 /**
  * Run `attempt()` (→ a fetch Response) until it is not rate-limited or the
  * retries run out. Returns `{ response, exhausted }` — `exhausted` true when
- * the LAST response is still a 429, so the caller phrases its own refusal (and
- * marks it retryable: rate limiting is the failure where waiting is the whole
- * answer, and the one a refusal must stay distinguishable from).
+ * the LAST response is still rate-limited, so the caller phrases its own
+ * refusal (and marks it retryable: rate limiting is the failure where waiting
+ * is the whole answer, and the one a refusal must stay distinguishable from).
  */
-async function withRateLimitRetry(attempt, { sleep, maxRetries = MAX_RETRIES, maxBackoffMs = MAX_BACKOFF_MS } = {}) {
+async function withRateLimitRetry(
+  attempt,
+  { sleep, maxRetries = MAX_RETRIES, maxBackoffMs = MAX_BACKOFF_MS, isLimited = isTooManyRequests, now } = {},
+) {
   const wait = sleep || ((ms) => new Promise((r) => setTimeout(r, ms)))
   for (let n = 0; ; n++) {
     const response = await attempt()
-    if (response.status === 429 && n < maxRetries) {
-      await wait(retryDelay(response, n, maxBackoffMs))
+    const limited = isLimited(response)
+    if (limited && n < maxRetries) {
+      await wait(retryDelay(response, n, maxBackoffMs, now))
       continue
     }
-    return { response, exhausted: response.status === 429 }
+    return { response, exhausted: limited }
   }
 }
 
-module.exports = { withRateLimitRetry, retryDelay, MAX_RETRIES, MAX_BACKOFF_MS }
+module.exports = { withRateLimitRetry, retryDelay, isTooManyRequests, MAX_RETRIES, MAX_BACKOFF_MS }

package/src/vendor/provider-kit/src/list-assignee.js

@@ -0,0 +1,71 @@
+'use strict'
+
+/**
+ * `spec-sync list --mine | --by <user>` — whose tickets to list.
+ *
+ * Linear defined the contract (`linear/src/cli-sync.js`, decision 9 of
+ * `feat-linear-assignment`); this is the same contract for every provider that
+ * lists over the API, so the two sentences below mean the same thing anywhere:
+ *
+ *   - `--mine` with an UNKNOWN identity lists nothing and exits 0. Identity is
+ *     an ordinary unknown (a bot token, an offline machine). What must never
+ *     happen is dropping the filter and printing everyone's work under a
+ *     heading that promised yours.
+ *   - `--by` that matches nobody, or more than one person, exits 1. The
+ *     argument is wrong and only the caller can fix it — the same shape as an
+ *     unknown `--state` — and a fallback to everyone would be the same lie.
+ *
+ * Returns `{ assignee: { id, name } | null }` to carry on with, or
+ * `{ code, lines }` to print and stop.
+ */
+async function resolveListAssignee({ flags, config, env, adapter, resolveIdentity, displayNameOf, tracker, prog }) {
+  if (flags.mine && flags.by) {
+    return {
+      code: 1,
+      lines: [
+        `${prog} list: --mine and --by both filter by assignee, so they cannot be combined`,
+        '  use --mine for your own, or --by <user> for someone else.',
+      ],
+    }
+  }
+  if (flags.mine) {
+    const who = await resolveIdentity(config, env, { adapter })
+    if (!who || !who.ok) {
+      return {
+        code: 0,
+        lines: [
+          `${prog} list: --mine needs to know who you are, and it does not (${(who && who.reason) || 'no identity'})`,
+          '  run `spec-sync whoami --set <id>` to say so, or use --by <user>.',
+        ],
+      }
+    }
+    return { assignee: { id: who.id, name: who.name || who.id } }
+  }
+  if (flags.by) {
+    const term = String(flags.by)
+    let found
+    try {
+      found = await adapter.searchUsers(term, { limit: 50 })
+    } catch (error) {
+      return { code: 1, lines: [`${prog} list: could not search users (${error.message})`] }
+    }
+    const users = (found && found.users) || []
+    if (!users.length) {
+      return {
+        code: 1,
+        lines: [`${prog} list: no ${tracker} user matches ${JSON.stringify(term)}`, '  `spec-sync users <term>` lists who there is.'],
+      }
+    }
+    if (users.length > 1) {
+      const lines = [`${prog} list: ${users.length} users match ${JSON.stringify(term)}`]
+      for (const u of users.slice(0, 10)) lines.push(`  ${displayNameOf(u) || '(unnamed)'}${u.email ? `  ${u.email}` : ''}`)
+      if (users.length > 10) lines.push(`  … and ${users.length - 10} more`)
+      lines.push('  narrow it — an email address matches exactly one person.')
+      return { code: 1, lines }
+    }
+    return { assignee: { id: users[0].id, name: displayNameOf(users[0]) || users[0].id } }
+  }
+  return { assignee: null }
+}
+
+module.exports = { resolveListAssignee }

package/src/vendor/provider-kit/src/list-rows.js

@@ -0,0 +1,35 @@
+'use strict'
+
+/**
+ * Shared pieces of `spec-sync list`: what `--state` means, and how a row's
+ * board state and its spec's own status are put side by side.
+ */
+
+const { remoteStateReading, stateNamesFor, LIFECYCLE_BUCKETS } = require('../../sync-core')
+
+// `--state` takes a lifecycle bucket as well as a tracker state. A bucket
+// expands to every tracker name it has (`stateNamesFor`, aliases included); any
+// other value is a tracker state, matched as it always was.
+function expandStateArgs(args, config) {
+  return (args || []).flatMap((arg) => (LIFECYCLE_BUCKETS.includes(arg) ? stateNamesFor(arg, config) : [arg]))
+}
+
+// The spec's status beside the board's, and whether they disagree. A board
+// state that maps to no bucket never disagrees: it is somewhere push does not
+// manage, which is not a claim about the spec. Nor does a row whose spec is not
+// on this machine — there is nothing to disagree WITH.
+function specColumn(stateName, spec, config) {
+  const specStatus = spec ? spec.bucket : null
+  const seen = stateName == null ? null : remoteStateReading({ state: { name: stateName } }, config)
+  const disagrees = Boolean(specStatus && seen && seen.mapped && seen.bucket !== specStatus)
+  return { specStatus, disagrees }
+}
+
+// The cell itself: `in-progress`, `≠ backlog` when it disagrees, `—` when the
+// spec is not here.
+function specCell({ specStatus, disagrees }) {
+  if (!specStatus) return '—'
+  return disagrees ? `≠ ${specStatus}` : specStatus
+}
+
+module.exports = { expandStateArgs, specColumn, specCell }