@raidiant/notifai 0.1.0

package/src/main.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { Command } from 'commander'
+import {
+  askCommand,
+  authStatusCommand,
+  capabilitiesCommand,
+  closeCommand,
+  configSetCommand,
+  configShowCommand,
+  devicesCommand,
+  doctorCommand,
+  hookRunCommand,
+  hooksInstallCommand,
+  hooksUninstallCommand,
+  initCommand,
+  loginCommand,
+  logoutCommand,
+  realIo,
+  repliesCommand,
+  sendCommand,
+  statusCommand,
+  type CommandDeps,
+} from './commands.js'
+import { defaultCredentialStore } from './credentials.js'
+import type { Platform } from '@raidiant/notifai-protocol'
+
+const deps: CommandDeps = {
+  io: realIo(),
+  store: defaultCredentialStore(),
+  env: process.env,
+  cwd: process.cwd(),
+}
+
+/**
+ * Harness hooks deliver their event payload on stdin. Bounded on both time and
+ * size: a wrapper that opens the pipe without writing would otherwise hold the
+ * read until the harness killed the hook, delaying the user's own prompt.
+ */
+async function readStdin(timeoutMs = 2000, maxBytes = 1_000_000): Promise<string> {
+  if (process.stdin.isTTY) return ''
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = []
+    let total = 0
+    let settled = false
+    const finish = (): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      process.stdin.destroy()
+      resolve(Buffer.concat(chunks).toString('utf8'))
+    }
+    const timer = setTimeout(finish, timeoutMs)
+    timer.unref?.()
+    process.stdin.on('data', (chunk: Buffer) => {
+      total += chunk.length
+      if (total > maxBytes) return finish()
+      chunks.push(chunk)
+    })
+    process.stdin.on('end', finish)
+    process.stdin.on('error', finish)
+  })
+}
+
+const program = new Command('notifai')
+  .description('Send native device notifications from agents and local programs')
+  .version('0.1.0')
+
+program
+  .command('login')
+  .description('Pair this machine with your NotifAI account via browser approval')
+  .option('--name <name>', 'machine name shown in the dashboard (default: hostname)')
+  .option('--base-url <url>', 'NotifAI server URL')
+  .option('--no-open', 'do not open the approval page in a browser')
+  .action(async (opts: { name?: string; baseUrl?: string; open?: boolean }) => {
+    process.exit(await loginCommand(deps, opts))
+  })
+
+program
+  .command('logout')
+  .description('Remove the stored machine credential')
+  .action(() => {
+    process.exit(logoutCommand(deps))
+  })
+
+const auth = program.command('auth').description('Authentication helpers')
+auth
+  .command('status')
+  .description('Show the stored machine identity')
+  .option('--json', 'machine-readable output')
+  .action((opts: { json?: boolean }) => {
+    process.exit(authStatusCommand(deps, opts))
+  })
+
+program
+  .command('devices')
+  .description('List registered devices and their delivery readiness')
+  .option('--json', 'machine-readable output')
+  .action(async (opts: { json?: boolean }) => {
+    process.exit(await devicesCommand(deps, opts))
+  })
+
+program
+  .command('capabilities')
+  .description('Show a platform capability contract')
+  .option('--platform <platform>', 'platform to describe (default: ios)')
+  .option('--json', 'machine-readable output')
+  .action(async (opts: { json?: boolean; platform?: Platform }) => {
+    process.exit(await capabilitiesCommand(deps, opts))
+  })
+
+program
+  .command('send')
+  .description('Send a notification')
+  .requiredOption('--title <title>', 'notification title')
+  .requiredOption('--body <body>', 'notification body')
+  .option('--subtitle <subtitle>')
+  .option('--detail <markdown>', 'long-form markdown shown only in the app, never on the banner')
+  .option('--detail-file <path>', 'read --detail from a file (use - for stdin)')
+  .option('--event <event>', 'agent event name, e.g. tests_passed')
+  .option('--kind <kind>', 'what this is: update (default) | done | question (requires --reply)')
+  .option('--project <id>', 'project identifier, e.g. my-app (lazily registered)')
+  .option('--session <id>', 'session identity (env: NOTIFAI_SESSION); presentation varies by surface')
+  .option('--device <id>', 'target a device id (repeatable)', (v: string, all: string[]) => [...all, v], [])
+  .option('--all', 'target all routable devices (overrides configured devices)')
+  .option('--ttl <seconds>', 'delivery window in seconds', (v: string) => Number(v))
+  .option('--collapse-key <key>', 'replace earlier notifications with the same key')
+  .option('--platform <platform>', 'platform whose optional fields to include (default: ios)')
+  .option('--sound <sound>', 'default | done | attention | alert | none')
+  .option('--badge <n>', 'app badge count', (v: string) => Number(v))
+  .option('--thread-id <id>', 'group related notifications')
+  .option('--level <level>', 'interruption level: passive | active | time_sensitive')
+  .option('--relevance <score>', '0..1 relevance score', (v: string) => Number(v))
+  .option('--target-content-id <id>')
+  .option('--data <key=value>', 'custom data (repeatable)', (v: string, all: string[]) => [...all, v], [])
+  .option('--image <path|url|media_id>', 'upload or attach an image')
+  .option('--reply', 'enable the inline reply action and block for the answer')
+  .option('--reply-timeout <seconds>', 'how long to wait for a reply (default: 900)', (v: string) => Number(v))
+  .option('--reply-window <seconds>', 'how long the server accepts a reply (default: 86400)', (v: string) => Number(v))
+  .option(
+    '--reply-choice <label>',
+    'with --reply, ask a closed question (2-6 answers); one value splits on commas, or repeat the flag',
+    (v: string, all: string[]) => [...all, v], [],
+  )
+  // Kept registered, and always a usage error with --reply, so the caller gets
+  // a message pointing at `ask` instead of "unknown option".
+  .option('--no-block', 'rejected with --reply; use `notifai ask` to ask and end the turn')
+  .option('--wait <seconds>', 'how long to wait for provider outcomes', (v: string) => Number(v))
+  .option('--no-wait', 'return immediately after acceptance')
+  .option('--idempotency-key <key>', 'safe-retry key (default: random)')
+  .option('--base-url <url>', 'NotifAI server URL')
+  .option('--json', 'print the full submission receipt as JSON')
+  .action(async (opts: Record<string, unknown>) => {
+    // commander maps --no-wait onto the same "wait" flag; disentangle.
+    const noWait = opts['wait'] === false
+    const wait = typeof opts['wait'] === 'number' ? opts['wait'] : undefined
+    const noBlock = opts['block'] === false
+    const sendOpts = { ...opts }
+    // Same empty-collector normalisation as `ask`.
+    if (Array.isArray(sendOpts['replyChoice']) && sendOpts['replyChoice'].length === 0) {
+      delete sendOpts['replyChoice']
+    }
+    delete sendOpts['block']
+    // Long-form detail is usually a build log or a diff summary, which nobody
+    // wants to shell-escape onto a command line.
+    const detailFile = sendOpts['detailFile']
+    delete sendOpts['detailFile']
+    if (typeof detailFile === 'string') {
+      if (sendOpts['detail'] !== undefined) {
+        deps.io.err('Pass either --detail or --detail-file, not both.')
+        process.exit(2)
+      }
+      try {
+        sendOpts['detail'] = readFileSync(detailFile === '-' ? 0 : detailFile, 'utf8')
+      } catch (err) {
+        deps.io.err(`Could not read ${detailFile}: ${String(err)}`)
+        process.exit(2)
+      }
+    }
+    const flags = { ...sendOpts, noWait, noBlock } as Parameters<typeof sendCommand>[1]
+    if (wait === undefined) delete (flags as { wait?: number }).wait
+    else flags.wait = wait
+    process.exit(await sendCommand(deps, flags))
+  })
+
+program
+  .command('replies <request_id>')
+  .description('Retrieve replies for a notification request')
+  .option('--wait <seconds>', 'how long to wait for a reply', (v: string) => Number(v))
+  .option('--after <seq>', 'return replies after this sequence number', (v: string) => Number(v))
+  .option('--json', 'machine-readable output')
+  .action(async (requestId: string, opts: { wait?: number; after?: number; json?: boolean }) => {
+    process.exit(await repliesCommand(deps, requestId, opts))
+  })
+
+program
+  .command('status <request_id>')
+  .description('Show the evidence trail for a notification request')
+  .option('--json', 'machine-readable output')
+  .action(async (requestId: string, opts: { json?: boolean }) => {
+    process.exit(await statusCommand(deps, requestId, opts))
+  })
+
+program
+  .command('ask <question>')
+  .description('Register a question for the turn-end hook to route under your presence settings')
+  .option(
+    '--choice <label>',
+    'answers to offer instead of free text (2-6); one value splits on commas, or repeat the flag',
+    (v: string, all: string[]) => [...all, v], [],
+  )
+  .option('--session <id>', 'session id (default: the session working in this directory, else $NOTIFAI_SESSION)')
+  .action((question: string, opts: { choice?: string[]; session?: string }) => {
+    // commander's collector defaults to []; an empty list means "not asked".
+    const flags: Parameters<typeof askCommand>[2] = {
+      ...(opts.session !== undefined ? { session: opts.session } : {}),
+      ...(opts.choice?.length ? { choice: opts.choice } : {}),
+    }
+    process.exit(askCommand(deps, question, flags))
+  })
+
+program
+  .command('close <request_id>')
+  .description('Retire a question so late answers are rejected rather than lost')
+  .action(async (requestId: string) => {
+    process.exit(await closeCommand(deps, requestId))
+  })
+
+program
+  .command('hook <event>')
+  .description('Internal: run a harness hook (reads hook JSON on stdin)')
+  // Inert, and the point of it is that it is inert: the installed command line
+  // carries a marker that says "NotifAI wrote this" independently of which
+  // checkout wrote it.
+  .option('--owner <name>', 'internal ownership marker')
+  .option('--harness <name>', 'internal harness output adapter')
+  .action(async (event: string, opts: { harness?: string }) => {
+    process.exit(
+      await hookRunCommand(deps, event, readStdin, opts.harness === 'cursor' ? 'cursor' : undefined),
+    )
+  })
+
+const hooks = program.command('hooks').description('Install harness hooks for registered-question routing')
+hooks
+  .command('install')
+  .description('Wire this harness to route registered questions to your devices')
+  .option(
+    '--harness <name>',
+    'claude-code | codex | cursor | opencode (default: detected; OpenCode cannot resume an idle turn from an answer)',
+  )
+  .option('--global', 'install for every project instead of just this one')
+  .action((opts: { harness?: string; global?: boolean }) => {
+    process.exit(hooksInstallCommand(deps, opts))
+  })
+hooks
+  .command('uninstall')
+  .description('Remove the hooks this CLI installed')
+  .option('--harness <name>', 'claude-code | codex | cursor | opencode (default: detected)')
+  .option('--global', 'remove the machine-wide install')
+  .action((opts: { harness?: string; global?: boolean }) => {
+    process.exit(hooksUninstallCommand(deps, opts))
+  })
+
+const config = program.command('config').description('Show or change configuration')
+config
+  .command('show')
+  .description('Show the resolved configuration')
+  .option('--explain', 'show where each value comes from')
+  .option('--json', 'machine-readable output')
+  .action((opts: { json?: boolean; explain?: boolean }) => {
+    process.exit(configShowCommand(deps, opts))
+  })
+config
+  .command('set <key> <value>')
+  .description(
+    'Set a configuration value (choose a layer interactively; unattended defaults machine-global and requires --yes)',
+  )
+  .option('--project', 'write to the shared .notifai/config.toml instead')
+  .option('--local', 'write to personal .notifai/config.local.toml (keep it gitignored)')
+  .option('--session <id>', 'apply only to one session')
+  .option('--yes', 'skip the confirmation gate')
+  .action(
+    async (
+      key: string,
+      value: string,
+      opts: { project?: boolean; local?: boolean; session?: string; yes?: boolean },
+    ) => {
+      process.exit(await configSetCommand(deps, key, value, opts))
+    },
+  )
+
+program
+  .command('init')
+  .description(
+    'Set up NotifAI here, idempotently: sign-in, project id, hooks, device readiness. ' +
+      'Interactive at a human terminal; never prompts otherwise (agents: pass flags)',
+  )
+  .option('--project-id <id>', 'project identifier slug (default: derived from the directory name)')
+  .option('--skills', 'reserved: this build has no published agent-skill source and exits with an error')
+  .option('--no-skills', 'suppress the optional agent-skill status line')
+  .option('--hooks', 'install harness hooks for registered-question routing')
+  .option('--no-hooks', 'skip the hooks without being asked')
+  .action(async (opts: { projectId?: string; skills?: boolean; hooks?: boolean }) => {
+    process.exit(await initCommand(deps, opts))
+  })
+
+program
+  .command('doctor')
+  .description('Audit config, credential, server, contract, device, and hook readiness (no live send)')
+  .option('--json', 'machine-readable output')
+  .action(async (opts: { json?: boolean }) => {
+    process.exit(await doctorCommand(deps, opts))
+  })
+
+await program.parseAsync(process.argv)

package/src/opencode-plugin.ts

@@ -0,0 +1,203 @@
+import path from 'node:path'
+import { configHome } from './install-hooks.js'
+
+/**
+ * The OpenCode adapter.
+ *
+ * OpenCode's extension point is a TypeScript/JavaScript plugin module, not a
+ * command hook, so it needs a different adapter rather than a different path
+ * through the existing one. What it is *not* is different logic: the generated
+ * plugin shells out to the same `notifai hook <event>` commands Claude Code and
+ * Codex invoke, and every decision — presence, the grace window, the reply
+ * wait, retirement — stays in one place.
+ *
+ * The three lifecycle joints map onto the same three events. OpenCode exposes
+ * `chat.message` as a direct hook, while session lifecycle notifications arrive
+ * through its generic `event` hook:
+ *
+ *   chat.message   -> user-prompt-submit   (the user is at the keyboard)
+ *   session.idle   -> stop                 (the turn ended; escalate)
+ *   session.deleted -> session-end         (retire local session state)
+ *
+ * Permission prompts deliberately stay in OpenCode. The CLI question flow
+ * only escalates questions explicitly registered with `notifai ask`.
+ */
+
+/** Marker line; also how an install from another checkout is recognised. */
+export const OPENCODE_PLUGIN_MARKER = '// notifai managed opencode plugin'
+
+/** Filename we own inside whichever plugins directory is being written. */
+export const OPENCODE_PLUGIN_FILENAME = 'notifai.js'
+
+/** Bump when an installed generated file must be rewritten to remain functional. */
+const OPENCODE_ADAPTER_VERSION = 2
+
+export function opencodePluginDir(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return global
+    ? path.join(configHome(env, 'OPENCODE_CONFIG_DIR', '.config/opencode'), 'plugins')
+    : path.join(cwd, '.opencode', 'plugins')
+}
+
+export function opencodePluginPath(
+  global: boolean,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(opencodePluginDir(global, cwd, env), OPENCODE_PLUGIN_FILENAME)
+}
+
+export interface OpencodePluginOptions {
+  execPath: string
+  scriptPath: string
+  /** Child-process lifetime; covers grace, reply wait, and teardown headroom. */
+  timeoutSeconds: number
+}
+
+/**
+ * The generated module.
+ *
+ * Written as a string rather than compiled from a source file because it has to
+ * embed the absolute interpreter and script paths — a bare `notifai` on PATH
+ * fails silently under a plugin host the same way it does under a hook shell.
+ *
+ * Everything it does is build the hook envelope OpenCode's event gives it and
+ * hand that to the CLI on stdin. It deliberately fails open: an adapter error
+ * never changes OpenCode's own behavior.
+ */
+export function opencodePluginSource(options: OpencodePluginOptions): string {
+  const { execPath, scriptPath, timeoutSeconds } = options
+  return `${OPENCODE_PLUGIN_MARKER}
+// Generated by \`notifai hooks install --harness opencode\`. Edits are lost on
+// the next install; change the CLI instead, which is where the logic lives.
+import { spawn } from "node:child_process"
+
+const EXEC = ${JSON.stringify(execPath)}
+const SCRIPT = ${JSON.stringify(scriptPath)}
+const TIMEOUT_MS = ${timeoutSeconds * 1000}
+const ADAPTER_VERSION = ${OPENCODE_ADAPTER_VERSION}
+
+/**
+ * Runs \`notifai hook <event>\`, feeding it the same JSON envelope the other
+ * harnesses send. Resolves to stdout, or null if anything at all went wrong.
+ */
+function runHook(event, envelope) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(EXEC, [SCRIPT, "hook", event, "--owner", "notifai"], {
+        env: process.env,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+      })
+    } catch {
+      resolve(null)
+      return
+    }
+
+    let stdout = ""
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM")
+      finish(null)
+    }, TIMEOUT_MS)
+
+    child.stdout?.setEncoding("utf-8")
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk
+    })
+    // Hook stderr is diagnostics, not plugin output; discard it here.
+    child.stderr?.resume()
+    child.on("error", () => finish(null))
+    child.on("close", () => finish(stdout))
+
+    try {
+      child.stdin?.end(JSON.stringify(envelope))
+    } catch {
+      finish(null)
+    }
+  })
+}
+
+export const NotifAIPlugin = async ({ directory }) => {
+  const cwd = typeof directory === "string" && directory.length > 0 ? directory : process.cwd()
+
+  return {
+    /**
+     * Presence. The user typing is the signal every harness shares, and it is
+     * also what publishes the project -> session pointer \`notifai ask\` reads.
+     */
+    "chat.message": async (input) => {
+      await runHook("user-prompt-submit", {
+        session_id: input?.sessionID ?? input?.info?.sessionID,
+        cwd,
+        hook_event_name: "UserPromptSubmit",
+      })
+    },
+
+    /** Session lifecycle events are delivered through OpenCode's event bus. */
+    event: async ({ event }) => {
+      if (event?.type === "session.idle") {
+        await runHook("stop", {
+          session_id: event?.properties?.sessionID,
+          cwd,
+          hook_event_name: "Stop",
+        })
+      } else if (event?.type === "session.deleted") {
+        await runHook("session-end", {
+          session_id: event?.properties?.info?.id,
+          cwd,
+          hook_event_name: "SessionEnd",
+        })
+      }
+    },
+  }
+}
+`
+}
+
+/** True when a plugin file on disk is one of ours, whoever installed it. */
+export function isOurOpencodePlugin(contents: string): boolean {
+  return contents.includes(OPENCODE_PLUGIN_MARKER)
+}
+
+/**
+ * The interpreter and script a generated plugin will actually run.
+ *
+ * A plugin is a module rather than a command line, so which *build* it invokes
+ * is not visible in the way it is for a settings-file handler — it is baked
+ * into the two constants at the top. `doctor` needs it to answer the question
+ * it exists to answer ("are two checkouts both installed?"), and without it
+ * the plugin's own path stands in for the build and every OpenCode install
+ * looks like a second one.
+ *
+ * Returns null for a plugin we did not generate, or one whose constants have
+ * been edited out of recognisable shape.
+ */
+export function opencodePluginTarget(
+  contents: string,
+): { exec: string; script: string; current: boolean } | null {
+  if (!isOurOpencodePlugin(contents)) return null
+  const exec = /^const EXEC = (".*")$/m.exec(contents)?.[1]
+  const script = /^const SCRIPT = (".*")$/m.exec(contents)?.[1]
+  const version = Number(/^const ADAPTER_VERSION = (\d+)$/m.exec(contents)?.[1] ?? 1)
+  if (exec === undefined || script === undefined) return null
+  try {
+    return {
+      exec: JSON.parse(exec) as string,
+      script: JSON.parse(script) as string,
+      current: version === OPENCODE_ADAPTER_VERSION,
+    }
+  } catch {
+    return null
+  }
+}

package/src/readiness.ts

@@ -0,0 +1,88 @@
+/**
+ * What "set up" means, in one place.
+ *
+ * `init` and `doctor` used to each carry their own idea of this — a fixed
+ * five-step script in one, a flat list of checks in the other — which is two
+ * copies of the same knowledge that can disagree, and did: doctor called
+ * missing hooks fine while init offered to install them, and only doctor knew
+ * what a revoked credential looked like.
+ *
+ * So the model lives here and both commands render it. `doctor` shows every
+ * state at once, because a report is what it is for. `init` walks the same
+ * list in order and stops at the first thing standing in the way, because
+ * someone handed five tasks does none of them. An agent gets the same states
+ * through a third renderer that never prompts.
+ *
+ * The ordering is a dependency chain, not a preference: there is no point
+ * asking the server about devices before there is a credential to ask with,
+ * and no point reporting a stale contract to someone who cannot reach the
+ * server at all. Assessment stops descending when a prerequisite is missing
+ * and marks what follows `unknown` rather than guessing.
+ */
+
+/** Whether the gap can be closed from here, and by whom. */
+export type Remedy =
+  /**
+   * The CLI can do it unattended — no prompt, no human. `command` is how a
+   * reader would ask for it later, for the case where it was declined or
+   * skipped; it is never needed to perform the action.
+   */
+  | { by: 'cli'; summary: string; command?: string }
+  /**
+   * A human at this terminal. `interactive` marks the ones the CLI can drive
+   * on their behalf when someone is actually watching — a browser sign-in is
+   * the CLI's to launch but the human's to complete, so an agent must still
+   * treat it as out of reach.
+   */
+  | { by: 'user-here'; summary: string; command: string; interactive?: boolean }
+  /**
+   * A human somewhere else entirely — phone in hand, app store, permission
+   * dialog. The class the old init could only print a sentence about, and the
+   * one most likely to end an onboarding.
+   */
+  | { by: 'user-elsewhere'; summary: string }
+
+export type StateStatus =
+  /** Satisfied. */
+  | 'ready'
+  /** Not satisfied, and it stands in the way. */
+  | 'gap'
+  /** Not satisfied, and that is a legitimate choice. */
+  | 'optional-gap'
+  /** A prerequisite is missing, so this was never evaluated. */
+  | 'unknown'
+
+export interface ReadinessState {
+  id: string
+  /** Human words for what this is, not the field name. */
+  title: string
+  status: StateStatus
+  /** The current condition, phrased so it reads under either renderer. */
+  detail: string
+  remedy?: Remedy
+}
+
+export interface Readiness {
+  states: ReadinessState[]
+}
+
+/** The first thing standing in the way, or null when nothing is. */
+export function firstBlocker(readiness: Readiness): ReadinessState | null {
+  return readiness.states.find((s) => s.status === 'gap') ?? null
+}
+
+/**
+ * Ready enough to be useful, which is not the same as every box ticked.
+ *
+ * Hooks and the agent skill are genuinely optional — `send` works without
+ * them — so an install that declined both is finished, not half-done. Saying
+ * otherwise trains people to ignore the summary line.
+ */
+export function isReady(readiness: Readiness): boolean {
+  return firstBlocker(readiness) === null
+}
+
+/** Everything that could still be done, blocking or not, in dependency order. */
+export function openItems(readiness: Readiness): ReadinessState[] {
+  return readiness.states.filter((s) => s.status === 'gap' || s.status === 'optional-gap')
+}