@raidiant/notifai 0.2.1 → 0.4.0

package/dist/ui/theme.js

@@ -0,0 +1,261 @@
+/**
+ * One visual language for every human-facing surface: help, `config show`,
+ * `doctor`, and the interactive app.
+ *
+ * Two rules hold everything here together.
+ *
+ * Colour is decoration, never information. Every state that colour marks also
+ * carries a glyph and a word, because the output is read through pipes, on
+ * monochrome terminals, by screen readers, and by people who cannot separate
+ * red from green. `picocolors` resolves to identity functions when stdout is
+ * not a TTY or `NO_COLOR` is set, so the plain path is the same code, not a
+ * second implementation that can drift.
+ *
+ * And an agent's bytes are not ours to restyle. Machine-readable output
+ * (`--json`) never routes through this module, and every non-TTY invocation
+ * lands on the uncoloured branch by construction.
+ */
+import pc from 'picocolors';
+/** True when the terminal can render the box-drawing and status glyphs below. */
+export const unicode = process.platform !== 'win32' ||
+    process.env['WT_SESSION'] !== undefined ||
+    process.env['TERM_PROGRAM'] === 'vscode' ||
+    process.env['ConEmuTask'] === '{cmd::Cmder}';
+/** True when 24-bit colour is available, which the banner gradient needs. */
+export function supportsTrueColor(env = process.env) {
+    if (!pc.isColorSupported)
+        return false;
+    const colorterm = env['COLORTERM'] ?? '';
+    if (/^(truecolor|24bit)$/i.test(colorterm))
+        return true;
+    return env['TERM_PROGRAM'] === 'iTerm.app' || env['TERM_PROGRAM'] === 'vscode';
+}
+export const color = pc;
+/**
+ * Brand ramp, shared with the companion app icon: pink → coral → rose →
+ * magenta. Used for the wordmark and for accenting the surfaces a human sees.
+ */
+export const BRAND_RAMP = ['#FF9EC0', '#FF816B', '#EC5A73', '#B84E93'];
+function hexToRgb(hex) {
+    const value = Number.parseInt(hex.slice(1), 16);
+    return { r: (value >> 16) & 255, g: (value >> 8) & 255, b: value & 255 };
+}
+function mix(a, b, t) {
+    return {
+        r: Math.round(a.r + (b.r - a.r) * t),
+        g: Math.round(a.g + (b.g - a.g) * t),
+        b: Math.round(a.b + (b.b - a.b) * t),
+    };
+}
+/**
+ * Sample the brand ramp at `t` in [0, 1]. Multi-stop so the gradient keeps the
+ * icon's coral midtones instead of washing straight from pink to magenta.
+ */
+export function rampAt(t, ramp = BRAND_RAMP) {
+    const clamped = Math.min(1, Math.max(0, t));
+    const span = ramp.length - 1;
+    const scaled = clamped * span;
+    const index = Math.min(span - 1, Math.floor(scaled));
+    const { r, g, b } = mix(hexToRgb(ramp[index]), hexToRgb(ramp[index + 1]), scaled - index);
+    return `[38;2;${r};${g};${b}m`;
+}
+const RESET = '';
+/**
+ * SGR escape sequences, in the three shapes the helpers below need: stripping
+ * them to measure, splitting around them to slice, and recognising one on its
+ * own. Kept together so a change to what counts as an escape lands once.
+ */
+const ANSI_GLOBAL = /\[[0-9;]*m/g;
+const ANSI_SPLIT = /(\[[0-9;]*m)/;
+const ANSI_ONLY = /^\[[0-9;]*m$/;
+/**
+ * Paint `text` across the brand ramp, one escape per character.
+ *
+ * Falls back to a single flat brand colour without truecolor, and to the bare
+ * string with colour off — a gradient is the most decorative thing this CLI
+ * does, so it must also be the first thing to degrade quietly.
+ */
+export function gradient(text, ramp = BRAND_RAMP) {
+    if (!pc.isColorSupported)
+        return text;
+    if (!supportsTrueColor())
+        return pc.magenta(text);
+    const chars = [...text];
+    const last = Math.max(1, chars.length - 1);
+    return chars.map((char, i) => (char === ' ' ? char : `${rampAt(i / last, ramp)}${char}`)).join('') + RESET;
+}
+/**
+ * Paint each line of a block so the gradient runs left-to-right across the
+ * whole block rather than restarting per line. The wordmark is one image, and
+ * per-line gradients make it read as several.
+ */
+export function gradientBlock(lines, ramp = BRAND_RAMP) {
+    if (!pc.isColorSupported)
+        return [...lines];
+    const width = Math.max(1, ...lines.map((line) => [...line].length));
+    if (!supportsTrueColor())
+        return lines.map((line) => pc.magenta(line));
+    return lines.map((line) => [...line]
+        .map((char, i) => (char === ' ' ? char : `${rampAt(i / Math.max(1, width - 1), ramp)}${char}`))
+        .join('') + RESET);
+}
+// ---------------------------------------------------------------------------
+// Semantic styles
+// ---------------------------------------------------------------------------
+export const style = {
+    /** A heading that opens a section. */
+    heading: (text) => pc.bold(text),
+    /** The brand voice — command names, the product name, the selected thing. */
+    accent: (text) => pc.magenta(text),
+    /** Secondary text: hints, provenance, units, defaults. */
+    dim: (text) => pc.dim(text),
+    /** Something the reader can type. */
+    code: (text) => pc.cyan(text),
+    ok: (text) => pc.green(text),
+    warn: (text) => pc.yellow(text),
+    bad: (text) => pc.red(text),
+    /** A value as it currently stands. */
+    value: (text) => pc.bold(pc.white(text)),
+    /** A value that is not set, or is inherited rather than chosen. */
+    unset: (text) => pc.dim(pc.italic(text)),
+};
+/**
+ * Status marks. The glyph and the colour say the same thing twice on purpose;
+ * either alone is enough to read the line.
+ */
+export const glyph = {
+    ok: unicode ? '●' : '*',
+    warn: unicode ? '▲' : '!',
+    bad: unicode ? '✕' : 'x',
+    pending: unicode ? '○' : 'o',
+    bullet: unicode ? '•' : '-',
+    arrow: unicode ? '→' : '->',
+    chevron: unicode ? '›' : '>',
+    bar: unicode ? '│' : '|',
+};
+/** A coloured glyph for a tone; the caller supplies the words. */
+export function mark(tone) {
+    switch (tone) {
+        case 'ok':
+            return style.ok(glyph.ok);
+        case 'warn':
+            return style.warn(glyph.warn);
+        case 'bad':
+            return style.bad(glyph.bad);
+        case 'pending':
+            return style.dim(glyph.pending);
+    }
+}
+/** Visible width, ignoring ANSI escapes, for alignment maths. */
+export function width(text) {
+    return [...text.replace(ANSI_GLOBAL, '')].length;
+}
+/** Pad to `size` using visible width, so colour never breaks a column. */
+export function pad(text, size) {
+    return text + ' '.repeat(Math.max(0, size - width(text)));
+}
+/**
+ * Usable terminal width: the real one, capped so paragraphs do not run to 200
+ * characters on a maximised window.
+ *
+ * No lower clamp. Raising a narrow terminal to a comfortable minimum sounds
+ * harmless and is not — every box drawn to that invented width overflows the
+ * real one and wraps, which looks far worse than a cramped box that fits.
+ */
+export function terminalWidth(fallback = 80) {
+    const columns = process.stdout.columns;
+    if (typeof columns !== 'number' || columns <= 0)
+        return fallback;
+    return Math.min(100, columns);
+}
+/**
+ * A titled box around `rows`.
+ *
+ * Hand-drawn rather than delegated, because the obvious library call sizes
+ * itself from `process.stdout.columns` and divides by it — a pty that reports
+ * zero columns (some CI runners, some `script` invocations) makes the padding
+ * negative and throws, taking the whole screen down with it. A status card is
+ * decoration; it may degrade, but it must never be what crashes the app.
+ *
+ * Rows are measured with `width`, so colour inside them does not skew the
+ * border, and anything too wide for the terminal is clipped rather than
+ * wrapped — a status line that wraps stops being a status line.
+ */
+export function card(title, rows, columns = terminalWidth()) {
+    const [tl, tr, bl, br, h, v] = unicode
+        ? ['╭', '╮', '╰', '╯', '─', '│']
+        : ['+', '+', '+', '+', '-', '|'];
+    const inner = Math.max(20, columns - 4);
+    const content = rows.map((row) => (width(row) > inner ? clip(row, inner) : row));
+    const bodyWidth = Math.max(width(title) + 4, ...content.map((row) => width(row)));
+    const boxWidth = Math.min(inner, bodyWidth);
+    const heading = `${h} ${style.heading(title)} `;
+    const lines = [];
+    lines.push(style.dim(tl) + heading + style.dim(h.repeat(Math.max(0, boxWidth - width(heading) + 2))) + style.dim(tr));
+    for (const row of content) {
+        lines.push(`${style.dim(v)} ${pad(row, boxWidth)} ${style.dim(v)}`);
+    }
+    lines.push(style.dim(bl + h.repeat(boxWidth + 2) + br));
+    return lines;
+}
+/**
+ * Truncate to a visible width, carrying escape sequences through untouched.
+ *
+ * Counting only printable characters is the whole point: slicing a coloured
+ * string by `String.length` cuts through an escape sequence and spills raw
+ * `[38;2` into the terminal.
+ */
+export function clip(text, limit) {
+    if (width(text) <= limit)
+        return text;
+    const parts = text.split(ANSI_SPLIT);
+    let out = '';
+    let visible = 0;
+    for (const part of parts) {
+        if (part === undefined || part === '')
+            continue;
+        if (ANSI_ONLY.test(part)) {
+            out += part;
+            continue;
+        }
+        for (const char of part) {
+            if (visible >= limit - 1)
+                return `${out}\u2026${RESET}`;
+            out += char;
+            visible += 1;
+        }
+    }
+    return `${out}${RESET}`;
+}
+/**
+ * Wrap `text` to `columns`, returning bare lines.
+ *
+ * Indentation is the caller's, deliberately: an earlier version indented
+ * continuation lines itself, callers indented every line as well, and each
+ * wrapped paragraph stepped further right down the page.
+ */
+export function wrap(text, columns) {
+    // Honour the width asked for. A floor here would silently ignore small
+    // values and hand back lines wider than the caller reserved room for; a
+    // width of zero or less is the only nonsense, and that falls back.
+    const limit = columns > 0 ? columns : 80;
+    const words = text.split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return [''];
+    const lines = [];
+    let line = '';
+    for (const word of words) {
+        const candidate = line === '' ? word : `${line} ${word}`;
+        if (width(candidate) > limit && line !== '') {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = candidate;
+        }
+    }
+    if (line !== '')
+        lines.push(line);
+    return lines;
+}
+//# sourceMappingURL=theme.js.map

package/dist/ui/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../src/ui/theme.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raidiant/notifai",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "Send native phone notifications from agents and local programs",
   "bin": {
@@ -11,10 +11,17 @@
     "src",
     "tsconfig.json"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "pretest": "pnpm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@raidiant/notifai-protocol": "0.2.0",
+    "@raidiant/notifai-protocol": "0.3.0",
     "commander": "^14.0.0",
+    "picocolors": "^1.1.1",
     "smol-toml": "^1.4.0"
   },
   "devDependencies": {
@@ -47,10 +54,5 @@
     "ai",
     "claude",
     "codex"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run"
-  }
-}
+  ]
+}

package/src/atomic-file.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from 'node:crypto'
 import {
+  chmodSync,
   closeSync,
   fsyncSync,
   lstatSync,
@@ -14,6 +15,10 @@ import path from 'node:path'
 export interface AtomicWriteOptions {
   /** Mode for a newly created file. Existing regular files keep their mode. */
   mode?: number
+  /** False when a managed executable must keep the requested mode on repair. */
+  preserveMode?: boolean
+  /** Reject a target owned by another user instead of replacing it. */
+  requireCurrentUserOwner?: boolean
 }
 
 /**
@@ -28,19 +33,29 @@ export function atomicWriteFileSync(
   contents: string,
   options: AtomicWriteOptions = {},
 ): void {
-  mkdirSync(path.dirname(file), { recursive: true })
-  const mode = targetMode(file, options.mode ?? 0o600)
+  const directory = path.dirname(file)
+  mkdirSync(directory, { recursive: true })
+  const parent = safeDirectory(directory, options.requireCurrentUserOwner ?? false)
+  const target = targetMetadata(
+    file,
+    options.mode ?? 0o600,
+    options.preserveMode ?? true,
+    options.requireCurrentUserOwner ?? false,
+  )
   const temp = path.join(
-    path.dirname(file),
+    directory,
     `.${path.basename(file)}.notifai-${process.pid}-${randomBytes(6).toString('hex')}.tmp`,
   )
   let handle: number | undefined
   try {
-    handle = openSync(temp, 'wx', mode)
+    handle = openSync(temp, 'wx', target.mode)
     writeFileSync(handle, contents)
     fsyncSync(handle)
     closeSync(handle)
     handle = undefined
+    chmodSync(temp, target.mode)
+    assertSameDirectory(directory, parent)
+    assertUnchangedTarget(file, target)
     renameSync(temp, file)
   } catch (err) {
     if (handle !== undefined) closeSync(handle)
@@ -54,12 +69,24 @@ export function atomicWriteFileSync(
 }
 
 /** Mode to preserve, or the mode for a new file. Refuses a non-regular target. */
-function targetMode(file: string, fallback: number): number {
+interface TargetMetadata {
+  mode: number
+  identity: { dev: number; ino: number } | null
+}
+
+function targetMetadata(
+  file: string,
+  fallback: number,
+  preserveMode: boolean,
+  requireCurrentUserOwner: boolean,
+): TargetMetadata {
   let stat
   try {
     stat = lstatSync(file)
   } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return fallback
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { mode: fallback, identity: null }
+    }
     throw err
   }
   if (stat.isSymbolicLink()) {
@@ -69,5 +96,57 @@ function targetMode(file: string, fallback: number): number {
     )
   }
   if (!stat.isFile()) throw new Error(`${file} is not a regular file; refusing to replace it.`)
-  return stat.mode & 0o777
+  if (requireCurrentUserOwner) assertCurrentUserOwns(file, stat.uid)
+  return {
+    mode: preserveMode ? stat.mode & 0o777 : fallback,
+    identity: { dev: stat.dev, ino: stat.ino },
+  }
+}
+
+function assertUnchangedTarget(file: string, target: TargetMetadata): void {
+  let current
+  try {
+    current = lstatSync(file)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT' && target.identity === null) return
+    throw new Error(`${file} changed during the atomic write; refusing to replace it.`)
+  }
+  if (
+    target.identity === null ||
+    current.dev !== target.identity.dev ||
+    current.ino !== target.identity.ino
+  ) {
+    throw new Error(`${file} changed during the atomic write; refusing to replace it.`)
+  }
+}
+
+function safeDirectory(
+  directory: string,
+  requireCurrentUserOwner: boolean,
+): { dev: number; ino: number } {
+  const stat = lstatSync(directory)
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`${directory} is not a regular directory; refusing to write inside it.`)
+  }
+  if (requireCurrentUserOwner) assertCurrentUserOwns(directory, stat.uid)
+  return { dev: stat.dev, ino: stat.ino }
+}
+
+function assertSameDirectory(directory: string, expected: { dev: number; ino: number }): void {
+  const current = lstatSync(directory)
+  if (
+    current.isSymbolicLink() ||
+    !current.isDirectory() ||
+    current.dev !== expected.dev ||
+    current.ino !== expected.ino
+  ) {
+    throw new Error(`${directory} changed during the write; refusing to publish the file.`)
+  }
+}
+
+function assertCurrentUserOwns(file: string, owner: number): void {
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+  if (uid !== undefined && owner !== uid) {
+    throw new Error(`${file} is owned by uid ${owner}, not the current user; refusing to replace it.`)
+  }
 }

package/src/client.test.ts

@@ -51,6 +51,18 @@ describe('a server that never answers', () => {
     await expect(client.listDevices()).rejects.toThrow(/did not respond within/)
   })
 
+  it('clamps a late request to the caller whole-operation deadline', async () => {
+    const baseUrl = await serving(() => {})
+    const started = Date.now()
+    const client = createClient(baseUrl, null, {
+      timeoutMs: 5_000,
+      deadlineAt: started + 200,
+    })
+
+    await expect(client.listDevices()).rejects.toBeInstanceOf(NetworkError)
+    expect(Date.now() - started).toBeLessThan(2_000)
+  })
+
   it('allows for the long poll it asked the server to hold', async () => {
     // The deadline is per request, so a 25s long poll must not be cut off by
     // the ordinary budget — otherwise waiting for a reply could never work.

package/src/client.ts

@@ -13,6 +13,7 @@ import type {
   SubmissionReceipt,
   SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
+import type { Logger } from './logging.js'
 
 export class ApiCallError extends Error {
   constructor(
@@ -28,6 +29,18 @@ export class ApiCallError extends Error {
 
 export class NetworkError extends Error {}
 
+/**
+ * Whether a replies-poll failure is temporary while the durable request stays
+ * live. Transport faults, throttling, request timeouts, and server failures
+ * can recover on a later poll; client errors cannot be repaired by retrying
+ * the same authenticated request.
+ */
+export function isRetryableReplyPollError(err: unknown): boolean {
+  if (err instanceof NetworkError) return true
+  if (!(err instanceof ApiCallError)) return false
+  return err.status >= 500 || err.status === 429 || err.status === 408
+}
+
 /**
  * A deadline that fired reads as an abort, which says nothing useful on its
  * own. Naming the timeout is what lets someone tell a hung server apart from a
@@ -57,8 +70,8 @@ export interface ApiClient {
     requestId: string,
     options: { waitSeconds: number; afterSeq: number },
   ): Promise<ListRepliesResponse>
-  /** Retire a question so a late device answer is rejected rather than lost. */
-  closeReplies(requestId: string): Promise<void>
+  /** Retire a question and return the replies committed before the close fence. */
+  closeReplies(requestId: string): Promise<ListRepliesResponse>
   createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>
   uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>
   health(): Promise<boolean>
@@ -71,6 +84,21 @@ export interface ClientOptions {
    * whole network path stays inside the budget the harness allows them.
    */
   timeoutMs?: number
+  /**
+   * Absolute wall-clock ceiling for the caller's whole operation. This is
+   * intentionally separate from `timeoutMs`: a late long poll must not get a
+   * fresh per-request allowance after its owning harness hook is nearly done.
+   */
+  deadlineAt?: number
+  /** Test seam for `deadlineAt`; production uses the wall clock. */
+  now?: () => number
+  /**
+   * Records each call locally. Worth having because the two failures that cost
+   * the most time — a server older than this CLI, and a network path that only
+   * fails inside a hook — both look identical from outside and are told apart
+   * instantly by a status code and a duration.
+   */
+  logger?: Pick<Logger, 'debug' | 'error'>
 }
 
 /** Generous enough for a slow link, short enough that nothing hangs for ever. */
@@ -83,6 +111,8 @@ export function createClient(
 ): ApiClient {
   const root = baseUrl.replace(/\/$/, '')
   const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const now = options.now ?? Date.now
+  const logger = options.logger
 
   async function call<T>(
     method: string,
@@ -90,12 +120,47 @@ export function createClient(
     body?: unknown,
     /** Seconds the server was asked to hold the connection open. */
     serverWaitSeconds = 0,
+  ): Promise<T> {
+    const startedAt = Date.now()
+    try {
+      const result = await callOnce<T>(method, apiPath, body, serverWaitSeconds)
+      logger?.debug('http.call', {
+        method,
+        path: apiPath,
+        ok: true,
+        duration_ms: Date.now() - startedAt,
+      })
+      return result
+    } catch (err) {
+      logger?.error('http.call', {
+        method,
+        path: apiPath,
+        ok: false,
+        duration_ms: Date.now() - startedAt,
+        ...(err instanceof ApiCallError
+          ? { status: err.status, code: err.code, message: err.message, details: err.details }
+          : { message: String(err) }),
+      })
+      throw err
+    }
+  }
+
+  async function callOnce<T>(
+    method: string,
+    apiPath: string,
+    body?: unknown,
+    serverWaitSeconds = 0,
   ): Promise<T> {
     // Without this, a server that accepts the connection and then never answers
     // hangs until the harness kills the whole hook — and the reply-poll deadline
     // cannot interrupt an individual fetch. The signal covers the
     // body read too, not just the response headers.
-    const limitMs = budgetMs + serverWaitSeconds * 1000
+    const requestBudgetMs = budgetMs + serverWaitSeconds * 1000
+    const remainingMs =
+      options.deadlineAt === undefined
+        ? requestBudgetMs
+        : Math.max(1, options.deadlineAt - now())
+    const limitMs = Math.max(1, Math.min(requestBudgetMs, remainingMs))
     const signal = AbortSignal.timeout(limitMs)
     let response: Response
     try {
@@ -154,7 +219,10 @@ export function createClient(
         waitSeconds,
       ),
     closeReplies: (requestId) =>
-      call('POST', `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`),
+      call<ListRepliesResponse>(
+        'POST',
+        `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`,
+      ),
     createMediaUpload: (body) => call('POST', '/api/v1/media', body),
     uploadMedia: async (grant, bytes) => {
       let response: Response