spexcode 0.4.1 → 0.4.3

package/spec-cli/src/pi-harness.ts

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { shimRuntimeSource } from './shim-runtime.js'
+
+// @@@ pi-harness helpers - the pi-ONLY machinery behind harness.ts's piHarness adapter: the generated
+// extension source (pi's shim is a TypeScript extension, not a hooks JSON — pi has no external hook binding;
+// its lifecycle surface IS the extension API) and the trust writer (pi's project-trust store,
+// ~/.pi/agent/trust.json). Kept out of harness.ts so the adapter table stays scannable; imports NOTHING from
+// harness.ts at runtime (no cycle — harness.ts imports us).
+
+// ---------------------------------------------------------------------------------------------------------
+// the pi shim = a generated extension at .pi/extensions/spexcode.ts (pi runs .ts extensions natively). It is
+// a THIN HOST over the shared shim runtime ([[shim-runtime]], embedded verbatim): this generator declares
+// only pi's event-name mapping and its ExtensionAPI bindings —
+//   session_start → SessionStart · input → UserPromptSubmit · tool_call → PreToolUse (blockable) ·
+//   tool_result → PostToolUse · agent_end + agent_settled → Stop (dual binding, one shared bit)
+// — while the payload synthesis, the block-verdict parse (exit 2 + stdout decision:block JSON), and the
+// rendezvous server all come from the runtime. pi's two host-specific verdict consumers: a tool_call block
+// returns pi's typed { block: true, reason }; a Stop block has no blocking return, so Stop rides the
+// runtime's dispatchStop on a DUAL binding — agent_end (awaited in the run loop: a queued teach drains as
+// the same prompt's continuation, never an orphan) plus agent_settled (fires once per prompt after every
+// drain: the terminal backstop whose flagged dispatch guarantees the gate's escape runs before settlement
+// completes) — with stop_hook_active synthesized across both and the gate's reason SENT BACK IN as a user
+// message; a no-longer-injectable host is reported loud — never silently dropped (a dropped rejection is
+// a session stuck `active` forever).
+// The rendezvous inject is pi.sendUserMessage({deliverAs: steer}), always able → no canInject gate.
+export function piExtensionSource(dispatch: string, spex: string): string {
+  return `// generated by spexcode materialize — DO NOT EDIT (regenerated per clone; identity: dispatch.sh)
+// SpexCode's pi shim: forwards pi lifecycle events to dispatch.sh as Claude-shaped hook payloads, and serves
+// this session's rendezvous socket for prompt delivery + liveness.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+${shimRuntimeSource('pi', dispatch, spex)}
+
+// pi tool names → the Claude tool vocabulary harness.sh parses (unknown names pass through untouched).
+const TOOL: Record<string, string> = { read: "Read", edit: "Edit", write: "Write", bash: "Bash" }
+
+export default function spexcode(pi: ExtensionAPI) {
+  let sessionId = process.env.SPEXCODE_SESSION_ID || ""
+  const rt = spexShimRuntime({ sessionId: () => sessionId })
+  const toolFields = (toolName: string, input: unknown) =>
+    ({ tool_name: TOOL[toolName] ?? toolName, tool_input: rt.toolInput(input, "path") })
+
+  // bound as soon as the extension loads so liveness reads online early; only a governed launch carries the
+  // socket env (sessions.ts rvEnv) — a self-launched bare \`pi\` skips this.
+  const rv = rt.serveRendezvous((text: string) => pi.sendUserMessage(text, { deliverAs: "steer" }))
+
+  pi.on("session_start", async (_event, ctx) => {
+    sessionId = ctx.sessionManager.getSessionId() || sessionId
+    process.env.PI_SESSION_ID = sessionId   // tool subprocesses inherit it → spex CLI knows its session
+    await rt.dispatchEvent("SessionStart")
+  })
+  pi.on("input", async (event) => { await rt.dispatchEvent("UserPromptSubmit", { prompt: event.text }) })
+  pi.on("tool_call", async (event) => {
+    const r = await rt.dispatchEvent("PreToolUse", toolFields(event.toolName, event.input))
+    if (rt.blocked(r)) return { block: true, reason: rt.blockReason(r, "blocked by a SpexCode hook") }
+  })
+  pi.on("tool_result", async (event) => { await rt.dispatchEvent("PostToolUse", toolFields(event.toolName, event.input)) })
+  // Stop rides the runtime's dispatchStop on TWO bindings that never duplicate: agent_end performs the
+  // NORMAL dispatch (pi awaits its listeners inside the run loop and drains a queued teach as the SAME
+  // awaited prompt's continuation — never the orphaned settle-time prompt whose late inject threw
+  // "extension ctx is stale"), while agent_settled — which fires exactly once per prompt, after every
+  // drain — consumes AT MOST ONE PENDING BLOCKED stop (measured gap: in real dispatched runs the drained
+  // continuation's own agent_end does not reliably re-reach the extension, so without the backstop the
+  // flagged escape never runs). A naturally allowed agent_end leaves no
+  // pending state and settle dispatches NOTHING (exactly one gate entry per stop); only a blocked
+  // agent_end arms it, and the flagged settle dispatch always ends allowed (the gate's continuation paths
+  // terminate), clearing the pending bit through a subprocess write with no duplicate inject. An
+  // uninjectable host stays caught-loud.
+  const stop = () => rt.dispatchStop(
+    async (reason: string) => pi.sendUserMessage(reason, { deliverAs: "steer" }),
+    "a SpexCode Stop hook blocked this stop without giving a reason",
+  )
+  pi.on("agent_end", async () => { await stop() })
+  pi.on("agent_settled", async () => { if (rt.stopPending()) await stop() })
+  pi.on("session_shutdown", async () => { rv?.close() })
+}
+`
+}
+
+// ---------------------------------------------------------------------------------------------------------
+// pi trust — make a dispatched/self-launched pi load our project-local extension with zero prompts. pi gates
+// EVERY project-local resource (.pi/extensions, .pi/skills, .pi/prompts, .pi/settings.json) behind project
+// trust: saved decisions live in ~/.pi/agent/trust.json as a flat { "<canonical dir>": true|false } map, and
+// the CLOSEST saved decision on the cwd's parent chain wins (pi trust-manager findNearestTrustEntry). So ONE
+// entry keyed by the MAIN CHECKOUT covers every .worktrees/<id> worktree beneath it. The launch additionally
+// carries `--approve` (one-run trust) as defence for a worktree living OUTSIDE the checkout. Writes are
+// idempotent and surgical: other projects' decisions are untouched; a corrupt trust.json FAILS LOUD rather
+// than being clobbered; remove only deletes a `true` we could have written, never a user's saved "false".
+
+// pi has no config-dir env of its own (hardcoded ~/.pi/agent) — SPEXCODE_PI_AGENT_DIR is OUR test seam only.
+const piAgentDir = () => process.env.SPEXCODE_PI_AGENT_DIR || join(homedir(), '.pi', 'agent')
+// pi canonicalizes trust keys (realpath); mirror it so our key matches its lookup.
+const canonical = (p: string) => { try { return realpathSync(p) } catch { return p } }
+
+function readTrust(file: string): Record<string, unknown> {
+  if (!existsSync(file)) return {}
+  const raw = readFileSync(file, 'utf8')
+  try { return JSON.parse(raw) as Record<string, unknown> } catch (e) {
+    throw new Error(`${file} is not valid JSON — refusing to rewrite pi's trust store: ${String(e)}`)
+  }
+}
+
+export function writePiTrust(proj: string): string {
+  const dir = piAgentDir()
+  const file = join(dir, 'trust.json')
+  const key = canonical(proj)
+  const data = readTrust(file)
+  if (data[key] === true) return file   // already trusted — no churn
+  data[key] = true
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+  return file
+}
+
+export function removePiTrust(proj: string): void {
+  const file = join(piAgentDir(), 'trust.json')
+  if (!existsSync(file)) return
+  const key = canonical(proj)
+  const data = readTrust(file)
+  if (data[key] !== true) return   // absent, or a user's own "do not trust" — never touch it
+  delete data[key]
+  writeFileSync(file, JSON.stringify(data, null, 2) + '\n')
+}

package/spec-cli/src/project-identity.ts

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { spexcodeHome } from './layout.js'
+import {
+  resolvedIdentityIcon, DEFAULT_GATEWAY_ICON, DEFAULT_PROJECT_ICON, requireIdentityChoice,
+} from './identity-presets.js'
+
+export type ResolvedIdentity = { title: string; icon: string }
+export type GatewayIdentitySource = { identity: ResolvedIdentity; revision: string }
+
+const revisionOf = (raw: string | null): string =>
+  createHash('sha256').update(raw === null ? 'missing' : `present\0${raw}`).digest('hex')
+
+function readObject(file: string): { value: Record<string, any>; raw: string | null } {
+  if (!existsSync(file)) return { value: {}, raw: null }
+  const raw = readFileSync(file, 'utf8')
+  let value: unknown
+  try { value = JSON.parse(raw) }
+  catch (e) { throw new Error(`malformed ${file}: ${(e as Error).message}`) }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${file} must contain one top-level JSON object`)
+  return { value: value as Record<string, any>, raw }
+}
+
+export function resolveProjectIdentity(configRoot: string, canonicalRoot = configRoot): ResolvedIdentity {
+  const { value } = readObject(join(configRoot, 'spexcode.json'))
+  const dashboard = value.dashboard && typeof value.dashboard === 'object' && !Array.isArray(value.dashboard)
+    ? value.dashboard as Record<string, unknown>
+    : {}
+  const configuredTitle = typeof dashboard.title === 'string' ? dashboard.title.trim() : ''
+  return {
+    title: configuredTitle || basename(canonicalRoot),
+    icon: resolvedIdentityIcon(dashboard.icon, DEFAULT_PROJECT_ICON),
+  }
+}
+
+export const hostConfigPath = (): string => join(spexcodeHome(), 'config.json')
+
+export function readGatewayIdentity(): GatewayIdentitySource {
+  const { value, raw } = readObject(hostConfigPath())
+  const gateway = value.gateway && typeof value.gateway === 'object' && !Array.isArray(value.gateway)
+    ? value.gateway as Record<string, unknown>
+    : {}
+  return {
+    identity: { title: 'Projects', icon: resolvedIdentityIcon(gateway.icon, DEFAULT_GATEWAY_ICON) },
+    revision: revisionOf(raw),
+  }
+}
+
+export function writeGatewayIcon(icon: unknown, revision: string): GatewayIdentitySource {
+  const canonical = requireIdentityChoice(icon)
+  const file = hostConfigPath()
+  const current = readObject(file)
+  if (revision !== revisionOf(current.raw)) {
+    const error = new Error('host config changed on disk — reload before saving') as Error & { status?: number }
+    error.status = 409
+    throw error
+  }
+  const gateway = current.value.gateway && typeof current.value.gateway === 'object' && !Array.isArray(current.value.gateway)
+    ? current.value.gateway as Record<string, unknown>
+    : {}
+  const next = { ...current.value, gateway: { ...gateway, icon: canonical } }
+  const raw = `${JSON.stringify(next, null, 2)}\n`
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 })
+  const tmp = `${file}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, raw, { mode: 0o600 })
+    renameSync(tmp, file)
+  } finally {
+    try { rmSync(tmp) } catch { /* rename consumed it / write never created it */ }
+  }
+  return { identity: { title: 'Projects', icon: canonical }, revision: revisionOf(raw) }
+}