@raidiant/notifai 0.2.0 → 0.3.0

package/src/commands.ts

@@ -41,8 +41,21 @@ import {
   type ConfigKey,
   type FlagOverrides,
 } from './config.js'
+import { acceptedValues, configInfo } from './config-schema.js'
+import {
+  renderConfigExplain,
+  renderConfigList,
+  renderConfigPlain,
+} from './ui/config-view.js'
 import type { CredentialStore, MachineCredential } from './credentials.js'
-import { firstBlocker, openItems, type Readiness, type ReadinessState } from './readiness.js'
+import {
+  firstBlocker,
+  openItems,
+  type Readiness,
+  type ReadinessState,
+  type StateStatus,
+} from './readiness.js'
+import type { Tone } from './ui/theme.js'
 import {
   handleSessionEnd,
   handleStop,
@@ -113,7 +126,13 @@ export interface CommandIo {
   outro?(message: string): Promise<void>
   note?(message: string, title?: string): Promise<void>
   spinner?(message: string): Promise<CommandSpinner | null>
-  check?(ok: boolean, message: string): Promise<void>
+  /**
+   * 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 {
@@ -387,6 +406,32 @@ export async function devicesCommand(deps: CommandDeps, flags: { json?: boolean
   }
 }
 
+/**
+ * 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 = loadConfig({ 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 },
@@ -637,20 +682,25 @@ export async function repliesCommand(
     deps.io.err('Pass a request id or --pending, not both.')
     return EXIT.usage
   }
-  let requestId = requestedId
+  let requestIds = requestedId === undefined ? [] : [requestedId]
   if (flags.pending === true) {
     const sessionId = readProjectSession(deps.cwd, deps.env, (deps.now ?? Date.now)())
     if (sessionId === null) {
       deps.io.err('No active session pointer is available in this directory.')
       return EXIT.noReply
     }
-    requestId = readSessionState(sessionId, deps.env).pending?.request_id
-    if (requestId === undefined) {
+    // Every delivered question in the session's queue, in registration order —
+    // an agent may have several outstanding at once.
+    const state = readSessionState(sessionId, deps.env)
+    requestIds = (Array.isArray(state.pending) ? state.pending : [])
+      .map((entry) => entry.request_id)
+      .filter((id): id is string => id !== undefined)
+    if (requestIds.length === 0) {
       deps.io.err(`Session ${sessionId} has no pushed question pending.`)
       return EXIT.noReply
     }
   }
-  if (requestId === undefined) {
+  if (requestIds.length === 0) {
     deps.io.err('Pass a request id or --pending.')
     return EXIT.usage
   }
@@ -659,24 +709,40 @@ export async function repliesCommand(
   const authed = authedClient(deps, config)
   if (!authed) return EXIT.auth
   try {
-    const result = await waitForReply(authed.client, requestId, {
-      timeoutSeconds: waitSeconds,
-      afterSeq,
-      now: deps.now,
-      sleep: deps.sleep,
-    })
+    let anyReplies = false
+    let anyDegraded = false
+    let allTimedOut = true
+    const jsonBodies: object[] = []
+    for (const requestId of requestIds) {
+      const result = await waitForReply(authed.client, requestId, {
+        timeoutSeconds: waitSeconds,
+        afterSeq,
+        now: deps.now,
+        sleep: deps.sleep,
+      })
+      if (flags.json) {
+        jsonBodies.push({ ...result.response, degraded: result.degraded })
+      } else if (result.response.replies.length > 0) {
+        if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
+        printReplies(deps, result.response.replies)
+      } else {
+        printNoReply(deps, requestId, result.response.reply_expires_at)
+      }
+      anyReplies ||= result.response.replies.length > 0
+      anyDegraded ||= result.degraded
+      allTimedOut &&= result.timedOut
+    }
     if (flags.json) {
-      deps.io.out(JSON.stringify({ ...result.response, degraded: result.degraded }, null, 2))
-    } else if (result.response.replies.length > 0) {
-      if (flags.pending === true) deps.io.out(`pending request ${requestId}`)
-      printReplies(deps, result.response.replies)
+      // One request keeps the response shape agents already parse; several
+      // (only possible via --pending) arrive as an array in queue order.
+      deps.io.out(JSON.stringify(jsonBodies.length === 1 ? jsonBodies[0] : jsonBodies, null, 2))
     }
-    else printNoReply(deps, requestId, result.response.reply_expires_at)
-    if (result.degraded) {
+    if (anyDegraded) {
       deps.io.err(DEGRADED_WAIT_WARNING)
       return EXIT.network
     }
-    return result.timedOut ? EXIT.noReply : EXIT.ok
+    if (anyReplies) return EXIT.ok
+    return allTimedOut ? EXIT.noReply : EXIT.ok
   } catch (err) {
     return reportError(deps, err)
   }
@@ -1729,7 +1795,7 @@ function resolveHarness(deps: CommandDeps, requested: string | undefined): Harne
 
 export function configShowCommand(
   deps: CommandDeps,
-  flags: { json?: boolean; explain?: boolean },
+  flags: { json?: boolean; explain?: boolean; plain?: boolean },
 ): number {
   const config = loadConfig({ cwd: deps.cwd, env: deps.env })
   if (flags.json) {
@@ -1739,14 +1805,111 @@ export function configShowCommand(
     deps.io.out(JSON.stringify(output, null, 2))
     return EXIT.ok
   }
-  for (const key of CONFIG_KEYS) {
-    const entry = config[key]
-    const provenance = flags.explain ? `  [${entry.source}]` : ''
-    deps.io.out(`${key} = ${JSON.stringify(entry.value)}${provenance}`)
+  // 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 `require_idle = true` and there was
+ * nowhere to go from there. 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 = loadConfig({ 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,
@@ -1754,30 +1917,43 @@ export async function configSetCommand(
   flags: { project?: boolean; local?: boolean; session?: string; yes?: boolean },
 ): Promise<number> {
   if (!(CONFIG_KEYS as readonly string[]).includes(key)) {
-    deps.io.err(`Unknown key "${key}". Valid keys: ${CONFIG_KEYS.join(', ')}`)
+    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 EXIT.usage
   }
+  const configKey = key as ConfigKey
+  const info = configInfo(configKey)
   let value: unknown = rawValue
-  if (NUMERIC_CONFIG_KEYS.includes(key as ConfigKey)) {
+  if (NUMERIC_CONFIG_KEYS.includes(configKey)) {
     const numeric = Number(rawValue)
     if (!Number.isInteger(numeric)) {
-      deps.io.err(`"${rawValue}" is not an integer.`)
+      deps.io.err(`${key} takes ${acceptedValues(configKey)}, not "${rawValue}".`)
       return EXIT.usage
     }
-    const bounds = configBounds(key as ConfigKey)
+    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(key as ConfigKey)) {
+  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)
 
   let layer = flags.local ? 'local' : flags.project ? 'project' : 'global'
@@ -1836,7 +2012,7 @@ export async function configSetCommand(
  * 1.5.x, `owner/repo@name` selects a skill; a Git ref belongs after `#`.
  * Keep this immutable and public because the command is printed to users.
  */
-export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.2.0'
+export const SKILLS_SOURCE = 'Raidiant-io/notifai#v0.3.0'
 
 function skillSourceParts(): { source: string; ref: string } | null {
   const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE)
@@ -2991,7 +3167,13 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   // costs nothing.
   if (deps.io.interactive === true && deps.io.check) {
     await deps.io.intro?.('Notifai doctor')
-    for (const s of readiness.states) await deps.io.check(s.status !== 'gap', line(s))
+    for (const s of readiness.states) {
+      // Four states, not two. Rendering `optional-gap` and `unknown` as
+      // successes made a green report that had never checked half of what it
+      // listed, and put a tick beside things the reader had deliberately
+      // declined.
+      await deps.io.check(s.status !== 'gap', line(s), doctorTone(s.status))
+    }
     await deps.io.outro?.(ok ? 'Everything looks good' : `Start with: ${remedyLine(blocker)}`)
   } else {
     for (const s of readiness.states) {
@@ -3010,6 +3192,20 @@ export async function doctorCommand(deps: CommandDeps, flags: { json?: boolean }
   return ok ? EXIT.ok : EXIT.failed
 }
 
+/** Readiness status as a report tone. */
+function doctorTone(status: StateStatus): Tone {
+  switch (status) {
+    case 'ready':
+      return 'ok'
+    case 'gap':
+      return 'bad'
+    case 'optional-gap':
+      return 'warn'
+    case 'unknown':
+      return 'pending'
+  }
+}
+
 /** One line telling the reader what to actually do about a state. */
 function remedyLine(state: ReadinessState): string {
   const remedy = state.remedy
@@ -3036,12 +3232,16 @@ function remedyLine(state: ReadinessState): string {
  * way and is not worth re-deriving. The judgment added here is which failures
  * actually stand in the way.
  *
- * Two do not. A hook that has never fired is the normal condition of an
- * install thirty seconds old, and OpenCode's inability to resume an idle turn
- * is a property of that harness rather than a fault in this setup. Treating
- * either as blocking would mean `init` could never finish for an OpenCode
- * user, or could only finish after a session had already run — so both report
- * as things worth knowing rather than things to fix.
+ * Not everything failed is in the way. A pointer that has never been
+ * published is the normal condition of an install thirty seconds old — the
+ * next prompt fixes it and no command can — and OpenCode's inability to
+ * resume an idle turn is a property of that harness rather than a fault in
+ * this setup. Treating those as blocking would mean `init` could never
+ * finish for an OpenCode user, or could only finish after a session had
+ * already run — so they report as things worth knowing rather than things to
+ * fix, and `init` walks on to the states it can actually close, delivery
+ * proof included. Which failures are informational, and what the true remedy
+ * is, is each check's own call (`HookCheck`).
  */
 function hookStates(deps: CommandDeps): ReadinessState[] {
   const installations = findInstallations(deps.cwd, deps.env)
@@ -3084,7 +3284,6 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
 
   /** Real but not in the way; see the note above. */
   const informational = new Set(['hooks (opencode continuation)'])
-  if (active === null) informational.add('hooks (fired)')
   return [
     ...hookChecks(deps).map((check) => ({
       id: check.name.replace(/[ ()]+/g, '-').replace(/-$/, ''),
@@ -3092,15 +3291,24 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
         check.name === 'hooks' || check.name.startsWith('hooks (active')
           ? 'Question routing'
           : check.name,
-      status: check.ok ? 'ready' as const : informational.has(check.name) ? 'optional-gap' as const : 'gap' as const,
+      status: check.ok
+        ? 'ready' as const
+        : check.informational === true || informational.has(check.name)
+          ? 'optional-gap' as const
+          : 'gap' as const,
       detail: check.detail,
       ...(check.ok
         ? {}
         : {
             remedy: {
               by: 'user-here' as const,
-              summary: 'the detail above names what to change',
-              command: 'notifai hooks install',
+              // The check's own remedy when it has one; the generic reinstall
+              // line was wrong exactly where it mattered (an unfired pointer
+              // needs a prompt, not `hooks install`).
+              ...(check.remedy ?? {
+                summary: 'the detail above names what to change',
+                command: 'notifai hooks install',
+              }),
             },
           }),
     })),
@@ -3108,8 +3316,18 @@ function hookStates(deps: CommandDeps): ReadinessState[] {
   ]
 }
 
-function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: string }[] {
-  const checks: { name: string; ok: boolean; detail: string }[] = []
+interface HookCheck {
+  name: string
+  ok: boolean
+  detail: string
+  /** Real but not in the way: worth a line, never a blocker. */
+  informational?: boolean
+  /** A remedy truer than the generic `notifai hooks install`. */
+  remedy?: { summary: string; command: string }
+}
+
+function hookChecks(deps: CommandDeps): HookCheck[] {
+  const checks: HookCheck[] = []
   const installations = findInstallations(deps.cwd, deps.env)
 
   // Not having hooks is a setup someone chose, not a fault: `send` works
@@ -3143,23 +3361,52 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
         activeInstallations.length > 0
           ? `active ${active.label} session has a matching hook installation`
           : `active ${active.label} session has no matching hook installation — run \`notifai hooks install --harness ${active.harness}\``,
+      ...(activeInstallations.length > 0
+        ? {}
+        : {
+            remedy: {
+              summary: `install hooks for the active ${active.label} session`,
+              command: `notifai hooks install --harness ${active.harness}`,
+            },
+          }),
     })
     if (activeInstallations.length > 0) {
       const pointer = readProjectSessionPointer(deps.cwd, deps.env, (deps.now ?? Date.now)())
-      const matches =
-        pointer !== null &&
-        pointer.harness === active.harness &&
-        (active.sessionId === undefined || pointer.sessionId === active.sessionId)
-      checks.push({
-        name: 'hooks (active session)',
-        ok: matches,
-        detail:
-          pointer === null
-            ? `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`
-            : matches
-              ? `the project pointer belongs to the active ${active.label} session`
-              : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
-      })
+      if (pointer === null) {
+        // The normal condition of hooks installed moments ago: the pointer
+        // appears when the harness next fires a hook, and no command can
+        // force that. Informational, so `init` walks on to the states it can
+        // actually prove instead of exiting over evidence only time produces.
+        checks.push({
+          name: 'hooks (active session)',
+          ok: false,
+          informational: true,
+          detail: `active ${active.label} session has not published a live pointer — send one ${active.label} prompt, then check again`,
+          remedy: {
+            summary: `send one ${active.label} prompt — its hook publishes the routing pointer`,
+            command: 'notifai doctor',
+          },
+        })
+      } else {
+        const matches =
+          pointer.harness === active.harness &&
+          (active.sessionId === undefined || pointer.sessionId === active.sessionId)
+        checks.push({
+          name: 'hooks (active session)',
+          ok: matches,
+          detail: matches
+            ? `the project pointer belongs to the active ${active.label} session`
+            : `the project pointer belongs to another ${active.label} session or harness; refusing cross-session routing`,
+          ...(matches
+            ? {}
+            : {
+                remedy: {
+                  summary: `send one ${active.label} prompt in this session so the pointer belongs to it`,
+                  command: 'notifai doctor',
+                },
+              }),
+        })
+      }
     }
   }
 
@@ -3252,9 +3499,20 @@ function hookChecks(deps: CommandDeps): { name: string; ok: boolean; detail: str
   checks.push({
     name: 'hooks (fired)',
     ok: fired,
+    // Never-fired is evidence about the past, not a fault in the setup, and
+    // the cure is a prompt no command can send.
+    informational: true,
     detail: fired
       ? 'a session in this directory has run them'
       : `no session pointer from the last 24 hours — ${hookActivationAdvice(activationInstallations)}`,
+    ...(fired
+      ? {}
+      : {
+          remedy: {
+            summary: 'send one prompt in a session here, then re-check',
+            command: 'notifai doctor',
+          },
+        }),
   })
 
   if (installations.some((installation) => installation.harness === 'opencode')) {
@@ -3380,11 +3638,21 @@ export function realIo(env: NodeJS.ProcessEnv = process.env): CommandIo {
         error: (next) => progress.error(next),
       }
     },
-    check: async (ok, message) => {
+    check: async (ok, message, tone) => {
       if (!interactive()) return
       const { log } = await clack()
-      if (ok) log.success(message)
-      else log.error(message)
+      switch (tone ?? (ok ? 'ok' : 'bad')) {
+        case 'ok':
+          return log.success(message)
+        case 'warn':
+          return log.warn(message)
+        case 'pending':
+          // Never checked. `log.info` reads as neutral, which is the honest
+          // rendering for a state no evidence was gathered about.
+          return log.info(message)
+        case 'bad':
+          return log.error(message)
+      }
     },
     openUrl: (url) => {
       try {