@raidiant/notifai 10.0.0 → 10.1.1

package/src/install-hooks.test.ts

@@ -22,6 +22,17 @@ import {
   opencodePluginSource,
   opencodePluginTarget,
 } from './opencode-plugin.js'
+import {
+  OPENCLAW_PLUGIN_MARKER,
+  isOurOpenclawPlugin,
+  mergeOpenclawNotifaiEntry,
+  openclawHasGlobalEvidence,
+  openclawPluginPath,
+  openclawPluginSource,
+  openclawPluginTarget,
+  parseOpenclawConfig,
+  removeOpenclawNotifaiEntry,
+} from './openclaw-plugin.js'
 import {
   MISSING_LIFECYCLE_GUIDANCE_CONTEXT,
   WORKER_ACTIVATION_CONTEXT,
@@ -1068,6 +1079,179 @@ describe('the OpenCode adapter', () => {
   })
 })
 
+describe('the OpenClaw adapter', () => {
+  const source = openclawPluginSource({
+    adapterPath: ADAPTER,
+    timeoutSeconds: 240,
+  })
+
+  async function loadPlugin() {
+    return (await import(
+      `data:text/javascript;base64,${Buffer.from(source).toString('base64')}`
+    )) as {
+      default: {
+        id: string
+        register(api: {
+          on(name: string, handler: (...args: never[]) => unknown): void
+        }): void
+      }
+    }
+  }
+
+  function handlersOf(mod: Awaited<ReturnType<typeof loadPlugin>>) {
+    const handlers = new Map<string, (...args: never[]) => unknown>()
+    mod.default.register({
+      on(name, handler) {
+        handlers.set(name, handler)
+      },
+    })
+    return handlers
+  }
+
+  it('shells out to the same hook commands the other harnesses run', () => {
+    expect(source).toContain('"hook", event')
+    expect(source).toContain('"--harness", "openclaw"')
+    expect(source).toContain(JSON.stringify(ADAPTER))
+    expect(source).not.toContain('command:stop')
+  })
+
+  it('wires current plugin joints and leaves user abort alone', () => {
+    expect(source).toContain('api.on("before_prompt_build"')
+    expect(source).toContain('api.on("message_received"')
+    expect(source).toContain('api.on("agent_end"')
+    expect(source).toContain('api.on("session_end"')
+    expect(source).toContain('api.on("resolve_exec_env"')
+    expect(source).not.toContain('command:stop')
+  })
+
+  it('classifies root, subagent, ACP, and missing identity safely', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const activate = handlers.get('before_prompt_build') as (
+      event: object,
+      ctx: object,
+    ) => Promise<{ prependContext?: string } | undefined>
+
+    const root = await activate({}, { sessionKey: 'agent:main:main', workspaceDir: '/ws' })
+    expect(root?.prependContext).toBe(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)
+
+    const worker = await activate({}, { sessionKey: 'agent:main:subagent:abc', workspaceDir: '/ws' })
+    expect(worker?.prependContext).toBe(WORKER_ACTIVATION_CONTEXT)
+
+    const acp = await activate({}, { sessionKey: 'agent:main:acp-child', targetKind: 'acp' })
+    expect(acp?.prependContext).toBe(WORKER_ACTIVATION_CONTEXT)
+
+    const missing = await activate({}, {})
+    expect(missing?.prependContext).toBe(WORKER_ACTIVATION_CONTEXT)
+  })
+
+  it('does not treat heartbeat or cron traffic as User presence', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const presence = handlers.get('message_received') as (
+      event: object,
+      ctx: object,
+    ) => Promise<void>
+    await presence({ from: '' }, { sessionKey: 'agent:main:main' })
+    await presence({ from: 'cron' }, { sessionKey: 'agent:main:main', trigger: 'cron' })
+    await presence({ from: 'hb' }, { sessionKey: 'agent:main:main', trigger: 'heartbeat' })
+    expect(source).toContain('trigger === "cron" || trigger === "heartbeat"')
+  })
+
+  it('publishes exact sessionKey markers into exec without PATH', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const resolve = handlers.get('resolve_exec_env') as (
+      event: object,
+      ctx: object,
+    ) => Record<string, string> | undefined
+    expect(resolve({}, { sessionKey: 'agent:main:telegram:dm:1' })).toEqual({
+      NOTIFAI_ACTIVE_HARNESS: 'openclaw',
+      NOTIFAI_ACTIVE_SESSION_ID: 'agent:main:telegram:dm:1',
+    })
+    expect(resolve({}, {})).toBeUndefined()
+    expect(source).not.toContain('PATH:')
+  })
+
+  it('activates a parent session only once', async () => {
+    const handlers = handlersOf(await loadPlugin())
+    const activate = handlers.get('before_prompt_build') as (
+      event: object,
+      ctx: object,
+    ) => Promise<{ prependContext?: string } | undefined>
+    const first = await activate({}, { sessionKey: 'agent:main:main' })
+    const second = await activate({}, { sessionKey: 'agent:main:main' })
+    expect(first?.prependContext).toBe(MISSING_LIFECYCLE_GUIDANCE_CONTEXT)
+    expect(second).toBeUndefined()
+  })
+
+  it('carries the ownership marker so a second checkout replaces it', () => {
+    expect(source).toContain(OPENCLAW_PLUGIN_MARKER)
+    expect(isOurOpenclawPlugin(source)).toBe(true)
+    expect(isOurOpenclawPlugin('export default { id: "other" }')).toBe(false)
+  })
+
+  it('installs beside the OpenClaw config rather than into a hook document', () => {
+    const local = openclawPluginPath(false, '/repo', {})
+    expect(local).toBe(path.join('/repo', '.openclaw', 'extensions', 'notifai', 'index.js'))
+    const global = openclawPluginPath(true, '/repo', { OPENCLAW_STATE_DIR: '/cfg/openclaw' })
+    expect(global).toBe(path.join('/cfg/openclaw', 'extensions', 'notifai', 'index.js'))
+  })
+
+  it('is a harness `hooks install` knows about', () => {
+    expect(HOOK_INSTALLABLE_HARNESSES).toContain('openclaw')
+    expect(settingsFile('openclaw', false, '/repo', {})).toContain('index.js')
+  })
+
+  it('reports the same stable adapter identity as command-hook harnesses', () => {
+    expect(openclawPluginTarget(source)).toEqual({
+      adapter: ADAPTER,
+      current: true,
+      timeoutSeconds: 240,
+    })
+    expect(openclawPluginTarget(source.replace(/^const ADAPTER_VERSION = .*\n/m, ''))).toEqual({
+      adapter: ADAPTER,
+      current: false,
+      timeoutSeconds: 240,
+    })
+    expect(openclawPluginTarget('export default { id: "other" }')).toBeNull()
+  })
+
+  it('merges only the Notifai plugin entry into OpenClaw config', () => {
+    const merged = mergeOpenclawNotifaiEntry(
+      { gateway: { port: 18789 }, plugins: { entries: { memory: { enabled: true } } } },
+      '/repo/.openclaw/extensions/notifai',
+      false,
+    )
+    expect(merged).toMatchObject({
+      gateway: { port: 18789 },
+      plugins: {
+        entries: {
+          memory: { enabled: true },
+          notifai: { enabled: true, hooks: { allowConversationAccess: true } },
+        },
+        load: { paths: ['/repo/.openclaw/extensions/notifai'] },
+      },
+    })
+    const stripped = removeOpenclawNotifaiEntry(merged, '/repo/.openclaw/extensions/notifai')
+    expect(stripped).toEqual({
+      gateway: { port: 18789 },
+      plugins: { entries: { memory: { enabled: true } } },
+    })
+  })
+
+  it('parses JSON with comments without requiring a JSON5 dependency', () => {
+    expect(parseOpenclawConfig('{\n  // port\n  "gateway": { "port": 1 },\n}\n')).toEqual({
+      gateway: { port: 1 },
+    })
+  })
+
+  it('does not treat a skills-only ~/.openclaw tree as OpenClaw evidence', () => {
+    const home = mkdtempSync(path.join(os.tmpdir(), 'notifai-openclaw-skills-only-'))
+    mkdirSync(path.join(home, '.openclaw', 'skills'), { recursive: true })
+    expect(openclawHasGlobalEvidence(existsSync, { HOME: home })).toBe(false)
+    writeFileSync(path.join(home, '.openclaw', 'openclaw.json'), '{}\n')
+    expect(openclawHasGlobalEvidence(existsSync, { HOME: home })).toBe(true)
+  })
+})
+
 describe('detectHarness', () => {
   function project(...entries: string[]): string {
     const dir = mkdtempSync(path.join(os.tmpdir(), 'notifai-detect-'))
@@ -1113,6 +1297,7 @@ describe('detectHarness', () => {
     expect(detectHarness(project('.codex'))).toBe('codex')
     expect(detectHarness(project('.cursor'))).toBe('cursor')
     expect(detectHarness(project('.opencode'))).toBe('opencode')
+    expect(detectHarness(project('.openclaw'))).toBe('openclaw')
   })
 
   it('returns null when the project itself names two harnesses', () => {
@@ -1233,6 +1418,9 @@ describe('Windows hook commands and discovery', () => {
     expect(opencodePluginPath(true, '/repo', env, 'win32')).toBe(
       path.join('C:\\Users\\Ada', '.config', 'opencode', 'plugins', 'notifai.js'),
     )
+    expect(openclawPluginPath(true, '/repo', env, 'win32')).toBe(
+      path.join('C:\\Users\\Ada', '.openclaw', 'extensions', 'notifai', 'index.js'),
+    )
   })
 
   it('makes OpenCode spawn the adapter through Node on Windows with shell:false', () => {
@@ -1254,6 +1442,26 @@ describe('Windows hook commands and discovery', () => {
       nodePath: winNode,
     })
   })
+
+  it('makes OpenClaw spawn the adapter through Node on Windows with shell:false', () => {
+    const source = openclawPluginSource({
+      adapterPath: winAdapter,
+      timeoutSeconds: 240,
+      platform: 'win32',
+      nodePath: winNode,
+    })
+    expect(source).toContain(`const NODE = ${JSON.stringify(winNode)}`)
+    expect(source).toContain('spawn(NODE, [ADAPTER, "hook", event, "--owner", "notifai", "--harness", "openclaw"]')
+    expect(source).toContain('shell: false')
+    expect(source).toContain('windowsHide: true')
+    expect(source).not.toContain('spawn(ADAPTER,')
+    expect(openclawPluginTarget(source)).toEqual({
+      adapter: winAdapter,
+      current: true,
+      timeoutSeconds: 240,
+      nodePath: winNode,
+    })
+  })
 })
 
 /**

package/src/install-hooks.ts

@@ -20,6 +20,12 @@ import {
   type HookHostPlatform,
 } from './hook-adapter.js'
 import { opencodePluginPath, opencodePluginTarget } from './opencode-plugin.js'
+import {
+  OPENCLAW_EVENTS,
+  openclawHasGlobalEvidence,
+  openclawPluginPath,
+  openclawPluginTarget,
+} from './openclaw-plugin.js'
 import { HOOK_INSTALLABLE_HARNESSES, type HookInstallableHarness } from './harnesses.js'
 import { accountHome } from './platform.js'
 import {
@@ -364,6 +370,8 @@ export function settingsFile(
     // generated plugin module, so it owns a whole file instead.
     case 'opencode':
       return opencodePluginPath(global, cwd, env, platform)
+    case 'openclaw':
+      return openclawPluginPath(global, cwd, env, platform)
     case 'cursor': {
       const home = harnessAccountHome(env, platform)
       return global
@@ -747,6 +755,7 @@ function localHarnessEvidence(cwd: string): HookInstallableHarness[] {
   if (existsSync(path.join(cwd, '.codex'))) found.push('codex')
   if (existsSync(path.join(cwd, '.cursor'))) found.push('cursor')
   if (existsSync(path.join(cwd, '.opencode'))) found.push('opencode')
+  if (existsSync(path.join(cwd, '.openclaw'))) found.push('openclaw')
   return found
 }
 
@@ -761,6 +770,7 @@ function globalHarnessEvidence(
   if (existsSync(codexGlobalDir(env, platform))) found.push('codex')
   if (existsSync(path.join(home, '.cursor'))) found.push('cursor')
   if (existsSync(path.join(home, '.config', 'opencode'))) found.push('opencode')
+  if (openclawHasGlobalEvidence(existsSync, env, platform)) found.push('openclaw')
   return found
 }
 
@@ -1337,38 +1347,38 @@ export function findInstallations(
       // OpenCode's adapter is a plugin module, not a settings document, so it
       // is reported as one installation covering all three events rather than
       // parsed for handlers.
-      if (harness === 'opencode') {
+      if (harness === 'opencode' || harness === 'openclaw') {
         let source: string
         try {
           source = readOwnedRegularFile(file)
         } catch {
           continue
         }
-        const target = opencodePluginTarget(source)
+        const target =
+          harness === 'openclaw' ? openclawPluginTarget(source) : opencodePluginTarget(source)
         if (target === null) continue
+        const label = harness === 'openclaw' ? 'OpenClaw' : 'OpenCode'
         const problems = [
           ...(!target.current
-            ? ['obsolete OpenCode event wiring; rerun `notifai hooks install --harness opencode`']
+            ? [`obsolete ${label} event wiring; rerun \`notifai hooks install --harness ${harness}\``]
             : []),
           ...(target.adapter !== hookAdapterPath(adapterHome)
             ? [
-                'OpenCode still names a mutable CLI or runtime path; rerun `notifai hooks install --harness opencode`',
+                `${label} still names a mutable CLI or runtime path; rerun \`notifai hooks install --harness ${harness}\``,
               ]
             : []),
         ]
+        const events = harness === 'openclaw' ? OPENCLAW_EVENTS : OPENCODE_EVENTS
         found.push({
           harness,
           file,
           global,
           ...(problems.length > 0 ? { problems } : {}),
-          // Reported as the command line the plugin will actually run, not as
-          // the plugin's own path: every check downstream asks which build a
-          // handler invokes, and for a module that answer lives inside it.
-          handlers: OPENCODE_EVENTS.map(([event, hookEvent]) => ({
+          handlers: events.map(([event, hookEvent]) => ({
             event,
             groupIndex: 0,
             handlerIndex: 0,
-            command: hookCommand(target.adapter, hookEvent, 'opencode', {
+            command: hookCommand(target.adapter, hookEvent, harness, {
               ...commandOptions,
               ...(target.nodePath === undefined ? {} : { nodePath: target.nodePath }),
             }),

package/src/interactive.test.ts

@@ -226,6 +226,37 @@ describe('interactiveCommand', () => {
     answers = []
   })
 
+  it('enters init on first-run instead of a parallel Sign in path', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-interactive-first-run-'))
+    const out: string[] = []
+    const deps = makeDeps(cwd)
+    deps.store.load = () => null
+    deps.io.out = (line: string) => {
+      out.push(line)
+    }
+    answers = [CANCEL]
+
+    expect(await interactiveCommand(deps, '0.0.0-test')).toBe(EXIT.ok)
+    expect(out.join('\n')).toContain('Next: This machine')
+    expect(out.join('\n')).toContain('notifai init')
+    expect(out.join('\n')).not.toContain('notifai login')
+    const menu = promptLog.find((entry) => entry.message === 'What would you like to do?')
+    expect(menu?.options?.[0]).toMatchObject({ value: 'setup', label: 'Finish setup' })
+    expect(optionLabels(menu!)).not.toContain('Sign in')
+    expect(optionLabels(menu!)).not.toContain('Add a device')
+  })
+
+  it('offers Finish setup instead of a parallel Add a device path', async () => {
+    const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-interactive-finish-setup-'))
+    answers = [CANCEL]
+
+    expect(await interactiveCommand(makeDeps(cwd), '0.0.0-test')).toBe(EXIT.ok)
+    const menu = promptLog.find((entry) => entry.message === 'What would you like to do?')
+    expect(menu?.options?.[0]).toMatchObject({ value: 'setup', label: 'Finish setup' })
+    expect(optionLabels(menu!)).not.toContain('Add a device')
+    expect(optionLabels(menu!)).not.toContain('Sign in')
+  })
+
   it('quits from the root menu on Escape', async () => {
     const cwd = mkdtempSync(path.join(os.tmpdir(), 'notifai-interactive-root-esc-'))
     answers = [CANCEL]

package/src/interactive.ts

@@ -15,10 +15,11 @@
  *
  * Three things shape the layout:
  *
- * 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 device is what makes the product real.
+ * First-run is `init`, not a second sign-in/device split. An unsigned machine
+ * enters that journey immediately; a remaining blocker is offered as Finish
+ * setup. Once send-prerequisites are ready, the menu leads with the test
+ * notification, because seeing the thing arrive on a 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
@@ -180,6 +181,10 @@ export async function interactiveCommand(deps: CommandDeps, version: string): Pr
   process.stdout.write(`  ${tagline(version)}\n`)
 
   let readiness = await assess(deps)
+  if (stateById(readiness, 'credential')?.status !== 'ready') {
+    await initCommand(deps, {})
+    readiness = await assess(deps)
+  }
   let first = true
 
   for (;;) {
@@ -362,15 +367,13 @@ function menuFor(readiness: Readiness): { value: Screen; label: string; hint?: s
 
   const options: { value: Screen; label: string; hint?: string }[] = []
 
-  if (!signedIn) {
-    options.push({ value: 'account', label: 'Sign in', hint: 'approve this machine in your browser' })
-  } else if (!hasDevice) {
+  if (blocker !== null) {
     options.push({
-      value: 'devices',
-      label: 'Add a device',
-      hint: 'install a supported Companion App',
+      value: 'setup',
+      label: 'Finish setup',
+      hint: shorten(blocker.title.toLowerCase(), 40),
     })
-  } else {
+  } else if (signedIn && hasDevice) {
     options.push({
       value: 'test',
       label: 'Send a test notification',
@@ -378,10 +381,6 @@ function menuFor(readiness: Readiness): { value: Screen; label: string; hint?: s
     })
   }
 
-  if (blocker !== null && signedIn) {
-    options.push({ value: 'setup', label: 'Finish setup', hint: shorten(blocker.title.toLowerCase(), 40) })
-  }
-
   options.push(
     { value: 'settings', label: 'Settings', hint: 'sounds, timing, presence, project' },
     {
@@ -393,11 +392,11 @@ function menuFor(readiness: Readiness): { value: Screen; label: string; hint?: s
   if (signedIn && hasDevice) {
     options.push({ value: 'devices', label: 'Devices', hint: 'what can receive right now' })
   }
-  options.push(
-    { value: 'doctor', label: 'Run diagnostics', hint: 'check every part of the setup' },
-    { value: 'account', label: 'Account', hint: signedIn ? 'plan, machine, sign out' : 'sign in' },
-    { value: 'quit', label: 'Quit' },
-  )
+  options.push({ value: 'doctor', label: 'Run diagnostics', hint: 'check every part of the setup' })
+  if (signedIn) {
+    options.push({ value: 'account', label: 'Account', hint: 'plan, machine, sign out' })
+  }
+  options.push({ value: 'quit', label: 'Quit' })
   return options
 }
 
@@ -822,12 +821,7 @@ async function accountScreen(deps: CommandDeps, readiness: Readiness): Promise<b
   const signedIn = stateById(readiness, 'credential')?.status === 'ready'
 
   if (!signedIn) {
-    const go = await clack.confirm({
-      message: 'Sign in now? This opens your browser to approve this machine.',
-      initialValue: true,
-    })
-    if (cancelled(go) || go !== true) return false
-    await loginCommand(deps, {})
+    await initCommand(deps, {})
     return true
   }
 

package/src/main-run.ts

@@ -0,0 +1,45 @@
+/**
+ * Everything the CLI needs to actually run a command.
+ *
+ * Separate from `main.ts` so that the Node floor check there can decide
+ * whether this file is safe to parse at all: a static import would be hoisted
+ * above the check and fail first on the very runtimes the check exists to
+ * turn away.
+ */
+import { realIo, type CommandDeps } from './commands.js'
+import { defaultCredentialStore } from './credentials.js'
+import { nativeSkills } from './native-skills.js'
+import { argvFlagNames, bootstrapLogger } from './logging.js'
+import { buildProgram } from './program.js'
+import { spawnQuestionSettlement } from './question-settlement-process.js'
+
+/**
+ * The local record for this invocation.
+ *
+ * Built before the command tree so that the very first thing recorded is the
+ * command starting — including for a command that goes on to fail before it has
+ * resolved anything. It configures itself from disk and disables itself if it
+ * cannot write, so nothing below has to handle it failing.
+ */
+const logger = bootstrapLogger()
+
+const deps: CommandDeps = {
+  io: realIo(),
+  store: defaultCredentialStore(),
+  env: process.env,
+  cwd: process.cwd(),
+  nativeSkills,
+  spawnQuestionSettlement,
+  logger,
+}
+
+const startedAt = Date.now()
+process.on('exit', (code) => {
+  logger.info('cli.end', {
+    exit: code,
+    duration_ms: Date.now() - startedAt,
+    flags: argvFlagNames(process.argv.slice(2)),
+  })
+})
+
+await buildProgram(deps).parseAsync(process.argv)

package/src/main.ts

@@ -1,36 +1,12 @@
 #!/usr/bin/env node
-import { realIo, type CommandDeps } from './commands.js'
-import { defaultCredentialStore } from './credentials.js'
-import { nativeSkills } from './native-skills.js'
-import { argvFlagNames, bootstrapLogger } from './logging.js'
-import { buildProgram } from './program.js'
-
-/**
- * The local record for this invocation.
- *
- * Built before the command tree so that the very first thing recorded is the
- * command starting — including for a command that goes on to fail before it has
- * resolved anything. It configures itself from disk and disables itself if it
- * cannot write, so nothing below has to handle it failing.
- */
-const logger = bootstrapLogger()
-
-const deps: CommandDeps = {
-  io: realIo(),
-  store: defaultCredentialStore(),
-  env: process.env,
-  cwd: process.cwd(),
-  nativeSkills,
-  logger,
+import { belowNodeFloor, nodeFloorMessage } from './node-floor.js'
+
+// Before anything else is parsed. `node-floor.js` imports nothing and uses no
+// syntax newer than the floor it checks, so it can report on the runtimes that
+// would otherwise fail somewhere in a dependency with no mention of Notifai.
+if (belowNodeFloor(process.version)) {
+  for (const line of nodeFloorMessage(process.version)) process.stderr.write(`${line}\n`)
+  process.exit(2)
 }
 
-const startedAt = Date.now()
-process.on('exit', (code) => {
-  logger.info('cli.end', {
-    exit: code,
-    duration_ms: Date.now() - startedAt,
-    flags: argvFlagNames(process.argv.slice(2)),
-  })
-})
-
-await buildProgram(deps).parseAsync(process.argv)
+await import('./main-run.js')

package/src/node-floor.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { NODE_MAJOR_FLOOR, belowNodeFloor, nodeFloorMessage, nodeMajor } from './node-floor.js'
+
+describe('the Node runtime floor', () => {
+  it('turns away a runtime below the floor', () => {
+    expect(belowNodeFloor('v20.11.1')).toBe(true)
+    expect(belowNodeFloor('v18.0.0')).toBe(true)
+  })
+
+  it('admits the floor and everything above it', () => {
+    expect(belowNodeFloor(`v${NODE_MAJOR_FLOOR}.0.0`)).toBe(false)
+    expect(belowNodeFloor('v24.3.0')).toBe(false)
+  })
+
+  it('does not strand a reader whose version it cannot read', () => {
+    expect(nodeMajor('bun-1.2')).toBeNull()
+    expect(belowNodeFloor('bun-1.2')).toBe(false)
+  })
+
+  it('says what is wrong and exactly one thing to do', () => {
+    const [problem, next] = nodeFloorMessage('v20.11.1')
+    expect(problem).toContain('Node 22 or newer')
+    expect(problem).toContain('v20.11.1')
+    expect(next).toMatch(/^next: /)
+    expect(next).toContain('nodejs.org')
+  })
+})

package/src/node-floor.ts

@@ -0,0 +1,37 @@
+/**
+ * The Node version this CLI needs, asserted before anything else loads.
+ *
+ * `engines` in package.json is advisory: npm prints a warning at install time
+ * and runs the binary anyway. So a reader on an older Node met a parser or
+ * module error naming a file they did not write, with no mention of Notifai,
+ * of Node, or of anything to do about it.
+ *
+ * This module is deliberately plain — no imports, no syntax newer than the
+ * floor it is checking — so it can run and report on the runtimes it exists to
+ * turn away. Everything else is loaded after it passes.
+ */
+
+export const NODE_MAJOR_FLOOR = 22
+
+/** The major from a `process.version` string, or null when unrecognisable. */
+export function nodeMajor(version: string): number | null {
+  const match = /^v?(\d+)\./.exec(version)
+  if (match === null) return null
+  const major = Number(match[1])
+  return Number.isFinite(major) ? major : null
+}
+
+export function belowNodeFloor(version: string): boolean {
+  const major = nodeMajor(version)
+  // An unrecognisable version is not evidence of an old runtime, and refusing
+  // to run on one would strand a reader whose Node is fine.
+  return major !== null && major < NODE_MAJOR_FLOOR
+}
+
+/** One sentence for what is wrong, one for what to do about it. */
+export function nodeFloorMessage(version: string): string[] {
+  return [
+    `Notifai needs Node ${NODE_MAJOR_FLOOR} or newer; this is Node ${version}.`,
+    `next: install Node ${NODE_MAJOR_FLOOR}+ (https://nodejs.org), then run this again.`,
+  ]
+}