@raidiant/notifai 0.2.0 → 0.3.0

package/dist/commands.d.ts

@@ -1,7 +1,8 @@
-import { type ListRepliesResponse, type Platform, type QuestionT, type ReplyView } from '@raidiant/notifai-protocol';
+import { type ListRepliesResponse, type Platform, type QuestionT, type ReplyView, type RoutableDevice } from '@raidiant/notifai-protocol';
 import { type ApiClient, type ClientOptions } from './client.js';
 import type { CredentialStore } from './credentials.js';
 import { type Readiness } from './readiness.js';
+import type { Tone } from './ui/theme.js';
 import { type HookHarness } from './hooks.js';
 import { type SendFlags } from './send.js';
 import type { NativeSkills, SkillScope } from './native-skills.js';
@@ -28,7 +29,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 {
     message(message: string): void;
@@ -75,6 +82,18 @@ export declare function accessStatusCommand(deps: CommandDeps, flags: {
 export declare function devicesCommand(deps: CommandDeps, flags: {
     json?: boolean;
 }): Promise<number>;
+/**
+ * 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 declare function deviceInventory(deps: CommandDeps): Promise<RoutableDevice[] | null>;
+/** Whether a device is in a state where a notification would actually arrive. */
+export declare function canDeviceReceive(device: RoutableDevice): boolean;
 export declare function capabilitiesCommand(deps: CommandDeps, flags: {
     json?: boolean;
     platform?: Platform;
@@ -197,6 +216,17 @@ export declare function hooksUninstallCommand(deps: CommandDeps, flags: HooksIns
 export declare function configShowCommand(deps: CommandDeps, flags: {
     json?: boolean;
     explain?: boolean;
+    plain?: boolean;
+}): number;
+/**
+ * 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 declare function configExplainCommand(deps: CommandDeps, key: string, flags?: {
+    json?: boolean;
 }): number;
 export declare function configSetCommand(deps: CommandDeps, key: string, rawValue: string, flags: {
     project?: boolean;
@@ -209,7 +239,7 @@ export declare function configSetCommand(deps: CommandDeps, key: string, rawValu
  * 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 declare const SKILLS_SOURCE = "Raidiant-io/notifai#v0.2.0";
+export declare const SKILLS_SOURCE = "Raidiant-io/notifai#v0.3.0";
 /** Derive a contract-valid project slug from a directory name. */
 export declare function projectSlugFrom(name: string): string;
 export interface InitFlags {

package/dist/commands.js

@@ -8,7 +8,9 @@ import { CAPABILITIES_V1, QUESTION_TEXT_MAX_LENGTH, REPLY_MAX_QUESTIONS, REPLY_M
 import { sha256Hex } from '@raidiant/notifai-protocol/node';
 import { ApiCallError, NetworkError, createClient, } from './client.js';
 import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS, NUMERIC_CONFIG_KEYS, configBounds, findProjectConfigPath, findProjectLocalConfigPath, globalConfigPath, loadConfig, sessionConfigPath, } from './config.js';
-import { firstBlocker, openItems } from './readiness.js';
+import { acceptedValues, configInfo } from './config-schema.js';
+import { renderConfigExplain, renderConfigList, renderConfigPlain, } from './ui/config-view.js';
+import { firstBlocker, openItems, } from './readiness.js';
 import { handleSessionEnd, handleStop, handleUserPromptSubmit, parseHookInput, pruneAbandonedSessions, readProjectSession, readProjectSessionPointer, readSessionState, registerQuestion, } from './hooks.js';
 import { readIdleSeconds } from './idle.js';
 import { HARNESSES, applyPlan, blockingHookTimeoutSeconds, buildCursorHookConfig, buildHookConfig, codexLayerDir, codexProjectRoot, detectHarness, findInstallations, handlerEvent, loadCursorSettings, loadSettings, mergeCursorHooks, mergeHooks, removeCursorHooks, removeHooks, settingsFile, } from './install-hooks.js';
@@ -237,6 +239,33 @@ export async function devicesCommand(deps, flags) {
         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) {
+    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) {
+    return deviceCanReceive(device);
+}
 export async function capabilitiesCommand(deps, flags) {
     const config = loadConfig({ cwd: deps.cwd, env: deps.env });
     const credential = deps.store.load();
@@ -433,20 +462,25 @@ export async function repliesCommand(deps, requestedId, flags) {
         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 !== 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;
     }
@@ -455,27 +489,44 @@ export async function repliesCommand(deps, requestedId, flags) {
     if (!authed)
         return EXIT.auth;
     try {
-        const result = await waitForReply(authed.client, requestId, {
-            timeoutSeconds: waitSeconds,
-            afterSeq,
-            now: deps.now,
-            sleep: deps.sleep,
-        });
-        if (flags.json) {
-            deps.io.out(JSON.stringify({ ...result.response, degraded: result.degraded }, null, 2));
+        let anyReplies = false;
+        let anyDegraded = false;
+        let allTimedOut = true;
+        const jsonBodies = [];
+        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;
         }
-        else if (result.response.replies.length > 0) {
-            if (flags.pending === true)
-                deps.io.out(`pending request ${requestId}`);
-            printReplies(deps, result.response.replies);
+        if (flags.json) {
+            // 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);
@@ -1378,39 +1429,133 @@ export function configShowCommand(deps, flags) {
         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, key, flags = {}) {
+    if (!CONFIG_KEYS.includes(key)) {
+        deps.io.err(`Unknown setting "${key}".`);
+        deps.io.err(`Valid settings: ${CONFIG_KEYS.join(', ')}`);
+        return EXIT.usage;
+    }
+    const configKey = key;
+    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) {
+    let best = 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, b) {
+    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, key, rawValue, flags) {
     if (!CONFIG_KEYS.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;
+    const info = configInfo(configKey);
     let value = rawValue;
-    if (NUMERIC_CONFIG_KEYS.includes(key)) {
+    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);
+        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)) {
+    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';
@@ -1462,7 +1607,7 @@ export async function configSetCommand(deps, key, rawValue, flags) {
  * 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() {
     const match = /^([^#]+)#(.+)$/.exec(SKILLS_SOURCE);
     return match === null ? null : { source: match[1], ref: match[2] };
@@ -2427,8 +2572,13 @@ export async function doctorCommand(deps, flags) {
     // 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 {
@@ -2447,6 +2597,19 @@ export async function doctorCommand(deps, flags) {
     }
     return ok ? EXIT.ok : EXIT.failed;
 }
+/** Readiness status as a report tone. */
+function doctorTone(status) {
+    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) {
     const remedy = state.remedy;
@@ -2474,12 +2637,16 @@ function remedyLine(state) {
  * 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) {
     const installations = findInstallations(deps.cwd, deps.env);
@@ -2519,23 +2686,30 @@ function hookStates(deps) {
     }
     /** 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(/-$/, ''),
             title: check.name === 'hooks' || check.name.startsWith('hooks (active')
                 ? 'Question routing'
                 : check.name,
-            status: check.ok ? 'ready' : informational.has(check.name) ? 'optional-gap' : 'gap',
+            status: check.ok
+                ? 'ready'
+                : check.informational === true || informational.has(check.name)
+                    ? 'optional-gap'
+                    : 'gap',
             detail: check.detail,
             ...(check.ok
                 ? {}
                 : {
                     remedy: {
                         by: 'user-here',
-                        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',
+                        }),
                     },
                 }),
         })),
@@ -2573,21 +2747,52 @@ function hookChecks(deps) {
             detail: 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
+            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',
+                            },
+                        }),
+                });
+            }
         }
     }
     // A handler naming an event this build dropped exits 2 every time the harness
@@ -2655,9 +2860,20 @@ function hookChecks(deps) {
     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')) {
         checks.push({
@@ -2778,14 +2994,22 @@ export function realIo(env = process.env) {
                 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 {