@raidiant/notifai 7.0.2 → 8.0.0

package/src/guidance.ts

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import path from 'node:path'
+import { globalConfigDir, personalProjectIdentity } from './config.js'
+import { SHIPPED_GUIDANCE } from './guidance-content.js'
+
+/**
+ * Layered notification-writing guidance with provenance. Most specific wins,
+ * per topic, exactly the discipline config keys follow:
+ *
+ *   project-local > project > global > shipped default
+ *
+ * A topic is one Markdown file named `<topic>.md`. A user file replaces the
+ * shipped topic of the same name wholesale — their words outrank the default,
+ * not annotate it — and a file whose name matches no shipped topic is purely
+ * additive house rules. There is no session layer: an instruction given in
+ * conversation tunes the session by being followed, not persisted.
+ */
+
+export type GuidanceSource =
+  | `project-local:${string}`
+  | `project:${string}`
+  | `global:${string}`
+  | 'default'
+
+export interface ResolvedGuidanceTopic {
+  name: string
+  source: GuidanceSource
+  /** One line for lists; user-authored topics describe themselves by content. */
+  summary: string
+  content: string
+}
+
+/**
+ * Topic names double as filenames, and the project layer arrives from a
+ * repository — untrusted input. Anything that does not match is not a topic,
+ * the same way `coerce` drops an unrecognised config value.
+ */
+export const GUIDANCE_TOPIC_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/
+
+/**
+ * One topic is capped at the body limit. Guidance is read into agent context
+ * on every session, and a repository could otherwise feed it without bound.
+ */
+export const GUIDANCE_TOPIC_MAX_BYTES = 16_000
+
+export function globalGuidanceDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(globalConfigDir(env), 'guidance')
+}
+
+/** Walk up from cwd looking for `.notifai/guidance` (shared, committed). */
+export function findProjectGuidanceDir(startDir: string): string | null {
+  let dir = path.resolve(startDir)
+  for (;;) {
+    const candidate = path.join(dir, '.notifai', 'guidance')
+    if (existsSync(candidate)) return candidate
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Personal project guidance lives beside the personal project config file,
+ * under the user's config home rather than the repository:
+ * `$XDG_CONFIG_HOME/notifai/projects/<identity>/guidance`.
+ */
+export function personalProjectGuidanceDir(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(globalConfigDir(env), 'projects', personalProjectIdentity(cwd), 'guidance')
+}
+
+function topicsInDir(dir: string): Map<string, string> {
+  const topics = new Map<string, string>()
+  if (!existsSync(dir)) return topics
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return topics
+  }
+  for (const entry of entries.sort()) {
+    if (!entry.endsWith('.md')) continue
+    const name = entry.slice(0, -'.md'.length)
+    if (!GUIDANCE_TOPIC_PATTERN.test(name)) continue
+    topics.set(name, path.join(dir, entry))
+  }
+  return topics
+}
+
+function readTopicFile(filePath: string): string | null {
+  let content: string
+  try {
+    content = readFileSync(filePath, 'utf8')
+  } catch {
+    return null
+  }
+  if (content.trim() === '') return null
+  if (content.length > GUIDANCE_TOPIC_MAX_BYTES) {
+    return `${content.slice(0, GUIDANCE_TOPIC_MAX_BYTES)}\n\n[Truncated: this guidance file exceeds ${GUIDANCE_TOPIC_MAX_BYTES} bytes.]\n`
+  }
+  return content
+}
+
+/**
+ * Every effective topic, shipped reading order first, additive user topics
+ * after it in name order. Each carries the layer that supplied it.
+ */
+export function resolveGuidance(options: {
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+}): ResolvedGuidanceTopic[] {
+  const env = options.env ?? process.env
+  const cwd = options.cwd ?? process.cwd()
+
+  // Ascending precedence: a later layer overwrites an earlier one per topic.
+  const layers: { dir: string | null; label: 'global' | 'project' | 'project-local' }[] = [
+    { dir: globalGuidanceDir(env), label: 'global' },
+    { dir: findProjectGuidanceDir(cwd), label: 'project' },
+    { dir: personalProjectGuidanceDir(cwd, env), label: 'project-local' },
+  ]
+
+  const winners = new Map<string, { source: GuidanceSource; content: string }>()
+  for (const layer of layers) {
+    if (layer.dir === null) continue
+    for (const [name, filePath] of topicsInDir(layer.dir)) {
+      const content = readTopicFile(filePath)
+      if (content === null) continue
+      winners.set(name, { source: `${layer.label}:${filePath}`, content })
+    }
+  }
+
+  const resolved: ResolvedGuidanceTopic[] = SHIPPED_GUIDANCE.map((topic) => {
+    const override = winners.get(topic.name)
+    winners.delete(topic.name)
+    return override === undefined
+      ? { name: topic.name, source: 'default', summary: topic.summary, content: topic.content }
+      : { name: topic.name, source: override.source, summary: topic.summary, content: override.content }
+  })
+  for (const name of [...winners.keys()].sort()) {
+    const extra = winners.get(name)!
+    resolved.push({
+      name,
+      source: extra.source,
+      summary: 'User-added guidance',
+      content: extra.content,
+    })
+  }
+  return resolved
+}

package/src/hooks.test.ts

@@ -157,7 +157,7 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
   return {
     beginPairing: notUsed,
     pollPairing: notUsed,
-    // Both current companion apps register reply categories.
+    // Current reply-capable Companion fixtures.
     listDevices: async () => ({
       devices: [
         {
@@ -555,6 +555,38 @@ describe('pushing a registered question', () => {
     expect(h.recorder.submitted[0]?.draft.platform?.ios?.sound).toBe('attention')
   })
 
+  it('routes a registered question to an answer-capable Android installation', async () => {
+    const h = harness([reply({ text: 'Yes' })])
+    const client = {
+      ...fakeClient(h.recorder, [reply({ text: 'Yes' })]),
+      listDevices: async () => ({
+        devices: [
+          {
+            device_id: 'dev_android',
+            display_name: 'Pixel',
+            platform: 'android' as const,
+            permission_status: 'authorized',
+            registration_healthy: true,
+            capabilities: ['answer'],
+            derived_status: 'working',
+            last_seen_at: null,
+          },
+        ],
+      }),
+    } as ApiClient
+    const deps = { ...h.deps, clientFactory: () => client }
+    writeSessionState('android-answer', h.env, { last_prompt_at: AWAY })
+    registerQuestion('android-answer', h.env, { question: 'Ship it?' }, NOW)
+
+    await hookRunCommand(deps, 'stop', stdin({ session_id: 'android-answer' }))
+
+    expect(h.recorder.submitted[0]?.draft.targets).toEqual({
+      mode: 'selected',
+      device_ids: ['dev_android'],
+    })
+    expect(h.recorder.submitted[0]?.draft.platform?.android?.sound).toBe('attention')
+  })
+
   it('keeps sparse alt text paired with its original media item', async () => {
     const h = harness([reply({ text: 'Yes' })])
     writeSessionState('media-order', h.env, { last_prompt_at: AWAY })
@@ -2323,9 +2355,9 @@ describe('ask registration', () => {
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'form1' }))
     const draft = h.recorder.submitted[0]?.draft
     expect(draft?.presentation.title).toBe('Deploy where?')
-    expect(draft?.presentation.body).toBe(
-      '1. Deploy where?\n2. Anything to watch?\n\n## Context\nThe long story.',
-    )
+    // The questions travel structured and the first one is the title; the
+    // body carries only the context so nothing renders twice.
+    expect(draft?.presentation.body).toBe('## Context\nThe long story.')
     expect(draft?.reply?.questions).toEqual([
       {
         id: 'deploy-where',
@@ -2818,7 +2850,7 @@ describe('session-end hook', () => {
         'the real Codex hook did not reach contended diagnostics before its deadline',
       )
 
-      // Reaching the second bakery ticket proves main.ts preAction did not write
+      // Reaching the second bakery ticket proves program.ts preAction did not write
       // first. Every durable cleanup must already be visible while diagnostics
       // are still blocked behind the live holder.
       expect(existsSync(stateFile)).toBe(false)

package/src/hooks.ts

@@ -651,8 +651,9 @@ function claimPath(sessionId: string, env: NodeJS.ProcessEnv): string {
 /**
  * A question is stored so a later hook can push it, and it reaches us from a
  * shell command, so its size is whatever the agent typed. The push itself is
- * bounded by the 4096-byte APNs envelope; this bounds what sits on disk in the
- * meantime, and keeps one runaway agent from writing megabytes per session.
+ * bounded by the current 4096-byte push-provider envelopes; this bounds what
+ * sits on disk in the meantime, and keeps one runaway agent from writing
+ * megabytes per session.
  */
 const MAX_STORED_QUESTION_CHARS = 2000
 
@@ -1089,17 +1090,16 @@ function permanentReplyFailureNote(failures: Map<string, string>): string | null
   return `reply polling stopped after a permanent server rejection (${details}); the affected question will be retired before its continuation owner exits`
 }
 
-/**
- * Healthy companion devices that implement replies. Both the iOS app and the
- * macOS app register reply categories and submit answers directly.
- */
+/** Healthy Companion devices that advertise the current answer job. */
 async function answerableDevices(ctx: HookContext): Promise<string[]> {
   const configured = ctx.config.devices.value
   const { devices } = await ctx.client.listDevices()
   return devices
     .filter(
       (device) =>
-        (device.platform === 'ios' || device.platform === 'macos') &&
+        (device.platform === 'ios' ||
+          device.platform === 'macos' ||
+          device.platform === 'android') &&
         device.registration_healthy &&
         device.capabilities?.includes('answer') === true &&
         device.derived_status !== 'must_update',

package/src/interactive.ts

@@ -18,7 +18,7 @@
  * The menu leads with whatever is actually in the way. Someone who is not
  * signed in is offered sign-in first; someone with no device that can receive
  * is offered a device; everyone else is offered the test notification, because
- * seeing the thing arrive on your phone is what makes the product real.
+ * seeing the thing arrive on your device is what makes the product real.
  *
  * Detail is earned, not given. A settings group shows fourteen one-line
  * summaries, and the paragraph explaining a key appears once the reader has
@@ -365,7 +365,11 @@ function menuFor(readiness: Readiness): { value: Screen; label: string; hint?: s
   if (!signedIn) {
     options.push({ value: 'account', label: 'Sign in', hint: 'approve this machine in your browser' })
   } else if (!hasDevice) {
-    options.push({ value: 'devices', label: 'Add a device', hint: 'install the app on your iPhone' })
+    options.push({
+      value: 'devices',
+      label: 'Add a device',
+      hint: 'install a supported Companion App',
+    })
   } else {
     options.push({
       value: 'test',
@@ -414,8 +418,8 @@ async function testNotificationScreen(deps: CommandDeps): Promise<void> {
 
   const body = await clack.text({
     message: 'Body',
-    placeholder: 'If you can read this on your phone, it works.',
-    defaultValue: 'If you can read this on your phone, it works.',
+    placeholder: 'If you can read this on your device, it works.',
+    defaultValue: 'If you can read this on your device, it works.',
   })
   if (cancelled(body)) return
 
@@ -457,8 +461,8 @@ async function devicesScreen(deps: CommandDeps): Promise<void> {
   if (devices.length === 0) {
     clack.note(
       'No devices are registered yet.\n\n' +
-        'Install the Notifai Companion App on your iPhone, sign in with the\n' +
-        'same Account, and allow notifications when it asks.',
+        'Install a supported Notifai Companion App, sign in with the same\n' +
+        'Account, and allow notifications when it asks.',
       'No devices',
     )
     return
@@ -733,8 +737,9 @@ async function routingScreen(deps: CommandDeps, readiness: Readiness): Promise<b
   const row = (label: string, value: string): string => `${style.dim(label.padEnd(16))}${value}`
   clack.note(
     'When an agent registers a question, it appears in your terminal first.\n' +
-      'After the grace below, it goes to your iPhone as a notification\n' +
-      'with real answer buttons, and your answer comes back to the agent —\n' +
+      'After the grace below, it goes to your Companion devices as a\n' +
+      'notification with a supported native or in-app answer surface, and\n' +
+      'your answer comes back to the agent —\n' +
       'whether or not you are still at this machine.\n\n' +
       [
         row('Wired to', wiringSummary(hooks)),