@markjaquith/agency 2.9.0 → 2.11.0

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test"
-import { access, realpath } from "node:fs/promises"
+import { access, mkdir, realpath } from "node:fs/promises"
 import { join } from "node:path"
 import { cleanupTempDir, createTempDir } from "./test-utils"
 
@@ -158,6 +158,8 @@ describe("CLI", () => {
 			["pr", "Usage: agency pr"],
 			["status", "Usage: agency status"],
 			["validate", "Usage: agency validate"],
+			["context", "Usage: agency context"],
+			["graph", "Usage: agency graph"],
 		] as const) {
 			const result = await runCli([command, "--help"])
 			expect(result.exitCode).toBe(0)
@@ -220,6 +222,69 @@ describe("CLI", () => {
 		).toEqual([await realpath(root)])
 	})
 
+	test("exports equivalent JSON and JSONL graph contracts", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		expect((await runCli(["init", root])).exitCode).toBe(0)
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await mkdir(join(root, "tasks/example"), { recursive: true })
+		await Bun.write(
+			join(root, "tasks/example/TASK.md"),
+			`---
+ticketUrl: null
+repo: agency
+branch: feat/example
+base: main
+pr: null
+status: open
+---
+
+# Example
+`,
+		)
+
+		const json = parseJson(
+			await runCli(
+				["graph", "--json", "--include", "bodies", "--kind", "task"],
+				root,
+			),
+		)
+		expect(json).toMatchObject({
+			version: 1,
+			includes: ["bodies"],
+			nodes: [
+				{ id: "task:example", body: expect.stringContaining("# Example") },
+			],
+			edges: [],
+		})
+
+		const streamed = await runCli(
+			["graph", "--jsonl", "--include", "bodies", "--kind", "task"],
+			root,
+		)
+		expect(streamed.exitCode).toBe(0)
+		expect(streamed.stderr).toBe("")
+		const records = streamed.stdout
+			.trim()
+			.split("\n")
+			.map((line) => JSON.parse(line))
+		expect(records.map((record) => record.type)).toEqual([
+			"meta",
+			"node",
+			"end",
+		])
+		const reconstructed = {
+			...records[0].graph,
+			nodes: records
+				.filter((record) => record.type === "node")
+				.map((record) => record.node),
+			edges: records
+				.filter((record) => record.type === "edge")
+				.map((record) => record.edge),
+		}
+		expect(reconstructed).toEqual(json)
+	})
+
 	test("lets JSON override silent and disables interactive task input", async () => {
 		const root = await createTempDir()
 		tempDirs.push(root)
@@ -242,6 +307,24 @@ describe("CLI", () => {
 
 		const version = await runCli(["status", "--version", "--json"])
 		expect(parseJson(version)).toEqual({ version: "0.0.0-development" })
+
+		const jsonlHelp = await runCli(["graph", "--help", "--jsonl"])
+		expect(parseJson(jsonlHelp)).toContain("Usage: agency graph")
+
+		const invalidJsonl = await runCli([
+			"graph",
+			"--jsonl",
+			"--include",
+			"secrets",
+		])
+		expect(invalidJsonl.exitCode).toBe(1)
+		expect(invalidJsonl.stderr).toBe("")
+		expect(invalidJsonl.stdout.trim().split("\n")).toHaveLength(1)
+		expect(JSON.parse(invalidJsonl.stdout)).toMatchObject({
+			version: 1,
+			ok: false,
+			error: { code: "CLI_USAGE" },
+		})
 	})
 
 	test("runs a multi-phase domain workflow through subprocesses", async () => {

package/src/commands/context.test.ts

@@ -0,0 +1,379 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir, rm } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { context } from "./context"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const run = async (cwd: string, args: string[]) => {
+	const process = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" })
+	const [exitCode, stderr] = await Promise.all([
+		process.exited,
+		new Response(process.stderr).text(),
+	])
+	if (exitCode !== 0) throw new Error(`${args.join(" ")}: ${stderr}`)
+}
+
+const readContext = async (
+	root: string,
+	target: string | undefined,
+	compact = false,
+) => {
+	const logs = await captureLogs(() =>
+		runTestEffect(context({ cwd: root, target, compact, json: true })),
+	)
+	expect(logs).toHaveLength(1)
+	return JSON.parse(logs[0]!)
+}
+
+describe("context", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+		for (const repo of ["agency", "docs"]) {
+			const path = join(root, "repos", repo)
+			await mkdir(path, { recursive: true })
+			await run(root, ["git", "init", "--initial-branch=main", path])
+			await run(path, ["git", "config", "user.email", "test@example.com"])
+			await run(path, ["git", "config", "user.name", "Test"])
+			await Bun.write(join(path, "README.md"), `${repo}\n`)
+			await run(path, ["git", "add", "README.md"])
+			await run(path, ["git", "commit", "-m", "initial"])
+		}
+
+		await write(
+			root,
+			"epics/contract/EPIC.md",
+			`---
+ticketUrl: https://example.com/contract
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: foundations
+  - id: agent-contract
+    dependsOn: [foundations]
+---
+
+# Contract
+`,
+		)
+		await write(
+			root,
+			"tasks/foundations/TASK.md",
+			`---
+ticketUrl: null
+epic: contract
+repo: agency
+branch: foundations
+base: main
+pr: https://github.com/example/agency/pull/1
+status: done
+---
+
+# Foundations
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/TASK.md",
+			`---
+ticketUrl: null
+epic: contract
+phases:
+  - id: schema
+  - id: context-command
+    dependsOn: [schema]
+---
+
+# Agent contract
+Task prose.
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/schema/PHASE.md",
+			`---
+repo: agency
+branch: schema
+base: main
+pr: https://github.com/example/agency/pull/2
+status: done
+---
+
+# Schema
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/context-command/PHASE.md",
+			`---
+repo: agency
+repos:
+  - repo: docs
+    ref: main
+branch: feat/context
+base: main
+pr: null
+status: open
+---
+
+# Context command
+Phase prose.
+`,
+		)
+
+		const code = join(root, "tasks/agent-contract/phases/context-command/code")
+		await mkdir(code, { recursive: true })
+		await run(join(root, "repos/agency"), [
+			"git",
+			"worktree",
+			"add",
+			"-b",
+			"feat/context",
+			join(code, "agency"),
+			"main",
+		])
+		await run(join(root, "repos/docs"), [
+			"git",
+			"worktree",
+			"add",
+			"--detach",
+			join(code, "docs"),
+			"main",
+		])
+	})
+
+	afterEach(async () => {
+		await cleanupTempDir(root)
+	})
+
+	test("returns complete phase context with graph, authority, Git, and validation state", async () => {
+		const target = "tasks/agent-contract/phases/context-command"
+		const result = await readContext(root, target)
+
+		expect(result).toMatchObject({
+			projection: "complete",
+			workbase: { root, version: 2 },
+			target: {
+				kind: "phase",
+				taskId: "agent-contract",
+				phaseId: "context-command",
+			},
+			graph: {
+				parent: { kind: "task", id: "agent-contract" },
+				dependencies: ["schema"],
+				readiness: { ready: true, blocked: false, blockers: [] },
+				aggregate: { status: "open", total: 1, open: 1 },
+			},
+			authority: {
+				mode: "execution",
+				writable: { repo: "agency", branch: "feat/context", base: "main" },
+				references: [{ repo: "docs", ref: "main" }],
+			},
+			workspace: {
+				materialization: "complete",
+				writable: {
+					materialized: true,
+					registered: true,
+					checkoutBranch: "feat/context",
+					detached: false,
+				},
+				references: [
+					{
+						repo: "docs",
+						materialized: true,
+						registered: true,
+						detached: true,
+					},
+				],
+			},
+			pr: { url: null, state: "none" },
+			validation: { valid: true, warnings: [] },
+		})
+		expect(result.documents.epic.body).toContain("# Contract")
+		expect(result.documents.task.body).toContain("Task prose.")
+		expect(result.documents.phase.body).toContain("Phase prose.")
+		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.workspace.writable.branchCommit).toMatch(/^[a-f0-9]{40}$/)
+		expect(result.workspace.writable.baseCommit).toMatch(/^[a-f0-9]{40}$/)
+		expect(result.workspace.references[0].resolvedCommit).toMatch(
+			/^[a-f0-9]{40}$/,
+		)
+	})
+
+	test("makes compact projection explicit without omitting essential identity", async () => {
+		const result = await readContext(
+			root,
+			"tasks/agent-contract/phases/context-command/code/agency",
+			true,
+		)
+
+		expect(result.projection).toBe("compact")
+		expect(result.target.kind).toBe("phase")
+		expect(result.documents.phase.body).toBeUndefined()
+		expect(result.documents.phase.data.branch).toBe("feat/context")
+		expect(result.documents.phase.sha256).toMatch(/^[a-f0-9]{64}$/)
+		expect(result.workspace.writable).toEqual({
+			materialized: true,
+			registered: true,
+		})
+		expect(result.authority.writable.checkoutPath).toContain("code/agency")
+	})
+
+	test("reports dependency and validation blockers deterministically", async () => {
+		await write(
+			root,
+			"tasks/agent-contract/phases/schema/PHASE.md",
+			`---
+repo: missing
+branch: schema
+base: main
+pr: null
+status: dropped
+---
+
+# Schema
+`,
+		)
+		const result = await readContext(
+			root,
+			"tasks/agent-contract/phases/context-command",
+		)
+
+		expect(result.graph.readiness.ready).toBe(false)
+		expect(result.graph.readiness.blockers).toContainEqual({
+			kind: "dependency",
+			id: "schema",
+			status: "dropped",
+			reason: "Phase dependency is dropped",
+		})
+		expect(result.validation.valid).toBe(false)
+		expect(result.validation.warnings).toContainEqual({
+			path: "tasks/agent-contract/phases/schema/PHASE.md",
+			message: "Unknown repository alias 'missing'",
+		})
+	})
+
+	test("resolves a bare task ID and rejects a root target", async () => {
+		const task = await readContext(root, "agent-contract")
+		expect(task.target).toMatchObject({
+			kind: "task",
+			taskId: "agent-contract",
+		})
+		expect(task.graph.parent).toEqual({ kind: "epic", id: "contract" })
+
+		await expect(readContext(root, ".")).rejects.toThrow(
+			"Cannot infer an Agency target",
+		)
+	})
+
+	test("resolves bare task IDs from inside another target", async () => {
+		const cwd = join(
+			root,
+			"tasks/agent-contract/phases/context-command/code/agency",
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(context({ cwd, target: "foundations", json: true })),
+		)
+		const result = JSON.parse(logs[0]!)
+		expect(result.target).toMatchObject({ kind: "task", taskId: "foundations" })
+		expect(result.authority.writable.branch).toBe("foundations")
+	})
+
+	test("computes orchestration readiness from runnable descendants", async () => {
+		await write(
+			root,
+			"tasks/agent-contract/TASK.md",
+			`---
+ticketUrl: null
+epic: contract
+phases:
+  - id: schema
+  - id: context-command
+    dependsOn: [schema]
+  - id: parallel
+---
+
+# Agent contract
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/schema/PHASE.md",
+			`---
+repo: agency
+branch: schema
+base: main
+pr: null
+status: working
+---
+
+# Schema
+`,
+		)
+		await write(
+			root,
+			"tasks/agent-contract/phases/parallel/PHASE.md",
+			`---
+repo: docs
+branch: parallel
+base: main
+pr: null
+status: open
+---
+
+# Parallel
+`,
+		)
+
+		const task = await readContext(root, "agent-contract")
+		expect(task.graph.readiness).toMatchObject({ ready: true, blocked: false })
+		expect(task.graph.aggregate).toMatchObject({
+			status: "working",
+			total: 3,
+			open: 2,
+			working: 1,
+		})
+
+		const epic = await readContext(root, "epics/contract")
+		expect(epic.graph.readiness).toMatchObject({ ready: true, blocked: false })
+		expect(epic.graph.aggregate).toMatchObject({
+			status: "working",
+			total: 4,
+			done: 1,
+			open: 2,
+			working: 1,
+		})
+	})
+
+	test("reports stale worktree registration independently of materialization", async () => {
+		const checkout = join(
+			root,
+			"tasks/agent-contract/phases/context-command/code/agency",
+		)
+		await rm(checkout, { recursive: true, force: true })
+
+		const result = await readContext(
+			root,
+			"tasks/agent-contract/phases/context-command",
+		)
+		expect(result.workspace.writable).toMatchObject({
+			materialized: false,
+			registered: true,
+		})
+		expect(result.workspace.materialization).toBe("partial")
+	})
+})

package/src/commands/context.ts

@@ -0,0 +1,29 @@
+import { Effect } from "effect"
+import type { BaseCommandOptions } from "../utils/command"
+import { ContextService } from "../services/ContextService"
+import { createLoggers } from "../utils/effect"
+
+interface ContextOptions extends BaseCommandOptions {
+	readonly target?: string
+	readonly compact?: boolean
+	readonly json?: boolean
+}
+
+export const context = (options: ContextOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* ContextService
+		const { log } = createLoggers(options)
+		const result = yield* service.get(options)
+		log(JSON.stringify(result, null, 2))
+	})
+
+export const help = `
+Usage: agency context [target] [options]
+
+Return the complete, read-only context for an epic, task, or phase. The target
+defaults to the current directory and may be an entity path or task ID.
+
+Options:
+  --json              Output a versioned machine result
+  --compact           Omit prose bodies and low-level Git details
+`

package/src/commands/graph.ts

@@ -0,0 +1,103 @@
+import { Effect } from "effect"
+import {
+	graphJsonlRecords,
+	type GraphInclude,
+	type GraphNodeKind,
+} from "../graph-schema"
+import { GraphService } from "../services/GraphService"
+import type { WorkStatus } from "../workbase/schemas"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface GraphCommandOptions extends BaseCommandOptions {
+	readonly json?: boolean
+	readonly jsonl?: boolean
+	readonly ready?: boolean
+	readonly blocked?: boolean
+	readonly statuses?: readonly string[]
+	readonly repositories?: readonly string[]
+	readonly kinds?: readonly string[]
+	readonly include?: readonly string[]
+}
+
+const allowedStatuses = new Set<WorkStatus>([
+	"open",
+	"working",
+	"delegated",
+	"done",
+	"dropped",
+])
+const allowedKinds = new Set<GraphNodeKind>([
+	"epic",
+	"task",
+	"phase",
+	"repository",
+	"execution-unit",
+])
+const allowedIncludes = new Set<GraphInclude>([
+	"bodies",
+	"workspace",
+	"git",
+	"pr",
+])
+
+const validated = <T extends string>(
+	label: string,
+	values: readonly string[] | undefined,
+	allowed: ReadonlySet<T>,
+): T[] =>
+	(values ?? []).map((value) => {
+		if (!allowed.has(value as T)) {
+			throw new Error(
+				`Invalid --${label} value '${value}'. Expected one of: ${[...allowed].join(", ")}`,
+			)
+		}
+		return value as T
+	})
+
+export const graph = (options: GraphCommandOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* GraphService
+		const { log } = createLoggers(options)
+		const statuses = yield* Effect.sync(() =>
+			validated("status", options.statuses, allowedStatuses),
+		)
+		const kinds = yield* Effect.sync(() =>
+			validated("kind", options.kinds, allowedKinds),
+		)
+		const include = yield* Effect.sync(() =>
+			validated("include", options.include, allowedIncludes),
+		)
+		const result = yield* service.get({
+			cwd: options.cwd,
+			ready: options.ready,
+			blocked: options.blocked,
+			statuses,
+			repositories: options.repositories,
+			kinds,
+			include,
+		})
+		if (options.jsonl) {
+			for (const record of graphJsonlRecords(result)) {
+				process.stdout.write(`${JSON.stringify(record)}\n`)
+			}
+			return
+		}
+		log(JSON.stringify(result, null, 2))
+	})
+
+export const help = `
+Usage: agency graph [options]
+
+Export the workbase as a deterministic, versioned graph.
+
+Options:
+  --json                    Output one versioned machine result
+  --jsonl                   Stream versioned graph records
+  --ready                   Include only ready nodes
+  --blocked                 Include only blocked nodes
+  --status <status>         Filter by status (repeatable)
+  --repository <alias>      Filter by repository (repeatable)
+  --kind <kind>             Filter by entity kind (repeatable)
+  --include <layer>         Include bodies, workspace, git, or pr (repeatable)
+`

package/src/commands/read-only.test.ts

@@ -11,6 +11,8 @@ import { repo } from "./repo"
 import { status } from "./status"
 import { task } from "./task"
 import { validate } from "./validate"
+import { context } from "./context"
+import { graph } from "./graph"
 
 const write = async (root: string, path: string, content: string) => {
 	const fullPath = join(root, path)
@@ -135,6 +137,14 @@ status: open
 		)
 		await runTestEffect(status({ cwd: root, silent: true }))
 		await runTestEffect(validate({ path: root, silent: true }))
+		await runTestEffect(
+			context({
+				target: "tasks/example-task/phases/implementation",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(graph({ cwd: root, silent: true }))
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(

package/src/graph-schema.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test"
+import jsonSchema from "../schemas/agency-graph-v1.schema.json"
+import { graphJsonlRecords, type AgencyGraph } from "./graph-schema"
+
+describe("graph contract", () => {
+	test("publishes the v1 JSON Schema", () => {
+		expect(jsonSchema).toMatchObject({
+			$schema: "https://json-schema.org/draft/2020-12/schema",
+			title: "Agency workbase graph v1",
+			properties: { version: { const: 1 } },
+		})
+		expect(jsonSchema.properties.filters).toMatchObject({
+			additionalProperties: false,
+			required: ["ready", "blocked", "statuses", "repositories", "kinds"],
+		})
+		expect(jsonSchema.$defs.node.allOf).toHaveLength(5)
+		expect(jsonSchema.$defs.node.allOf[3]?.then?.properties).toMatchObject({
+			status: { type: "null" },
+			readiness: { type: "null" },
+			aggregate: { type: "null" },
+		})
+	})
+
+	test("streams records that reconstruct graph semantics", () => {
+		const graph = {
+			version: 1,
+			workbase: { version: 2 },
+			filters: {
+				ready: null,
+				blocked: null,
+				statuses: [],
+				repositories: [],
+				kinds: [],
+			},
+			includes: [],
+			nodes: [],
+			edges: [],
+			summary: {
+				status: "open",
+				total: 0,
+				open: 0,
+				working: 0,
+				delegated: 0,
+				done: 0,
+				dropped: 0,
+				terminal: 0,
+			},
+			validation: { valid: true, issues: [] },
+		} satisfies AgencyGraph
+		const records = [...graphJsonlRecords(graph)]
+		const { nodes: _nodes, edges: _edges, ...metadata } = graph
+		expect(records).toEqual([
+			{
+				version: 1,
+				type: "meta",
+				graph: metadata,
+			},
+			{ version: 1, type: "end", nodeCount: 0, edgeCount: 0 },
+		])
+	})
+})