@raidiant/notifai 0.2.1 → 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.1";
+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();
@@ -1400,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';
@@ -1484,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.1';
+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] };
@@ -2449,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 {
@@ -2469,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;
@@ -2853,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 {