@raidiant/notifai 8.0.0 → 9.0.0

package/src/guidance.ts

@@ -1,4 +1,15 @@
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+  readdirSync,
+  realpathSync,
+  type Dirent,
+} from 'node:fs'
 import path from 'node:path'
 import { globalConfigDir, personalProjectIdentity } from './config.js'
 import { SHIPPED_GUIDANCE } from './guidance-content.js'
@@ -14,6 +25,16 @@ import { SHIPPED_GUIDANCE } from './guidance-content.js'
  * 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.
+ *
+ * Two of those layers are the User's own word and one is not. `global` and
+ * `project-local` live under the User's config home: only they can write
+ * there. `project` is `.notifai/guidance` inside the repository, so it
+ * arrives with a clone and is written by whoever wrote the repository —
+ * which may be nobody the User has ever met. It remains authoritative about
+ * *how this project's notifications should read*, because shared house rules
+ * are the feature; it is never the User speaking. `authority` carries that
+ * distinction to every reader so a cloned repository cannot borrow the
+ * User's voice.
  */
 
 export type GuidanceSource =
@@ -22,14 +43,30 @@ export type GuidanceSource =
   | `global:${string}`
   | 'default'
 
+/**
+ * Who is speaking in a topic.
+ *
+ * - `user` — the User's own standing word, from a location only they can write.
+ * - `repository` — this checkout's shared house rules; committed content, and
+ *   therefore untrusted input that speaks for the project, not the User.
+ * - `shipped` — the default that applies when nobody said otherwise.
+ */
+export type GuidanceAuthority = 'user' | 'repository' | 'shipped'
+
 export interface ResolvedGuidanceTopic {
   name: string
   source: GuidanceSource
+  authority: GuidanceAuthority
   /** One line for lists; user-authored topics describe themselves by content. */
   summary: string
   content: string
 }
 
+export function guidanceAuthority(source: GuidanceSource): GuidanceAuthority {
+  if (source === 'default') return 'shipped'
+  return source.startsWith('project:') ? 'repository' : 'user'
+}
+
 /**
  * Topic names double as filenames, and the project layer arrives from a
  * repository — untrusted input. Anything that does not match is not a topic,
@@ -47,12 +84,29 @@ export function globalGuidanceDir(env: NodeJS.ProcessEnv = process.env): string
   return path.join(globalConfigDir(env), 'guidance')
 }
 
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate)
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`))
+}
+
 /** 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
+    if (existsSync(candidate)) {
+      try {
+        // A clone may contain symlinks. Repository guidance may read only
+        // regular content rooted in that repository; it must never turn a
+        // local private file into model context by pointing outside the tree.
+        const candidateStat = lstatSync(candidate)
+        const repositoryRoot = realpathSync(dir)
+        const resolved = realpathSync(candidate)
+        if (candidateStat.isDirectory() && isWithin(repositoryRoot, resolved)) return candidate
+      } catch {
+        // An unreadable or unstable candidate is not guidance. Keep walking.
+      }
+    }
     const parent = path.dirname(dir)
     if (parent === dir) return null
     dir = parent
@@ -74,33 +128,47 @@ export function personalProjectGuidanceDir(
 function topicsInDir(dir: string): Map<string, string> {
   const topics = new Map<string, string>()
   if (!existsSync(dir)) return topics
-  let entries: string[]
+  let entries: Dirent[]
   try {
-    entries = readdirSync(dir)
+    if (!lstatSync(dir).isDirectory()) return topics
+    entries = readdirSync(dir, { withFileTypes: true })
   } catch {
     return topics
   }
-  for (const entry of entries.sort()) {
-    if (!entry.endsWith('.md')) continue
-    const name = entry.slice(0, -'.md'.length)
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    // In particular, refuse symlinks. A committed link to a User-owned file
+    // must not make that file part of repository guidance output.
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue
+    const name = entry.name.slice(0, -'.md'.length)
     if (!GUIDANCE_TOPIC_PATTERN.test(name)) continue
-    topics.set(name, path.join(dir, entry))
+    topics.set(name, path.join(dir, entry.name))
   }
   return topics
 }
 
 function readTopicFile(filePath: string): string | null {
-  let content: string
+  let descriptor: number | null = null
   try {
-    content = readFileSync(filePath, 'utf8')
+    descriptor = openSync(filePath, constants.O_RDONLY | constants.O_NOFOLLOW)
+    if (!fstatSync(descriptor).isFile()) return null
+    const bytes = Buffer.alloc(GUIDANCE_TOPIC_MAX_BYTES + 1)
+    let offset = 0
+    while (offset < bytes.length) {
+      const count = readSync(descriptor, bytes, offset, bytes.length - offset, offset)
+      if (count === 0) break
+      offset += count
+    }
+    const truncated = offset > GUIDANCE_TOPIC_MAX_BYTES
+    const content = bytes.subarray(0, Math.min(offset, GUIDANCE_TOPIC_MAX_BYTES)).toString('utf8')
+    if (content.trim() === '') return null
+    return truncated
+      ? `${content}\n\n[Truncated: this guidance file exceeds ${GUIDANCE_TOPIC_MAX_BYTES} bytes.]\n`
+      : content
   } catch {
     return null
+  } finally {
+    if (descriptor !== null) closeSync(descriptor)
   }
-  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
 }
 
 /**
@@ -135,15 +203,29 @@ export function resolveGuidance(options: {
     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 }
+      ? {
+          name: topic.name,
+          source: 'default' as const,
+          authority: 'shipped' as const,
+          summary: topic.summary,
+          content: topic.content,
+        }
+      : {
+          name: topic.name,
+          source: override.source,
+          authority: guidanceAuthority(override.source),
+          summary: topic.summary,
+          content: override.content,
+        }
   })
   for (const name of [...winners.keys()].sort()) {
     const extra = winners.get(name)!
+    const authority = guidanceAuthority(extra.source)
     resolved.push({
       name,
       source: extra.source,
-      summary: 'User-added guidance',
+      authority,
+      summary: authority === 'repository' ? 'Project house rules' : 'User-added guidance',
       content: extra.content,
     })
   }

package/src/hook-adapter.test.ts

@@ -11,6 +11,7 @@ import {
 } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import {
   hookAdapterPath,
@@ -27,6 +28,35 @@ function isolated(): { root: string; homeDir: string } {
 }
 
 describe('stable hook adapter', () => {
+  it('delivers session activation through the installed adapter before setup exists', () => {
+    const { root, homeDir } = isolated()
+    const scriptPath = fileURLToPath(new URL('../dist/main.js', import.meta.url))
+    const installed = installHookAdapter({ execPath: process.execPath, scriptPath }, homeDir)
+    const run = spawnSync(
+      installed.path,
+      ['hook', 'session-start', '--owner', 'notifai', '--harness', 'codex'],
+      {
+        encoding: 'utf8',
+        input: JSON.stringify({ session_id: 'adapter-session', cwd: root, source: 'startup' }),
+        env: {
+          ...process.env,
+          HOME: homeDir,
+          XDG_CONFIG_HOME: path.join(root, 'config'),
+          XDG_STATE_HOME: path.join(root, 'state'),
+        },
+      },
+    )
+
+    expect(run.status).toBe(0)
+    expect(run.stderr).toBe('')
+    expect(JSON.parse(run.stdout)).toMatchObject({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: expect.stringMatching(/Notifai.*session/i),
+      },
+    })
+  })
+
   it('executes paths with spaces, quotes, and shell syntax without evaluating them', () => {
     const { root, homeDir } = isolated()
     const odd = path.join(root, "odd ' $(touch should-not-run)")
@@ -122,6 +152,36 @@ describe('stable hook adapter', () => {
     )
   })
 
+  it('carries the stable POSIX harness parent through direct and npx targets', () => {
+    const { root, homeDir } = isolated()
+    const direct = path.join(root, 'direct.js')
+    const npmCli = path.join(root, 'npm-cli.js')
+    const source = 'process.stdout.write(process.env.NOTIFAI_HOOK_SOURCE_PID ?? "missing")\n'
+    writeFileSync(direct, source)
+    writeFileSync(npmCli, source)
+
+    const directAdapter = installHookAdapter(
+      { execPath: process.execPath, scriptPath: direct },
+      homeDir,
+    )
+    const directRun = spawnSync(directAdapter.path, [], { encoding: 'utf8' })
+    const npxAdapter = installHookAdapter(
+      {
+        kind: 'npx',
+        execPath: process.execPath,
+        npmCli,
+        spec: '@raidiant/notifai@0.5.1',
+      },
+      homeDir,
+    )
+    const npxRun = spawnSync(npxAdapter.path, [], { encoding: 'utf8' })
+
+    expect(directRun.status).toBe(0)
+    expect(npxRun.status).toBe(0)
+    expect(directRun.stdout).toBe(String(process.pid))
+    expect(npxRun.stdout).toBe(String(process.pid))
+  })
+
   it('uses a fixed home-relative pathname with no XDG input surface', () => {
     const { homeDir } = isolated()
     expect(hookAdapterPath(homeDir)).toBe(
@@ -202,6 +262,32 @@ describe('stable hook adapter', () => {
     ])
   })
 
+  it('keeps working when a node upgrade moved the pinned runtime but left the CLI', () => {
+    const { root, homeDir } = isolated()
+    const bin = path.join(root, 'fallback-bin')
+    mkdirSync(bin, { recursive: true })
+    const pathNode = path.join(bin, 'node')
+    writeFileSync(pathNode, '#!/bin/sh\nprintf "ran %s" "$1"\n')
+    chmodSync(pathNode, 0o700)
+    const pinnedNode = path.join(root, 'pinned-node')
+    const cli = path.join(root, 'cli.js')
+    writeFileSync(pinnedNode, '#!/bin/sh\n')
+    chmodSync(pinnedNode, 0o700)
+    writeFileSync(cli, '')
+    const installed = installHookAdapter({ execPath: pinnedNode, scriptPath: cli }, homeDir)
+    // What `brew upgrade node` and `nvm uninstall` both do: the interpreter
+    // moves, the installed CLI does not.
+    rmSync(pinnedNode)
+
+    const run = spawnSync(installed.path, ['hook', 'stop'], {
+      encoding: 'utf8',
+      env: { PATH: bin },
+    })
+
+    expect(run.status).toBe(0)
+    expect(run.stdout).toBe(`ran ${cli}`)
+  })
+
   it('fails closed instead of executing an unregistered PATH target after the registered target vanished', () => {
     const { root, homeDir } = isolated()
     const bin = path.join(root, 'new-bin')
@@ -237,11 +323,14 @@ describe('Windows hook adapter', () => {
     }
     expect(hookAdapterSource(target, 'posix')).toBe(`#!/bin/sh
 # notifai managed hook adapter
-# adapter-version: 1
+# adapter-version: 2
 # target-exec-json: "/usr/local/bin/node"
 # target-script-json: "/opt/notifai/dist/main.js"
 set -eu
 
+NOTIFAI_HOOK_SOURCE_PID=$PPID
+export NOTIFAI_HOOK_SOURCE_PID
+
 registered_exec='/usr/local/bin/node'
 registered_script='/opt/notifai/dist/main.js'
 
@@ -249,6 +338,10 @@ if [ -x "$registered_exec" ] && [ -f "$registered_script" ]; then
   exec "$registered_exec" "$registered_script" "$@"
 fi
 
+if [ -f "$registered_script" ] && command -v node >/dev/null 2>&1; then
+  exec node "$registered_script" "$@"
+fi
+
 printf '%s
 ' 'Notifai hook adapter target is stale; run notifai hooks install.' >&2
 exit 127
@@ -297,6 +390,25 @@ exit 127
     ).not.toThrow()
   })
 
+  it('carries the stable Windows harness parent into each CLI process', () => {
+    const { root, homeDir } = isolated()
+    const script = path.join(root, 'source-pid.js')
+    writeFileSync(
+      script,
+      'process.stdout.write(process.env.NOTIFAI_HOOK_SOURCE_PID ?? "missing")\n',
+    )
+    const installed = installHookAdapter(
+      { execPath: process.execPath, scriptPath: script },
+      homeDir,
+      'win32',
+    )
+
+    const run = spawnSync(process.execPath, [installed.path], { encoding: 'utf8' })
+
+    expect(run.status).toBe(0)
+    expect(run.stdout).toBe(String(process.pid))
+  })
+
   it('does not treat 0666 as a protection or health failure', () => {
     const { root, homeDir } = isolated()
     const script = path.join(root, 'target.js')

package/src/hook-adapter.ts

@@ -13,7 +13,7 @@ import { withTargetFileLock } from './file-lock.js'
 
 const ADAPTER_MARKER = '# notifai managed hook adapter'
 const WIN32_ADAPTER_MARKER = '// notifai managed hook adapter'
-const ADAPTER_VERSION = 1
+const ADAPTER_VERSION = 2
 
 export type HookHostPlatform = 'posix' | 'win32'
 
@@ -212,6 +212,21 @@ export function hookAdapterSource(
     : posixHookAdapterSource(target)
 }
 
+/**
+ * Two rungs, and the difference between them is the whole safety argument.
+ *
+ * The registered runtime is a resolved path, so every node version manager
+ * makes it version-scoped: a Homebrew upgrade renames its Cellar directory, an
+ * nvm version gets pruned, and the pinned interpreter stops existing. The npm
+ * shim this adapter wraps already survives that — `main.ts` starts with
+ * `#!/usr/bin/env node` — so pinning the interpreter here was stricter than the
+ * binary it stands in front of, and the strictness bought nothing.
+ *
+ * So PATH may supply the *interpreter*, and never the *code*: both rungs keep
+ * the registered script path, and no rung resolves `notifai` from PATH. Which
+ * Notifai build a trusted hook definition runs stays a property of the
+ * installation, not of whatever environment the harness happens to hand us.
+ */
 function posixHookAdapterSource(target: HookAdapterTarget): string {
   if (isNpxAdapterTarget(target)) {
     return `#!/bin/sh
@@ -223,6 +238,9 @@ ${ADAPTER_MARKER}
 # target-spec-json: ${JSON.stringify(target.spec)}
 set -eu
 
+NOTIFAI_HOOK_SOURCE_PID=$PPID
+export NOTIFAI_HOOK_SOURCE_PID
+
 registered_exec=${quote(target.execPath)}
 registered_npm_cli=${quote(target.npmCli)}
 registered_spec=${quote(target.spec)}
@@ -231,6 +249,10 @@ if [ -x "$registered_exec" ] && [ -f "$registered_npm_cli" ]; then
   exec "$registered_exec" "$registered_npm_cli" exec --yes --package "$registered_spec" -- notifai "$@"
 fi
 
+if [ -f "$registered_npm_cli" ] && command -v node >/dev/null 2>&1; then
+  exec node "$registered_npm_cli" exec --yes --package "$registered_spec" -- notifai "$@"
+fi
+
 printf '%s\n' 'Notifai hook adapter target is stale; run notifai hooks install.' >&2
 exit 127
 `
@@ -242,6 +264,9 @@ ${ADAPTER_MARKER}
 # target-script-json: ${JSON.stringify(target.scriptPath)}
 set -eu
 
+NOTIFAI_HOOK_SOURCE_PID=$PPID
+export NOTIFAI_HOOK_SOURCE_PID
+
 registered_exec=${quote(target.execPath)}
 registered_script=${quote(target.scriptPath)}
 
@@ -249,6 +274,10 @@ if [ -x "$registered_exec" ] && [ -f "$registered_script" ]; then
   exec "$registered_exec" "$registered_script" "$@"
 fi
 
+if [ -f "$registered_script" ] && command -v node >/dev/null 2>&1; then
+  exec node "$registered_script" "$@"
+fi
+
 printf '%s\n' 'Notifai hook adapter target is stale; run notifai hooks install.' >&2
 exit 127
 `
@@ -288,10 +317,15 @@ function isFile(file) {
   }
 }
 
-if (isFile(registeredExec) && isFile(registeredCompanion)) {
-  const result = spawnSync(registeredExec, ${argv}, {
+// The pinned runtime is preferred; the runtime already executing this shim is
+// the fallback. Only the interpreter is allowed to move — the code stays pinned.
+const runtime = isFile(registeredExec) ? registeredExec : process.execPath;
+
+if (isFile(registeredCompanion)) {
+  const result = spawnSync(runtime, ${argv}, {
     stdio: "inherit",
     windowsHide: true,
+    env: { ...process.env, NOTIFAI_HOOK_SOURCE_PID: String(process.ppid) },
   });
   if (result.error) {
     process.stderr.write("Notifai hook adapter target is stale; run notifai hooks install.\\n");