@raidiant/notifai 10.1.0 → 10.1.1

package/src/program.ts

@@ -8,6 +8,7 @@ import {
   authStatusCommand,
   capabilitiesCommand,
   closeCommand,
+  cliUpdateCommand,
   configExplainCommand,
   configSetCommand,
   configShowCommand,
@@ -42,6 +43,7 @@ import type { SkillScope } from './native-skills.js'
 import { GROUP, SEND_GROUP, helpConfiguration, rootHelpFooter } from './ui/help.js'
 import { readStdinWithTimeout } from './hook-input.js'
 import { argvFlagNames } from './logging.js'
+import { QUESTION_SETTLEMENT_INPUT_ENV } from './question-settlement-process.js'
 
 /**
  * One source of truth for the version: the manifest npm actually published.
@@ -80,6 +82,7 @@ function commandPath(command: Command): string {
 const defaultRunners = {
   init: initCommand,
   doctor: doctorCommand,
+  update: cliUpdateCommand,
   login: loginCommand,
   logout: logoutCommand,
   authStatus: authStatusCommand,
@@ -261,6 +264,16 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
       exit(await runners.doctor(deps, opts))
     })
 
+  program
+    .command('update')
+    .helpGroup(GROUP.start)
+    .summary('Update the Notifai command this shell uses')
+    .description('Update the effective global Notifai installation and keep Question Routing on it')
+    .option('--json', 'machine-readable installation and adapter result')
+    .action((opts: { json?: boolean }) => {
+      exit(runners.update(deps, opts))
+    })
+
   const project = program
     .command('project')
     .helpGroup(GROUP.daily)
@@ -500,10 +513,10 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     })
 
   program
-    .command('status <request_id>')
+    .command('status <question_or_request_id>')
     .helpGroup(GROUP.agent)
-    .summary('Show the evidence trail for a request')
-    .description('Show the evidence trail for a notification request')
+    .summary('Show question state or request evidence')
+    .description('Show local question state and, once submitted, the notification request evidence trail')
     .option('--json', 'machine-readable output')
     .action(async (requestId: string, opts: { json?: boolean }) => {
       exit(await runners.status(deps, requestId, opts))
@@ -629,7 +642,18 @@ export function buildProgram(deps: CommandDeps, options: BuildProgramOptions = {
     .option('--harness <name>', 'internal harness output adapter')
     .action(async (event: string, opts: { harness?: string }) => {
       const harness = HOOK_INSTALLABLE_HARNESSES.find((candidate) => candidate === opts.harness)
-      exit(await runners.hookRun(deps, event, () => readStdinWithTimeout(), harness))
+      const settlementInput = deps.env[QUESTION_SETTLEMENT_INPUT_ENV]
+      if (event === 'question-settlement') {
+        delete deps.env[QUESTION_SETTLEMENT_INPUT_ENV]
+      }
+      exit(await runners.hookRun(
+        deps,
+        event,
+        event === 'question-settlement' && settlementInput !== undefined
+          ? async () => settlementInput
+          : () => readStdinWithTimeout(),
+        harness,
+      ))
     })
 
   const hooks = program

package/src/question-settlement-process.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import type { HookInstallableHarness } from './harnesses.js'
+import type { HookEnvelope } from './hooks.js'
+
+/** Private handoff from the short prompt hook to its detached question owner. */
+export const QUESTION_SETTLEMENT_INPUT_ENV = 'NOTIFAI_INTERNAL_QUESTION_SETTLEMENT_INPUT'
+
+export interface QuestionSettlementLaunch {
+  envelope: Pick<HookEnvelope, 'session_id' | 'cwd'>
+  harness: HookInstallableHarness
+}
+
+/**
+ * Launch the exact installed CLI build as a detached owner.
+ *
+ * UserPromptSubmit sits in front of the User's new turn, so it may only pay the
+ * process-spawn cost. The child owns submission and the complete answer window.
+ */
+export function spawnQuestionSettlement(launch: QuestionSettlementLaunch): void {
+  const child = spawn(
+    process.execPath,
+    [
+      fileURLToPath(new URL('./main.js', import.meta.url)),
+      'hook',
+      'question-settlement',
+      '--owner',
+      'notifai',
+      '--harness',
+      launch.harness,
+    ],
+    {
+      cwd: launch.envelope.cwd ?? process.cwd(),
+      detached: true,
+      env: {
+        ...process.env,
+        [QUESTION_SETTLEMENT_INPUT_ENV]: JSON.stringify(launch.envelope),
+      },
+      stdio: 'ignore',
+      windowsHide: true,
+    },
+  )
+  // Spawn failures are diagnosed by the next ordinary lifecycle hook, which
+  // still owns the durable registration. Never turn one into a prompt delay.
+  child.once('error', () => undefined)
+  child.unref()
+}

package/src/readiness.ts

@@ -80,15 +80,48 @@ export function firstBlocker(readiness: Readiness): ReadinessState | null {
   return readiness.states.find((s) => s.status === 'gap') ?? null
 }
 
+/**
+ * Question Routing: what lets a question reach a phone when nobody is at the
+ * terminal. Hooks, their sub-states, and the setting that admits them.
+ *
+ * Separate from `isOptionalSetup` because these are also the states a human
+ * should not be handed as leftovers — "Optional, not set up" is a fair line
+ * about the agent skill and a confusing one about a session pointer.
+ */
+export function isOptionalAutomation(id: string): boolean {
+  return id === 'hooks' || id.startsWith('hooks-') || id === 'question-routing-settings'
+}
+
+/**
+ * Automation layered on top of a product that already sends: Question Routing
+ * and the agent guidance skill.
+ *
+ * Real, and reported. `doctor` is the report and judges it strictly. Anything
+ * whose job is to get a first notification delivered treats it as a line to
+ * print, never a gate — a hook diagnostic or a duplicate skill install in
+ * front of the delivery proof means a setup that can already send never proves
+ * that it can. The one that fires most often, a turn that has not ended yet,
+ * cannot be closed by the agent standing inside that turn at all.
+ */
+export function isOptionalSetup(id: string): boolean {
+  return id === 'skill' || isOptionalAutomation(id)
+}
+
+/** The first thing in the way that is not optional automation. */
+export function firstRequiredBlocker(readiness: Readiness): ReadinessState | null {
+  return readiness.states.find((s) => s.status === 'gap' && !isOptionalSetup(s.id)) ?? 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.
+ * otherwise trains people to ignore the summary line, and it is the summary
+ * line an agent branches on.
  */
 export function isReady(readiness: Readiness): boolean {
-  return firstBlocker(readiness) === null
+  return firstRequiredBlocker(readiness) === null
 }
 
 const SEND_PREREQUISITES = new Set([

package/src/setup-destinations.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import {
+  companionPlatformLabel,
+  setupAccessUrl,
+  setupCompanionUrl,
+  supportPageUrl,
+} from './setup-destinations.js'
+
+describe('focused setup destinations', () => {
+  it('sends a hosted reader to the dashboard they can sign in to', () => {
+    expect(setupAccessUrl('https://api.notifai.sh')).toBe('https://app.notifai.sh/setup/access')
+    expect(setupCompanionUrl('https://notifai.fly.dev')).toBe(
+      'https://app.notifai.sh/setup/companion',
+    )
+  })
+
+  it('keeps a self-host on its own origin', () => {
+    expect(setupAccessUrl('https://notify.example.com/')).toBe(
+      'https://notify.example.com/setup/access',
+    )
+  })
+
+  it('carries the platform this terminal already asked about', () => {
+    expect(setupCompanionUrl('https://api.notifai.sh', 'iphone')).toBe(
+      'https://app.notifai.sh/setup/companion?platform=iphone',
+    )
+    expect(setupAccessUrl('https://api.notifai.sh', 'android')).toBe(
+      'https://app.notifai.sh/setup/access?platform=android',
+    )
+  })
+
+  it('keeps the omnibus help page separate from any setup errand', () => {
+    expect(supportPageUrl('https://api.notifai.sh')).toBe('https://app.notifai.sh/support')
+    expect(setupAccessUrl('https://api.notifai.sh')).not.toContain('/support')
+  })
+
+  it('names each platform the way a reader would', () => {
+    expect(companionPlatformLabel('iphone')).toBe('iPhone')
+    expect(companionPlatformLabel('android')).toBe('Android')
+  })
+})

package/src/setup-destinations.ts

@@ -0,0 +1,50 @@
+/**
+ * Where a cross-surface setup errand is finished.
+ *
+ * Every handoff opens the destination for exactly one errand, carrying the
+ * platform when this terminal already asked for it. The omnibus help page is
+ * help: it covers access, two install routes, billing, refunds, deletion,
+ * privacy and terms, and its own next step is to go somewhere else. Sending
+ * someone there for a named gate makes them find it themselves.
+ *
+ * The server prints these same paths into `next_action`, which is the value
+ * this CLI prefers whenever it has one. These builders are the fallback for
+ * the paths where it does not, and they must stay spelled the same.
+ */
+
+/** The two platforms that can receive a notification. Mac is not one. */
+export const COMPANION_PLATFORMS = ['iphone', 'android'] as const
+export type CompanionPlatform = (typeof COMPANION_PLATFORMS)[number]
+
+export function companionPlatformLabel(platform: CompanionPlatform): string {
+  return platform === 'iphone' ? 'iPhone' : 'Android'
+}
+
+/**
+ * The dashboard a reader can sign in to, which is not always the API origin.
+ * Only the hosted deployment splits them; a self-host serves both from one.
+ */
+function dashboardOrigin(baseUrl: string): string {
+  const normalized = baseUrl.replace(/\/+$/, '')
+  if (normalized === 'https://api.notifai.sh' || normalized === 'https://notifai.fly.dev') {
+    return 'https://app.notifai.sh'
+  }
+  return normalized
+}
+
+/** Getting this Account access to Notifai, and nothing else. */
+export function setupAccessUrl(baseUrl: string, platform?: CompanionPlatform): string {
+  const base = `${dashboardOrigin(baseUrl)}/setup/access`
+  return platform === undefined ? base : `${base}?platform=${platform}`
+}
+
+/** Installing the Companion App on one named platform. */
+export function setupCompanionUrl(baseUrl: string, platform?: CompanionPlatform): string {
+  const base = `${dashboardOrigin(baseUrl)}/setup/companion`
+  return platform === undefined ? base : `${base}?platform=${platform}`
+}
+
+/** General help: billing, policies, and everything setup is not. */
+export function supportPageUrl(baseUrl: string): string {
+  return `${dashboardOrigin(baseUrl)}/support`
+}

package/src/skill.test.ts

@@ -278,6 +278,17 @@ describe('Notifai agent skill', () => {
     expect(ask).toMatch(/tell me here/i)
   })
 
+  it('keeps local registration distinct from submission and delivery evidence', () => {
+    const ask = section('## Ask a question')
+    expect(ask).toMatch(/`registered: true`[\s\S]{0,180}local/i)
+    expect(ask).toMatch(/not yet been submitted as a\s+Notification\s+Request/i)
+    expect(ask).toMatch(/no Provider Acceptance/i)
+    expect(ask).toContain('notifai status <question_id> --json')
+    expect(ask).toMatch(/local.*frozen.*live.*answered.*withdrawn.*retired/is)
+    expect(ask).toMatch(/never call a question\s+sent\s+or\s+delivered\s+from registration alone/i)
+    expect(ask).toMatch(/inspect or close the original[\s\S]{0,160}do not register/i)
+  })
+
   it('requires an acknowledgement before any resumed work', () => {
     const answers = section('## When the answer arrives')
     const acknowledge = answers.indexOf('notifai acknowledge')

package/src/commands-devices.test.ts

@@ -1,15 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { supportPageUrl } from './commands-devices.js'
-
-describe('supportPageUrl', () => {
-  it('routes hosted control-plane origins to the dashboard support surface', () => {
-    expect(supportPageUrl('https://api.notifai.sh')).toBe('https://app.notifai.sh/support')
-    expect(supportPageUrl('https://notifai.fly.dev/')).toBe('https://app.notifai.sh/support')
-  })
-
-  it('keeps a self-hosted deployment on its own support route', () => {
-    expect(supportPageUrl('https://notifai.example.test/')).toBe(
-      'https://notifai.example.test/support',
-    )
-  })
-})