@juicesharp/rpiv-workflow 1.14.0

package/outcomes/collectors/workspace-diff.test.ts

@@ -0,0 +1,107 @@
+import { execSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { CollectCtx, SnapshotCtx } from "../../output-spec.js";
+import { type WorkspaceDiffSnapshot, workspaceDiffCollector } from "./workspace-diff.js";
+
+const hasGit = (() => {
+	try {
+		execSync("git --version", { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+})();
+
+const initRepo = (cwd: string): void => {
+	execSync("git init -q", { cwd });
+	execSync("git config user.email test@example.com", { cwd });
+	execSync("git config user.name Test", { cwd });
+	execSync("git commit --allow-empty -q -m initial", { cwd });
+};
+
+const snapshotCtxOf = (cwd: string): SnapshotCtx => ({
+	cwd,
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+});
+
+const collectCtxOf = (
+	cwd: string,
+	snapshot: WorkspaceDiffSnapshot | undefined,
+): CollectCtx<WorkspaceDiffSnapshot | undefined> => ({
+	...snapshotCtxOf(cwd),
+	branch: [],
+	branchOffset: undefined,
+	snapshot,
+	skill: "test",
+});
+
+describe.runIf(hasGit)("workspaceDiffCollector", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rpiv-wd-"));
+	});
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("emits one fs artifact per file written during the stage", async () => {
+		initRepo(tmpDir);
+		const collector = workspaceDiffCollector();
+		const snapshot = await collector.snapshot?.(snapshotCtxOf(tmpDir));
+		// Write two files post-snapshot.
+		writeFileSync(join(tmpDir, "a.txt"), "hello");
+		writeFileSync(join(tmpDir, "b.txt"), "world");
+
+		const result = await collector.collect(collectCtxOf(tmpDir, snapshot));
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		const paths = result.artifacts.map((a) => (a.handle.kind === "fs" ? a.handle.path : "")).sort();
+		expect(paths).toEqual(["a.txt", "b.txt"]);
+		// Every artifact's role and meta hint come from the collector, not the user.
+		expect(result.artifacts[0]?.role).toBe("changed");
+		expect(result.artifacts[0]?.meta?.gitStatus).toBe("??");
+	});
+
+	it("skips files whose status was unchanged from snapshot (untouched files don't count)", async () => {
+		initRepo(tmpDir);
+		// Pre-snapshot file — already untracked.
+		writeFileSync(join(tmpDir, "preexisting.txt"), "x");
+		const collector = workspaceDiffCollector();
+		const snapshot = await collector.snapshot?.(snapshotCtxOf(tmpDir));
+
+		// Write a NEW file during the "stage."
+		writeFileSync(join(tmpDir, "new.txt"), "y");
+
+		const result = await collector.collect(collectCtxOf(tmpDir, snapshot));
+		expect(
+			result.kind === "ok" && result.artifacts.map((a) => (a.handle.kind === "fs" ? a.handle.path : "")),
+		).toEqual(["new.txt"]);
+	});
+
+	it("applies the optional filter", async () => {
+		initRepo(tmpDir);
+		const collector = workspaceDiffCollector({ filter: (p) => p.endsWith(".md") });
+		const snapshot = await collector.snapshot?.(snapshotCtxOf(tmpDir));
+		writeFileSync(join(tmpDir, "a.txt"), "x");
+		writeFileSync(join(tmpDir, "b.md"), "y");
+
+		const result = await collector.collect(collectCtxOf(tmpDir, snapshot));
+		expect(
+			result.kind === "ok" && result.artifacts.map((a) => (a.handle.kind === "fs" ? a.handle.path : "")),
+		).toEqual(["b.md"]);
+	});
+
+	it("fail-soft: cwd is not a git repo → snapshot undefined → collect returns empty", async () => {
+		const collector = workspaceDiffCollector();
+		const snapshot = await collector.snapshot?.(snapshotCtxOf(tmpDir));
+		expect(snapshot).toBeUndefined();
+		const result = await collector.collect(collectCtxOf(tmpDir, snapshot));
+		expect(result.kind === "ok" && result.artifacts).toEqual([]);
+	});
+});

package/outcomes/collectors/workspace-diff.ts

@@ -0,0 +1,123 @@
+/**
+ * Workspace-diff collector — emits one Artifact per file the stage
+ * touched in the working tree.
+ *
+ * Discovery model: capture `git status --porcelain` pre-stage as
+ * snapshot, then take the diff post-stage. Newly-untracked files and
+ * files whose status changed both count. Pure git — no transcript
+ * scanning, no tool-use observation, no agent narration involved.
+ *
+ * Fail-soft: cwd is not a git repo OR git isn't on PATH → snapshot is
+ * `undefined`, collector returns `ok` with an empty list (the runner's
+ * completion-strategy check then decides whether that's a halt). Same
+ * posture as `gitCommitCollector`.
+ *
+ * Optional `filter(path)` narrows the set — useful for "only `.ts`
+ * files," "only files under `src/`," etc. Authors who want more
+ * structural narrowing (per-file role tags, per-file metadata) write
+ * a custom collector — `workspaceDiffCollector` deliberately stays the
+ * thin diff primitive.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { type Artifact, fs as fsHandle } from "../../handle.js";
+import type { ArtifactCollector, CollectCtx, SnapshotCtx } from "../../output-spec.js";
+import { defineCollector } from "../../output-spec.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Same budget as gitCommitCollector — generous for local repos, short enough that a hung mount can't pin the stage. */
+const GIT_EXEC_TIMEOUT_MS = 5_000;
+
+export interface WorkspaceDiffSnapshot {
+	/** Post-stage diff compares against this set of (path, statusCode) pairs captured pre-stage. */
+	statusByPath: ReadonlyMap<string, string>;
+}
+
+export interface WorkspaceDiffCollectorOpts {
+	/**
+	 * Optional path predicate. Return true to include the file in the
+	 * collected artifacts, false to drop it. Receives the cwd-relative
+	 * path that `git status --porcelain` emitted.
+	 */
+	filter?: (path: string) => boolean;
+}
+
+export const workspaceDiffCollector = (
+	opts: WorkspaceDiffCollectorOpts = {},
+): ArtifactCollector<WorkspaceDiffSnapshot | undefined> =>
+	defineCollector<WorkspaceDiffSnapshot | undefined>({
+		snapshot: capturePorcelainSnapshot,
+		collect: (ctx) => collectDiffArtifacts(ctx, opts.filter),
+	});
+
+// ---------------------------------------------------------------------------
+// Snapshot + diff implementation
+// ---------------------------------------------------------------------------
+
+async function capturePorcelainSnapshot(ctx: SnapshotCtx): Promise<WorkspaceDiffSnapshot | undefined> {
+	const status = await runGitStatus(ctx.cwd);
+	if (status === undefined) return undefined;
+	return { statusByPath: parsePorcelain(status) };
+}
+
+async function collectDiffArtifacts(
+	ctx: CollectCtx<WorkspaceDiffSnapshot | undefined>,
+	filter: ((path: string) => boolean) | undefined,
+): Promise<{ kind: "ok"; artifacts: readonly Artifact[] }> {
+	const snapshot = ctx.snapshot;
+	if (!snapshot) return { kind: "ok", artifacts: [] };
+
+	const status = await runGitStatus(ctx.cwd);
+	if (status === undefined) return { kind: "ok", artifacts: [] };
+	const post = parsePorcelain(status);
+
+	const artifacts: Artifact[] = [];
+	for (const [path, code] of post) {
+		// Skip files whose status is unchanged from the snapshot — they
+		// weren't touched DURING this stage.
+		if (snapshot.statusByPath.get(path) === code) continue;
+		if (filter && !filter(path)) continue;
+		artifacts.push({ handle: fsHandle(path), role: "changed", meta: { gitStatus: code } });
+	}
+	return { kind: "ok", artifacts };
+}
+
+async function runGitStatus(cwd: string): Promise<string | undefined> {
+	try {
+		const { stdout } = await execFileAsync("git", ["status", "--porcelain"], {
+			cwd,
+			encoding: "utf-8",
+			timeout: GIT_EXEC_TIMEOUT_MS,
+		});
+		return stdout;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Parse `git status --porcelain` output: each line is `XY <path>` where
+ * XY is the two-character status code. We key by path and keep the
+ * full XY so post-stage diff sees status transitions (e.g. ` M` → `MM`).
+ *
+ * Renames (`R  old -> new`) are normalised to just the new path —
+ * downstream collectors / parsers don't usually care about the prior
+ * name and including both halves doubles the artifact count.
+ */
+function parsePorcelain(out: string): Map<string, string> {
+	const map = new Map<string, string>();
+	for (const line of out.split("\n")) {
+		if (line.length < 4) continue;
+		const code = line.slice(0, 2);
+		let path = line.slice(3).trim();
+		// Rename: `R  old -> new` — take the new name.
+		const arrow = path.indexOf(" -> ");
+		if (arrow !== -1) path = path.slice(arrow + 4);
+		// Strip wrapping quotes (paths with whitespace).
+		if (path.startsWith('"') && path.endsWith('"')) path = path.slice(1, -1);
+		map.set(path, code);
+	}
+	return map;
+}

package/outcomes/git-commit.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Tests for the git-commit outcome — covers the collector + parser pair
+ * on the success path, when git isn't on PATH, and when the working
+ * tree isn't a git repo.
+ *
+ * The outcome is fail-soft by contract: every git error path collapses
+ * to a `noOp: true` payload so the workflow keeps moving. These tests
+ * pin that contract — a regression that converts a failure into a throw
+ * would surface here as an unhandled rejection.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { CollectCtx, ParseCtx, SnapshotCtx } from "../output.js";
+import {
+	type GitHeadSnapshot,
+	gitCommitCollector,
+	gitCommitOutcome,
+	gitCommitParser,
+	gitHeadSnapshot,
+} from "./git-commit.js";
+
+const hasGit = (() => {
+	try {
+		execSync("git --version", { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+})();
+
+const initRepo = (cwd: string): void => {
+	execSync("git init -q", { cwd });
+	execSync("git config user.email test@example.com", { cwd });
+	execSync("git config user.name Test", { cwd });
+	execSync("git commit --allow-empty -q -m initial", { cwd });
+};
+
+const snapshotCtx = (cwd: string): SnapshotCtx => ({
+	cwd,
+	runId: "test-run",
+	stageIndex: 0,
+	state: {
+		originalInput: "",
+		primaryArtifact: undefined,
+		output: undefined,
+		named: {},
+		stagesCompleted: 0,
+		lastAllocatedStageNumber: 0,
+		telemetry: {
+			backwardJumps: 0,
+			droppedRoutingRows: [],
+		},
+		termination: {
+			success: false,
+			error: undefined,
+		},
+	},
+});
+
+const collectCtx = (cwd: string, snapshot: GitHeadSnapshot | undefined): CollectCtx<GitHeadSnapshot | undefined> => ({
+	...snapshotCtx(cwd),
+	branch: [],
+	branchOffset: undefined,
+	snapshot,
+	skill: "commit",
+});
+
+/**
+ * Run the full outcome (collector → parser) end-to-end, returning the
+ * commit data the parser produced. Mirrors what `produceAndValidateOutput`
+ * does in the runner.
+ */
+const runOutcome = async (cwd: string, snapshot: GitHeadSnapshot | undefined) => {
+	const ctx = collectCtx(cwd, snapshot);
+	const collected = await gitCommitOutcome.collector.collect(ctx);
+	if (collected.kind === "fatal") return collected;
+	const parseCtx: ParseCtx<GitHeadSnapshot | undefined> = { ...ctx, artifacts: collected.artifacts };
+	return gitCommitOutcome.parser!.parse(parseCtx);
+};
+
+describe.runIf(hasGit)("gitHeadSnapshot", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rpiv-git-snap-"));
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("returns the current HEAD SHA in a real repo", async () => {
+		initRepo(tmpDir);
+		const snap = await gitHeadSnapshot(snapshotCtx(tmpDir));
+		expect(snap?.baselineSha).toMatch(/^[0-9a-f]{40}$/);
+	});
+
+	it("returns undefined when cwd is not a git repo (no throw)", async () => {
+		const snap = await gitHeadSnapshot(snapshotCtx(tmpDir));
+		expect(snap).toBeUndefined();
+	});
+
+	it("returns undefined when cwd does not exist (no throw)", async () => {
+		const snap = await gitHeadSnapshot(snapshotCtx(join(tmpDir, "does-not-exist")));
+		expect(snap).toBeUndefined();
+	});
+});
+
+describe.runIf(hasGit)("gitCommitOutcome end-to-end", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rpiv-git-ext-"));
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("emits a real commit payload when HEAD moved between snapshot and collect", async () => {
+		initRepo(tmpDir);
+		const snap = await gitHeadSnapshot(snapshotCtx(tmpDir));
+		expect(snap?.baselineSha).toMatch(/^[0-9a-f]{40}$/);
+
+		writeFileSync(join(tmpDir, "a.txt"), "hello\n");
+		execSync("git add a.txt", { cwd: tmpDir });
+		execSync('git commit -q -m "add a"', { cwd: tmpDir });
+
+		const result = await runOutcome(tmpDir, snap);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.payload.kind).toBe("git-commit");
+		const data = result.payload.data;
+		expect(data.sha).toMatch(/^[0-9a-f]{40}$/);
+		expect(data.prevSha).toBe(snap?.baselineSha);
+		expect(data.subject).toBe("add a");
+		expect(data.filesChanged).toBe(1);
+		expect(data.noOp).toBeUndefined();
+	});
+
+	it("emits noOp payload when HEAD did not move", async () => {
+		initRepo(tmpDir);
+		const snap = await gitHeadSnapshot(snapshotCtx(tmpDir));
+		const result = await runOutcome(tmpDir, snap);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.payload.data.noOp).toBe(true);
+		expect(result.payload.data.prevSha).toBe(snap?.baselineSha);
+	});
+
+	it("emits noOp payload when snapshot is undefined (snapshot failure upstream)", async () => {
+		const result = await runOutcome(tmpDir, undefined);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.payload.data.noOp).toBe(true);
+	});
+
+	it("emits noOp payload when cwd is not a git repo (collectCommitData returns null)", async () => {
+		// Synthesize a snapshot with a fake baseline; collect runs in a non-repo cwd.
+		const result = await runOutcome(tmpDir, { baselineSha: "deadbeef" });
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.payload.data.noOp).toBe(true);
+	});
+});
+
+describe("gitCommitCollector always emits one artifact (the commit handle)", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rpiv-git-res-"));
+	});
+
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("emits role:'commit' opaque handle with the post-stage SHA (or empty when unavailable)", async () => {
+		const collected = await gitCommitCollector.collect(collectCtx(tmpDir, { baselineSha: "abc" }));
+		expect(collected.kind).toBe("ok");
+		if (collected.kind !== "ok") return;
+		expect(collected.artifacts).toHaveLength(1);
+		expect(collected.artifacts[0]?.role).toBe("commit");
+		expect(collected.artifacts[0]?.handle.kind).toBe("opaque");
+	});
+});
+
+// Suppress unused-import lint when this file runs without git on PATH.
+void existsSync;
+void gitCommitParser;

package/outcomes/git-commit.ts

@@ -0,0 +1,192 @@
+/**
+ * Git commit outcome + pre-stage git HEAD snapshot.
+ *
+ * Split into a collector (detects the commit and emits an `opaque(sha)`
+ * handle) and a parser (parses commit metadata into `GitCommitData`).
+ * `gitCommitOutcome` is the wired-up pair authors plug into a stage;
+ * `gitCommitCollector` and `gitCommitParser` are individually exposed
+ * so authors can compose them with other parsers / collectors.
+ *
+ * Shells out asynchronously via `execFile` so a slow `git` invocation
+ * (network-backed working tree, hung FS, large `--shortstat`) can't
+ * pin the event loop.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { type Artifact, opaque } from "../handle.js";
+import type {
+	ArtifactCollector,
+	ArtifactParser,
+	CollectCtx,
+	OutputSpec,
+	ParseCtx,
+	SnapshotCtx,
+} from "../output-spec.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Output data shape produced by `gitCommitParser` — co-located with
+ * the outcome that emits it. The `GitCommitOutput` alias in
+ * `output.ts` re-imports this type so downstream stages can narrow on
+ * `output.kind === "git-commit"` without reaching into per-outcome
+ * paths.
+ */
+export interface GitCommitData {
+	sha: string;
+	prevSha: string;
+	subject: string;
+	filesChanged: number;
+	noOp?: boolean;
+}
+
+/** Snapshot captured before the stage runs. */
+export interface GitHeadSnapshot {
+	baselineSha: string;
+}
+
+/** Per git command. 5 s is generous for `rev-parse` / `log -1` / `diff --shortstat` on local repos. */
+const GIT_EXEC_TIMEOUT_MS = 5_000;
+
+/** Run a git command from `cwd`, returning trimmed stdout. */
+async function git(cwd: string, ...args: string[]): Promise<string> {
+	const { stdout } = await execFileAsync("git", args, {
+		cwd,
+		encoding: "utf-8",
+		timeout: GIT_EXEC_TIMEOUT_MS,
+	});
+	return stdout.trim();
+}
+
+/**
+ * Pre-stage snapshot: capture the current HEAD SHA via async `execFile`.
+ *
+ * Async — keeps the event loop responsive even if `git` is slow (network
+ * FS, hung mount, contended index). Fail-soft: returns undefined on any
+ * failure (not a git repo, git missing, non-zero exit, timeout).
+ * `gitCommitCollector` handles `undefined` snapshot gracefully by
+ * emitting an artifact carrying a `noOp: true` payload.
+ */
+export async function gitHeadSnapshot(ctx: SnapshotCtx): Promise<GitHeadSnapshot | undefined> {
+	try {
+		const sha = await git(ctx.cwd, "rev-parse", "HEAD");
+		return sha ? { baselineSha: sha } : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Collector — detect "did HEAD move during this stage?"
+// ---------------------------------------------------------------------------
+
+/**
+ * Collector always emits exactly one artifact — even on no-op (HEAD
+ * unchanged) or git-unavailable, with the handle's `id` carrying the
+ * post-stage SHA (or empty string). The parser interprets the
+ * `noOp` flag from the artifact's `meta`. This shape keeps the
+ * collector's contract uniform (always one fact) while letting the
+ * parser produce the rich `GitCommitData` downstream consumers expect.
+ */
+export const gitCommitCollector: ArtifactCollector<GitHeadSnapshot | undefined> = {
+	snapshot: gitHeadSnapshot,
+	async collect(ctx: CollectCtx<GitHeadSnapshot | undefined>) {
+		const baselineSha = ctx.snapshot?.baselineSha ?? "";
+		const headSha = await safeHead(ctx.cwd);
+		const artifact: Artifact = {
+			handle: opaque(headSha || baselineSha),
+			role: "commit",
+			meta: { baselineSha, headSha, baselineMissing: !ctx.snapshot },
+		};
+		return { kind: "ok", artifacts: [artifact] };
+	},
+};
+
+async function safeHead(cwd: string): Promise<string> {
+	try {
+		return await git(cwd, "rev-parse", "HEAD");
+	} catch {
+		return "";
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Parser — turn the collected commit handle into typed GitCommitData
+// ---------------------------------------------------------------------------
+
+export const gitCommitParser: ArtifactParser<GitHeadSnapshot | undefined, "git-commit", GitCommitData> = {
+	async parse(ctx: ParseCtx<GitHeadSnapshot | undefined>) {
+		const artifact = ctx.artifacts[0];
+		if (!artifact) {
+			// Defensive — gitCommitCollector always emits one, but a composed
+			// collector may not. Treat as no-op against the baseline.
+			return { kind: "ok", payload: { kind: "git-commit", data: noOpData(ctx.snapshot?.baselineSha ?? "") } };
+		}
+		const meta = artifact.meta as { baselineSha: string; headSha: string; baselineMissing: boolean } | undefined;
+		const baselineSha = meta?.baselineSha ?? "";
+		const headSha = meta?.headSha ?? "";
+
+		if (meta?.baselineMissing) {
+			return { kind: "ok", payload: { kind: "git-commit", data: noOpData("") } };
+		}
+
+		const data = (await collectCommitData(ctx.cwd, baselineSha, headSha)) ?? noOpData(baselineSha);
+		return { kind: "ok", payload: { kind: "git-commit", data } };
+	},
+};
+
+// ---------------------------------------------------------------------------
+// OutputSpec — the wired-up pair
+// ---------------------------------------------------------------------------
+
+/**
+ * Git commit outcome — composes `gitCommitCollector` (which carries the
+ * `gitHeadSnapshot` snapshot internally) with `gitCommitParser`.
+ *
+ * Concrete generics: snapshot is `GitHeadSnapshot | undefined`
+ * (undefined when not in a git repo), output kind is `"git-commit"`,
+ * data is `GitCommitData`.
+ */
+export const gitCommitOutcome: OutputSpec<GitHeadSnapshot | undefined, "git-commit", GitCommitData> = {
+	collector: gitCommitCollector,
+	parser: gitCommitParser,
+};
+
+// ---------------------------------------------------------------------------
+// Commit-data collection
+// ---------------------------------------------------------------------------
+
+/**
+ * Build `GitCommitData` given pre/post SHAs already gathered by the
+ * collector. Returns `null` if any follow-up git call throws — caller
+ * substitutes a baseline-aware no-op payload so the workflow keeps
+ * moving.
+ */
+async function collectCommitData(cwd: string, baselineSha: string, headSha: string): Promise<GitCommitData | null> {
+	try {
+		if (!headSha || headSha === baselineSha) return noOpData(baselineSha, headSha);
+		const [subject, filesChanged] = await Promise.all([
+			git(cwd, "log", "-1", "--format=%s", headSha),
+			countFilesChanged(cwd, baselineSha, headSha),
+		]);
+		return { sha: headSha, prevSha: baselineSha, subject, filesChanged };
+	} catch {
+		return null;
+	}
+}
+
+/** Parse `git diff --shortstat` output for the "N files changed" count. */
+async function countFilesChanged(cwd: string, baselineSha: string, headSha: string): Promise<number> {
+	const diffStat = await git(cwd, "diff", "--shortstat", baselineSha, headSha);
+	const match = diffStat.match(/^(\d+) files? changed/);
+	return match ? parseInt(match[1]!, 10) : 0;
+}
+
+const noOpData = (prevSha: string, sha = ""): GitCommitData => ({
+	sha,
+	prevSha,
+	subject: "",
+	filesChanged: 0,
+	noOp: true,
+});

package/outcomes/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Barrel re-exports for the bundled outcomes + their primitive parts.
+ *
+ * `artifactMdOutcome` is deliberately NOT bundled here — the
+ * `.rpiv/artifacts/<bucket>/<file>.md` layout is an rpiv-pi convention,
+ * not a framework truth. rpiv-pi ships its own `rpivArtifactMdOutcome`
+ * (and `rpivArtifactCollector` / `rpivBucketCollector` helpers) built on
+ * top of the framework primitives re-exported from `./collectors` and
+ * `./parsers`.
+ */
+
+export * from "./collectors/index.js";
+export {
+	type GitCommitData,
+	type GitHeadSnapshot,
+	gitCommitCollector,
+	gitCommitOutcome,
+	gitCommitParser,
+	gitHeadSnapshot,
+} from "./git-commit.js";
+export * from "./parsers/index.js";
+export { noopCollector, sideEffectOutcome } from "./side-effect.js";

package/outcomes/parsers/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Bundled parsers — host-agnostic primitives that turn collected
+ * artifacts into the typed `output.data` channel downstream stages
+ * see. Re-exported through `outcomes/index.ts`.
+ *
+ * Format-specific parsers (`frontmatterParser` for markdown-with-YAML)
+ * live in the convention layer that owns them — rpiv-pi ships its
+ * own. The framework ships only universal interpretations.
+ */
+
+export { jsonBodyParser } from "./json-body.js";