@raidiant/notifai 7.0.2 → 9.0.0

package/src/guidance.ts

@@ -0,0 +1,233 @@
+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'
+
+/**
+ * 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.
+ *
+ * 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 =
+  | `project-local:${string}`
+  | `project:${string}`
+  | `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,
+ * 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')
+}
+
+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)) {
+      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
+  }
+}
+
+/**
+ * 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: Dirent[]
+  try {
+    if (!lstatSync(dir).isDirectory()) return topics
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return topics
+  }
+  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.name))
+  }
+  return topics
+}
+
+function readTopicFile(filePath: string): string | null {
+  let descriptor: number | null = null
+  try {
+    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)
+  }
+}
+
+/**
+ * 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' 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,
+      authority,
+      summary: authority === 'repository' ? 'Project house rules' : 'User-added guidance',
+      content: extra.content,
+    })
+  }
+  return resolved
+}

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");