spexcode 0.6.1 → 0.6.5

package/spec-cli/src/commit-surgery.ts

@@ -1,68 +0,0 @@
-import { execFileSync } from 'node:child_process'
-import { relative } from 'node:path'
-import { materialize, stripSpexcodeBlock, GENERATED_MARK } from './materialize.js'
-import { HARNESSES } from './harness.js'
-import { gitBinary } from './git.js'
-
-// GIT ENV, deliberately INVERTED from git.ts's git(): every call here PRESERVES the hook's environment —
-// GIT_INDEX_FILE must be honored so the surgery reads/writes the EXACT index this commit is being built
-// from (a `git commit <path>` pathspec commit and `git commit -a` both run hooks against a TEMPORARY index;
-// operating on the real one would silently miss them). git.ts strips that env for repo DISCOVERY reasons;
-// index surgery is the one place the env is the point.
-const raw = (args: string[], input?: string): string =>
-  execFileSync(gitBinary(process.env), args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
-
-function inHead(p: string): boolean {
-  try { raw(['cat-file', '-e', `HEAD:${p}`]); return true } catch { return false }
-}
-function stagedBlob(p: string): string | null {
-  try { return raw(['show', `:${p}`]) } catch { return null }
-}
-function evict(p: string, why: string): void {
-  raw(['update-index', '--force-remove', '--', p])
-  console.error(`spexcode: unstaged ${p} (${why} — generated artifacts are never tracked; the file stays on disk)`)
-}
-function replaceBlob(p: string, content: string): void {
-  const stage = raw(['ls-files', '--stage', '--', p]).trim()          // "100644 <sha> 0\t<p>"
-  const mode = stage.split(/\s/)[0] || '100644'
-  const sha = raw(['hash-object', '-w', '--stdin'], content).trim()
-  raw(['update-index', '--cacheinfo', `${mode},${sha},${p}`])
-  console.error(`spexcode: stripped the <!-- spexcode --> block from staged ${p} (the block is working-tree context, never history)`)
-}
-
-export function commitSurgery(proj = process.cwd()): void {
-  // (1) unconditional materialize — machine-fixable state (exclude entries, filter binding, kind flips)
-  // is repaired BEFORE the index is inspected, so the inspection below judges against fresh masks.
-  try { materialize(proj) } catch (e) {
-    console.error(`spexcode: pre-commit materialize failed (${(e as Error).message}) — footprint may be stale this commit`)
-  }
-  const staged = raw(['diff', '--cached', '--name-only', '-z']).split('\0').filter(Boolean)
-  if (!staged.length) return
-  const rel = (f: string) => relative(proj, f)
-  const contracts = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)).map(rel))
-  const machine = new Set<string>(['spexcode.local.json', '.session'])
-  for (const h of HARNESSES) {
-    machine.add(rel(h.shimFile(proj)))
-    const a = h.worktreeHookAnchor(proj)
-    if (a) machine.add(rel(a))
-  }
-  const generatedDirs = HARNESSES.flatMap((h) => [h.skillDir(proj), h.agentDir(proj)])
-    .filter((d): d is string => !!d).map((d) => `${rel(d)}/`)
-  for (const p of staged) {
-    if (contracts.has(p)) {
-      const blob = stagedBlob(p)
-      if (blob === null) continue
-      const stripped = stripSpexcodeBlock(blob)
-      if (stripped === blob) continue                               // no block staged — clean already did its job
-      if (!stripped.trim() && !inHead(p)) evict(p, 'wholly a spexcode materialized artifact')
-      else replaceBlob(p, stripped)
-    } else if (machine.has(p) || p.startsWith('.worktrees/')) {
-      if (!inHead(p)) evict(p, 'a machine-local spexcode file')
-      else console.error(`spexcode: ${p} is a machine-local spexcode file but HEAD already tracks it — not touching a tracked file; untrack it yourself (git rm --cached ${p})`)
-    } else if (generatedDirs.some((d) => p.startsWith(d))) {
-      if (inHead(p)) continue                                       // historically tracked — the host's call
-      const blob = stagedBlob(p)
-      if (blob !== null && blob.includes(GENERATED_MARK)) evict(p, 'a generated skill/agent artifact')
-    }
-  }
-}

package/spec-cli/src/contract-filter.ts

@@ -1,202 +0,0 @@
-import { mkdirSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, statSync } from 'node:fs'
-import { join, relative } from 'node:path'
-import { execFileSync } from 'node:child_process'
-import { git, gitBinary } from './git.js'
-import { writeManagedBlock, removeManagedBlock } from './harness.js'
-import { encodeProject, runtimeRoot, treeSlotDir } from './layout.js'
-import { writeFileIfChanged } from './file-write.js'
-
-// the three field-sharpened edges this module owes ([[content-filter]]):
-//   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
-//     missing — a bare missing filter command makes git spray "cannot fork" fatals on EVERY operation;
-//   ② a changed contract does NOT propagate by itself (git re-smudges only on checkout) — materialize's
-//     re-materialize writes the managed block straight into the working file (writeManagedBlock IS the re-smudge),
-//     and this module refreshes the block file the shim reads so future checkouts agree;
-//   ③ unplanting must strip the block from the WORKING FILES before the config goes away, or the block
-//     residue surfaces as an uncommitted modification — the caller (dematerialize) removes the managed
-//     blocks first and only then calls removeContractFilter.
-
-function commonDirOf(proj: string): string {
-  return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim()
-}
-const filterDir = (common: string) => join(common, 'spexcode')
-const shimPath = (common: string) => join(filterDir(common), 'contract-filter.sh')
-const rootPath = (common: string) => join(filterDir(common), 'contract-filter-root')
-const bindingsPath = (common: string) => join(filterDir(common), 'contract-filter-bindings')
-const treeFilterDir = (proj: string) => join(treeSlotDir(proj), 'contract-filter')
-const attributesPath = (common: string) => join(common, 'info', 'attributes')
-
-export type ContractFilterPayload = { file: string; content: string }
-export type ContractFilterBinding = { file: string; start: string; end: string }
-
-// The common shim both filter directions run through. Pure shell/awk (no node boot on git's hot path), it
-// resolves the invoking checkout to that tree's payload before mirroring managed-block normalization:
-//   clean : drop the sentinel block (+ the blank line smudge printed before it) → the pristine host prose.
-//   smudge: clean first (a block already in the index can never double-inject), then append the tree payload.
-// Byte-exactness holds for text ending in exactly one newline (git's own well-formed-text shape); a pristine
-// file ending in zero or 2+ newlines is normalized to one on the first round-trip and stable after.
-const SHIM = `#!/usr/bin/env bash
-# spexcode managed-text filter (generated by spex materialize; see [[content-filter]]).
-# One common driver selects the payload belonging to the Git checkout that invoked it.
-set -u
-mode="\${1:?usage: contract-filter.sh smudge|clean <path>}"
-path="\${2:?usage: contract-filter.sh smudge|clean <path>}"
-here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
-binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
-[ -n "$binding" ] || { cat; exit 0; }
-start="\${binding%%$'\t'*}"; rest="\${binding#*$'\t'}"
-end="$rest"
-top="$(git rev-parse --show-toplevel 2>/dev/null || true)"
-root="$(cat "$here/contract-filter-root" 2>/dev/null || true)"
-key="$(printf '%s' "$top" | sed 's#[/.]#-#g')"
-manifest="$root/trees/$key/contract-filter/manifest"
-payload="$(awk -F '\t' -v p="$path" '$1 == p { print $2; exit }' "$manifest" 2>/dev/null)"
-strip() {
-  awk -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
-    { lines[n++] = $0 }
-    END {
-      s = -1; e = -1
-      for (i = 0; i < n; i++) {
-        if (lines[i] == sline && s < 0) s = i
-        if (lines[i] == eline && s >= 0 && e < 0) e = i
-      }
-      if (s >= 0 && e >= s) {
-        a = s; while (a > 0 && lines[a-1] == "") a--
-        b = e; while (b + 1 < n && lines[b+1] == "") b++
-        j = 0
-        for (i = 0; i < n; i++) if (i < a || i > b) lines[j++] = lines[i]
-        n = j
-      }
-      for (i = 0; i < n; i++) print lines[i]
-    }'
-}
-case "$mode" in
-  clean) strip ;;
-  smudge)
-    if [ ! -r "$payload" ]; then strip; exit 0; fi
-    strip | awk -v b="$payload" -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
-      { lines[n++] = $0 }
-      END {
-        while (n > 0 && lines[n-1] == "") n--
-        for (i = 0; i < n; i++) print lines[i]
-        if (n > 0) print ""
-        print sline
-        while ((getline l < b) > 0) print l
-        print eline
-      }' ;;
-  *) echo "contract-filter.sh: unknown mode $mode" >&2; exit 1 ;;
-esac
-`
-
-// edge ①: the command git runs is a tolerant wrapper — the shim path is an ARGUMENT ($0), and a missing/
-// unreadable shim degrades to `cat` (identity) instead of a per-operation fatal.
-const filterCmd = (shim: string, mode: 'smudge' | 'clean') =>
-  `sh -c 'test -r "$0" && exec bash "$0" ${mode} "$1" || exec cat' '${shim.replace(/'/g, `'\\''`)}' %f`
-
-// plant (or refresh) the filter for the given contract files (tracked, or untracked-with-host-content —
-// pre-armed): the shim + the block content it smudges, the per-clone git config, and the attribute lines
-// binding each file to the filter. `contract` is the assembled block body (guide + surface:system).
-// settleIndexStat skips untracked entries (no index blob) by design and only runs after a real filter change.
-export function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[], changedFiles: readonly string[] = []): boolean {
-  const common = commonDirOf(proj)
-  mkdirSync(filterDir(common), { recursive: true })
-  let changed = writeFileIfChanged(shimPath(common), SHIM)
-  if (changed || (statSync(shimPath(common)).mode & 0o777) !== 0o755) chmodSync(shimPath(common), 0o755)
-  const commands = new Map([
-    ['filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')],
-    ['filter.spexcode.clean', filterCmd(shimPath(common), 'clean')],
-  ])
-  const configured = new Map<string, string>()
-  try {
-    for (const row of git(['-C', proj, 'config', '--get-regexp', '^filter\\.spexcode\\.(smudge|clean)$']).trimEnd().split('\n')) {
-      const at = row.indexOf(' ')
-      if (at > 0) configured.set(row.slice(0, at), row.slice(at + 1))
-    }
-  } catch {}
-  for (const [key, command] of commands) {
-    if (configured.get(key) === command) continue
-    git(['-C', proj, 'config', key, command])
-    changed = true
-  }
-  changed = writeFileIfChanged(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}`).join('\n') + '\n') || changed
-  const dir = treeFilterDir(proj)
-  mkdirSync(dir, { recursive: true })
-  const manifest: string[] = []
-  const wanted = new Set(['manifest'])
-  for (const [i, payload] of payloads.entries()) {
-    const target = join(dir, String(i))
-    wanted.add(String(i))
-    changed = writeFileIfChanged(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`) || changed
-    manifest.push(`${payload.file}\t${target}`)
-  }
-  for (const entry of readdirSync(dir)) {
-    if (!wanted.has(entry)) { rmSync(join(dir, entry), { recursive: true, force: true }); changed = true }
-  }
-  const manifestPath = join(dir, 'manifest')
-  changed = writeFileIfChanged(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : '')) || changed
-  changed = writeFileIfChanged(rootPath(common), `${runtimeRoot(proj)}\n`) || changed
-  // Attribute patterns are checkout-relative; the stable binding set is safe in the common git dir because
-  // the driver selects a payload from the invoking checkout's tree slot.
-  const entries = bindings.map((b) => `/${b.file} filter=spexcode`).sort().join('\n')
-  mkdirSync(join(common, 'info'), { recursive: true })
-  changed = writeManagedBlock(attributesPath(common), entries, ['# ', '']) || changed
-  const settle = changed ? payloads.map((p) => join(proj, p.file)) : changedFiles
-  if (settle.length) settleIndexStat(proj, [...new Set(settle)])
-  return changed
-}
-
-// settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
-// clean-filtered path by stat alone (worktree size ≠ blob size by design), and `git status` reports such an
-// entry modified FOREVER without ever content-checking it (field-verified on git 2.43; `git diff` meanwhile
-// runs the filter and shows nothing; even `update-index --really-refresh` leaves it). The block-strip side of
-// a mode switch/backout leaves the same stale stat on the then-unfiltered path. `git add --renormalize`
-// re-cleans the file and refreshes the cached stat — run ONLY when the (possibly filtered) worktree already
-// EQUALS the index blob, so it is a pure stat refresh that can never stage a user's real unstaged edit (a
-// genuine edit keeps its honest `M`). Exported for dematerialize (the unplant side); plant calls it below.
-// Best-effort: an unsettled stat is cosmetic noise, never corruption.
-export function settleIndexStat(proj: string, files: string[]): void {
-  const env = { ...process.env }
-  delete env.GIT_DIR; delete env.GIT_WORK_TREE; delete env.GIT_INDEX_FILE; delete env.GIT_OBJECT_DIRECTORY
-  for (const f of files) {
-    const rel = relative(proj, f)
-    try {
-      const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim()
-      const filtered = execFileSync(gitBinary(env), ['-C', proj, 'hash-object', '--path', rel, '--stdin'],
-        { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim()
-      if (indexBlob === filtered) git(['-C', proj, 'add', '--renormalize', '--', rel])
-    } catch { /* best-effort */ }
-  }
-}
-
-// the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
-// config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
-// (evidence blobs), so only OUR two files go, never the dir.
-export function clearContractFilterPayload(proj: string, files: string[] = []): void {
-  try { rmSync(treeFilterDir(proj), { recursive: true, force: true }) } catch { /* inaccessible tree */ }
-  settleIndexStat(proj, files)
-}
-
-export function removeContractFilter(proj: string, files: string[] = [], final = false): void {
-  let common: string
-  try { common = commonDirOf(proj) } catch { return }   // not a git repo → nothing was ever planted
-  clearContractFilterPayload(proj, files)
-  const anotherPayload = final ? false : (() => {
-    const rows = git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0')
-    const root = runtimeRoot(proj)
-    return rows
-      .filter((row) => row.startsWith('worktree '))
-      .map((row) => row.slice('worktree '.length))
-      .some((tree) => existsSync(join(root, 'trees', encodeProject(tree), 'contract-filter', 'manifest')))
-  })()
-  if (!final && anotherPayload) return
-  removeManagedBlock(attributesPath(common), ['# ', ''], true)
-  for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
-    try { git(['-C', proj, 'config', '--unset-all', key]) } catch { /* not set — already clean */ }
-  }
-  for (const path of [shimPath(common), rootPath(common), bindingsPath(common)]) rmSync(path, { force: true })
-}
-
-// is the filter currently planted? (the assert-side probe tests use; cheap: one config read)
-export function contractFilterPlanted(proj: string): boolean {
-  try { return git(['-C', proj, 'config', 'filter.spexcode.clean']).trim().length > 0 } catch { return false }
-}

package/spec-cli/src/delivery-queue.ts

@@ -1,107 +0,0 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
-import { join } from 'node:path'
-import { runtimeRoot, sessionArtifactPath, sessionStoreDir } from './layout.js'
-
-// @@@ delivery-queue - what a session still OWES its agent. The log ([[session-timeline]]) is the record and
-// grows forever; this is the debt and is consumed, so it lives in its own small file whose resting state is
-// EMPTY. Nothing here reads the log: an entry carries the text it will hand over, so history could be trimmed
-// or archived without changing what is owed. A session that predates this mechanism owes nothing, because a
-// queue is only ever filled by an enqueue — which is why no backlog migration exists.
-
-export type PendingMessage = { mid: string; text: string; from: string | null }
-
-const queuePath = (id: string): string => sessionArtifactPath(id, 'pending.json')
-
-// @@@ its own lock, deliberately NOT the record lock - the drain holds this across the adapter insert, which
-// is what makes "claim" real: two processes draining the same session cannot both hand over one message. The
-// record lock could never span that call — a native turn runs lifecycle hooks that re-enter the record writer,
-// and holding it there deadlocks the adapter's own confirmation. Nothing in the delivery path takes this one,
-// so spanning the insert costs no contention. PID liveness reclaims a lock whose holder died mid-insert.
-const lockRoot = (): string => join(runtimeRoot(), '.delivery-locks')
-const lockPath = (id: string): string => join(lockRoot(), `${id}.lock`)
-
-const pause = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms))
-
-async function acquire(id: string, timeoutMs: number): Promise<(() => void) | null> {
-  mkdirSync(lockRoot(), { recursive: true })
-  const path = lockPath(id), deadline = Date.now() + timeoutMs
-  for (;;) {
-    try {
-      const fd = openSync(path, 'wx')
-      writeSync(fd, String(process.pid))
-      closeSync(fd)
-      return () => { try { unlinkSync(path) } catch { /* a liveness reclaim already removed it */ } }
-    } catch (e) {
-      if ((e as NodeJS.ErrnoException).code !== 'EEXIST') throw e
-      let owner = 0
-      try { owner = Number(readFileSync(path, 'utf8').trim()) || 0 } catch { /* race with creator/releaser */ }
-      if (owner && owner !== process.pid) {
-        try { process.kill(owner, 0) } catch { try { unlinkSync(path) } catch { /* race */ }; continue }
-      }
-      // A drain is never urgent enough to fight for: whoever holds the lock is delivering these same messages,
-      // and the retry sweep will come back. Declining is not a lost message.
-      if (Date.now() >= deadline) return null
-      await pause(25)
-    }
-  }
-}
-
-function read(id: string): PendingMessage[] {
-  try {
-    const raw = JSON.parse(readFileSync(queuePath(id), 'utf8')) as unknown
-    if (!Array.isArray(raw)) return []
-    return raw.filter((m): m is PendingMessage =>
-      !!m && typeof m === 'object'
-      && typeof (m as PendingMessage).mid === 'string'
-      && typeof (m as PendingMessage).text === 'string')
-  } catch { return [] }   // absent, empty, or unparseable all mean the honest thing: nothing owed
-}
-
-// Written whole and atomically; an empty queue is REMOVED rather than left as `[]`, so "is anything owed?" is
-// one existsSync on the sweep's hot path.
-function write(id: string, msgs: PendingMessage[]): void {
-  const path = queuePath(id)
-  if (!msgs.length) { try { unlinkSync(path) } catch { /* already gone */ } ; return }
-  mkdirSync(sessionStoreDir(id), { recursive: true })
-  const tmp = `${path}.${process.pid}.tmp`
-  writeFileSync(tmp, JSON.stringify(msgs, null, 2) + '\n')
-  renameSync(tmp, path)
-}
-
-// The enqueue rides the timeline append ([[dispatch]]): the caller holds the session's RECORD lock across
-// both, and the record is written first, so a crash between them leaves a message visible but undelivered —
-// never delivered but unrecorded.
-export function enqueue(id: string, msg: PendingMessage): void {
-  write(id, [...read(id), msg])
-}
-
-export const pendingMessages = (id: string): PendingMessage[] => read(id)
-
-export const owesDelivery = (id: string): boolean => existsSync(queuePath(id))
-
-// Hand over what is owed, in order, exactly once. `insert` reports whether the adapter took the message: only
-// then is the entry dropped. A refusal ENDS the pass with that entry still queued and everything behind it
-// still behind it — order is a property of a conversation, so a message is never skipped to deliver a later
-// one. Returns how many were handed over and how many are still owed.
-export async function drain(
-  id: string,
-  insert: (msg: PendingMessage) => Promise<boolean>,
-  timeoutMs = 5_000,
-): Promise<{ delivered: number; remaining: number }> {
-  const release = await acquire(id, timeoutMs)
-  if (!release) return { delivered: 0, remaining: read(id).length }
-  let delivered = 0
-  try {
-    for (;;) {
-      const queued = read(id)
-      if (!queued.length) return { delivered, remaining: 0 }
-      let ok = false
-      try { ok = await insert(queued[0]) } catch { ok = false }
-      if (!ok) return { delivered, remaining: queued.length }
-      // Re-read before removing: a send that landed while this pass ran appended to the tail, and rewriting a
-      // stale snapshot minus the head would silently drop it.
-      write(id, read(id).filter((m) => m.mid !== queued[0].mid))
-      delivered++
-    }
-  } finally { release() }
-}