@agfpd/iapeer 0.1.0

package/src/install/index.ts

@@ -0,0 +1,84 @@
+// install — the foundation install-phase (contract Установка §INSTALL). The
+// foundation ships as ONE real binary at a STABLE host-wide path
+// (~/.local/bin/iapeer), built standalone from src via `bun build --compile`, so
+// PROD is DECOUPLED from the mutable src working tree: the daemon/infra launchd
+// plists run the INSTALLED binary, and any edit/git-op in the tree no longer hits
+// prod. Update = atomic overwrite in place (build to .tmp → rename over), with ONE
+// .prev for rollback. NO versions/ catalog + resolver-symlink (that pattern is for
+// multi-version toolchains; the foundation is one-latest — and a stable path keeps
+// macOS TCC rights through updates, which a versioned path would re-prompt).
+
+import { copyFileSync, existsSync, mkdirSync, renameSync, statSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+
+/** The stable host-wide install path of the `iapeer` binary. Standard user-bin (no
+ *  admin, not tied to a node/bun version), ON $PATH. The launchd plists reference
+ *  THIS path, not process.execPath / a src file — that is the decoupling. */
+export function iapeerBinPath(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env.HOME?.trim() || homedir()
+  // IAPEER_BIN_DIR override is for tests/sandbox only (never write a real ~/.local/bin
+  // in a test). Default = ~/.local/bin.
+  const binDir = env.IAPEER_BIN_DIR?.trim() || join(home, '.local', 'bin')
+  return join(binDir, 'iapeer')
+}
+
+export interface InstallResult {
+  binPath: string
+  /** The previous binary preserved for rollback (when one existed). */
+  prevPath?: string
+  /** Bytes of the installed binary. */
+  size?: number
+}
+
+/**
+ * Build the standalone `iapeer` binary from the CLI entrypoint and place it at the
+ * stable path ATOMICALLY: `bun build --compile <entry> → <bin>.tmp`, then rename over
+ * <bin> (atomic on one fs; a running daemon keeps its old inode, new launches take the
+ * new one). An existing binary is preserved as <bin>.prev first. Throws on build
+ * failure (never leaves a half-written bin). The build runs from the SRC TREE (the
+ * dev/npx bootstrap); the resulting binary is self-contained (no tree dependency).
+ */
+/** Fail-closed sandbox guard (audit #25, symmetric to the registry's): under
+ *  IAPEER_TEST_SANDBOX=1 refuse to build over the REAL ~/.local/bin/iapeer (the live
+ *  prod binary). A test/sandbox MUST set IAPEER_BIN_DIR to an isolated path. */
+function assertInstallSandboxIsolated(binPath: string, env: NodeJS.ProcessEnv): void {
+  if (env.IAPEER_TEST_SANDBOX !== '1') return
+  const realBin = join(env.HOME?.trim() || homedir(), '.local', 'bin', 'iapeer')
+  if (binPath === realBin) {
+    throw new Error(
+      `refusing to overwrite the REAL prod binary (${realBin}) under IAPEER_TEST_SANDBOX=1 — ` +
+        'set IAPEER_BIN_DIR to an isolated path',
+    )
+  }
+}
+
+export function installIapeer(cliEntrypoint: string, env: NodeJS.ProcessEnv = process.env): InstallResult {
+  const binPath = iapeerBinPath(env)
+  assertInstallSandboxIsolated(binPath, env)
+  mkdirSync(join(binPath, '..'), { recursive: true })
+  const tmp = `${binPath}.tmp`
+  const build = spawnSync('bun', ['build', '--compile', cliEntrypoint, '--outfile', tmp], {
+    encoding: 'utf8',
+  })
+  if (build.status !== 0 || !existsSync(tmp)) {
+    throw new Error(`iapeer build failed: ${(build.stderr ?? '').trim() || `exit ${build.status}`}`)
+  }
+  let prevPath: string | undefined
+  if (existsSync(binPath)) {
+    prevPath = `${binPath}.prev`
+    // COPY (not move) the current binary to .prev so binPath is NEVER absent (audit
+    // #7): a move-then-move leaves no binary in the window between the two renames —
+    // if the second throws, the prod daemon + infra fleet crash-loop with no bin.
+    copyFileSync(binPath, prevPath)
+  }
+  renameSync(tmp, binPath) // atomic replace in place (POSIX rename over an existing file)
+  let size: number | undefined
+  try {
+    size = statSync(binPath).size
+  } catch {
+    /* best-effort */
+  }
+  return { binPath, prevPath, size }
+}

package/src/install/install.test.ts

@@ -0,0 +1,31 @@
+// install — the stable binary path + (lightly) the build. iapeerBinPath is the
+// decoupling anchor: the launchd plists reference it, not process.execPath / a src
+// file. The full `bun build --compile` is exercised LIVE (it writes a ~60M binary —
+// too heavy for a unit test); here we pin the path resolution.
+
+import { describe, expect, test } from 'bun:test'
+import { join } from 'path'
+import { iapeerBinPath, installIapeer } from './index.ts'
+
+describe('iapeerBinPath', () => {
+  test('default = <home>/.local/bin/iapeer (stable host-wide path, on $PATH)', () => {
+    expect(iapeerBinPath({ HOME: '/Users/x' } as NodeJS.ProcessEnv)).toBe('/Users/x/.local/bin/iapeer')
+  })
+  test('IAPEER_BIN_DIR override (tests/sandbox — never a real ~/.local/bin)', () => {
+    expect(iapeerBinPath({ HOME: '/Users/x', IAPEER_BIN_DIR: '/tmp/sbx/bin' } as NodeJS.ProcessEnv)).toBe(
+      join('/tmp/sbx/bin', 'iapeer'),
+    )
+  })
+})
+
+// Audit #25 — fail-closed sandbox guard (symmetric to the registry's). installIapeer
+// overwrites the live prod binary ~/.local/bin/iapeer; a sandbox/test that forgets
+// IAPEER_BIN_DIR must be REFUSED, never clobber prod. The guard fires BEFORE the build,
+// so no `bun build --compile` runs here.
+describe('installIapeer fail-closed sandbox guard', () => {
+  test('THROWS under IAPEER_TEST_SANDBOX=1 when binPath falls through to the REAL ~/.local/bin/iapeer', () => {
+    const env = { IAPEER_TEST_SANDBOX: '1', HOME: '/Users/fake-home' } as NodeJS.ProcessEnv
+    expect(iapeerBinPath(env)).toBe('/Users/fake-home/.local/bin/iapeer')
+    expect(() => installIapeer('/x/entry.ts', env)).toThrow(/refusing to overwrite the REAL prod binary/)
+  })
+})

package/src/launch/adapters/claude.ts

@@ -0,0 +1,250 @@
+// claude RuntimeAdapter — the "HOW to launch / observe ONE claude session" half
+// of the launch contract (src/launch/types.ts). Runtime-agnostic launch.launch
+// drives it: argv → boot dialogs → ready marker → activity-proxy ready-gate →
+// permission autopilot → resume preflight. Consolidated from three frozen
+// sources, with the exact slug fix that already lives in lifecycle:
+//
+//   - Persistent-Peer/bin/claude-start.sh — argv (292-318: --dangerously-skip-
+//     permissions, --disallowedTools AskUserQuestion, --system-prompt-file), the
+//     ready-marker (`❯` + dev-channels-gone, 357-371) and the boot dialog answers
+//     (the dev-channels "I am using this for local development" Enter, 335-345).
+//   - Spawned-Peer/src/spawner.ts — buildClaudeArgv (759-787: same flags +
+//     optional --resume <uuid>) and findLatestTranscript (522-538: resume uuid).
+//   - IAPeer/src/lifecycle/index.ts — claudeInputReady / claudeBootDialog /
+//     newestClaudeTranscriptMtime / findLatestClaudeTranscript. This is the
+//     canonical port: the slug is realpath(cwd).replace(/[^a-zA-Z0-9]/g,'-') —
+//     claude encodes EVERY non-alphanumeric char (not just '/'); the old
+//     Spawned-Peer replace(/\//g,'-') silently broke on a cwd carrying '_' or '.'
+//     (a mkdtemp temp dir). REUSE this exact logic — do not reintroduce the bug.
+//
+// NO currency on this path: no marketplace check, no plugin install/update — that
+// is install-time (blueprint §0.6 fast-wake), not session bring-up.
+
+import { homedir } from 'os'
+import { join } from 'path'
+import { readdirSync, realpathSync, statSync } from 'fs'
+import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Boot dialog + ready markers (lifecycle claudeBootDialog / claudeInputReady)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The known claude startup dialogs whose default-highlighted option is the
+ * proceed path, so a single Enter clears each:
+ *   - 'trust this folder'                      — first-run folder-trust modal.
+ *   - 'Allow external CLAUDE.md file imports?' — external-import consent.
+ *   - 'I am using this for local development'   — dev-channels accept
+ *     (claude-start.sh:337), shown when PEER_START_ARGS carries
+ *     --dangerously-load-development-channels.
+ *   - 'Resume from summary' / 'Resuming the full session' — the --resume picker.
+ * Same set, same order as lifecycle.claudeBootDialog (index.ts:281-289).
+ */
+const CLAUDE_BOOT_DIALOG_MARKERS = [
+  'trust this folder',
+  'Allow external CLAUDE.md file imports?',
+  'I am using this for local development',
+  'Resume from summary',
+  'Resuming the full session',
+] as const
+
+function anyBootDialog(pane: string): boolean {
+  return CLAUDE_BOOT_DIALOG_MARKERS.some(m => pane.includes(m))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transcript activity proxy + resume uuid (lifecycle port, claude slug fix)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Claude's project-dir slug: realpath(cwd) with EVERY non-alphanumeric char
+ * replaced by '-' (index.ts:232-245). NOT just '/' — a segment with '_' or '.'
+ * is slugged too; the Spawned-Peer canon's replace(/\//g,'-') silently worked
+ * only because the live fleet's ~/Peers/<name> paths have none, then broke on a
+ * mkdtemp temp cwd. realpath first so a symlinked cwd maps to the dir claude
+ * actually wrote (a stale path falls through to the original string).
+ */
+function transcriptSlug(workDir: string): string {
+  let phys = workDir
+  try {
+    phys = realpathSync(workDir)
+  } catch {
+    /* stale path — slug the original */
+  }
+  return phys.replace(/[^a-zA-Z0-9]/g, '-')
+}
+
+function transcriptDir(workDir: string): string {
+  return join(homedir(), '.claude', 'projects', transcriptSlug(workDir))
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// claudeAdapter
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const claudeAdapter: RuntimeAdapter = {
+  runtime: 'claude',
+  kind: 'tui',
+  usesDoctrine: true,
+
+  /**
+   * Delivery markers for submitIntoTui (07.06 refactor — moved out of transport's
+   * PROMPT_GLYPHS union into the adapter; docs/Рантайм claude "Доставка"):
+   *   - promptGlyphs ['❯'] — the same U+276F input-prompt glyph as isInputReady;
+   *     submitIntoTui finds the prompt row by it. claude-only (codex uses '›'), so
+   *     a stray codex glyph in a claude pane no longer false-matches.
+   *   - pastePatterns '[Pasted text' / '[Image #' — claude's bracketed-paste land
+   *     confirmations (claude-start.sh / transport.ts:191), checked alongside the
+   *     envelope tail-marker.
+   */
+  deliveryMarkers: {
+    promptGlyphs: ['❯'],
+    pastePatterns: [/\[Pasted text/, /\[Image #/],
+  },
+
+  /**
+   * argv = claudeBin + headless flags + (system-prompt-file when set) +
+   * (--resume <ref> when resumeRef set) + extraArgs.
+   *
+   *   - '--dangerously-skip-permissions'  claude-start.sh:318, spawner.ts:776 —
+   *     headless peer has no interactive owner to grant per-tool permission.
+   *   - '--disallowedTools','AskUserQuestion'  claude-start.sh:313/316,
+   *     spawner.ts:777 — AskUserQuestion would render in a TUI no headless peer
+   *     owner watches; the question goes "into the void". Default is the literal
+   *     'AskUserQuestion'; the per-peer override (PEER_DISALLOWED_TOOLS empty =
+   *     allow all) is install-time launch.env, not this path.
+   *   - '--system-prompt-file', spec.systemPromptFile  claude-start.sh:318 —
+   *     ONLY when set (a tui runtime that usesDoctrine composes one). Swaps the
+   *     CC coding baseline for the merged peer doctrine; plugin/MCP/CLAUDE.md
+   *     layers stay intact (claude-start.sh:293-303).
+   *   - '--resume', spec.resumeRef  spawner.ts:779-781 — ONLY when the caller
+   *     pre-resolved a uuid (resolveResume); never a silent fresh fallback.
+   *   - ...extraArgs  PEER_START_ARGS passthrough (LaunchSpec.extraArgs).
+   * NO currency — no marketplace/install/update on this path.
+   */
+  buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    return [
+      cfg.claudeBin,
+      '--dangerously-skip-permissions',
+      '--disallowedTools',
+      'AskUserQuestion',
+      ...(spec.systemPromptFile ? ['--system-prompt-file', spec.systemPromptFile] : []),
+      ...(spec.resumeRef ? ['--resume', spec.resumeRef] : []),
+      ...(spec.extraArgs ?? []),
+    ]
+  },
+
+  /**
+   * A visible startup dialog → ['Enter'] to clear it (its default-highlighted
+   * option is the proceed path), else null. Same marker set as
+   * lifecycle.claudeBootDialog; claude-start.sh:341 (dev-channels) and the
+   * folder-trust/import/resume modals all accept a bare Enter.
+   */
+  bootDialogKeys(pane: string): string[] | null {
+    return anyBootDialog(pane) ? ['Enter'] : null
+  },
+
+  /**
+   * Ready for the first message iff the input surface is rendered AND no startup
+   * dialog is still up (lifecycle.claudeInputReady, index.ts:272-279;
+   * claude-start.sh:365-366):
+   *   - '❯' (U+276F) — the TUI input-prompt glyph, present only at the ready
+   *     input row, never in the splash art (claude-start.sh:357-360).
+   *   - 'bypass permissions on' — the banner --dangerously-skip-permissions
+   *     emits once booted past the splash.
+   *   - none of the boot dialogs present (a dialog row can also carry '❯').
+   */
+  isInputReady(pane: string): boolean {
+    if (anyBootDialog(pane)) return false
+    return pane.includes('❯') && pane.includes('bypass permissions on')
+  },
+
+  /**
+   * Newest ~/.claude/projects/<slug>/*.jsonl mtimeMs, or null when the dir is
+   * absent / empty (index.ts:247-266). The ready-gate waits for this to strictly
+   * advance past baseline (model produced its first turn); idle accounting reads
+   * the same proxy. slug = transcriptSlug(cwd) (the claude non-alnum encoding).
+   */
+  newestActivityMtime(cwd: string): number | null {
+    let entries: string[]
+    try {
+      entries = readdirSync(transcriptDir(cwd))
+    } catch {
+      return null
+    }
+    let newest = 0
+    for (const name of entries) {
+      if (!name.endsWith('.jsonl')) continue
+      try {
+        const mt = statSync(join(transcriptDir(cwd), name)).mtimeMs
+        if (mt > newest) newest = mt
+      } catch {
+        /* race — entry vanished between readdir and stat */
+      }
+    }
+    return newest > 0 ? newest : null
+  },
+
+  /**
+   * A claude tool-permission/approval modal is open iff the pane shows
+   * 'Do you want to proceed?' (Spawned-Peer dialogs.ts:60-61,
+   * approve-watch.sh:78). Defensive only: a --dangerously-skip-permissions peer
+   * does not normally reach it, but a stray approval (e.g. a connector) must not
+   * stall a headless session.
+   */
+  permissionDialogActive(pane: string): boolean {
+    return pane.includes('Do you want to proceed?')
+  },
+
+  /**
+   * Affirm a claude approval with ['Enter']: option 1 ('Yes') is the
+   * default-highlighted choice, so a bare Enter accepts (approve-watch.sh:22-25,
+   * Spawned-Peer watcher.ts:298).
+   */
+  permissionDialogKeys(): string[] {
+    return ['Enter']
+  },
+
+  /**
+   * Resume preflight (fail-loud — never a silent fresh fallback): resolve the
+   * newest transcript uuid for cwd via the claude-slug dir scan (lifecycle.
+   * findLatestClaudeTranscript / spawner.findLatestTranscript). {ok:true, ref}
+   * when one exists, else {ok:false, reason:'no transcript to resume'} so the
+   * caller surfaces a real failure instead of starting a context-less session.
+   */
+  resolveResume(cwd: string): { ok: boolean; ref?: string; reason?: string } {
+    let entries: string[]
+    try {
+      entries = readdirSync(transcriptDir(cwd))
+    } catch {
+      return { ok: false, reason: 'no transcript to resume' }
+    }
+    let best: { name: string; mt: number } | null = null
+    for (const name of entries) {
+      if (!name.endsWith('.jsonl')) continue
+      try {
+        const mt = statSync(join(transcriptDir(cwd), name)).mtimeMs
+        if (!best || mt > best.mt) best = { name, mt }
+      } catch {
+        /* race */
+      }
+    }
+    if (!best) return { ok: false, reason: 'no transcript to resume' }
+    return { ok: true, ref: best.name.replace(/\.jsonl$/, '') }
+  },
+
+  /**
+   * Map a control command to claude's in-session mechanism (Ф-E, docs/Control-команды
+   * + docs/TUI-взаимодействие):
+   *   - interrupt → ['Escape'] (claude interrupts the current turn with ONE Escape;
+   *     the session + context stay intact — distinct from the `stop` verb which halts
+   *     the session). The "кнопка заткнуть бредящего" without losing context.
+   *   - compact → type '/compact' then Enter (claude's context-compaction slash).
+   *   - anything else → null (unsupported → explicit refusal upstream).
+   */
+  executeControl(command: ControlCommand): ControlPlan | null {
+    if (command.name === 'interrupt') return { sequence: [['Escape']] }
+    if (command.name === 'compact') return { sequence: [['-l', '/compact'], ['Enter']], stepDelayMs: 300 }
+    return null
+  },
+}