@agfpd/iapeer 0.1.0

package/src/daemon/main.ts

@@ -0,0 +1,230 @@
+// Production daemon main — THE composition point. The library `startDaemon`
+// (daemon/index.ts) is transport-only (route / deliver / liveness) and takes the
+// lifecycle primitives as INJECTED hooks; this module wires them:
+//   • wake-on-miss  → lifecycle.wakeOrSpawn (a send to a dead, non-launchd peer
+//     spawns it and delivers the envelope as its boot first-message). H4 (never
+//     wake a launchd-managed peer) lives INSIDE wakeOrSpawn.
+//   • supervise     → a timer running lifecycle.superviseTick (idle-reap /
+//     zombie-sweep), H4-guarded per session inside.
+// This is where Ф1 (transport) meets Ф2 (lifecycle). It also installs the daemon's
+// OWN always-on launchd plist (label com.agfpd.iapeer — a SEPARATE namespace from
+// the com.iapeer.* peer fleet, so it never collides with persistent-peer plists).
+//
+// The CLI at the bottom is the launchd-held process (`bun main.ts`) and the
+// foreground entrypoint for acceptance. Installing the plist is a SEPARATE explicit
+// action (`--install-plist`); it writes the file but does NOT load it — a live
+// `launchctl bootstrap` stays a deliberate operator step.
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+import { DAEMON_PLIST_LABEL } from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
+import { pluginLogsDir } from '../storage/index.ts'
+import {
+  isFoundationOwnedPlist,
+  launchAgentsDir,
+  renderLaunchdPlist,
+} from '../launch/launchd.ts'
+import type { LaunchdPlistSpec } from '../launch/launchd.ts'
+import {
+  loadLifecycleConfig,
+  processEagerRelaunches,
+  superviseTick,
+  wakeOrSpawn,
+  type LifecycleConfig,
+} from '../lifecycle/index.ts'
+import type { WakeFn, WakeOutcome, WakeRequest } from '../transport/index.ts'
+import { iapeerBinPath } from '../install/index.ts'
+import { defaultDaemonSocketPath, startDaemon, type DaemonHandle } from './index.ts'
+
+/** Default TCP loopback port for the always-on router. Real http MCP clients
+ *  (claude/codex `--transport http <url>`) bind to a fixed URL, so production needs
+ *  a STABLE port, not an ephemeral one. Override with IAPEER_PORT. */
+export const DEFAULT_DAEMON_PORT = 8765
+
+/** Default supervise-tick cadence (idle-reap / zombie-sweep). idleSecs (1h default)
+ *  is the reap threshold; this is just how often the timer checks. */
+export const DEFAULT_SUPERVISE_INTERVAL_MS = 60_000
+
+// This module's own path — the launchd plist runs `bun <this>` as the daemon.
+const DAEMON_MAIN_PATH = fileURLToPath(import.meta.url)
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Composition: wire startDaemon ⇆ lifecycle (wake + supervise)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Adapt the transport WakeFn contract to lifecycle.wakeOrSpawn. The two shapes are
+ * structurally identical (WakeRequest ⊆ WakeArgs, WakeResult ⊆ WakeOutcome); this
+ * is the one place transport's injected-wake meets the lifecycle implementation.
+ */
+export function makeWakeFn(cfg: LifecycleConfig, env: NodeJS.ProcessEnv): WakeFn {
+  return (req: WakeRequest): Promise<WakeOutcome> =>
+    wakeOrSpawn(
+      { personality: req.personality, runtime: req.runtime, topic: req.topic, task: req.task },
+      { cfg, env },
+    )
+}
+
+export interface ConfiguredDaemonOptions {
+  /** TCP loopback port (default DEFAULT_DAEMON_PORT). */
+  port?: number
+  host?: string
+  /** Unix-socket path (H8 same-uid base; default: defaultDaemonSocketPath). */
+  socketPath?: string
+  /** H8 bearer token; falls back to env.IAPEER_BEARER_TOKEN. Off when neither set. */
+  bearerToken?: string
+  superviseIntervalMs?: number
+  /** Write the router.json discovery file (default true for production). */
+  discovery?: boolean
+  rootDir?: string
+  env?: NodeJS.ProcessEnv
+}
+
+/**
+ * Start the fully-composed production daemon: the router (startDaemon) wired to
+ * wake-on-miss (wakeOrSpawn) and the supervise timer (superviseTick). DUAL-LISTEN
+ * by default — a 0600 unix socket (local same-uid callers: notifier/telegram/CLI)
+ * AND TCP loopback (real http MCP agent clients), both over one MCP handler — and
+ * the router.json discovery file written for daemon-aware `iap send`. The bearer
+ * layer (H8) engages only when a token is configured.
+ */
+export async function startConfiguredDaemon(opts: ConfiguredDaemonOptions = {}): Promise<DaemonHandle> {
+  const env = opts.env ?? process.env
+  const cfg = loadLifecycleConfig(env)
+  const bearerToken = opts.bearerToken ?? (env.IAPEER_BEARER_TOKEN?.trim() || undefined)
+  return startDaemon({
+    wake: makeWakeFn(cfg, env),
+    supervise: {
+      intervalMs: opts.superviseIntervalMs ?? DEFAULT_SUPERVISE_INTERVAL_MS,
+      // idle-reap / zombie-sweep, THEN C4b eager fresh re-launch for any peer whose
+      // session died carrying a /new graceful mark (async, best-effort).
+      tick: async () => {
+        const outcomes = superviseTick(cfg, { env })
+        await processEagerRelaunches(cfg, outcomes, { env })
+      },
+    },
+    bearerToken,
+    port: opts.port ?? DEFAULT_DAEMON_PORT,
+    host: opts.host ?? '127.0.0.1',
+    socketPath: opts.socketPath ?? defaultDaemonSocketPath({ env, rootDir: opts.rootDir }),
+    discovery: opts.discovery ?? true,
+    env,
+    rootDir: opts.rootDir,
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The daemon's OWN launchd plist (com.agfpd.iapeer) — distinct from peer plists
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function daemonPlistPath(env: NodeJS.ProcessEnv = process.env): string {
+  return join(launchAgentsDir(env), `${DAEMON_PLIST_LABEL}.plist`)
+}
+
+export interface InstallDaemonPlistOptions {
+  /** How to launch the daemon (default [bun, main.ts]). */
+  programArgv?: string[]
+  /** TCP port baked into the plist env (default DEFAULT_DAEMON_PORT). */
+  port?: number
+  /** H8 bearer token baked into the plist env (only when provided). */
+  bearerToken?: string
+  /** PATH for the launchd minimal env. */
+  path?: string
+  workingDirectory?: string
+  env?: NodeJS.ProcessEnv
+  throttleIntervalSecs?: number
+}
+
+/** Build the daemon's launchd plist spec (PURE — render/lint-testable). */
+export function buildDaemonPlistSpec(opts: InstallDaemonPlistOptions = {}): LaunchdPlistSpec {
+  const env = opts.env ?? process.env
+  const home = env.HOME?.trim() || homedir()
+  const defaultPath = `${home}/.bun/bin:${home}/.local/bin:/opt/homebrew/bin:/usr/bin:/bin`
+  const logDir = pluginLogsDir('iapeer', { env })
+  const environment: Record<string, string> = {
+    PATH: opts.path ?? env.PATH ?? defaultPath,
+    IAPEER_PORT: String(opts.port ?? DEFAULT_DAEMON_PORT),
+  }
+  if (opts.bearerToken) environment.IAPEER_BEARER_TOKEN = opts.bearerToken
+  // Propagate the FULL set of non-default path overrides so the launchd-held daemon
+  // reads the SAME tree the rest of the fleet uses (audit #26: a sandbox daemon that
+  // carried only IAPEER_ROOT would scan the wrong tmux socket dir and key its H4
+  // launchd-guard on the wrong LaunchAgents dir — the routing + fleet-guard surfaces).
+  for (const key of ['IAPEER_ROOT', 'IAPEER_SOCK_DIR', 'IAPEER_LAUNCHAGENTS_DIR'] as const) {
+    if (env[key]?.trim()) environment[key] = env[key]!.trim()
+  }
+  return {
+    label: DAEMON_PLIST_LABEL,
+    // Ф-F: run the INSTALLED binary (`iapeer daemon`), NOT `bun <src>/daemon/main.ts`
+    // — this is the decoupling of prod from the mutable src tree. opts.programArgv
+    // overrides for tests / a non-default layout.
+    programArguments: opts.programArgv ?? [iapeerBinPath(env), 'daemon'],
+    workingDirectory: opts.workingDirectory ?? home, // daemon is cwd-agnostic (per-request identity)
+    environment,
+    stdoutPath: join(logDir, 'daemon-stdout.log'),
+    stderrPath: join(logDir, 'daemon-stderr.log'),
+    throttleIntervalSecs: opts.throttleIntervalSecs,
+  }
+}
+
+/**
+ * Generate + install the daemon's always-on launchd plist at
+ * ~/Library/LaunchAgents/com.agfpd.iapeer.plist (or IAPEER_LAUNCHAGENTS_DIR),
+ * returning the path. Writes the FILE only — does NOT bootstrap it (load is a
+ * deliberate operator step). Collision guard: refuses to overwrite an existing
+ * com.agfpd.iapeer.plist that is not foundation-owned (lacks the sentinel) — the
+ * same ownership proof the peer-plist installer uses. com.agfpd.* is the
+ * foundation-exclusive daemon namespace, so this never touches the com.iapeer.*
+ * persistent-peer fleet.
+ */
+export function installDaemonPlist(opts: InstallDaemonPlistOptions = {}): string {
+  const env = opts.env ?? process.env
+  const path = daemonPlistPath(env)
+  if (existsSync(path) && !isFoundationOwnedPlist(path)) {
+    throw new IapError(
+      `refusing to overwrite ${path}: ${DAEMON_PLIST_LABEL} exists but is not foundation-managed ` +
+        `(no ownership sentinel) — another manager owns it`,
+    )
+  }
+  const spec = buildDaemonPlistSpec(opts)
+  mkdirSync(launchAgentsDir(env), { recursive: true })
+  mkdirSync(pluginLogsDir('iapeer', { env }), { recursive: true, mode: 0o700 })
+  writeFileSync(path, renderLaunchdPlist(spec), { mode: 0o644 })
+  return path
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI — launchd-held process / foreground acceptance entrypoint
+// ─────────────────────────────────────────────────────────────────────────────
+
+if (import.meta.main) {
+  const arg = process.argv[2]
+  if (arg === '--print-plist') {
+    process.stdout.write(renderLaunchdPlist(buildDaemonPlistSpec()))
+    process.exit(0)
+  } else if (arg === '--install-plist') {
+    const p = installDaemonPlist()
+    process.stdout.write(
+      `installed daemon plist: ${p}\n` +
+        `NOT loaded. To start it live: launchctl bootstrap gui/$(id -u) ${p}\n`,
+    )
+    process.exit(0)
+  } else {
+    const env = process.env
+    const handle = await startConfiguredDaemon({
+      port: Number(env.IAPEER_PORT ?? DEFAULT_DAEMON_PORT),
+      socketPath: env.IAPEER_DAEMON_SOCKET?.trim() || undefined,
+      env,
+    })
+    process.stderr.write(`[iapeer-daemon] READY tcp=${handle.url} sock=${handle.socketPath}\n`)
+    const shutdown = () => {
+      void handle.close().then(() => process.exit(0))
+    }
+    process.on('SIGTERM', shutdown)
+    process.on('SIGINT', shutdown)
+    await new Promise(() => {}) // launchd KeepAlive holds this process; block forever
+  }
+}

package/src/enable/enable.test.ts

@@ -0,0 +1,92 @@
+// enable — the PURE fleet-safety + idempotency logic: parse `claude plugin list
+// --json`, match the entry for THIS peer's projectPath (realpath), and detect a
+// plugin's `setup` from iapeer.json (SIMPLE vs СЛОЖНЫЙ). The spawn/install paths are
+// live-verified on a throwaway test-peer (project-scope is keyed by projectPath, so a
+// test install never touches a live peer's entry).
+
+import { describe, expect, test } from 'bun:test'
+import { mkdtempSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { findPeerScopedEntry, parseCodexPluginStatus, parseInstalledPlugins, readSetupDescriptor } from './index.ts'
+
+// a realistic `claude plugin list --json` array (the live shape: id/scope/enabled/
+// projectPath/installPath), two live peers + the same plugin user-scope.
+const LIST = JSON.stringify([
+  { id: 'Inter-Agent-Protocol@agfpd', scope: 'project', enabled: true, projectPath: '/Users/x/agents/linus', installPath: '/c/iap/0.7.11' },
+  { id: 'peer-voice@agfpd', scope: 'project', enabled: true, projectPath: '/Users/x/agents/boris', installPath: '/c/pv/0.1.8' },
+  { id: 'peer-voice@agfpd', scope: 'user', enabled: false, installPath: '/c/pv/0.1.8' },
+])
+
+describe('parseInstalledPlugins', () => {
+  test('parses the flat array into typed entries; tolerates junk', () => {
+    const e = parseInstalledPlugins(LIST)
+    expect(e.length).toBe(3)
+    expect(e[0]).toMatchObject({ id: 'Inter-Agent-Protocol@agfpd', scope: 'project', enabled: true, projectPath: '/Users/x/agents/linus' })
+    expect(parseInstalledPlugins('not json')).toEqual([])
+    expect(parseInstalledPlugins('{"not":"array"}')).toEqual([])
+    expect(parseInstalledPlugins('[1, null, {"no":"id"}]')).toEqual([]) // entries without a string id are dropped
+  })
+})
+
+describe('findPeerScopedEntry (per-peer, fleet-safe)', () => {
+  test('matches ONLY the project-scope entry for this peer cwd', () => {
+    const e = parseInstalledPlugins(LIST)
+    expect(findPeerScopedEntry(e, 'peer-voice', 'agfpd', '/Users/x/agents/boris')?.enabled).toBe(true)
+    // a DIFFERENT peer cwd → no match (never reports another peer's install as ours)
+    expect(findPeerScopedEntry(e, 'peer-voice', 'agfpd', '/Users/x/agents/darwin')).toBeNull()
+    // user-scope is not a per-peer match
+    expect(findPeerScopedEntry(e, 'peer-voice', 'agfpd', '/Users/x/agents/boris')?.scope).toBe('project')
+  })
+  test('absent plugin for this peer → null (drives install, not false-skip)', () => {
+    const e = parseInstalledPlugins(LIST)
+    expect(findPeerScopedEntry(e, 'MergeMind', 'agfpd', '/Users/x/agents/linus')).toBeNull()
+  })
+})
+
+// the real `codex plugin list` table shape (whitespace-aligned columns)
+const CODEX_LIST = `Marketplace \`agfpd\`
+
+PLUGIN                      STATUS              VERSION  PATH
+spawned-peer@agfpd          not installed                https://github.com/agfpd/Spawned-Peer.git
+peer-voice@agfpd            installed, enabled  0.1.8    https://github.com/agfpd/Peer-Voice.git
+MergeMind@agfpd             installed, disabled 0.14.70  https://github.com/agfpd/MergeMind.git`
+
+describe('parseCodexPluginStatus', () => {
+  test('reads the STATUS column per plugin id', () => {
+    expect(parseCodexPluginStatus(CODEX_LIST, 'peer-voice@agfpd')).toBe('enabled')
+    expect(parseCodexPluginStatus(CODEX_LIST, 'spawned-peer@agfpd')).toBe('absent') // "not installed"
+    expect(parseCodexPluginStatus(CODEX_LIST, 'MergeMind@agfpd')).toBe('disabled')
+    expect(parseCodexPluginStatus(CODEX_LIST, 'totp-presence@agfpd')).toBe('absent') // not in list
+    expect(parseCodexPluginStatus('', 'x@agfpd')).toBe('absent')
+  })
+})
+
+describe('readSetupDescriptor (SIMPLE vs СЛОЖНЫЙ)', () => {
+  test('no installPath / no iapeer.json → null (SIMPLE: install+enable only)', () => {
+    expect(readSetupDescriptor(undefined)).toBeNull()
+    const dir = mkdtempSync(join(tmpdir(), 'iapeer-enable-simple-'))
+    try {
+      expect(readSetupDescriptor(dir)).toBeNull() // peer-voice-like: no manifest
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+  test('iapeer.json with setup string → returns it; with {command,args} → object', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'iapeer-enable-complex-'))
+    try {
+      writeFileSync(join(dir, 'iapeer.json'), JSON.stringify({ setup: 'bin/setup' }))
+      expect(readSetupDescriptor(dir)).toBe('bin/setup')
+      writeFileSync(join(dir, 'iapeer.json'), JSON.stringify({ setup: { command: 'node', args: ['setup.js'] } }))
+      expect(readSetupDescriptor(dir)).toEqual({ command: 'node', args: ['setup.js'] })
+      // requires present but NO setup → still SIMPLE (iapeer does not resolve requires)
+      writeFileSync(join(dir, 'iapeer.json'), JSON.stringify({ requires: ['telegram'] }))
+      expect(readSetupDescriptor(dir)).toBeNull()
+      // malformed manifest → treated as SIMPLE, never throws
+      writeFileSync(join(dir, 'iapeer.json'), '{ broken')
+      expect(readSetupDescriptor(dir)).toBeNull()
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})