@agfpd/iapeer 0.1.0

package/src/runtime/index.ts

@@ -0,0 +1,191 @@
+// runtime — the PACKAGE-FACING contract for an iapeer runtime package (telegram,
+// notifier, …): the runtime MANIFEST a package declares, and the PER-PEER self-config
+// hook the foundation invokes. This is the Волна-2 gate (contract Протокол iapeer
+// рантайма / Стандарт iapeer плагина): a runtime package implements against THIS
+// surface; the foundation orchestrates without knowing the package's internals.
+//
+// TWO PROVISION MODES, ONE HOOK (the key shape):
+//   (a) declared-set  — a package whose peers are FIXED FUNCTIONS (notifier: timer +
+//       watcher) lists them in manifest.peers; `deployRuntime` provisions the whole
+//       declared set. Static.
+//   (b) operator-add  — a package whose peers are PEOPLE the package can't know ahead
+//       (telegram: a human) declares NO peers; the operator adds one dynamically with
+//       `iapeer create maria --runtime telegram`. Dynamic.
+// BOTH converge on the SAME per-peer self-config hook ("configure runtime state for
+// peer X", idempotent). The hook is per-peer; only the enumeration/trigger differs.
+// So manifest.peers is OPTIONAL (mode b omits it); manifest.selfConfig is the shared
+// contract both modes call. (Mirror of the capability `setup` descriptor in enable.)
+//
+// The manifest lives at ~/.iapeer/runtimes/<runtime>/runtime.json — the runtime's own
+// namespace (zone Хранение). The package writes it at npx-install (self-deploy); the
+// foundation reads it at create / deploy.
+
+import { spawnSync } from 'child_process'
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { isRuntime, type Intelligence, type Runtime } from '../core/constants.ts'
+import { IapError } from '../core/errors.ts'
+import { runtimeRoot, writeFileAtomic, type StorageOptions } from '../storage/index.ts'
+
+/** The runtime manifest filename inside ~/.iapeer/runtimes/<runtime>/. */
+export const RUNTIME_MANIFEST_FILE = 'runtime.json'
+
+/** A self-config hook descriptor: a bare command (PATH-resolvable or absolute), or
+ *  {command, args}. Same shape as the capability `setup` descriptor (enable). */
+export type SelfConfigDescriptor = string | { command: string; args?: string[] }
+
+/** One declared peer in a package's FIXED set (mode a). personality is required; the
+ *  rest default (intelligence → the runtime's zone default; cwd → ~/.iapeer/peers/<p>). */
+export interface RuntimePeerDecl {
+  personality: string
+  intelligence?: Intelligence
+  description?: string
+  /** Explicit cwd; default ~/.iapeer/peers/<personality>. */
+  path?: string
+  /** Abs path / PATH name of the runtime launcher for THIS peer's plist (rarely
+   *  needed — the default `<runtime>-runtime` on PATH resolves it). */
+  runtimeBin?: string
+}
+
+/** The package-declared runtime manifest (~/.iapeer/runtimes/<runtime>/runtime.json). */
+export interface RuntimeManifest {
+  /** The runtime id this manifest describes (must match the folder it lives in). */
+  runtime: Runtime
+  /** OPTIONAL per-peer self-config hook (the shared contract both modes call). */
+  selfConfig?: SelfConfigDescriptor
+  /** OPTIONAL fixed peer-set (mode a). Omitted by an operator-add runtime (mode b). */
+  peers?: RuntimePeerDecl[]
+}
+
+/** Path to a runtime's manifest: ~/.iapeer/runtimes/<runtime>/runtime.json. */
+export function runtimeManifestPath(runtime: Runtime, options: StorageOptions = {}): string {
+  return join(runtimeRoot(runtime, options), RUNTIME_MANIFEST_FILE)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Read / write the manifest
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeManifest(raw: unknown, runtime: Runtime): RuntimeManifest {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new IapError(`runtime manifest for "${runtime}" is not a JSON object`)
+  }
+  const obj = raw as Record<string, unknown>
+  const declaredRuntime = typeof obj.runtime === 'string' ? obj.runtime : runtime
+  if (!isRuntime(declaredRuntime)) {
+    throw new IapError(`runtime manifest "runtime" is invalid: "${String(obj.runtime)}"`)
+  }
+  if (declaredRuntime !== runtime) {
+    throw new IapError(
+      `runtime manifest at runtimes/${runtime}/ declares runtime "${declaredRuntime}" — mismatch`,
+    )
+  }
+  let selfConfig: SelfConfigDescriptor | undefined
+  if (typeof obj.selfConfig === 'string' && obj.selfConfig.trim()) {
+    selfConfig = obj.selfConfig
+  } else if (
+    obj.selfConfig &&
+    typeof obj.selfConfig === 'object' &&
+    typeof (obj.selfConfig as { command?: unknown }).command === 'string'
+  ) {
+    const sc = obj.selfConfig as { command: string; args?: unknown }
+    selfConfig = { command: sc.command, args: Array.isArray(sc.args) ? sc.args.map(String) : undefined }
+  }
+  let peers: RuntimePeerDecl[] | undefined
+  if (Array.isArray(obj.peers)) {
+    peers = obj.peers.flatMap(p => {
+      if (!p || typeof p !== 'object') return []
+      const o = p as Record<string, unknown>
+      if (typeof o.personality !== 'string' || !o.personality.trim()) return []
+      return [
+        {
+          personality: o.personality,
+          intelligence: typeof o.intelligence === 'string' ? (o.intelligence as Intelligence) : undefined,
+          description: typeof o.description === 'string' ? o.description : undefined,
+          path: typeof o.path === 'string' ? o.path : undefined,
+          runtimeBin: typeof o.runtimeBin === 'string' ? o.runtimeBin : undefined,
+        },
+      ]
+    })
+  }
+  return { runtime: declaredRuntime, ...(selfConfig ? { selfConfig } : {}), ...(peers ? { peers } : {}) }
+}
+
+/** Read a runtime's manifest (~/.iapeer/runtimes/<runtime>/runtime.json), or null when
+ *  absent (the package is not installed). Throws on a present-but-malformed manifest —
+ *  it is the package's declared contract, a corruption should surface, not silently
+ *  degrade an always-on deploy. */
+export function readRuntimeManifest(runtime: Runtime, options: StorageOptions = {}): RuntimeManifest | null {
+  const path = runtimeManifestPath(runtime, options)
+  if (!existsSync(path)) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (e) {
+    throw new IapError(`runtime manifest ${path} is invalid JSON: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  return normalizeManifest(raw, runtime)
+}
+
+/** Write a runtime's manifest atomically (the helper a package uses at npx-install to
+ *  self-deploy its declaration; also used by tests/foundation registration). */
+export function writeRuntimeManifest(manifest: RuntimeManifest, options: StorageOptions = {}): string {
+  if (!isRuntime(manifest.runtime)) {
+    throw new IapError(`writeRuntimeManifest: invalid runtime "${manifest.runtime}"`)
+  }
+  const path = runtimeManifestPath(manifest.runtime, options)
+  writeFileAtomic(path, `${JSON.stringify(manifest, null, 2)}\n`, 0o644)
+  return path
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-peer self-config hook invocation (the shared contract both modes call)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SelfConfigState =
+  | 'absent' // no manifest / no selfConfig declared → nothing to run (no-op)
+  | 'configured' // the hook ran and exited 0
+  | 'failed' // the hook ran and exited non-zero (or could not be spawned)
+
+export interface SelfConfigResult {
+  state: SelfConfigState
+  detail?: string
+}
+
+export interface SelfConfigPeer {
+  personality: string
+  cwd: string
+  runtime: Runtime
+  intelligence: Intelligence
+}
+
+/**
+ * Invoke a runtime package's PER-PEER self-config hook (the shared contract for both
+ * provision modes). Looks up the runtime's manifest; if it declares `selfConfig`, runs
+ * it with cwd = the peer cwd and the peer context in NAMESPACED env (IAPEER_PEER_* —
+ * NOT the bare PEER_* the identity gate keys on, same lesson as enable's setup). The
+ * package's hook is expected to be IDEMPOTENT ("ensure runtime state for this peer").
+ * No manifest / no hook → `absent` (a no-op — e.g. an agentic runtime, or a runtime
+ * package not installed). A non-zero exit → `failed` (the caller decides fail-closed).
+ */
+export function runtimeSelfConfig(peer: SelfConfigPeer, options: StorageOptions = {}): SelfConfigResult {
+  const env = options.env ?? process.env
+  const manifest = readRuntimeManifest(peer.runtime, { env })
+  const descriptor = manifest?.selfConfig
+  if (!descriptor) return { state: 'absent' }
+
+  const [command, ...preArgs] =
+    typeof descriptor === 'string' ? [descriptor] : [descriptor.command, ...(descriptor.args ?? [])]
+  const hookEnv: NodeJS.ProcessEnv = {
+    ...env,
+    IAPEER_PEER_PERSONALITY: peer.personality,
+    IAPEER_PEER_CWD: peer.cwd,
+    IAPEER_PEER_RUNTIME: peer.runtime,
+    IAPEER_PEER_INTELLIGENCE: peer.intelligence,
+  }
+  const r = spawnSync(command, preArgs, { cwd: peer.cwd, encoding: 'utf8', env: hookEnv as Record<string, string> })
+  if (r.error || (r.status ?? 1) !== 0) {
+    return { state: 'failed', detail: (r.stderr || r.stdout || r.error?.message || `exit ${r.status}`).trim() }
+  }
+  return { state: 'configured' }
+}

package/src/runtime/runtime.test.ts

@@ -0,0 +1,226 @@
+// runtime contract — manifest read/write, the per-peer self-config hook (env
+// passthrough + fail states), and deployRuntime (declared-set provisioning). All under
+// IAPEER_ROOT / IAPEER_LAUNCHAGENTS_DIR temp dirs; IAPEER_TEST_SANDBOX skips the real
+// launchctl, so deploy provisions (folder + registry + plist) without loading a job.
+
+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 { readRuntimeManifest, runtimeSelfConfig, writeRuntimeManifest, type RuntimeManifest } from './index.ts'
+import {
+  deployRuntime,
+  installRuntimePackage,
+  onboardRuntime,
+  resolveRuntimePackage,
+  RUNTIME_PACKAGES,
+} from './deploy.ts'
+import { findPeer, readPeersIndex } from '../registry/index.ts'
+import { launchdPlistPath } from '../launch/index.ts'
+
+const roots: string[] = []
+function mkTmp(): string {
+  const d = mkdtempSync(join(tmpdir(), 'iapeer-rtm-'))
+  roots.push(d)
+  return d
+}
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+function envFor(root: string, path?: string): NodeJS.ProcessEnv {
+  return {
+    IAPEER_ROOT: join(root, 'iapeer'),
+    IAPEER_LAUNCHAGENTS_DIR: join(root, 'LA'),
+    IAPEER_TEST_SANDBOX: '1',
+    HOME: root,
+    ...(path ? { PATH: path } : {}),
+  } as NodeJS.ProcessEnv
+}
+
+/** A stub runtime launcher (so provision's resolveExecutable succeeds) + a stub
+ *  self-config hook that records the per-peer env it was handed. */
+function stubBins(): { dir: string; launcher: string; hook: string; marker: (p: string) => string } {
+  const dir = mkTmp()
+  const launcher = join(dir, 'notifier-runtime')
+  writeFileSync(launcher, '#!/bin/sh\nexec sleep 1\n', { mode: 0o755 })
+  const hook = join(dir, 'self-config.sh')
+  // record IAPEER_PEER_* to a marker file named by personality → proves env passthrough
+  writeFileSync(
+    hook,
+    '#!/bin/sh\nprintf "%s|%s|%s" "$IAPEER_PEER_PERSONALITY" "$IAPEER_PEER_RUNTIME" "$IAPEER_PEER_INTELLIGENCE" > "$IAPEER_ROOT/sc-$IAPEER_PEER_PERSONALITY"\nexit 0\n',
+    { mode: 0o755 },
+  )
+  return { dir, launcher, hook, marker: p => join(dir, p) }
+}
+
+describe('runtime manifest', () => {
+  test('write → read round-trip preserves runtime / selfConfig / peers', () => {
+    const env = envFor(mkTmp())
+    writeRuntimeManifest(
+      { runtime: 'notifier', selfConfig: { command: 'notifier-runtime', args: ['self-config'] }, peers: [{ personality: 'timer', intelligence: 'absent' }] },
+      { env },
+    )
+    const m = readRuntimeManifest('notifier', { env })!
+    expect(m.runtime).toBe('notifier')
+    expect(m.selfConfig).toEqual({ command: 'notifier-runtime', args: ['self-config'] })
+    expect(m.peers?.[0].personality).toBe('timer')
+  })
+
+  test('absent manifest → null; runtime mismatch → throws', () => {
+    const env = envFor(mkTmp())
+    expect(readRuntimeManifest('notifier', { env })).toBeNull()
+    // hand-write a manifest whose runtime field disagrees with its folder
+    const path = join(env.IAPEER_ROOT as string, 'runtimes', 'notifier')
+    writeFileSync(join(mkTmp(), 'ignore'), '') // keep tmp tracking happy
+    rmSync(path, { recursive: true, force: true })
+    writeRuntimeManifest({ runtime: 'notifier' }, { env })
+    // corrupt the on-disk runtime field
+    const file = join(path, 'runtime.json')
+    writeFileSync(file, JSON.stringify({ runtime: 'telegram' }))
+    expect(() => readRuntimeManifest('notifier', { env })).toThrow(/mismatch/)
+  })
+})
+
+describe('runtimeSelfConfig (per-peer hook)', () => {
+  test('absent when no manifest declares a hook', () => {
+    const env = envFor(mkTmp())
+    const r = runtimeSelfConfig({ personality: 'timer', cwd: mkTmp(), runtime: 'notifier', intelligence: 'absent' }, { env })
+    expect(r.state).toBe('absent')
+  })
+
+  test('configured: hook runs with IAPEER_PEER_* env (NOT bare PEER_*)', () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const { hook } = stubBins()
+    writeRuntimeManifest({ runtime: 'notifier', selfConfig: hook }, { env })
+    const cwd = mkTmp()
+    const r = runtimeSelfConfig({ personality: 'timer', cwd, runtime: 'notifier', intelligence: 'absent' }, { env })
+    expect(r.state).toBe('configured')
+    // the hook wrote the per-peer env it received
+    const recorded = readFileSync(join(env.IAPEER_ROOT as string, 'sc-timer'), 'utf8')
+    expect(recorded).toBe('timer|notifier|absent')
+  })
+
+  test('failed: a non-zero hook is reported (caller decides fail-closed)', () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    const dir = mkTmp()
+    const hook = join(dir, 'bad.sh')
+    writeFileSync(hook, '#!/bin/sh\necho boom >&2\nexit 3\n', { mode: 0o755 })
+    writeRuntimeManifest({ runtime: 'notifier', selfConfig: hook }, { env })
+    const r = runtimeSelfConfig({ personality: 'timer', cwd: mkTmp(), runtime: 'notifier', intelligence: 'absent' }, { env })
+    expect(r.state).toBe('failed')
+    expect(r.detail).toContain('boom')
+  })
+})
+
+describe('deployRuntime (declared-set, mode a)', () => {
+  test('provisions the whole declared peer-set (folder + registry + plist + self-config)', async () => {
+    const root = mkTmp()
+    const { dir: bindir, launcher, hook } = stubBins()
+    const env = envFor(root, bindir)
+    writeRuntimeManifest(
+      {
+        runtime: 'notifier',
+        selfConfig: hook,
+        peers: [
+          { personality: 'timer', intelligence: 'absent' },
+          { personality: 'watcher', intelligence: 'absent' },
+        ],
+      },
+      { env },
+    )
+
+    void launcher // resolved by provision via env.PATH (bindir holds notifier-runtime)
+    const r = await deployRuntime({ runtime: 'notifier', env })
+    expect(r.operatorAddOnly).toBe(false)
+    expect(r.peers.map(p => p.personality).sort()).toEqual(['timer', 'watcher'])
+    for (const p of r.peers) {
+      expect(p.selfConfig).toBe('configured')
+      expect(p.bootstrap).toBe('skipped-sandbox') // sandbox: not loaded
+      expect(findPeer(readPeersIndex({ env }), p.personality)).not.toBeNull()
+      expect(existsSync(launchdPlistPath(p.personality, env))).toBe(true)
+    }
+  })
+
+  test('a runtime with no declared peers → operatorAddOnly (telegram = mode b)', async () => {
+    const root = mkTmp()
+    const env = envFor(root)
+    writeRuntimeManifest({ runtime: 'telegram', selfConfig: 'telegram-runtime self-config' }, { env })
+    const r = await deployRuntime({ runtime: 'telegram', env })
+    expect(r.operatorAddOnly).toBe(true)
+    expect(r.peers.length).toBe(0)
+  })
+})
+
+describe('§6 — package registry + npx install + onboardRuntime', () => {
+  test('resolveRuntimePackage: built-in registry, --package override', () => {
+    expect(resolveRuntimePackage('telegram')).toBe(RUNTIME_PACKAGES.telegram)
+    expect(resolveRuntimePackage('notifier')).toBe('@agfpd/notifier-runtime')
+    expect(resolveRuntimePackage('telegram', '@me/fork')).toBe('@me/fork') // override wins
+    expect(resolveRuntimePackage('webhook')).toBeUndefined() // no mapping
+  })
+
+  test('installRuntimePackage: skipped when manifest present (idempotent)', () => {
+    const env = envFor(mkTmp())
+    writeRuntimeManifest({ runtime: 'notifier' }, { env })
+    let called = false
+    const r = installRuntimePackage({ runtime: 'notifier', env, runNpx: () => ((called = true), { ok: true }) })
+    expect(r.state).toBe('skipped')
+    expect(called).toBe(false) // never ran npx — package already installed
+  })
+
+  test('installRuntimePackage: ran (npx invoked) when no manifest', () => {
+    const env = envFor(mkTmp())
+    let gotPkg = ''
+    const r = installRuntimePackage({
+      runtime: 'notifier',
+      env,
+      runNpx: pkg => ((gotPkg = pkg), { ok: true }),
+    })
+    expect(r.state).toBe('ran')
+    expect(gotPkg).toBe('@agfpd/notifier-runtime') // resolved from the registry
+  })
+
+  test('installRuntimePackage: no-package when no mapping + no --package + no manifest', () => {
+    const env = envFor(mkTmp())
+    const r = installRuntimePackage({ runtime: 'webhook', env, runNpx: () => ({ ok: true }) })
+    expect(r.state).toBe('no-package')
+  })
+
+  test('onboardRuntime: npx (self-deploy manifest) → deploy declared set', async () => {
+    const root = mkTmp()
+    const bindir = mkTmp()
+    writeFileSync(join(bindir, 'notifier-runtime'), '#!/bin/sh\nexec sleep 1\n', { mode: 0o755 })
+    const hook = join(bindir, 'sc.sh')
+    writeFileSync(hook, '#!/bin/sh\nexit 0\n', { mode: 0o755 })
+    const env = envFor(root, bindir)
+
+    // simulate the package self-deploying its manifest on npx (bin pre-staged on PATH)
+    const runNpx = (_pkg: string, e: NodeJS.ProcessEnv) => {
+      const m: RuntimeManifest = {
+        runtime: 'notifier',
+        selfConfig: hook,
+        peers: [{ personality: 'sbxt', intelligence: 'absent' }],
+      }
+      writeRuntimeManifest(m, { env: e })
+      return { ok: true }
+    }
+
+    const r = await onboardRuntime({ runtime: 'notifier', env, runNpx })
+    expect(r.install.state).toBe('ran')
+    expect(r.deploy?.peers.map(p => p.personality)).toEqual(['sbxt'])
+    expect(r.deploy?.peers[0].selfConfig).toBe('configured')
+    expect(r.deploy?.peers[0].bootstrap).toBe('skipped-sandbox')
+    expect(findPeer(readPeersIndex({ env }), 'sbxt')).not.toBeNull()
+  })
+
+  test('onboardRuntime: failed npx aborts before deploy (fail-closed)', async () => {
+    const env = envFor(mkTmp())
+    await expect(
+      onboardRuntime({ runtime: 'notifier', env, runNpx: () => ({ ok: false, detail: 'network' }) }),
+    ).rejects.toThrow(/npx install.*failed/)
+    expect(findPeer(readPeersIndex({ env }), 'sbxt')).toBeNull()
+  })
+})