@agfpd/iapeer 0.1.0

package/src/provision/index.ts

@@ -0,0 +1,170 @@
+// Provision — the one-call peer-creation entrypoint. Composes the two foundation
+// writes a new peer needs: identity.ensurePeerProfile (local <cwd>/.iapeer/
+// peer-profile.json + scaffold + — for an INFRA runtime — the always-on launchd
+// plist) and registry.upsertPeer (the global peers-profiles.json entry the daemon
+// reads for its tool-list, caller resolution, and wake-on-miss findPeer).
+//
+// INFRA gotcha closed at this layer: a notifier/telegram always-on plist runs its
+// launcher under launchd's MINIMAL PATH (no ~/.local/bin, ~/.bun/bin). So before
+// writing the plist we RESOLVE the runtime launcher to an absolute path against the
+// rich provisioning PATH and bake it in (NOTIFIER_RUNTIME_BIN / TELEGRAM_RUNTIME_BIN
+// via installAlwaysOnPlist). If it does not resolve to an executable, we REFUSE to
+// provision rather than create a peer whose always-on session crash-loops.
+
+import { basename, resolve } from 'path'
+import {
+  INFRA_RUNTIME_DEFAULT_BIN,
+  isInfraRuntime,
+  isRuntime,
+  normalizeNameCandidate,
+  type Intelligence,
+  type Runtime,
+} from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
+import { peerProfilePath } from '../storage/index.ts'
+import { ensurePeerProfile } from '../identity/index.ts'
+import { readPeersIndex, upsertPeer } from '../registry/index.ts'
+import { launchdPlistPath, resolveExecutable } from '../launch/launchd.ts'
+
+export interface ProvisionPeerOptions {
+  /** The peer's working directory. personality defaults to normalized basename. */
+  cwd: string
+  runtime: Runtime
+  /** Explicit personality override (default: normalized basename(cwd)). */
+  personality?: string
+  description?: string
+  intelligence?: Intelligence
+  /** Infra runtime launcher (abs path or PATH name); resolved to an abs path. */
+  runtimeBin?: string
+  env?: NodeJS.ProcessEnv
+  warn?: (message: string) => void
+}
+
+export interface ProvisionResult {
+  personality: string
+  runtime: Runtime
+  cwd: string
+  profilePath: string
+  intelligence: Intelligence
+  /** For an infra runtime: the installed always-on plist path. */
+  plistPath?: string
+  /** For an infra runtime: the absolute launcher path baked into the plist. */
+  runtimeBin?: string
+}
+
+/**
+ * Provision a new peer in one call: local profile + scaffold (+ infra always-on
+ * plist with a pinned launcher) then the registry entry. Idempotent-ish: if the
+ * cwd already has a peer-profile.json, ensurePeerProfile returns it unchanged (no
+ * second plist install) and the registry is upserted (merge-with-existing).
+ */
+export async function provisionPeer(opts: ProvisionPeerOptions): Promise<ProvisionResult> {
+  const env = opts.env ?? process.env
+  if (!isRuntime(opts.runtime)) {
+    throw new IapError(`invalid runtime "${opts.runtime}" — must match /^[a-z][a-z0-9]{0,31}$/`)
+  }
+  const cwd = resolve(opts.cwd)
+
+  // INFRA: resolve the launcher to an abs path NOW (rich provisioning PATH) and
+  // refuse to provision a crash-looper. Warm-on-demand runtimes need no plist.
+  let runtimeBin: string | undefined
+  if (isInfraRuntime(opts.runtime)) {
+    const want = opts.runtimeBin ?? INFRA_RUNTIME_DEFAULT_BIN[opts.runtime] ?? opts.runtime
+    runtimeBin = resolveExecutable(want, env)
+    if (!runtimeBin) {
+      throw new IapError(
+        `cannot provision infra peer "${opts.personality ?? normalizeNameCandidate(basename(cwd))}": ` +
+          `runtime launcher "${want}" not found on PATH or not executable. Install ${opts.runtime}-runtime ` +
+          `(or pass an absolute --bin) so the always-on plist resolves it under launchd's minimal PATH.`,
+      )
+    }
+  }
+
+  const peers = readPeersIndex({ env }).peers
+  // 1) local profile + scaffold + (infra) always-on plist with the pinned launcher.
+  const profile = ensurePeerProfile({
+    cwd,
+    runtime: opts.runtime,
+    env,
+    peers,
+    personality: opts.personality,
+    runtimeBin,
+    warn: opts.warn,
+  })
+  // 2) registry entry — without it the daemon does not see the peer (tool-list,
+  //    caller resolution, wake-on-miss findPeer all read peers-profiles.json).
+  await upsertPeer(
+    {
+      personality: profile.personality,
+      runtime: opts.runtime,
+      cwd,
+      intelligence: opts.intelligence ?? profile.intelligence,
+      description: opts.description,
+    },
+    { env, warn: opts.warn },
+  )
+
+  return {
+    personality: profile.personality,
+    runtime: opts.runtime,
+    cwd,
+    profilePath: peerProfilePath(cwd),
+    intelligence: opts.intelligence ?? profile.intelligence,
+    plistPath: isInfraRuntime(opts.runtime) ? launchdPlistPath(profile.personality, env) : undefined,
+    runtimeBin,
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI — `bun src/provision/index.ts <cwd> <runtime> [--personality p] [--bin path]
+//        [--description d] [--intelligence i]`
+// ─────────────────────────────────────────────────────────────────────────────
+
+function parseFlags(argv: string[]): { positionals: string[]; flags: Record<string, string> } {
+  const positionals: string[] = []
+  const flags: Record<string, string> = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) {
+      flags[a.slice(2)] = argv[++i] ?? ''
+    } else {
+      positionals.push(a)
+    }
+  }
+  return { positionals, flags }
+}
+
+if (import.meta.main) {
+  const { positionals, flags } = parseFlags(process.argv.slice(2))
+  const [cwd, runtime] = positionals
+  if (!cwd || !runtime) {
+    process.stderr.write(
+      'usage: provision-peer <cwd> <runtime> [--personality <p>] [--bin <abs-launcher>] ' +
+        '[--description <d>] [--intelligence artificial|natural|absent]\n',
+    )
+    process.exit(2)
+  }
+  provisionPeer({
+    cwd,
+    runtime,
+    personality: flags.personality,
+    description: flags.description,
+    intelligence: flags.intelligence as Intelligence | undefined,
+    runtimeBin: flags.bin,
+    warn: m => process.stderr.write(`warn: ${m}\n`),
+  })
+    .then(r => {
+      process.stdout.write(
+        `provisioned peer "${r.personality}" (${r.runtime}, ${r.intelligence})\n` +
+          `  profile:  ${r.profilePath}\n` +
+          `  registry: peers-profiles.json updated\n` +
+          (r.plistPath ? `  plist:    ${r.plistPath}\n  launcher: ${r.runtimeBin}\n` : '') +
+          (r.plistPath ? `  (plist written, NOT loaded — run: launchctl bootstrap gui/$(id -u) ${r.plistPath})\n` : ''),
+      )
+      process.exit(0)
+    })
+    .catch(e => {
+      process.stderr.write(`provision failed: ${e instanceof Error ? e.message : String(e)}\n`)
+      process.exit(1)
+    })
+}

package/src/provision/provision.test.ts

@@ -0,0 +1,104 @@
+// provisionPeer — one-call peer creation: profile + registry (+ infra plist with a
+// PINNED launcher). All registry/plist writes go under IAPEER_ROOT /
+// IAPEER_LAUNCHAGENTS_DIR temp dirs so the suite never touches the live fleet.
+
+import { afterEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { provisionPeer } from './index.ts'
+import { peerProfilePath } from '../storage/index.ts'
+import { readPeerProfile } from '../identity/index.ts'
+import { findPeer, readPeersIndex } from '../registry/index.ts'
+import { isFoundationOwnedPlist, launchdPlistPath } from '../launch/index.ts'
+
+const roots: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-prov-'))
+  roots.push(d)
+  return d
+}
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function fakeBinDir(name = 'notifier-runtime'): { dir: string; bin: string } {
+  const dir = mkTmp()
+  const bin = join(dir, name)
+  writeFileSync(bin, '#!/bin/sh\nexit 0\n', { mode: 0o755 })
+  return { dir, bin }
+}
+function envFor(root: string, path?: string): NodeJS.ProcessEnv {
+  return {
+    IAPEER_ROOT: join(root, 'iapeer'),
+    IAPEER_LAUNCHAGENTS_DIR: join(root, 'LA'),
+    HOME: root,
+    ...(path ? { PATH: path } : {}),
+  } as NodeJS.ProcessEnv
+}
+
+describe('provisionPeer', () => {
+  test('infra (notifier): writes profile + registry + plist with a pinned abs launcher', async () => {
+    const root = mkTmp()
+    const { dir: bindir, bin } = fakeBinDir()
+    const env = envFor(root, bindir)
+    const cwd = join(root, 'timer') // basename → personality 'timer'
+
+    const r = await provisionPeer({ cwd, runtime: 'notifier', env })
+
+    expect(r.personality).toBe('timer')
+    expect(r.intelligence).toBe('absent') // notifier zone default
+    expect(r.runtimeBin).toBe(bin)
+    // local profile
+    expect(existsSync(peerProfilePath(cwd))).toBe(true)
+    expect(readPeerProfile(cwd)!.runtime).toBe('notifier')
+    // registry entry (daemon reads this for tool-list / findPeer / wake)
+    expect(findPeer(readPeersIndex({ env }), 'timer')?.cwd).toBe(cwd)
+    // plist pins the launcher to an abs path (launchd minimal PATH safe)
+    const plist = launchdPlistPath('timer', env)
+    expect(existsSync(plist)).toBe(true)
+    expect(isFoundationOwnedPlist(plist)).toBe(true)
+    const xml = readFileSync(plist, 'utf8')
+    expect(xml).toContain('<key>NOTIFIER_RUNTIME_BIN</key>')
+    expect(xml).toContain(`<string>${bin}</string>`)
+  })
+
+  test('infra with unresolvable launcher → REFUSED (no profile, no registry, no plist)', async () => {
+    const root = mkTmp()
+    const env = envFor(root, join(root, 'empty')) // PATH dir without notifier-runtime
+    const cwd = join(root, 'timer')
+
+    await expect(provisionPeer({ cwd, runtime: 'notifier', env })).rejects.toThrow(/not found on PATH|launcher/i)
+
+    expect(existsSync(peerProfilePath(cwd))).toBe(false)
+    expect(findPeer(readPeersIndex({ env }), 'timer')).toBeNull()
+    expect(existsSync(launchdPlistPath('timer', env))).toBe(false)
+  })
+
+  test('warm-on-demand (claude): profile + registry, NO plist (no launcher needed)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const cwd = join(root, 'worker')
+
+    const r = await provisionPeer({ cwd, runtime: 'claude', env })
+
+    expect(r.plistPath).toBeUndefined()
+    expect(r.runtimeBin).toBeUndefined()
+    expect(existsSync(peerProfilePath(cwd))).toBe(true)
+    expect(findPeer(readPeersIndex({ env }), 'worker')?.runtime).toBe('claude')
+    expect(existsSync(launchdPlistPath('worker', env))).toBe(false)
+  })
+
+  test('explicit personality override (not basename) provisions under that name', async () => {
+    const root = mkTmp()
+    const { dir: bindir } = fakeBinDir()
+    const env = envFor(root, bindir)
+    const cwd = join(root, 'some-dir')
+
+    const r = await provisionPeer({ cwd, runtime: 'notifier', personality: 'timer', env })
+
+    expect(r.personality).toBe('timer')
+    expect(existsSync(launchdPlistPath('timer', env))).toBe(true)
+    expect(findPeer(readPeersIndex({ env }), 'timer')?.cwd).toBe(cwd)
+  })
+})