@raidiant/notifai 4.0.0 → 6.0.0

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