@aperant/framework 0.6.3 → 0.6.5

package/src/cli/artifacts/classification.mjs

@@ -174,6 +174,11 @@ const RULES = Object.freeze([
 		class: ARTIFACT_CLASS.EPHEMERAL,
 		why: 'Append-only daily log of lifecycle transitions.',
 	},
+	{
+		pattern: '.aperant/install/**',
+		class: ARTIFACT_CLASS.EPHEMERAL,
+		why: 'Install telemetry/summaries (last-init/last-install) — runtime artifacts.',
+	},
 	{
 		pattern: '.aperant/team-status/**',
 		class: ARTIFACT_CLASS.EPHEMERAL,
@@ -249,6 +254,11 @@ const RULES = Object.freeze([
 		class: ARTIFACT_CLASS.EPHEMERAL,
 		why: 'Design-scan outputs (tokens, extracted repo, synthesis) — rebuildable.',
 	},
+	{
+		pattern: '.aperant/product-context.json',
+		class: ARTIFACT_CLASS.EPHEMERAL,
+		why: 'Derived/read-through sidecar used by CLI flows; rebuilt from onboarding context.',
+	},
 	// ── Explicit ephemeral: secrets/tokens MUST never classify committable ─
 	{
 		pattern: '.aperant/secrets/**',

package/src/cli/ci-watch/lock.mjs

@@ -0,0 +1,178 @@
+/**
+ * ci-watch/lock.mjs — per-PR O_EXCL atomic lock (D-05).
+ *
+ * Mirrors Claude Code's `cronTasksLock.ts`: a per-PR `.aperant/ci-watches/{pr}.lock`
+ * file created with `openSync(..., 'wx')` (O_EXCL). Two concurrent callers
+ * cannot both create the file; the loser reads the existing lock and decides
+ * whether to declare BUSY or recover a stale lock.
+ *
+ * Stale-recovery (spec.md §8): a lock is recoverable iff
+ *   (a) holder PID is dead (`!isPidAlive`), AND
+ *   (b) `Date.now() - acquiredAt > ttl_seconds*1000`.
+ * Live PID alone is NEVER recoverable, even past TTL — TTL alone is not
+ * enough. Per D-05: PID-based stale recovery.
+ *
+ * Lock file shape (spec.md §8):
+ *   { sessionId, pid, acquiredAt, ttl_seconds }
+ *
+ * Return shapes:
+ *   acquireLock → { status: 'ok', lock: {...} }
+ *              OR { status: 'busy', holder: {...} }
+ *   releaseLock → boolean (true on release, false if owner mismatch / missing)
+ *   readLock   → lock object or null
+ */
+
+import {
+	closeSync,
+	existsSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	unlinkSync,
+	writeSync,
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isPidAlive } from '../lock/pid.mjs'
+
+const TTL_SECONDS = 1800 // 30 min — D-05
+
+function watchesDir(root) {
+	return join(resolve(root), '.aperant', 'ci-watches')
+}
+
+function lockPath(root, pr) {
+	return join(watchesDir(root), `${pr}.lock`)
+}
+
+/**
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function readLock(root, pr) {
+	const path = lockPath(root, pr)
+	if (!existsSync(path)) return null
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch {
+		// A corrupted lock is treated as no lock — re-acquire will overwrite.
+		return null
+	}
+}
+
+function writeLockFile(path, payload) {
+	mkdirSync(resolve(path, '..'), { recursive: true })
+	const fd = openSync(path, 'wx')
+	try {
+		writeSync(fd, `${JSON.stringify(payload, null, 2)}\n`, 0, 'utf-8')
+	} finally {
+		closeSync(fd)
+	}
+}
+
+/**
+ * Try to acquire the per-PR lock. On EEXIST, parse the existing lock — if the
+ * holder PID is dead AND TTL has elapsed, unlink + retry once. Otherwise
+ * return `{status:'busy', holder}`.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {string} sessionId
+ * @param {number} [pid=process.pid]
+ */
+export function acquireLock(root, pr, sessionId, pid = process.pid) {
+	const path = lockPath(root, pr)
+	const payload = {
+		sessionId,
+		pid,
+		acquiredAt: new Date().toISOString(),
+		ttl_seconds: TTL_SECONDS,
+	}
+
+	try {
+		writeLockFile(path, payload)
+		return { status: 'ok', lock: payload }
+	} catch (err) {
+		if (err.code !== 'EEXIST') throw err
+	}
+
+	// Lock file exists — inspect.
+	const existing = readLock(root, pr)
+	if (!existing) {
+		// Corrupted lock — treat as recoverable, unlink + retry once.
+		try {
+			unlinkSync(path)
+		} catch {
+			/* race — another caller cleaned up */
+		}
+		try {
+			writeLockFile(path, payload)
+			return { status: 'ok', lock: payload }
+		} catch (err) {
+			if (err.code === 'EEXIST') {
+				return { status: 'busy', holder: readLock(root, pr) }
+			}
+			throw err
+		}
+	}
+
+	if (isStale(existing)) {
+		try {
+			unlinkSync(path)
+		} catch {
+			/* race — another caller cleaned up */
+		}
+		try {
+			writeLockFile(path, payload)
+			return { status: 'ok', lock: payload }
+		} catch (err) {
+			if (err.code === 'EEXIST') {
+				return { status: 'busy', holder: readLock(root, pr) }
+			}
+			throw err
+		}
+	}
+
+	return { status: 'busy', holder: existing }
+}
+
+/**
+ * Release the per-PR lock. Owner must match (`sessionId` equality). Returns
+ * `true` if released, `false` if the lock is missing or owned by someone
+ * else.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {string} sessionId
+ */
+export function releaseLock(root, pr, sessionId) {
+	const path = lockPath(root, pr)
+	if (!existsSync(path)) return false
+	const existing = readLock(root, pr)
+	if (!existing) {
+		// Corrupted — fail open (let next caller clean up).
+		return false
+	}
+	if (existing.sessionId !== sessionId) return false
+	try {
+		unlinkSync(path)
+		return true
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Is the given lock stale (i.e., recoverable by a new caller)? Per D-05,
+ * BOTH conditions are required: dead PID AND past TTL.
+ *
+ * Exposed for unit tests; the orchestrator does not call this directly.
+ *
+ * @param {{ pid: number, acquiredAt: string, ttl_seconds: number }} lockData
+ */
+export function isStale(lockData) {
+	if (!lockData || typeof lockData !== 'object') return false
+	const ttlMs = (lockData.ttl_seconds || TTL_SECONDS) * 1000
+	const age = Date.now() - new Date(lockData.acquiredAt).getTime()
+	if (age <= ttlMs) return false
+	return !isPidAlive(lockData.pid)
+}

package/src/cli/ci-watch/state.mjs

@@ -0,0 +1,103 @@
+/**
+ * ci-watch/state.mjs — per-PR state-file primitives for the /apt:watch-ci
+ * post-ship watcher (D-04).
+ *
+ * Storage shape (`.aperant/ci-watches/{pr}.json`), spec.md §8:
+ *
+ *   {
+ *     pr, task_id, host, scheduler_handle | null,
+ *     attempts, started_at, deadline, last_poll,
+ *     last_status | null, next_tick_interval_ms,
+ *     paused, auto_merge_on_green
+ *   }
+ *
+ * This module is pure read/write — classification logic lives in
+ * stop-matrix.mjs, the orchestrator lives in commands/ci-watch.mjs.
+ *
+ * Crash-safety: `writeState` goes through `atomicWriteJson` (tmp + fsync +
+ * rename). `readState` returns `null` for a missing file and never throws on
+ * a missing path — callers can distinguish "no watch yet" from "watch is
+ * corrupted".
+ *
+ * The corrupted-JSON branch returns a recoverable error envelope rather than
+ * throwing so the orchestrator can surface it without crashing the cron
+ * payload mid-tick.
+ */
+
+import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { atomicWriteJson } from '../util/io.mjs'
+
+function watchesDir(root) {
+	return join(resolve(root), '.aperant', 'ci-watches')
+}
+
+function stateFile(root, pr) {
+	return join(watchesDir(root), `${pr}.json`)
+}
+
+/**
+ * Read the per-PR state file. Returns `null` when the file does not exist.
+ * Returns `{ error: 'corrupted', message }` when the file exists but is not
+ * parseable JSON — callers route that to the infra-backoff branch.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function readState(root, pr) {
+	const path = stateFile(root, pr)
+	if (!existsSync(path)) return null
+	try {
+		return JSON.parse(readFileSync(path, 'utf-8'))
+	} catch (err) {
+		return { error: 'corrupted', message: err.message }
+	}
+}
+
+/**
+ * Atomically write the per-PR state file. Caller passes the full state object
+ * — this function does not merge, it overwrites. Use `readState` first if a
+ * merge is needed.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ * @param {object} state
+ */
+export function writeState(root, pr, state) {
+	atomicWriteJson(stateFile(root, pr), state)
+}
+
+/**
+ * Delete the per-PR state file. No-op when the file does not exist.
+ *
+ * @param {string} root
+ * @param {number|string} pr
+ */
+export function deleteState(root, pr) {
+	const path = stateFile(root, pr)
+	if (existsSync(path)) unlinkSync(path)
+}
+
+/**
+ * Enumerate every per-PR state file under `.aperant/ci-watches/`. Returns an
+ * array of parsed state objects in lexicographic filename order. Skips files
+ * whose name does not match `<pr>.json` and skips corrupted files (their
+ * presence does not block the rest of the listing).
+ *
+ * @param {string} root
+ */
+export function listWatches(root) {
+	const dir = watchesDir(root)
+	if (!existsSync(dir)) return []
+	const watches = []
+	for (const f of readdirSync(dir).sort()) {
+		if (!/^\d+\.json$/.test(f)) continue
+		try {
+			watches.push(JSON.parse(readFileSync(join(dir, f), 'utf-8')))
+		} catch {
+			// Skip corrupted state files — listWatches is a read-only enumerator
+			// and must not throw on partial corruption.
+		}
+	}
+	return watches
+}

package/src/cli/ci-watch/stop-matrix.mjs

@@ -0,0 +1,181 @@
+/**
+ * ci-watch/stop-matrix.mjs — pure stop-matrix classifier (D-06).
+ *
+ * `classify({checks, state, prMetadata})` returns
+ *   { action, counts_toward_budget, reason }
+ *
+ * No I/O, no fs, no gh CLI shell-outs — caller pre-fetches `checks` (the
+ * payload from `gh pr checks --json name,bucket,state,conclusion,detailsUrl`)
+ * and `prMetadata` (`gh pr view --json state,reviewDecision`) and passes them
+ * in. The orchestrator in commands/ci-watch.mjs handles the side effects
+ * implied by the action.
+ *
+ * Predicate order matters — short-circuits go first (merged/closed/green/cap
+ * fire before any per-check inspection). See spec.md §9 table for the full
+ * ordering.
+ *
+ * The 11 actions:
+ *   merged, closed, green, attempts-cap, wall-cap, reviewer-pause,
+ *   identical-log, flake-skip, infra-backoff, diverged-rebased,
+ *   diverged-bailed, fix
+ *
+ * `counts_toward_budget` is `true` for fix attempts (including rebase
+ * attempts and rebase-bail); `false` for flake-skip / infra-backoff; `false`
+ * (with a sentinel meaning "n/a") for terminal actions.
+ */
+
+const ATTEMPTS_CAP = 5
+
+const INFRA_FAILURE_CLASSES = new Set(['runner-oom', 'runner-cancelled', 'gh-5xx', 'timeout'])
+
+/**
+ * @typedef {Object} CheckRow
+ * @property {string} [name]
+ * @property {string} [conclusion] e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
+ * @property {string} [state]
+ * @property {string} [bucket]
+ * @property {string} [failure_class] — optional pre-classified hint (test-only seam)
+ * @property {string} [log_fingerprint] — optional digest for identical-log detection
+ *
+ * @typedef {Object} ClassifyInput
+ * @property {CheckRow[]} checks
+ * @property {Object} state — per-PR state (see state.mjs §8)
+ * @property {Object} prMetadata — { state: 'OPEN'|'CLOSED'|'MERGED', reviewDecision?: string }
+ *
+ * @typedef {Object} ClassifyOutput
+ * @property {string} action
+ * @property {boolean} counts_toward_budget
+ * @property {string} reason
+ *
+ * @param {ClassifyInput} input
+ * @returns {ClassifyOutput}
+ */
+export function classify({ checks, state, prMetadata }) {
+	const pr = prMetadata || {}
+	const st = state || {}
+	const rows = Array.isArray(checks) ? checks : []
+
+	// 1. MERGED.
+	if (pr.state === 'MERGED') {
+		return { action: 'merged', counts_toward_budget: false, reason: 'pr is merged' }
+	}
+	// 2. CLOSED (not merged).
+	if (pr.state === 'CLOSED') {
+		return { action: 'closed', counts_toward_budget: false, reason: 'pr is closed unmerged' }
+	}
+
+	const failed = rows.filter((c) => isFailing(c))
+	const allGreen = rows.length > 0 && rows.every((c) => c.conclusion === 'success')
+
+	// 3. All checks green.
+	if (allGreen) {
+		return { action: 'green', counts_toward_budget: false, reason: 'all checks succeeded' }
+	}
+
+	// 3b. No checks registered yet — CI hasn't enqueued jobs. Wait without
+	// burning a fix attempt.
+	if (rows.length === 0) {
+		return { action: 'wait', counts_toward_budget: false, reason: 'no checks registered yet' }
+	}
+
+	// 4. Attempts cap (only when red present — otherwise green/merged/closed would have fired).
+	const attempts = st.attempts || 0
+	if (attempts >= ATTEMPTS_CAP && failed.length > 0) {
+		return {
+			action: 'attempts-cap',
+			counts_toward_budget: false,
+			reason: `${attempts} fix attempts used; cap is ${ATTEMPTS_CAP}`,
+		}
+	}
+
+	// 5. Wall-clock cap.
+	if (st.deadline && Date.now() > new Date(st.deadline).getTime() && failed.length > 0) {
+		return {
+			action: 'wall-cap',
+			counts_toward_budget: false,
+			reason: 'past 4h deadline',
+		}
+	}
+
+	// 6. Reviewer asked for changes.
+	if (pr.reviewDecision === 'CHANGES_REQUESTED') {
+		return {
+			action: 'reviewer-pause',
+			counts_toward_budget: false,
+			reason: 'reviewer requested changes — pausing',
+		}
+	}
+
+	// 7. Identical-log → non-converging fixer.
+	// Compare aggregate fingerprints (same format as the write side in ci-watch.mjs).
+	if (attempts > 0 && st.last_status && failed.length > 0) {
+		const currentFingerprint = failed
+			.map((f) => `${f.name}:${f.log_fingerprint ?? ''}`)
+			.sort()
+			.join('|')
+		if (currentFingerprint === st.last_status) {
+			return {
+				action: 'identical-log',
+				counts_toward_budget: false,
+				reason: 'failed-check fingerprint identical to last attempt',
+			}
+		}
+	}
+
+	// 8. Flake-skip — same check failed then passed on rerun, no commit between.
+	// The classifier sees this as an explicit hint from the caller: failed rows
+	// classified as `bucket === 'flake'` or `failure_class === 'flake'` are the
+	// flaky-test variety and must not burn a fix attempt. Fires when EVERY
+	// remaining failure is a flake — if any non-flake failure is present, we
+	// fall through and the real failure governs.
+	if (
+		failed.length > 0 &&
+		failed.every((c) => c.bucket === 'flake' || c.failure_class === 'flake')
+	) {
+		return {
+			action: 'flake-skip',
+			counts_toward_budget: false,
+			reason: 'check transient — passed on rerun',
+		}
+	}
+
+	// 9. Infra failure class.
+	if (failed.some((c) => INFRA_FAILURE_CLASSES.has(c.failure_class))) {
+		return {
+			action: 'infra-backoff',
+			counts_toward_budget: false,
+			reason: 'infra-class failure — backoff and retry',
+		}
+	}
+
+	// 10. Diverged branch — caller has already done the fetch + dry-rebase and
+	// passes the outcome in `prMetadata.diverged`:
+	//   { rebased: true }   → action 'diverged-rebased' (counts)
+	//   { rebased: false }  → action 'diverged-bailed'  (counts)
+	if (pr.diverged && typeof pr.diverged === 'object') {
+		if (pr.diverged.rebased === true) {
+			return {
+				action: 'diverged-rebased',
+				counts_toward_budget: true,
+				reason: 'origin ahead; rebased successfully',
+			}
+		}
+		return {
+			action: 'diverged-bailed',
+			counts_toward_budget: true,
+			reason: 'origin ahead; rebase conflict',
+		}
+	}
+
+	// 11. Default red — go fix.
+	return {
+		action: 'fix',
+		counts_toward_budget: true,
+		reason: 'red checks present — attempting fix',
+	}
+}
+
+export function isFailing(check) {
+	const c = check.conclusion
+	return c === 'failure' || c === 'cancelled' || c === 'timed_out' || c === 'action_required'
+}

package/src/cli/cli-wrappers/ci-watch.mjs

@@ -0,0 +1,9 @@
+/**
+ * cli-wrappers/ci-watch.mjs — Layer 2 wrapper for the ci-watch cmd.
+ *
+ * Today this is a passthrough — DISPATCH calls wrap(cmdCiWatch) directly.
+ * Re-exporting under cliCiWatch keeps the file-per-cmd structural seam
+ * (mirrors task.mjs / pr-review.mjs).
+ */
+
+export { cmdCiWatch as cliCiWatch } from '../commands/ci-watch.mjs'