@raidiant/notifai 7.0.2 → 9.0.0

package/src/commands-doctor.ts

@@ -40,15 +40,17 @@ import {
 } from './readiness.js'
 import { packageVersion } from './release.js'
 import type { Tone } from './ui/theme.js'
+import type { MachineCredential } from './credentials.js'
 import {
   EXIT,
   UPDATE_CLI_COMMAND,
+  diagnoseIgnoredOriginOverride,
   loadLoggedConfig,
   makeClient,
   resolvedBaseUrl,
   type CommandDeps,
 } from './commands-core.js'
-import { deviceInstallRemedy, readyIosDevices, supportPageUrl } from './commands-devices.js'
+import { deviceInstallRemedy, readyCompanionDevices, supportPageUrl } from './commands-devices.js'
 import {
   activeHarnessSession,
   claudeSessionPid,
@@ -56,8 +58,25 @@ import {
   type ActiveHarnessSession,
 } from './commands-harness-context.js'
 import { stopShapeProblems } from './commands-hook-shape.js'
-import { HOOK_EVENTS, activeQuestionRouteProblems, hookActivationAdvice } from './commands-hooks.js'
-import { observedCompanionReceipt, readSetupProof } from './commands-setup-proof.js'
+import {
+  HOOK_EVENTS,
+  activeQuestionRouteProblems,
+  hookActivationAdvice,
+  requiredHookEvents,
+} from './commands-hooks.js'
+import { cliBinReadiness } from './cli-bin.js'
+import {
+  latestPublishedCliVersion,
+  newerPublishedCli,
+  shouldConsultCliRegistry,
+  thisCliVersion,
+} from './cli-release.js'
+import {
+  SETUP_PROOF_STALE_MS,
+  observedCompanionReceipt,
+  readSetupProof,
+  setupProofIsStale,
+} from './commands-setup-proof.js'
 import { skillReadiness } from './commands-skill.js'
 
 // ---------------------------------------------------------------------------
@@ -236,10 +255,14 @@ function remoteStatesFrom(previous: Readiness): {
   return { credential, server, contract, auth, devices, proof }
 }
 
-function remoteInvalidatedByConfig(previous: Readiness, config: CliConfig): boolean {
-  if (config.base_url.source === 'default') return false
+function remoteInvalidatedByConfig(
+  previous: Readiness,
+  config: CliConfig,
+  credential: MachineCredential | null,
+): boolean {
+  const origin = resolvedBaseUrl(config, credential)
   const server = previous.states.find((state) => state.id === 'server')
-  return server === undefined || !server.detail.includes(config.base_url.value)
+  return server === undefined || !server.detail.includes(origin)
 }
 
 /**
@@ -257,9 +280,12 @@ export async function assessReadiness(
     skillScope?: SkillScope
     previous?: Readiness
     refresh?: readonly ReadinessRefresh[]
+    json?: boolean
   } = {},
 ): Promise<Readiness> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env })
+  const credential = deps.store.load()
+  if (credential) diagnoseIgnoredOriginOverride(deps.io, config, credential)
   const previous = options.previous
   const refresh = options.refresh
   if (previous !== undefined && refresh !== undefined && refresh.length === 0) return previous
@@ -268,12 +294,13 @@ export async function assessReadiness(
     previous !== undefined &&
     refresh !== undefined &&
     !refresh.includes('remote') &&
-    !remoteInvalidatedByConfig(previous, config)
+    !remoteInvalidatedByConfig(previous, config, credential)
   if (reuseRemote) {
     const reused = remoteStatesFrom(previous)
     if (reused !== null) {
       return {
         states: [
+          cliBinReadiness(deps.env, deps.hookPlatform ?? process.platform),
           projectReadiness(deps, config),
           reused.credential,
           reused.server,
@@ -292,9 +319,9 @@ export async function assessReadiness(
   let accountClient: ApiClient | null = null
   let accountDevices: RoutableDevice[] | null = null
 
+  states.push(cliBinReadiness(deps.env, deps.hookPlatform ?? process.platform))
   states.push(projectReadiness(deps, config))
 
-  const credential = deps.store.load()
   states.push(
     credential
       ? {
@@ -418,15 +445,17 @@ export async function assessReadiness(
     states.push({ id: 'devices', title: 'Your devices', status: 'unknown', detail: 'not checked — sign-in failed' })
   } else {
     const devices = accountDevices
-    const iphoneDevices = devices.filter((device) => device.platform === 'ios')
-    const ready = readyIosDevices(iphoneDevices)
+    const companionDevices = devices.filter(
+      (device) => device.platform === 'ios' || device.platform === 'android',
+    )
+    const ready = readyCompanionDevices(companionDevices)
     states.push(
       ready.length > 0
         ? {
             id: 'devices',
             title: 'Your devices',
             status: 'ready',
-            detail: `${ready.map((d) => d.display_name).join(', ')} ready to receive`,
+            detail: `${ready.map((d) => `${d.display_name} (${d.platform})`).join(', ')} ready to receive`,
           }
         : {
             id: 'devices',
@@ -439,15 +468,15 @@ export async function assessReadiness(
             // permission prompt. The live bridge is /support on the
             // dashboard origin — not a placeholder, and not typed by hand.
             detail:
-              iphoneDevices.length === 0
-                ? `no iPhone registered yet; install Notifai on iPhone via ${supportPageUrl(baseUrl)}`
-                : `${iphoneDevices.map((d) => `${d.display_name} (${d.permission_status})`).join(', ')} — registered but not able to receive`,
+              companionDevices.length === 0
+                ? `no active Companion device registered yet; install Notifai via ${supportPageUrl(baseUrl)}`
+                : `${companionDevices.map((d) => `${d.display_name} (${d.platform}, ${d.permission_status})`).join(', ')} — registered but not able to receive`,
             remedy: {
               by: 'user-elsewhere',
               summary: deviceInstallRemedy({
                 baseUrl,
                 email: accountEmail,
-                devices: iphoneDevices,
+                devices: companionDevices,
               }),
             },
           },
@@ -455,10 +484,39 @@ export async function assessReadiness(
   }
 
   states.push(await setupProofState(deps, config, accountClient, accountDevices))
+  await applyRegistryRecommendation(deps, options.json === true, states)
 
   return { states }
 }
 
+async function applyRegistryRecommendation(
+  deps: CommandDeps,
+  json: boolean,
+  states: ReadinessState[],
+): Promise<void> {
+  if (
+    !shouldConsultCliRegistry({
+      ...(deps.io.interactive === undefined ? {} : { interactive: deps.io.interactive }),
+      json,
+      env: deps.env,
+    })
+  ) {
+    return
+  }
+  const latest = await latestPublishedCliVersion(deps.fetchImpl)
+  const newer = newerPublishedCli(thisCliVersion(), latest)
+  if (newer === null) return
+  const contract = states.find((state) => state.id === 'contract')
+  if (contract === undefined || contract.status === 'gap') return
+  contract.status = 'optional-gap'
+  contract.detail = 'A newer Notifai is available.'
+  contract.remedy = {
+    by: 'user-here',
+    summary: 'update Notifai',
+    command: UPDATE_CLI_COMMAND,
+  }
+}
+
 async function setupProofState(
   deps: CommandDeps,
   config: CliConfig,
@@ -474,18 +532,21 @@ async function setupProofState(
     }
   }
 
-  const ios = readyIosDevices(devices)
-  if (ios.length === 0) {
+  const companions = readyCompanionDevices(devices)
+  if (companions.length === 0) {
     return {
       id: 'proof',
       title: 'Delivery proof',
       status: 'unknown',
-      detail: 'not checked — no iPhone is ready',
+      detail: 'not checked — no iPhone or Android Companion App is ready',
     }
   }
 
   const proof = readSetupProof(deps)
-  const target = proof === null ? null : ios.find((device) => device.device_id === proof.device_id)
+  const target =
+    proof === null
+      ? null
+      : companions.find((device) => device.device_id === proof.device_id)
   if (proof === null || proof.project !== config.project.value || target === undefined) {
     return {
       id: 'proof',
@@ -513,6 +574,20 @@ async function setupProofState(
         detail: `Companion Receipt (the app's delivery confirmation) observed from ${observed.delivery.device_name} at ${observed.observedAt} (${proof.request_id})`,
       }
     }
+    const now = (deps.now ?? Date.now)()
+    if (setupProofIsStale(proof, now)) {
+      return {
+        id: 'proof',
+        title: 'Delivery proof',
+        status: 'gap',
+        detail: `${proof.request_id} is older than ${SETUP_PROOF_STALE_MS / 36e5}h with no Companion Receipt; init will send a replacement`,
+        remedy: {
+          by: 'cli',
+          summary: 'replace the stale verification notification',
+          command: 'notifai init',
+        },
+      }
+    }
     return {
       id: 'proof',
       title: 'Delivery proof',
@@ -544,7 +619,8 @@ export async function doctorCommand(
   flags: { json?: boolean },
   options: { readiness?: Readiness } = {},
 ): Promise<number> {
-  const readiness = options.readiness ?? (await assessReadiness(deps))
+  const readiness =
+    options.readiness ?? (await assessReadiness(deps, flags.json === true ? { json: true } : {}))
   const blocker = firstBlocker(readiness)
   const ok = blocker === null
 
@@ -874,13 +950,25 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
       })
       .map((h) => `${h.event} -> ${handlerEvent(h.command)} in ${i.file}`),
   )
+  const missing = installations.flatMap((installation) => {
+    const required = requiredHookEvents(installation.harness)
+    const installed = new Set(
+      installation.handlers
+        .map((handler) => handlerEvent(handler.command))
+        .filter((event): event is string => event !== null),
+    )
+    const absent = required.filter((event) => !installed.has(event))
+    return absent.length === 0
+      ? []
+      : [`${installation.file} is missing ${absent.join(', ')}`]
+  })
   checks.push({
     name: 'hooks (stale)',
-    ok: stale.length === 0,
+    ok: stale.length === 0 && missing.length === 0,
     detail:
-      stale.length === 0
-        ? 'every installed handler names an event this build serves'
-        : `${stale.join('; ')} — rerun \`notifai hooks install\` to drop ${stale.length === 1 ? 'it' : 'them'}`,
+      stale.length === 0 && missing.length === 0
+        ? 'every installed handler names an event this build serves, and every required lifecycle handler is present'
+        : `${[...stale, ...missing].join('; ')} — rerun \`notifai hooks install\` to refresh the complete lifecycle set`,
   })
 
   const adapterProblems = installations.flatMap((installation) =>
@@ -935,7 +1023,10 @@ function hookChecks(deps: CommandDeps): HookCheck[] {
   // Project and global definitions for one harness both fire. Stable adapter
   // identity deliberately makes their command bytes equal, so comparing
   // command targets would now hide this duplicate rather than diagnose it.
-  // Different harnesses remain independent: only the active one runs.
+  // Cursor is the exception to harness independence because it may also load
+  // Claude's user hook file. The shared adapter detects Cursor's hook-only
+  // environment and makes that compatibility copy a no-op; the native Cursor
+  // definition remains the single routing owner.
   const duplicated = [...new Set(installations.map((i) => i.harness))]
     .map((harness) => ({
       harness,

package/src/commands-guidance.ts

@@ -0,0 +1,216 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { describeSource } from './config-schema.js'
+import { EXIT, type CommandDeps } from './commands-core.js'
+import {
+  GUIDANCE_TRUST_PREAMBLE,
+  SHIPPED_GUIDANCE,
+  shippedGuidanceTopic,
+} from './guidance-content.js'
+import {
+  GUIDANCE_TOPIC_MAX_BYTES,
+  GUIDANCE_TOPIC_PATTERN,
+  findProjectGuidanceDir,
+  globalGuidanceDir,
+  personalProjectGuidanceDir,
+  resolveGuidance,
+  type GuidanceAuthority,
+} from './guidance.js'
+
+// ---------------------------------------------------------------------------
+// guidance show / set / unset
+// ---------------------------------------------------------------------------
+
+/** How each authority is named in the marker above a topic. */
+const AUTHORITY_LABEL: Record<GuidanceAuthority, string> = {
+  user: 'you',
+  repository: 'this repository',
+  shipped: 'shipped default',
+}
+
+/**
+ * The token that makes a marker line ours.
+ *
+ * Without it, a repository topic could open with a handwritten
+ * `<!-- when-to-notify · this machine · /Users/... -->` and everything after
+ * it would read as the User's own standing word. The marker therefore carries
+ * a fixed token, and any occurrence of that token inside file content is
+ * defanged below — so the only lines that can claim to be provenance are the
+ * ones this command wrote.
+ */
+const MARKER_TOKEN = 'notifai:guidance'
+
+function markerSafe(content: string): string {
+  return content.replaceAll(MARKER_TOKEN, `${MARKER_TOKEN.replace(':', '-')} [not a provenance marker]`)
+}
+
+/**
+ * The whole effective guidance, ready to be followed as read.
+ *
+ * The trust preamble comes first and belongs to the CLI: it says who supplied
+ * each topic and what no topic may ask for. Each topic then follows its own
+ * marker, so a reader can tell the User's standing word from a repository's
+ * house rules from the shipped default without the output stopping being
+ * Markdown.
+ */
+export function guidanceShowCommand(deps: CommandDeps, flags: { json?: boolean }): number {
+  const topics = resolveGuidance({ cwd: deps.cwd, env: deps.env })
+  if (flags.json) {
+    deps.io.out(
+      JSON.stringify(
+        {
+          trust: GUIDANCE_TRUST_PREAMBLE,
+          topics: topics.map((topic) => ({
+            name: topic.name,
+            source: topic.source,
+            authority: topic.authority,
+            summary: topic.summary,
+            content: topic.content,
+          })),
+        },
+        null,
+        2,
+      ),
+    )
+    return EXIT.ok
+  }
+  const blocks = topics.map((topic) => {
+    const { path: filePath } = describeSource(topic.source)
+    const marker =
+      `<!-- ${MARKER_TOKEN} topic=${topic.name} from=${AUTHORITY_LABEL[topic.authority]}` +
+      `${filePath === null ? '' : ` file=${encodeURIComponent(filePath)}`} -->`
+    return `${marker}\n${markerSafe(topic.content).trimEnd()}`
+  })
+  deps.io.out([GUIDANCE_TRUST_PREAMBLE, ...blocks].join('\n\n'))
+  return EXIT.ok
+}
+
+type GuidanceMutationFlags = {
+  project?: boolean | undefined
+  local?: boolean | undefined
+  yes?: boolean | undefined
+}
+type GuidanceLayer = 'global' | 'project' | 'local'
+
+/**
+ * Where a topic file for one layer lives. The project layer prefers an
+ * existing `.notifai/guidance` up the tree and otherwise starts one at cwd,
+ * the same anchoring `config set --project` uses for its file.
+ */
+function guidanceLayerDir(deps: CommandDeps, layer: GuidanceLayer): string {
+  if (layer === 'local') return personalProjectGuidanceDir(deps.cwd, deps.env)
+  if (layer === 'project') {
+    return findProjectGuidanceDir(deps.cwd) ?? path.join(deps.cwd, '.notifai', 'guidance')
+  }
+  return globalGuidanceDir(deps.env)
+}
+
+async function guidanceMutationTarget(
+  deps: CommandDeps,
+  topic: string,
+  flags: GuidanceMutationFlags,
+): Promise<{ path: string; layer: GuidanceLayer } | null> {
+  if (!GUIDANCE_TOPIC_PATTERN.test(topic)) {
+    deps.io.err(
+      `"${topic}" is not a topic name. Use lowercase letters, digits, "-" and "_", e.g. ${SHIPPED_GUIDANCE.map((t) => t.name).join(', ')}.`,
+    )
+    return null
+  }
+  let layer: GuidanceLayer = flags.local ? 'local' : flags.project ? 'project' : 'global'
+  if (
+    flags.local !== true &&
+    flags.project !== true &&
+    flags.yes !== true &&
+    deps.io.interactive === true &&
+    deps.io.select
+  ) {
+    const selected = await deps.io.select('Where should this guidance live?', [
+      { value: 'global', label: 'This machine', hint: 'your standing word, applies across projects' },
+      { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/ — committed, read as project policy' },
+      { value: 'local', label: 'This project (personal)', hint: 'your standing word here, stored outside the repo' },
+    ])
+    if (selected === null) {
+      deps.io.err('No guidance layer selected.')
+      return null
+    }
+    layer = selected as GuidanceLayer
+  }
+  return { path: path.join(guidanceLayerDir(deps, layer), `${topic}.md`), layer }
+}
+
+/**
+ * Writes one topic at one layer, replacing the shipped topic of that name for
+ * this scope. The confirmation gate is the same one `config set` holds: the
+ * user owns their standing word, so an agent writes it only with their words
+ * and their say-so.
+ */
+export async function guidanceSetCommand(
+  deps: CommandDeps,
+  topic: string,
+  text: string,
+  flags: GuidanceMutationFlags,
+): Promise<number> {
+  if (text.trim() === '') {
+    deps.io.err('Guidance text is empty. Pass the text, or --file <path|-> to read it.')
+    return EXIT.usage
+  }
+  if (text.length > GUIDANCE_TOPIC_MAX_BYTES) {
+    deps.io.err(`Guidance for one topic is capped at ${GUIDANCE_TOPIC_MAX_BYTES} bytes.`)
+    return EXIT.usage
+  }
+  const target = await guidanceMutationTarget(deps, topic, flags)
+  if (target === null) return EXIT.usage
+
+  const shipped = shippedGuidanceTopic(topic)
+  if (!flags.yes) {
+    const replaces =
+      shipped === undefined
+        ? `Add guidance topic "${topic}"`
+        : `Replace the shipped "${topic}" guidance for this scope`
+    const confirmed = await deps.io.confirm(`${replaces} at ${target.path}?`)
+    if (!confirmed) {
+      deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
+      return EXIT.usage
+    }
+  }
+
+  mkdirSync(path.dirname(target.path), { recursive: true })
+  writeFileSync(target.path, text.endsWith('\n') ? text : `${text}\n`)
+  deps.io.out(`Wrote ${topic} to ${target.path}`)
+  if (shipped !== undefined) {
+    deps.io.out(`This file now replaces the shipped "${topic}" guidance wherever it applies.`)
+  }
+  // A shared file is committed and travels to everyone who clones this
+  // repository, where it is read as the project's policy rather than as
+  // anyone's personal standing word. Worth saying at the moment of writing:
+  // the same sentence means something different in the two locations.
+  if (target.layer === 'project') {
+    deps.io.out(
+      'This is shared project policy: it is committed, everyone working here reads it, and it is never read as the User\'s own standing word. Use --local for a personal preference.',
+    )
+  }
+  return EXIT.ok
+}
+
+export async function guidanceUnsetCommand(
+  deps: CommandDeps,
+  topic: string,
+  flags: GuidanceMutationFlags,
+): Promise<number> {
+  const target = await guidanceMutationTarget(deps, topic, flags)
+  if (target === null) return EXIT.usage
+  if (!existsSync(target.path)) {
+    deps.io.out(`${topic} is not set at ${target.path}`)
+    return EXIT.ok
+  }
+  if (!flags.yes) {
+    const confirmed = await deps.io.confirm(`Remove ${target.path}?`)
+    if (!confirmed) {
+      deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.')
+      return EXIT.usage
+    }
+  }
+  rmSync(target.path, { force: true })
+  deps.io.out(`Removed ${target.path}; the inherited guidance now applies.`)
+  return EXIT.ok
+}