@raidiant/notifai 5.0.0 → 6.0.0

package/src/commands-config.ts

@@ -0,0 +1,307 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import path from 'node:path'
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
+import { acceptedValues, configInfo } from './config-schema.js'
+import {
+  BOOLEAN_CONFIG_KEYS,
+  CONFIG_KEYS,
+  NUMERIC_CONFIG_KEYS,
+  configBounds,
+  configDefaultValue,
+  findProjectConfigPath,
+  globalConfigPath,
+  personalProjectConfigPath,
+  sessionConfigPath,
+  type ConfigKey,
+} from './config.js'
+import { renderConfigExplain, renderConfigList, renderConfigPlain } from './ui/config-view.js'
+import { EXIT, loadLoggedConfig, type CommandDeps } from './commands-core.js'
+
+// ---------------------------------------------------------------------------
+// config show / set / unset
+// ---------------------------------------------------------------------------
+
+export function configShowCommand(
+  deps: CommandDeps,
+  flags: { json?: boolean; explain?: boolean; plain?: boolean },
+): number {
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  if (flags.json) {
+    const output = Object.fromEntries(
+      CONFIG_KEYS.map((key) => [
+        key,
+        {
+          value: config[key].value,
+          source: config[key].source,
+          summary: configInfo(key).summary,
+        },
+      ]),
+    )
+    deps.io.out(JSON.stringify(output, null, 2))
+    return EXIT.ok
+  }
+  // Anything that is not a person at a terminal keeps the flat `key = value`
+  // form it has always had. Scripts parse this, and a prettier layout for an
+  // audience that cannot see it would only be a breaking change.
+  if (deps.io.interactive !== true || flags.plain === true) {
+    for (const line of renderConfigPlain(config, flags.explain === true)) deps.io.out(line)
+    return EXIT.ok
+  }
+  for (const line of renderConfigList(config, { showAdvanced: flags.explain === true })) {
+    deps.io.out(line)
+  }
+  return EXIT.ok
+}
+
+/**
+ * One setting, explained in full.
+ *
+ * The gap this closes: `config show` prints a value and provenance but that is
+ * not enough to explain the setting's consequences. Every key already had a
+ * careful explanation — in a TypeScript comment, read by everyone except the
+ * person who needed it.
+ */
+export function configExplainCommand(
+  deps: CommandDeps,
+  key: string,
+  flags: { json?: boolean } = {},
+): number {
+  if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
+    deps.io.err(`Unknown setting "${key}".`)
+    deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`)
+    return EXIT.usage
+  }
+  const configKey = key as ConfigKey
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const info = configInfo(configKey)
+  const entry = config[configKey]
+
+  if (flags.json) {
+    deps.io.out(
+      JSON.stringify(
+        {
+          key: configKey,
+          label: info.label,
+          group: info.group,
+          kind: info.kind,
+          summary: info.summary,
+          detail: info.detail,
+          accepts: acceptedValues(configKey),
+          ...(info.choices !== undefined ? { choices: info.choices } : {}),
+          value: entry.value,
+          source: entry.source,
+        },
+        null,
+        2,
+      ),
+    )
+    return EXIT.ok
+  }
+
+  if (deps.io.interactive !== true) {
+    deps.io.out(`${configKey} = ${JSON.stringify(entry.value)}  [${entry.source}]`)
+    deps.io.out(info.detail.replace(/\n\n/g, '\n'))
+    deps.io.out(`accepts: ${acceptedValues(configKey)}`)
+    return EXIT.ok
+  }
+  for (const line of renderConfigExplain(configKey, config)) deps.io.out(line)
+  return EXIT.ok
+}
+
+/**
+ * Closest config key by edit distance, or null when nothing is close.
+ *
+ * The threshold matters more than the algorithm: suggesting a key that shares
+ * three letters with the typo sends the reader to the wrong setting with
+ * confidence, which is worse than listing all fourteen and letting them look.
+ */
+function nearestKey(input: string): string | null {
+  let best: string | null = null
+  let bestDistance = Number.POSITIVE_INFINITY
+  for (const candidate of CONFIG_KEYS) {
+    const distance = editDistance(input.toLowerCase(), candidate)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = candidate
+    }
+  }
+  return best !== null && bestDistance <= Math.max(2, Math.floor(best.length / 3)) ? best : null
+}
+
+function editDistance(a: string, b: string): number {
+  const previous = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i += 1) {
+    let diagonal = previous[0]!
+    previous[0] = i
+    for (let j = 1; j <= b.length; j += 1) {
+      const above = previous[j]!
+      previous[j] = Math.min(
+        previous[j]! + 1,
+        previous[j - 1]! + 1,
+        diagonal + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+      diagonal = above
+    }
+  }
+  return previous[b.length]!
+}
+
+export async function configSetCommand(
+  deps: CommandDeps,
+  key: string,
+  rawValue: string,
+  flags: { project?: boolean; local?: boolean; session?: string; yes?: boolean },
+): Promise<number> {
+  const configKey = configMutationKey(deps, key)
+  if (configKey === null) return EXIT.usage
+  const info = configInfo(configKey)
+  let value: unknown = rawValue
+  if (NUMERIC_CONFIG_KEYS.includes(configKey)) {
+    const numeric = Number(rawValue)
+    if (!Number.isInteger(numeric)) {
+      deps.io.err(`${key} takes ${acceptedValues(configKey)}, not "${rawValue}".`)
+      return EXIT.usage
+    }
+    const bounds = configBounds(configKey)
+    if (bounds !== undefined && (numeric < bounds.min || numeric > bounds.max)) {
+      deps.io.err(`${key} must be between ${bounds.min} and ${bounds.max}.`)
+      return EXIT.usage
+    }
+    value = numeric
+  }
+  if (BOOLEAN_CONFIG_KEYS.includes(configKey)) {
+    if (rawValue !== 'true' && rawValue !== 'false') {
+      deps.io.err(`${key} is a toggle — pass "true" or "false", not "${rawValue}".`)
+      return EXIT.usage
+    }
+    value = rawValue === 'true'
+  }
+  // Enum keys were accepted unchecked, so `config set sound whatever` wrote a
+  // value the sender would later reject — a typo that only surfaces at the
+  // moment a notification fails to carry the sound you asked for.
+  if (info.kind === 'enum' && info.choices !== undefined && !info.choices.includes(rawValue)) {
+    deps.io.err(`${key} takes one of: ${info.choices.join(', ')} — not "${rawValue}".`)
+    return EXIT.usage
+  }
+  if (key === 'devices') value = rawValue.split(',').map((s) => s.trim()).filter(Boolean)
+
+  const target = await configMutationTarget(deps, flags)
+  if (target === null) return EXIT.usage
+  if (target.layer === 'global' && Object.is(value, configDefaultValue(configKey))) {
+    deps.io.err(`${key} is already the shipped default (${JSON.stringify(value)}).`)
+    deps.io.err(
+      `Run \`notifai config unset ${key} --yes\` to remove a redundant override instead of creating one.`,
+    )
+    return EXIT.usage
+  }
+
+  if (!flags.yes) {
+    const confirmed = await deps.io.confirm(`Set ${key} = ${JSON.stringify(value)} in ${target.path}?`)
+    if (!confirmed) {
+      deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
+      return EXIT.usage
+    }
+  }
+
+  const existing = existsSync(target.path)
+    ? (parseToml(readFileSync(target.path, 'utf8')) as Record<string, unknown>)
+    : {}
+  existing[key] = value
+  mkdirSync(path.dirname(target.path), { recursive: true })
+  writeFileSync(target.path, `${stringifyToml(existing)}\n`)
+  deps.io.out(`Wrote ${key} to ${target.path}`)
+  return EXIT.ok
+}
+
+function configMutationKey(deps: CommandDeps, key: string): ConfigKey | null {
+  if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
+    deps.io.err(`Unknown setting "${key}".`)
+    const near = nearestKey(key)
+    if (near !== null) deps.io.err(`Did you mean "${near}"?`)
+    deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`)
+    deps.io.err('Run `notifai config explain <key>` to see what one of them does.')
+    return null
+  }
+  return key as ConfigKey
+}
+
+type ConfigMutationFlags = { project?: boolean; local?: boolean; session?: string; yes?: boolean }
+type ConfigMutationLayer = 'global' | 'project' | 'local' | 'session'
+
+async function configMutationTarget(
+  deps: CommandDeps,
+  flags: ConfigMutationFlags,
+): Promise<{ path: string; layer: ConfigMutationLayer } | null> {
+  let layer = flags.local ? 'local' : flags.project ? 'project' : 'global'
+  if (
+    flags.session === undefined &&
+    flags.local !== true &&
+    flags.project !== true &&
+    flags.yes !== true &&
+    deps.io.interactive === true &&
+    deps.io.select
+  ) {
+    const selected = await deps.io.select('Where should this setting live?', [
+      { value: 'global', label: 'This machine', hint: 'applies across projects' },
+      { value: 'project', label: 'This project (shared)', hint: '.notifai/config.toml' },
+      { value: 'local', label: 'This project (personal)', hint: 'stored on this machine, not in the repo' },
+    ])
+    if (selected === null) {
+      deps.io.err('No configuration layer selected.')
+      return null
+    }
+    layer = selected
+  }
+
+  const targetPath = flags.session
+    ? sessionConfigPath(flags.session, deps.env)
+    : layer === 'local'
+      ? personalProjectConfigPath(deps.cwd, deps.env)
+      : layer === 'project'
+        ? (findProjectConfigPath(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'config.toml'))
+        : globalConfigPath(deps.env)
+  return {
+    path: targetPath,
+    layer: flags.session ? 'session' : (layer as Exclude<ConfigMutationLayer, 'session'>),
+  }
+}
+
+export async function configUnsetCommand(
+  deps: CommandDeps,
+  key: string,
+  flags: ConfigMutationFlags,
+): Promise<number> {
+  const configKey = configMutationKey(deps, key)
+  if (configKey === null) return EXIT.usage
+  const target = await configMutationTarget(deps, flags)
+  if (target === null) return EXIT.usage
+  const existing = existsSync(target.path)
+    ? (parseToml(readFileSync(target.path, 'utf8')) as Record<string, unknown>)
+    : {}
+  if (!Object.prototype.hasOwnProperty.call(existing, configKey)) {
+    deps.io.out(`${configKey} is not set in ${target.path}`)
+    return EXIT.ok
+  }
+  if (!flags.yes) {
+    const confirmed = await deps.io.confirm(`Remove ${configKey} from ${target.path}?`)
+    if (!confirmed) {
+      deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
+      return EXIT.usage
+    }
+  }
+
+  delete existing[configKey]
+  if (Object.keys(existing).length === 0) {
+    rmSync(target.path, { force: true })
+  } else {
+    writeFileSync(target.path, `${stringifyToml(existing)}\n`)
+  }
+  deps.io.out(`Removed ${configKey} from ${target.path}; the inherited value now applies.`)
+  return EXIT.ok
+}

package/src/commands-core.ts

@@ -0,0 +1,240 @@
+import { SHIPPED_CLI_CAPABILITIES, type RecoveryAction } from '@raidiant/notifai-protocol'
+import { type ClaudeWakeAdapters } from './claude-wake.js'
+import {
+  ApiCallError,
+  NetworkError,
+  createClient,
+  type ApiClient,
+  type ClientOptions,
+} from './client.js'
+import { type CodexWakeAdapters } from './codex-wake.js'
+import { loadConfig, type CliConfig } from './config.js'
+import type { CredentialStore, MachineCredential } from './credentials.js'
+import { type HookAdapterTarget } from './hook-adapter.js'
+import { logConfigResolved, logSettingsFrom, nullLogger, type Logger } from './logging.js'
+import type { NativeSkills } from './native-skills.js'
+import { packageVersion } from './release.js'
+import type { Tone } from './ui/theme.js'
+
+export interface CommandIo {
+  out(line: string): void
+  err(line: string): void
+  /** Interactive confirmation; resolves `fallback` (default false) when not interactive. */
+  confirm(question: string, fallback?: boolean): Promise<boolean>
+  openUrl(url: string): void
+  /**
+   * True only when a human is demonstrably driving a terminal. Everything below
+   * is optional sugar that MUST only be called behind this flag: an agent that
+   * reaches an interactive prompt does not error, it hangs — the prompt
+   * libraries wait on stdin for ever — so the gate is bypass, not handling.
+   * Test fakes leave all of this undefined and exercise the plain paths.
+   */
+  interactive?: boolean
+  select?(message: string, options: { value: string; label: string; hint?: string }[]): Promise<string | null>
+  /** Interactive multi-select. `initial` are pre-selected values. */
+  multiselect?(
+    message: string,
+    options: { value: string; label: string; hint?: string }[],
+    initial?: string[],
+  ): Promise<string[] | null>
+  intro?(title: string): Promise<void>
+  outro?(message: string): Promise<void>
+  note?(message: string, title?: string): Promise<void>
+  spinner?(message: string): Promise<CommandSpinner | null>
+  /**
+   * A report line. `tone` distinguishes the two states that are neither pass
+   * nor fail — something optional the user declined, and something that was
+   * never evaluated — which a boolean has to round to one or the other.
+   * Optional so existing implementations keep type-checking.
+   */
+  check?(ok: boolean, message: string, tone?: Tone): Promise<void>
+}
+
+export interface CommandSpinner {
+  message(message: string): void
+  stop(message: string): void
+  error(message: string): void
+}
+
+export interface CommandDeps {
+  io: CommandIo
+  store: CredentialStore
+  env: NodeJS.ProcessEnv
+  cwd: string
+  /** Test seam; production fixes the hook adapter under os.homedir(). */
+  hookAdapterHome?: string
+  /** Test seam; production uses this process's Node and CLI paths. */
+  hookInstallTarget?: HookAdapterTarget
+  /** Test seam; production uses process.platform for adapter format and quoting. */
+  hookPlatform?: NodeJS.Platform
+  /** Test seam; production uses fetch against base_url. */
+  clientFactory?: (baseUrl: string, bearer: string | null, options?: ClientOptions) => ApiClient
+  /** Test seam for bounded polling without wall-clock sleeps. */
+  now?: () => number
+  /** Test seam for retry/backoff timing. */
+  sleep?: (milliseconds: number) => Promise<void>
+  /** Test seams for Claude liveness, socket delivery, and cold resume. */
+  claudeWake?: ClaudeWakeAdapters
+  claudeSourcePid?: number
+  /** Test seams for the Codex thread-writer probe and cold resume. */
+  codexWake?: CodexWakeAdapters
+  codexSourcePid?: number
+  /** Test seam and production adapter for the external native skills installer. */
+  nativeSkills?: NativeSkills
+  /**
+   * The local record of what this invocation did. Optional so a test fake need
+   * not carry one; `log(deps)` supplies a logger that records nothing.
+   */
+  logger?: Logger
+}
+
+/** The invocation's logger, or one that discards everything. */
+export function log(deps: CommandDeps): Logger {
+  return deps.logger ?? nullLogger()
+}
+
+export function loadLoggedConfig(
+  deps: CommandDeps,
+  options: Parameters<typeof loadConfig>[0],
+): CliConfig {
+  const config = loadConfig(options)
+  const logger = log(deps)
+  logger.adopt(logSettingsFrom(config))
+  logger.bind({ project: config.project.value })
+  logConfigResolved(logger, config)
+  return config
+}
+
+export const EXIT = {
+  ok: 0,
+  failed: 1,
+  usage: 2,
+  noReply: 3,
+  auth: 4,
+  network: 5,
+} as const
+
+export function makeClient(
+  deps: CommandDeps,
+  baseUrl: string,
+  bearer: string | null,
+  options?: ClientOptions,
+): ApiClient {
+  return (deps.clientFactory ?? createClient)(baseUrl, bearer, {
+    ...options,
+    logger: log(deps),
+    cliVersion: packageVersion(),
+    capabilities: SHIPPED_CLI_CAPABILITIES,
+  })
+}
+
+export function resolvedBaseUrl(config: CliConfig, credential: MachineCredential | null): string {
+  return config.base_url.source === 'default' && credential ? credential.baseUrl : config.base_url.value
+}
+
+export function authedClient(deps: CommandDeps, config: CliConfig): { client: ApiClient; baseUrl: string } | null {
+  const credential = deps.store.load()
+  if (!credential) {
+    // The commonest reason a command does nothing, and one that leaves no other
+    // trace: it returns before any request is made, so without this the log
+    // shows an exit code and no cause.
+    log(deps).error('cli.error', { kind: 'auth', message: 'not signed in', store: deps.store.describe() })
+    deps.io.err('Not signed in. Run `notifai login` first.')
+    return null
+  }
+  const baseUrl = resolvedBaseUrl(config, credential)
+  return {
+    client: makeClient(deps, baseUrl, `Bearer nfm_${credential.machineId}.${credential.secret}`),
+    baseUrl,
+  }
+}
+
+export const UPDATE_CLI_COMMAND = 'npm install -g @raidiant/notifai'
+
+function localRecovery(action: RecoveryAction | null): string | null {
+  switch (action) {
+    case 'update_cli':
+      return `next: ${UPDATE_CLI_COMMAND}`
+    case 'update_companion':
+      return 'next: Update Notifai on the named device.'
+    case 'wait_for_service':
+      return 'next: The service is being updated; try again later.'
+    default:
+      return null
+  }
+}
+
+export function reportError(
+  deps: CommandDeps,
+  err: unknown,
+  context: Record<string, unknown> = {},
+): number {
+  // Recorded before it is printed: stderr from an agent's shell call is often
+  // the one thing that does not survive into the next turn, and this is exactly
+  // the line someone comes back looking for.
+  log(deps).error('cli.error', {
+    ...context,
+    ...(err instanceof ApiCallError
+      ? {
+          kind: 'api',
+          status: err.status,
+          code: err.code,
+          message: err.message,
+          next_action: err.nextAction,
+          recovery_action: err.recoveryAction,
+          details: err.details,
+        }
+      : err instanceof NetworkError
+        ? { kind: 'network', message: err.message }
+        : { kind: 'unknown', message: String(err) }),
+  })
+  if (err instanceof ApiCallError) {
+    deps.io.err(
+      deps.io.interactive === true && err.recoveryAction !== null
+        ? err.message
+        : `${err.code}: ${err.message}`,
+    )
+    // The server's field-level details were already being logged above, but
+    // stderr is the one surface an agent's next turn actually reads — so the
+    // diagnosis has to be on it, the same way the hook path prints it.
+    const paths = rejectedPaths(err.details)
+    if (paths.length > 0) deps.io.err(`the server rejected: ${paths.join(', ')}`)
+    // A 422 on a request this CLI built is not a user error: the two sides
+    // disagree about the contract, in whichever direction. `doctor` says which.
+    // Codes that name a policy the account chose are the exception — the
+    // contract held, the body simply did not satisfy that account.
+    if (
+      err.status === 422 &&
+      err.code !== 'acknowledgement_text_required' &&
+      err.code !== 'feature_unavailable'
+    ) {
+      deps.io.err(
+        'this build sent a field the server did not accept — the CLI and server ' +
+          'disagree about the contract; check with `notifai doctor`',
+      )
+    }
+    const recovery = localRecovery(err.recoveryAction)
+    if (recovery !== null) deps.io.err(recovery)
+    else if (err.recoveryAction === null && err.nextAction) deps.io.err(`next: ${err.nextAction}`)
+    if (err.code === 'auth_required' || err.code === 'machine_revoked') return EXIT.auth
+    return err.status >= 500 ? EXIT.network : EXIT.failed
+  }
+  if (err instanceof NetworkError) {
+    deps.io.err(err.message)
+    return EXIT.network
+  }
+  deps.io.err(String(err))
+  return EXIT.failed
+}
+
+export function rejectedPaths(details: unknown): string[] {
+  if (!Array.isArray(details)) return []
+  return details
+    .map((issue) =>
+      typeof issue === 'object' && issue !== null && typeof (issue as { path?: unknown }).path === 'string'
+        ? (issue as { path: string }).path
+        : null,
+    )
+    .filter((path): path is string => path !== null && path !== '')
+    .slice(0, 5)
+}

package/src/commands-devices.ts

@@ -0,0 +1,150 @@
+import { PLATFORMS, type Platform, type RoutableDevice } from '@raidiant/notifai-protocol'
+import {
+  EXIT,
+  authedClient,
+  loadLoggedConfig,
+  makeClient,
+  reportError,
+  resolvedBaseUrl,
+  type CommandDeps,
+} from './commands-core.js'
+
+// ---------------------------------------------------------------------------
+// devices / capabilities
+// ---------------------------------------------------------------------------
+
+export async function devicesCommand(deps: CommandDeps, flags: { json?: boolean }): Promise<number> {
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return EXIT.auth
+  try {
+    const result = await authed.client.listDevices()
+    if (flags.json) {
+      deps.io.out(JSON.stringify(result, null, 2))
+      return EXIT.ok
+    }
+    if (result.devices.length === 0) {
+      const supportUrl = supportPageUrl(authed.baseUrl)
+      let email: string | null = null
+      try {
+        email = (await authed.client.accessStatus()).email
+      } catch {
+        // Best-effort: the empty-state copy still points at /support without it.
+      }
+      deps.io.out(
+        `No devices yet. Install Notifai from ${supportUrl}, ${sameAccountSignInLine(email)}, and allow notifications.`,
+      )
+      return EXIT.ok
+    }
+    for (const d of result.devices) {
+      deps.io.out(
+        `${d.device_id}  ${d.display_name}  ${d.platform}  ${d.status_message ?? 'Working'}`,
+      )
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err)
+  }
+}
+
+/**
+ * Devices as data, for surfaces that render them themselves.
+ *
+ * `devicesCommand` prints and returns an exit code, which is the right shape
+ * for a command and the wrong one for a menu that wants to show names beside
+ * checkboxes. Silent on every failure by design: the interactive app already
+ * shows the credential and connectivity state on its status card, so a second
+ * error line here would be reporting the same fault twice.
+ */
+export async function deviceInventory(deps: CommandDeps): Promise<RoutableDevice[] | null> {
+  if (!deps.store.load()) return null
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const authed = authedClient(deps, config)
+  if (!authed) return null
+  try {
+    return (await authed.client.listDevices()).devices
+  } catch {
+    return null
+  }
+}
+
+/** Whether a device is in a state where a notification would actually arrive. */
+export function canDeviceReceive(device: RoutableDevice): boolean {
+  return deviceCanReceive(device)
+}
+
+export async function capabilitiesCommand(
+  deps: CommandDeps,
+  flags: { json?: boolean; platform?: Platform },
+): Promise<number> {
+  // Locally, and with the same message `send` gives. Spending a round trip to
+  // have the server answer "Request validation failed" told the caller neither
+  // which flag was wrong nor what it accepts.
+  if (flags.platform !== undefined && !(PLATFORMS as readonly string[]).includes(flags.platform)) {
+    deps.io.err(`Unknown platform "${flags.platform}" — use ${PLATFORMS.join(' or ')}.`)
+    return EXIT.usage
+  }
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const credential = deps.store.load()
+  const baseUrl = resolvedBaseUrl(config, credential)
+  const client = makeClient(deps, baseUrl, null)
+  try {
+    const doc = await client.capabilities(flags.platform ?? 'ios')
+    if (flags.json) {
+      deps.io.out(JSON.stringify(doc, null, 2))
+      return EXIT.ok
+    }
+    deps.io.out(`${doc.platform} capability contract v${doc.schema_version} (payload limit ${doc.payload_limit_bytes} bytes)`)
+    for (const field of doc.fields) {
+      deps.io.out(`  ${field.path}: ${field.status}${field.reason ? ` — ${field.reason}` : ''}`)
+    }
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err)
+  }
+}
+
+export function supportPageUrl(baseUrl: string): string {
+  return `${baseUrl.replace(/\/$/, '')}/support`
+}
+
+/** Same-account line for the device hop; prefers the real email when known. */
+export function sameAccountSignInLine(email: string | null | undefined): string {
+  return email
+    ? `sign in with the same email as this account (${email})`
+    : 'sign in with the same email as this account'
+}
+
+export function deviceInstallRemedy(options: {
+  baseUrl: string
+  email: string | null
+  devices: readonly RoutableDevice[]
+}): string {
+  const support = supportPageUrl(options.baseUrl)
+  const sameEmail = sameAccountSignInLine(options.email)
+  if (options.devices.length === 0) {
+    return (
+      `open the install steps at ${support} on your iPhone, ` +
+      `install Notifai, ${sameEmail}, and allow notifications`
+    )
+  }
+  if (options.devices.some((d) => d.permission_status === 'denied')) {
+    return 'allow notifications for Notifai in iPhone Settings'
+  }
+  return 'open Notifai on your iPhone and allow its notification prompt'
+}
+
+export function deviceCanReceive(device: RoutableDevice): boolean {
+  const receiveIsFloored =
+    device.support?.state === 'must_update' &&
+    device.support.affected_operation === 'receive_notifications'
+  return (
+    !receiveIsFloored &&
+    device.registration_healthy &&
+    (device.permission_status === 'authorized' || device.permission_status === 'provisional')
+  )
+}
+
+export function readyIosDevices(devices: readonly RoutableDevice[]): RoutableDevice[] {
+  return devices.filter((device) => device.platform === 'ios' && deviceCanReceive(device))
+}