@raidiant/notifai 4.0.0 → 6.0.0

package/src/client.test.ts

@@ -1,7 +1,8 @@
 import { createServer, type Server } from 'node:http'
 import type { AddressInfo } from 'node:net'
 import { afterEach, describe, expect, it } from 'vitest'
-import { NetworkError, createClient } from './client.js'
+import { CAPABILITIES_HEADER, CLI_VERSION_HEADER } from '@raidiant/notifai-protocol'
+import { ApiCallError, NetworkError, createClient } from './client.js'
 
 /**
  * These run against a real socket rather than a stubbed fetch, because the
@@ -192,3 +193,91 @@ describe('a server that never answers', () => {
     await expect(client.listDevices()).rejects.toBeInstanceOf(NetworkError)
   })
 })
+
+describe('compatibility metadata transport', () => {
+  it('advertises named CLI capabilities only on authenticated traffic', async () => {
+    const seen: Array<{
+      url: string | undefined
+      cliVersion: string | string[] | undefined
+      capabilities: string | string[] | undefined
+    }> = []
+    const baseUrl = await serving((request, response) => {
+      seen.push({
+        url: request.url,
+        cliVersion: request.headers[CLI_VERSION_HEADER],
+        capabilities: request.headers[CAPABILITIES_HEADER],
+      })
+      response.setHeader('content-type', 'application/json')
+      response.end(
+        JSON.stringify({
+          schema_version: 1,
+          platform: 'macos',
+          payload_limit_bytes: 4096,
+          sounds: [],
+          interruption_levels: [],
+          fields: [],
+        }),
+      )
+    })
+    const options = {
+      cliVersion: '5.0.0',
+      capabilities: ['agent_acknowledgement'] as const,
+    }
+
+    await createClient(baseUrl, 'Bearer machine', options).capabilities('macos', '0.1.0', '42')
+    await createClient(baseUrl, null, options).capabilities('macos')
+
+    expect(seen).toEqual([
+      {
+        url: '/api/v1/capabilities/macos?app_version=0.1.0&app_build=42',
+        cliVersion: '5.0.0',
+        capabilities: 'agent_acknowledgement',
+      },
+      {
+        url: '/api/v1/capabilities/macos',
+        cliVersion: undefined,
+        capabilities: undefined,
+      },
+    ])
+  })
+
+  it('keeps recovery typed when a feature is unavailable', async () => {
+    const baseUrl = await serving((_request, response) => {
+      response.statusCode = 422
+      response.setHeader('content-type', 'application/json')
+      response.end(
+        JSON.stringify({
+          error: {
+            code: 'feature_unavailable',
+            message: "The selected device can't answer questions.",
+            next_action: 'run an untrusted server command',
+            recovery_action: 'update_companion',
+            details: {
+              affected_operation: 'answer_questions',
+              missing_capabilities: ['answer'],
+            },
+          },
+        }),
+      )
+    })
+
+    let caught: unknown
+    try {
+      await createClient(baseUrl, 'Bearer machine').compatibility()
+    } catch (error) {
+      caught = error
+    }
+
+    expect(caught).toBeInstanceOf(ApiCallError)
+    expect(caught).toMatchObject({
+      status: 422,
+      code: 'feature_unavailable',
+      recoveryAction: 'update_companion',
+      nextAction: 'run an untrusted server command',
+      details: {
+        affected_operation: 'answer_questions',
+        missing_capabilities: ['answer'],
+      },
+    })
+  })
+})

package/src/client.ts

@@ -9,6 +9,9 @@ import type {
   EvidenceSnapshot,
   GetAgentAcknowledgementResponse,
   ListDevicesResponse,
+  ClientCapability,
+  CompatibilityResponse,
+  RecoveryAction,
   ListRepliesResponse,
   Platform,
   PollPairingResponse,
@@ -17,6 +20,10 @@ import type {
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
+import {
+  CAPABILITIES_HEADER,
+  CLI_VERSION_HEADER,
+} from '@raidiant/notifai-protocol'
 import type { Logger } from './logging.js'
 
 export class ApiCallError extends Error {
@@ -26,6 +33,7 @@ export class ApiCallError extends Error {
     message: string,
     public nextAction: string | null = null,
     public details: unknown = null,
+    public recoveryAction: RecoveryAction | null = null,
   ) {
     super(message)
   }
@@ -67,7 +75,12 @@ export interface ApiClient {
   pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>
   accessStatus(): Promise<AccountAccessResponse>
   listDevices(): Promise<ListDevicesResponse>
-  capabilities(platform?: Platform): Promise<CapabilityDocument>
+  capabilities(
+    platform?: Platform,
+    appVersion?: string,
+    appBuild?: string,
+  ): Promise<CapabilityDocument>
+  compatibility(): Promise<CompatibilityResponse>
   submit(body: SubmitNotificationRequestT, waitSeconds: number): Promise<SubmissionReceipt>
   evidence(requestId: string): Promise<EvidenceSnapshot>
   replies(
@@ -112,6 +125,9 @@ export interface ClientOptions {
    * instantly by a status code and a duration.
    */
   logger?: Pick<Logger, 'debug' | 'error'>
+  /** Artifact identity and named jobs advertised only on authenticated traffic. */
+  cliVersion?: string | null
+  capabilities?: readonly ClientCapability[]
 }
 
 /** Generous enough for a slow link, short enough that nothing hangs for ever. */
@@ -126,6 +142,14 @@ export function createClient(
   const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
   const now = options.now ?? Date.now
   const logger = options.logger
+  const clientHeaders: Record<string, string> = bearer
+    ? {
+        ...(options.cliVersion ? { [CLI_VERSION_HEADER]: options.cliVersion } : {}),
+        ...(options.capabilities
+          ? { [CAPABILITIES_HEADER]: options.capabilities.join(',') }
+          : {}),
+      }
+    : {}
 
   async function call<T>(
     method: string,
@@ -182,6 +206,7 @@ export function createClient(
         headers: {
           ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
           ...(bearer ? { authorization: bearer } : {}),
+          ...clientHeaders,
         },
         signal,
         ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
@@ -202,6 +227,7 @@ export function createClient(
         parsed?.error.message ?? `Request failed with status ${response.status}`,
         parsed?.error.next_action ?? null,
         parsed?.error.details ?? null,
+        parsed?.error.recovery_action ?? null,
       )
     }
     if (response.status === 204) return undefined as T
@@ -220,7 +246,14 @@ export function createClient(
       call('POST', `/api/v1/pairings/${pairingId}/poll`, { poll_verifier: pollVerifier }),
     accessStatus: () => call('GET', '/api/v1/account/access'),
     listDevices: () => call('GET', '/api/v1/devices'),
-    capabilities: (platform = 'ios') => call('GET', `/api/v1/capabilities/${platform}`),
+    capabilities: (platform = 'ios', appVersion, appBuild) => {
+      const query = new URLSearchParams()
+      if (appVersion !== undefined) query.set('app_version', appVersion)
+      if (appBuild !== undefined) query.set('app_build', appBuild)
+      const suffix = query.size > 0 ? `?${query.toString()}` : ''
+      return call('GET', `/api/v1/capabilities/${platform}${suffix}`)
+    },
+    compatibility: () => call('GET', '/api/v1/compatibility'),
     submit: (body, waitSeconds) =>
       call('POST', `/api/v1/notifications?wait_seconds=${waitSeconds}`, body, waitSeconds),
     evidence: (requestId) => call('GET', `/api/v1/notifications/${requestId}`),

package/src/commands-auth.ts

@@ -0,0 +1,174 @@
+import { type AccountAccessResponse } from '@raidiant/notifai-protocol'
+import { sha256Hex } from '@raidiant/notifai-protocol/node'
+import { randomBytes } from 'node:crypto'
+import os from 'node:os'
+import { NetworkError } from './client.js'
+import { type FlagOverrides } from './config.js'
+import {
+  EXIT,
+  authedClient,
+  loadLoggedConfig,
+  makeClient,
+  reportError,
+  type CommandDeps,
+} from './commands-core.js'
+
+// ---------------------------------------------------------------------------
+// login / logout / auth status
+// ---------------------------------------------------------------------------
+
+export async function loginCommand(
+  deps: CommandDeps,
+  flags: { name?: string; baseUrl?: string; open?: boolean },
+): Promise<number> {
+  const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env, flags: { base_url: flags.baseUrl } as FlagOverrides })
+  const baseUrl = config.base_url.value
+  const machineName = flags.name ?? os.hostname()
+  const secret = randomBytes(32).toString('base64url')
+  const pollVerifier = randomBytes(24).toString('base64url')
+  const client = makeClient(deps, baseUrl, null)
+
+  let begin
+  try {
+    begin = await client.beginPairing({
+      machine_name: machineName,
+      credential_hash: sha256Hex(secret),
+      poll_verifier_hash: sha256Hex(pollVerifier),
+    })
+  } catch (err) {
+    return reportError(deps, err)
+  }
+
+  const interactive = deps.io.interactive === true
+  if (interactive) {
+    await deps.io.intro?.('Notifai sign in')
+    await deps.io.note?.(`Code: ${begin.code}\n${begin.approve_url}`, 'Approve this machine')
+  } else {
+    deps.io.out(`Pairing code: ${begin.code}`)
+    deps.io.out(`Approve this machine at: ${begin.approve_url}`)
+    deps.io.out('Waiting for approval…')
+  }
+  if (flags.open !== false) deps.io.openUrl(begin.approve_url)
+
+  const expiresAt = new Date(begin.expires_at).getTime()
+  const intervalMs = Math.max(begin.poll_interval_seconds, 1) * 1000
+  const now = deps.now ?? Date.now
+  const sleep = deps.sleep ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)))
+  const approvalWaitMessage = (): string => {
+    const remainingSec = Math.max(0, Math.ceil((expiresAt - now()) / 1000))
+    const minutes = Math.floor(remainingSec / 60)
+    const seconds = remainingSec % 60
+    const remaining =
+      minutes > 0 ? `${minutes}m ${seconds.toString().padStart(2, '0')}s` : `${seconds}s`
+    return `Waiting for approval… code ${begin.code} · ${remaining} left`
+  }
+  const spinner = interactive ? await deps.io.spinner?.(approvalWaitMessage()) : null
+  while (now() < expiresAt) {
+    await sleep(intervalMs)
+    let poll
+    try {
+      poll = await client.pollPairing(begin.pairing_id, pollVerifier)
+    } catch (err) {
+      if (err instanceof NetworkError) {
+        spinner?.message(`Connection lost — retrying… code ${begin.code}`)
+        continue
+      }
+      spinner?.error('Pairing failed')
+      return reportError(deps, err)
+    }
+    if (poll.status === 'approved' && poll.machine_id) {
+      deps.store.save({ machineId: poll.machine_id, secret, baseUrl, machineName })
+      if (interactive) {
+        spinner?.stop(`Machine "${machineName}" approved`)
+        await deps.io.outro?.(`Credential stored in ${deps.store.describe()}`)
+      } else {
+        deps.io.out(`Machine "${machineName}" approved. Credential stored in ${deps.store.describe()}.`)
+      }
+      return EXIT.ok
+    }
+    if (poll.status === 'denied') {
+      spinner?.error('Pairing denied')
+      deps.io.err('Pairing was denied from the dashboard.')
+      return EXIT.auth
+    }
+    if (poll.status === 'no_active_plan') {
+      const next =
+        poll.next_action ??
+        `Open ${baseUrl.replace(/\/$/, '')}/support to request Alpha access, then retry.`
+      spinner?.error('Account has no Alpha access')
+      deps.io.err('This account has no active plan or temporary Alpha access.')
+      deps.io.err(`next: ${next}`)
+      deps.io.err('After access is granted, run `notifai login` again.')
+      return EXIT.auth
+    }
+    if (poll.status === 'expired') break
+    spinner?.message(approvalWaitMessage())
+  }
+  spinner?.error('Pairing expired')
+  deps.io.err('Pairing expired before it was approved. Run `notifai login` again.')
+  return EXIT.auth
+}
+
+export function logoutCommand(deps: CommandDeps): number {
+  deps.store.clear()
+  deps.io.out('Machine credential removed. Revoke it in the dashboard too if the machine is untrusted.')
+  return EXIT.ok
+}
+
+export function authStatusCommand(deps: CommandDeps, flags: { json?: boolean }): number {
+  const credential = deps.store.load()
+  if (flags.json) {
+    deps.io.out(
+      JSON.stringify(
+        credential
+          ? {
+              signed_in: true,
+              machine_id: credential.machineId,
+              machine_name: credential.machineName,
+              base_url: credential.baseUrl,
+              store: deps.store.describe(),
+            }
+          : { signed_in: false },
+        null,
+        2,
+      ),
+    )
+    return credential ? EXIT.ok : EXIT.auth
+  }
+  if (!credential) {
+    deps.io.err('Not signed in. Run `notifai login`.')
+    return EXIT.auth
+  }
+  deps.io.out(`Signed in as machine "${credential.machineName}" (${credential.machineId})`)
+  deps.io.out(`Server: ${credential.baseUrl}`)
+  deps.io.out(`Credential store: ${deps.store.describe()}`)
+  return EXIT.ok
+}
+
+/** Show the server's account access decision without attempting a product mutation. */
+export async function accessStatusCommand(
+  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 access: AccountAccessResponse = await authed.client.accessStatus()
+    if (flags.json) {
+      deps.io.out(JSON.stringify(access, null, 2))
+      return access.status === 'active' ? EXIT.ok : EXIT.failed
+    }
+    if (access.status === 'no_active_plan') {
+      const supportUrl = `${authed.baseUrl.replace(/\/$/, '')}/support`
+      deps.io.out('No active plan or temporary Alpha access for this account.')
+      deps.io.out(`next: Open ${supportUrl} to request Alpha access, then retry.`)
+      return EXIT.failed
+    }
+    const expiry = access.expires_at ? ` until ${access.expires_at}` : ''
+    deps.io.out(`Access active (${access.reason})${expiry}`)
+    return EXIT.ok
+  } catch (err) {
+    return reportError(deps, err)
+  }
+}

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