@raidiant/notifai 8.0.0 → 9.0.0

package/src/commands-doctor.ts

@@ -40,9 +40,11 @@ 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,
@@ -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
       ? {
@@ -457,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,
@@ -518,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',
@@ -549,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
 
@@ -879,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) =>
@@ -940,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

@@ -2,7 +2,11 @@ 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 { SHIPPED_GUIDANCE, shippedGuidanceTopic } from './guidance-content.js'
+import {
+  GUIDANCE_TRUST_PREAMBLE,
+  SHIPPED_GUIDANCE,
+  shippedGuidanceTopic,
+} from './guidance-content.js'
 import {
   GUIDANCE_TOPIC_MAX_BYTES,
   GUIDANCE_TOPIC_PATTERN,
@@ -10,28 +14,60 @@ import {
   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 whole effective guidance, ready to be followed as read. Each topic is
- * printed under a provenance comment so a reader can tell the user's standing
- * word from the shipped default without the output stopping being Markdown.
+ * 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(
-        topics.map((topic) => ({
-          name: topic.name,
-          source: topic.source,
-          summary: topic.summary,
-          content: topic.content,
-        })),
+        {
+          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,
       ),
@@ -39,12 +75,13 @@ export function guidanceShowCommand(deps: CommandDeps, flags: { json?: boolean }
     return EXIT.ok
   }
   const blocks = topics.map((topic) => {
-    const { label, path: filePath } = describeSource(topic.source)
-    const origin = topic.source === 'default' ? 'shipped default' : label
-    const provenance = filePath === null ? origin : `${origin} · ${filePath}`
-    return `<!-- ${topic.name} · ${provenance} -->\n${topic.content.trimEnd()}`
+    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(blocks.join('\n\n'))
+  deps.io.out([GUIDANCE_TRUST_PREAMBLE, ...blocks].join('\n\n'))
   return EXIT.ok
 }
 
@@ -72,7 +109,7 @@ async function guidanceMutationTarget(
   deps: CommandDeps,
   topic: string,
   flags: GuidanceMutationFlags,
-): Promise<string | null> {
+): 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(', ')}.`,
@@ -88,9 +125,9 @@ async function guidanceMutationTarget(
     deps.io.select
   ) {
     const selected = await deps.io.select('Where should this guidance live?', [
-      { value: 'global', label: 'This machine', hint: 'applies across projects' },
-      { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/' },
-      { value: 'local', label: 'This project (personal)', hint: 'stored on this machine, not in the repo' },
+      { 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.')
@@ -98,7 +135,7 @@ async function guidanceMutationTarget(
     }
     layer = selected as GuidanceLayer
   }
-  return path.join(guidanceLayerDir(deps, layer), `${topic}.md`)
+  return { path: path.join(guidanceLayerDir(deps, layer), `${topic}.md`), layer }
 }
 
 /**
@@ -130,19 +167,28 @@ export async function guidanceSetCommand(
       shipped === undefined
         ? `Add guidance topic "${topic}"`
         : `Replace the shipped "${topic}" guidance for this scope`
-    const confirmed = await deps.io.confirm(`${replaces} at ${target}?`)
+    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), { recursive: true })
-  writeFileSync(target, text.endsWith('\n') ? text : `${text}\n`)
-  deps.io.out(`Wrote ${topic} to ${target}`)
+  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
 }
 
@@ -153,18 +199,18 @@ export async function guidanceUnsetCommand(
 ): Promise<number> {
   const target = await guidanceMutationTarget(deps, topic, flags)
   if (target === null) return EXIT.usage
-  if (!existsSync(target)) {
-    deps.io.out(`${topic} is not set at ${target}`)
+  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}?`)
+    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, { force: true })
-  deps.io.out(`Removed ${target}; the inherited guidance now applies.`)
+  rmSync(target.path, { force: true })
+  deps.io.out(`Removed ${target.path}; the inherited guidance now applies.`)
   return EXIT.ok
 }