@agfpd/iapeer 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Foundation core for the IAPeer multi-agent ecosystem: identity, registry, storage, codec.",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -19,6 +19,8 @@ import {
   type Intelligence,
   type Runtime,
 } from '../core/constants.ts'
+import { IAPEER_VERSION } from '../core/version.ts'
+import { updateIapeer } from '../update/index.ts'
 import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/socket.ts'
 import { ensureGlobalIapScaffold } from '../storage/index.ts'
 import { findPeer, readPeersIndex, removePeer, type PeerRecord } from '../registry/index.ts'
@@ -346,6 +348,8 @@ export function parseArgs(argv: string[]): { positionals: string[]; flags: Recor
 
 const USAGE = `usage: iapeer <verb> [args]
   install                                                        build binary + global scaffold + daemon plist (one bootstrap)
+  update [--force]                                               pull the latest @agfpd/iapeer from npm (cloud) + restart the daemon
+  version | --version | -v                                       print the installed binary's version
   daemon [--install-plist]                                       run the host-wide HTTP-MCP router (launchd-held)
   onboard [--dry-run] [--infra <csv>]                            register the agfpd marketplace (+ npx-install & deploy infra runtimes)
   install-runtime <runtime> [--package pkg] [--npx]              npx-install a runtime package + deploy its declared peer-set
@@ -549,6 +553,38 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
         out(`delivered to ${r.delivered_to.personality} (${r.delivered_to.runtime})\n`)
         return 0
       }
+      case 'version':
+      case '--version':
+      case '-v': {
+        out(`${IAPEER_VERSION}\n`)
+        return 0
+      }
+      case 'update': {
+        // The single deploy path: pull the latest published foundation from npm and
+        // restart the daemon onto it (cloud-only — never a working-tree build). Foundation
+        // ONLY; the plist and other host packages are untouched. --force reinstalls even
+        // when already at latest. (Run from the installed binary; the first-ever install is
+        // `npx @agfpd/iapeer`.)
+        const r = updateIapeer({ env, force: flags.force === true })
+        if (r.status === 'failed') {
+          errOut(`update failed: ${r.reason}\n`)
+          return 1
+        }
+        if (r.status === 'already-latest') {
+          out(`already at the latest version (${r.from})\n`)
+          return 0
+        }
+        const daemonNote =
+          r.daemon === 'restarted'
+            ? 'daemon restarted onto the new binary'
+            : r.daemon === 'not-loaded'
+              ? 'daemon not loaded — new binary will be used on next start'
+              : r.daemon === 'failed'
+                ? `WARNING — ${r.reason}`
+                : String(r.daemon)
+        out(`updated ${r.from} → ${r.to}; ${daemonNote}\n`)
+        return r.daemon === 'failed' ? 1 : 0
+      }
       case 'install': {
         // UNIFIED foundation install (contract Установка §1 — "один npx ставит
         // фундамент"): ONE command does all three install-phase steps that used to be

package/src/core/index.ts

@@ -1,3 +1,4 @@
 export * from './constants.ts'
 export * from './errors.ts'
 export * from './socket.ts'
+export * from './version.ts'

package/src/core/version.ts

@@ -0,0 +1,10 @@
+// The installed binary's own version — BAKED at build time. `bun build --compile`
+// inlines this JSON import, so the standalone ~/.local/bin/iapeer reports its
+// version with NO package.json present at runtime. `iapeer update` compares this
+// against `npm view @agfpd/iapeer version` to decide whether a pull is needed.
+//
+// Single source of truth: package.json (bumped by `npm version` in the release
+// flow), so the binary's version and the published npm version never drift.
+import pkg from '../../package.json'
+
+export const IAPEER_VERSION: string = (pkg as { version: string }).version

package/src/index.ts

@@ -21,6 +21,8 @@ export * from './provision/index.ts'
 export * from './init/index.ts'
 // Install — the foundation install-phase (stable ~/.local/bin/iapeer, decoupled from src).
 export * from './install/index.ts'
+// Update — the cloud-only deploy path (`iapeer update`: npm latest → rebuild → restart).
+export * from './update/index.ts'
 // Onboard — the host-phase (idempotent marketplace registration in claude + codex).
 export * from './onboard/index.ts'
 export { composeSystemPrompt, gatherPromptInput } from './launch/composeSystemPrompt.ts'

package/src/launch/launchd.ts

@@ -19,6 +19,7 @@ import { join } from 'path'
 import { spawnSync } from 'child_process'
 import { iapeerBinPath } from '../install/index.ts'
 import {
+  DAEMON_PLIST_LABEL,
   IAPEER_DIR,
   INFRA_RUNTIME_BIN_ENV,
   INFRA_RUNTIME_DEFAULT_BIN,
@@ -214,6 +215,37 @@ function isLaunchdLoaded(label: string, uid: string): boolean {
   return spawnSync('launchctl', ['print', `gui/${uid}/${label}`], { stdio: 'ignore' }).status === 0
 }
 
+export type DaemonRestartState =
+  | 'restarted' // kickstart -k succeeded → the daemon is now on the freshly-installed binary
+  | 'not-loaded' // com.agfpd.iapeer is not in the gui domain → nothing to restart (new binary
+  //                will be used whenever it IS next started; nothing to do here)
+  | 'skipped-sandbox' // IAPEER_TEST_SANDBOX=1 → never touch the real launchd
+  | 'failed' // launchctl kickstart exited non-zero
+
+export interface DaemonRestartResult {
+  state: DaemonRestartState
+  detail?: string
+}
+
+/**
+ * Restart the foundation daemon (`com.agfpd.iapeer`) onto the binary currently on
+ * disk — `launchctl kickstart -k gui/<uid>/com.agfpd.iapeer`. This is the "activate
+ * the freshly-installed binary" step of `iapeer update`: a compiled daemon holds its
+ * old code in memory until restarted, and `-k` SIGKILLs + relaunches it (KeepAlive
+ * brings it right back). Only restarts when the service is actually loaded — a
+ * not-loaded daemon needs no restart (the new binary is taken on its next start).
+ * Never touches the plist (the launch path is version-stable). Sandbox-safe.
+ */
+export function kickstartDaemon(env: NodeJS.ProcessEnv = process.env): DaemonRestartResult {
+  if (env.IAPEER_TEST_SANDBOX === '1') return { state: 'skipped-sandbox' }
+  const uid = currentUid()
+  if (!isLaunchdLoaded(DAEMON_PLIST_LABEL, uid)) return { state: 'not-loaded' }
+  const r = spawnSync('launchctl', ['kickstart', '-k', `gui/${uid}/${DAEMON_PLIST_LABEL}`], { encoding: 'utf8' })
+  return r.status === 0
+    ? { state: 'restarted' }
+    : { state: 'failed', detail: (r.stderr ?? '').trim() || `launchctl kickstart exit ${r.status}` }
+}
+
 /**
  * AUTO-bootstrap a freshly-provisioned foundation plist into the gui domain
  * (`launchctl bootstrap gui/<uid> <plist>`) — the "load it now, don't write-and-wait

package/src/update/index.ts

@@ -0,0 +1,114 @@
+// `iapeer update` — the SINGLE deploy path: pull the latest published foundation
+// from npm (the cloud) and restart the daemon onto it. There is deliberately NO
+// "deploy from a working tree" — every host, including the dev host, activates a
+// release the same way: `npm run release` (publish) → `iapeer update` (pull + restart).
+//
+// Flow:
+//   1. latest = `npm view @agfpd/iapeer version`           (the cloud's truth)
+//   2. installed == latest && !--force → "already latest"  (no needless rebuild/restart)
+//   3. `npx @agfpd/iapeer@<latest> install`                (fetch + rebuild ~/.local/bin/iapeer
+//      atomically; the COMPILED binary can't rebuild itself from source, so we shell to
+//      npx, which runs the freshly-fetched package's own install — same path consumers use)
+//   4. kickstart com.agfpd.iapeer IF loaded                (activate the new binary)
+//
+// Scope: the foundation ONLY (the @agfpd/iapeer binary + its daemon). It never
+// touches the plist (version-stable launch path) and never touches other packages
+// on the host (telegram-runtime / notifier-runtime / MergeMind / the peer fleet) —
+// each of those has its own version and its own update.
+//
+// updateIapeer takes its three side-effects as INJECTED deps so the version-gate is
+// unit-testable with no network and no launchctl; the defaults are the real impls.
+
+import { spawnSync } from 'child_process'
+import { IapError } from '../core/errors.ts'
+import { IAPEER_VERSION } from '../core/version.ts'
+import { kickstartDaemon, type DaemonRestartResult } from '../launch/launchd.ts'
+
+/** The npm package the foundation publishes / updates from. */
+export const IAPEER_PACKAGE = '@agfpd/iapeer'
+
+export interface UpdateDeps {
+  env?: NodeJS.ProcessEnv
+  /** Reinstall + restart even when already at the latest version. */
+  force?: boolean
+  /** The currently-installed version (default: this binary's baked IAPEER_VERSION). */
+  currentVersion?: string
+  /** Resolve the latest published version (default: `npm view`). Returns null on
+   *  any failure (offline / registry error / non-semver) — update then fails loud. */
+  fetchLatest?: (env: NodeJS.ProcessEnv) => string | null
+  /** Pull + rebuild the binary for `version` (default: `npx @agfpd/iapeer@<v> install`).
+   *  Returns true on success. */
+  runInstall?: (version: string, env: NodeJS.ProcessEnv) => boolean
+  /** Restart the daemon onto the new binary (default: kickstartDaemon). */
+  restartDaemon?: (env: NodeJS.ProcessEnv) => DaemonRestartResult
+}
+
+export interface UpdateResult {
+  status: 'updated' | 'already-latest' | 'failed'
+  /** Version before the update (the running binary). */
+  from: string
+  /** Latest published version resolved from npm (undefined if it couldn't be resolved). */
+  latest?: string
+  /** Version installed by this run (set only on status 'updated'). */
+  to?: string
+  /** What happened to the live daemon (only on 'updated'). */
+  daemon?: DaemonRestartResult['state']
+  /** Human reason on 'failed' / extra detail on a daemon restart hiccup. */
+  reason?: string
+}
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/
+
+/** Default latest-resolver: `npm view @agfpd/iapeer version`. */
+function defaultFetchLatest(env: NodeJS.ProcessEnv): string | null {
+  const r = spawnSync('npm', ['view', IAPEER_PACKAGE, 'version'], { encoding: 'utf8', env })
+  if (r.status !== 0) return null
+  const v = (r.stdout ?? '').trim()
+  return SEMVER_RE.test(v) ? v : null
+}
+
+/** Default installer: `npx -y @agfpd/iapeer@<version> install` (pull from cloud + rebuild). */
+function defaultRunInstall(version: string, env: NodeJS.ProcessEnv): boolean {
+  if (env.IAPEER_TEST_SANDBOX === '1') {
+    // A real npx install rebuilds the prod ~/.local/bin/iapeer — never under a test.
+    throw new IapError('refusing a real `npx install` under IAPEER_TEST_SANDBOX=1 — inject runInstall in tests')
+  }
+  const r = spawnSync('npx', ['-y', `${IAPEER_PACKAGE}@${version}`, 'install'], { stdio: 'inherit', env })
+  return r.status === 0
+}
+
+/**
+ * Update the foundation to the latest published version (cloud-only) and restart
+ * the daemon onto it. Idempotent + version-gated: a no-op "already-latest" when the
+ * installed version equals the published one (unless `force`). Pure-ish — the three
+ * effects are injected, so this is fully unit-testable.
+ */
+export function updateIapeer(deps: UpdateDeps = {}): UpdateResult {
+  const env = deps.env ?? process.env
+  const from = deps.currentVersion ?? IAPEER_VERSION
+  const fetchLatest = deps.fetchLatest ?? defaultFetchLatest
+
+  const latest = fetchLatest(env)
+  if (!latest) {
+    return { status: 'failed', from, reason: `could not resolve the latest ${IAPEER_PACKAGE} version from npm (offline / registry error)` }
+  }
+  if (latest === from && !deps.force) {
+    return { status: 'already-latest', from, latest }
+  }
+
+  const runInstall = deps.runInstall ?? defaultRunInstall
+  if (!runInstall(latest, env)) {
+    return { status: 'failed', from, latest, reason: `\`npx ${IAPEER_PACKAGE}@${latest} install\` failed` }
+  }
+
+  const restart = deps.restartDaemon ?? kickstartDaemon
+  const d = restart(env)
+  return {
+    status: 'updated',
+    from,
+    to: latest,
+    latest,
+    daemon: d.state,
+    reason: d.state === 'failed' ? `binary updated but daemon restart failed: ${d.detail ?? ''}`.trim() : undefined,
+  }
+}

package/src/update/update.test.ts

@@ -0,0 +1,123 @@
+// updateIapeer — the version-gated, cloud-only deploy. The three side-effects
+// (resolve latest / install / restart) are injected, so the gate logic is tested
+// with NO network and NO launchctl. The sandbox guard on the REAL installer is
+// exercised too (a test must never npx-install over the prod binary).
+
+import { describe, expect, test } from 'bun:test'
+import { IAPEER_VERSION, updateIapeer } from '../index.ts'
+import type { DaemonRestartResult } from '../launch/launchd.ts'
+
+const restarted = (): DaemonRestartResult => ({ state: 'restarted' })
+
+/** A deps bundle with call-tracking spies. */
+function harness(opts: {
+  current: string
+  latest: string | null
+  installOk?: boolean
+  restart?: DaemonRestartResult
+  force?: boolean
+}) {
+  const calls = { install: [] as string[], restart: 0 }
+  const result = updateIapeer({
+    env: { IAPEER_TEST_SANDBOX: '1' },
+    force: opts.force,
+    currentVersion: opts.current,
+    fetchLatest: () => opts.latest,
+    runInstall: v => {
+      calls.install.push(v)
+      return opts.installOk ?? true
+    },
+    restartDaemon: () => {
+      calls.restart++
+      return opts.restart ?? restarted()
+    },
+  })
+  return { result, calls }
+}
+
+describe('updateIapeer — version gate', () => {
+  test('already at latest → no install, no restart', () => {
+    const { result, calls } = harness({ current: '0.2.2', latest: '0.2.2' })
+    expect(result.status).toBe('already-latest')
+    expect(result.from).toBe('0.2.2')
+    expect(result.latest).toBe('0.2.2')
+    expect(calls.install).toEqual([])
+    expect(calls.restart).toBe(0)
+  })
+
+  test('--force reinstalls + restarts even when already latest', () => {
+    const { result, calls } = harness({ current: '0.2.2', latest: '0.2.2', force: true })
+    expect(result.status).toBe('updated')
+    expect(result.to).toBe('0.2.2')
+    expect(calls.install).toEqual(['0.2.2'])
+    expect(calls.restart).toBe(1)
+  })
+
+  test('newer published version → installs THAT version + restarts', () => {
+    const { result, calls } = harness({ current: '0.2.2', latest: '0.3.0' })
+    expect(result.status).toBe('updated')
+    expect(result.from).toBe('0.2.2')
+    expect(result.to).toBe('0.3.0')
+    expect(result.daemon).toBe('restarted')
+    expect(calls.install).toEqual(['0.3.0']) // installs latest, not current
+    expect(calls.restart).toBe(1)
+  })
+})
+
+describe('updateIapeer — failure paths', () => {
+  test('latest unresolved (offline / registry error) → failed, no install', () => {
+    const { result, calls } = harness({ current: '0.2.2', latest: null })
+    expect(result.status).toBe('failed')
+    expect(result.reason).toMatch(/latest.*version.*npm|offline|registry/i)
+    expect(calls.install).toEqual([])
+    expect(calls.restart).toBe(0)
+  })
+
+  test('install fails → failed, daemon NOT restarted', () => {
+    const { result, calls } = harness({ current: '0.2.2', latest: '0.3.0', installOk: false })
+    expect(result.status).toBe('failed')
+    expect(result.latest).toBe('0.3.0')
+    expect(result.reason).toMatch(/install.*failed/i)
+    expect(calls.restart).toBe(0)
+  })
+
+  test('daemon not loaded → updated, daemon=not-loaded (no error)', () => {
+    const { result } = harness({ current: '0.2.2', latest: '0.3.0', restart: { state: 'not-loaded' } })
+    expect(result.status).toBe('updated')
+    expect(result.daemon).toBe('not-loaded')
+    expect(result.reason).toBeUndefined()
+  })
+
+  test('binary updated but restart failed → updated with a warning reason', () => {
+    const { result } = harness({
+      current: '0.2.2',
+      latest: '0.3.0',
+      restart: { state: 'failed', detail: 'kickstart exit 1' },
+    })
+    expect(result.status).toBe('updated')
+    expect(result.daemon).toBe('failed')
+    expect(result.reason).toMatch(/restart failed.*kickstart exit 1/i)
+  })
+})
+
+describe('updateIapeer — real-installer sandbox guard', () => {
+  test('default runInstall refuses a real npx install under IAPEER_TEST_SANDBOX', () => {
+    // fetchLatest injected (newer) so the gate proceeds to the DEFAULT installer,
+    // which must refuse rather than npx-install over the prod ~/.local/bin/iapeer.
+    expect(() =>
+      updateIapeer({
+        env: { IAPEER_TEST_SANDBOX: '1' },
+        currentVersion: '0.2.2',
+        fetchLatest: () => '0.3.0',
+        // runInstall NOT injected → exercises the real defaultRunInstall guard.
+        restartDaemon: restarted,
+      }),
+    ).toThrow(/IAPEER_TEST_SANDBOX/)
+  })
+})
+
+describe('IAPEER_VERSION', () => {
+  test('is a baked semver string', () => {
+    expect(IAPEER_VERSION).toMatch(/^\d+\.\d+\.\d+/)
+  })
+})

package/tsconfig.json

@@ -9,6 +9,7 @@
     "strict": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
+    "resolveJsonModule": true,
     "forceConsistentCasingInFileNames": true,
     "types": ["bun", "node"],
     "lib": ["ESNext"]