@markjaquith/agency 2.10.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"
 
@@ -159,6 +159,7 @@ describe("CLI", () => {
 			["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)
@@ -221,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)
@@ -243,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/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

@@ -12,6 +12,7 @@ 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)
@@ -143,6 +144,7 @@ status: open
 				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 },
+		])
+	})
+})

package/src/graph-schema.ts

@@ -0,0 +1,255 @@
+import { Schema } from "@effect/schema"
+import {
+	EpicFrontmatter,
+	PhaseFrontmatter,
+	TaskFrontmatter,
+	WorkStatus,
+} from "./workbase/schemas"
+
+export const GRAPH_VERSION = 1 as const
+
+export const GraphNodeKind = Schema.Literal(
+	"epic",
+	"task",
+	"phase",
+	"repository",
+	"execution-unit",
+)
+
+export const GraphEdgeKind = Schema.Literal(
+	"owns",
+	"depends_on",
+	"writes",
+	"references",
+)
+
+export const GraphInclude = Schema.Literal("bodies", "workspace", "git", "pr")
+
+export const GraphBlocker = Schema.Struct({
+	kind: Schema.Literal("dependency", "validation", "status"),
+	id: Schema.String,
+	status: Schema.optional(WorkStatus),
+	reason: Schema.String,
+})
+
+export const GraphProgress = Schema.Struct({
+	status: WorkStatus,
+	total: Schema.Number,
+	open: Schema.Number,
+	working: Schema.Number,
+	delegated: Schema.Number,
+	done: Schema.Number,
+	dropped: Schema.Number,
+	terminal: Schema.Number,
+})
+
+export const GraphReadiness = Schema.Struct({
+	ready: Schema.Boolean,
+	blocked: Schema.Boolean,
+	blockers: Schema.Array(GraphBlocker),
+})
+
+export const GraphWorkbase = Schema.Struct({
+	version: Schema.Literal(2),
+	root: Schema.optional(Schema.String),
+})
+
+export const GraphFilters = Schema.Struct({
+	ready: Schema.NullOr(Schema.Boolean),
+	blocked: Schema.NullOr(Schema.Boolean),
+	statuses: Schema.Array(WorkStatus),
+	repositories: Schema.Array(Schema.String),
+	kinds: Schema.Array(GraphNodeKind),
+})
+
+const DocumentHash = Schema.Struct({ sha256: Schema.String })
+export const GraphEpicData = Schema.extend(EpicFrontmatter, DocumentHash)
+export const GraphTaskData = Schema.extend(TaskFrontmatter, DocumentHash)
+export const GraphPhaseData = Schema.extend(PhaseFrontmatter, DocumentHash)
+export const GraphExecutionData = Schema.extend(
+	PhaseFrontmatter,
+	Schema.Struct({
+		taskId: Schema.String,
+		phaseId: Schema.optional(Schema.String),
+		ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
+		epic: Schema.optional(Schema.String),
+	}),
+)
+
+export const GraphDocumentWorkspace = Schema.Struct({
+	documentPath: Schema.String,
+	directory: Schema.String,
+})
+export const GraphRepositoryWorkspace = Schema.Struct({
+	path: Schema.String,
+	target: Schema.NullOr(Schema.String),
+})
+export const GraphExecutionWorkspace = Schema.Struct({
+	codePath: Schema.String,
+	checkoutPath: Schema.String,
+	materialized: Schema.Boolean,
+})
+export const GraphRepositoryGit = Schema.Struct({
+	kind: Schema.NullOr(Schema.Literal("bare", "repository")),
+	remote: Schema.NullOr(Schema.String),
+	head: Schema.NullOr(Schema.String),
+	branch: Schema.NullOr(Schema.String),
+})
+export const GraphExecutionGit = Schema.Struct({
+	branch: Schema.String,
+	base: Schema.String,
+	branchCommit: Schema.NullOr(Schema.String),
+	baseCommit: Schema.NullOr(Schema.String),
+	checkoutCommit: Schema.NullOr(Schema.String),
+	checkoutBranch: Schema.NullOr(Schema.String),
+	dirty: Schema.NullOr(Schema.Boolean),
+})
+export const GraphPr = Schema.Union(
+	Schema.Struct({ url: Schema.Null, state: Schema.Literal("none") }),
+	Schema.Struct({ url: Schema.String, state: Schema.Literal("unavailable") }),
+	Schema.Struct({
+		recordedUrl: Schema.String,
+		number: Schema.Number,
+		state: Schema.String,
+		title: Schema.String,
+		isDraft: Schema.Boolean,
+		headRefName: Schema.String,
+		baseRefName: Schema.String,
+		url: Schema.String,
+	}),
+)
+
+const NodeIdentity = {
+	id: Schema.String,
+	key: Schema.String,
+	dependents: Schema.Array(Schema.String),
+	repositories: Schema.Array(Schema.String),
+}
+const StatefulNode = {
+	...NodeIdentity,
+	status: WorkStatus,
+	readiness: GraphReadiness,
+	aggregate: GraphProgress,
+}
+const DocumentNode = {
+	...StatefulNode,
+	body: Schema.optional(Schema.String),
+	workspace: Schema.optional(GraphDocumentWorkspace),
+}
+
+export const GraphNode = Schema.Union(
+	Schema.Struct({
+		...DocumentNode,
+		kind: Schema.Literal("epic"),
+		data: GraphEpicData,
+	}),
+	Schema.Struct({
+		...DocumentNode,
+		kind: Schema.Literal("task"),
+		data: GraphTaskData,
+	}),
+	Schema.Struct({
+		...DocumentNode,
+		kind: Schema.Literal("phase"),
+		data: GraphPhaseData,
+	}),
+	Schema.Struct({
+		...NodeIdentity,
+		kind: Schema.Literal("repository"),
+		status: Schema.Null,
+		readiness: Schema.Null,
+		aggregate: Schema.Null,
+		data: Schema.Struct({ alias: Schema.String }),
+		workspace: Schema.optional(GraphRepositoryWorkspace),
+		git: Schema.optional(GraphRepositoryGit),
+	}),
+	Schema.Struct({
+		...StatefulNode,
+		kind: Schema.Literal("execution-unit"),
+		data: GraphExecutionData,
+		workspace: Schema.optional(GraphExecutionWorkspace),
+		git: Schema.optional(GraphExecutionGit),
+		pr: Schema.optional(GraphPr),
+	}),
+)
+
+export const GraphEdge = Schema.Struct({
+	id: Schema.String,
+	kind: GraphEdgeKind,
+	from: Schema.String,
+	to: Schema.String,
+})
+
+export const AgencyGraph = Schema.Struct({
+	version: Schema.Literal(GRAPH_VERSION),
+	workbase: GraphWorkbase,
+	filters: GraphFilters,
+	includes: Schema.Array(GraphInclude),
+	nodes: Schema.Array(GraphNode),
+	edges: Schema.Array(GraphEdge),
+	summary: GraphProgress,
+	validation: Schema.Struct({
+		valid: Schema.Boolean,
+		issues: Schema.Array(
+			Schema.Struct({ path: Schema.String, message: Schema.String }),
+		),
+	}),
+})
+
+export type GraphNodeKind = Schema.Schema.Type<typeof GraphNodeKind>
+export type GraphEdgeKind = Schema.Schema.Type<typeof GraphEdgeKind>
+export type GraphInclude = Schema.Schema.Type<typeof GraphInclude>
+export type GraphBlocker = Schema.Schema.Type<typeof GraphBlocker>
+export type GraphProgress = Schema.Schema.Type<typeof GraphProgress>
+export type GraphReadiness = Schema.Schema.Type<typeof GraphReadiness>
+export type GraphExecutionWorkspace = Schema.Schema.Type<
+	typeof GraphExecutionWorkspace
+>
+export type GraphExecutionGit = Schema.Schema.Type<typeof GraphExecutionGit>
+export type GraphRepositoryGit = Schema.Schema.Type<typeof GraphRepositoryGit>
+export type GraphPr = Schema.Schema.Type<typeof GraphPr>
+export type GraphNode = Schema.Schema.Type<typeof GraphNode>
+export type GraphEdge = Schema.Schema.Type<typeof GraphEdge>
+export type AgencyGraph = Schema.Schema.Type<typeof AgencyGraph>
+
+export type GraphJsonlRecord =
+	| {
+			readonly version: typeof GRAPH_VERSION
+			readonly type: "meta"
+			readonly graph: Omit<AgencyGraph, "nodes" | "edges">
+	  }
+	| {
+			readonly version: typeof GRAPH_VERSION
+			readonly type: "node"
+			readonly node: GraphNode
+	  }
+	| {
+			readonly version: typeof GRAPH_VERSION
+			readonly type: "edge"
+			readonly edge: GraphEdge
+	  }
+	| {
+			readonly version: typeof GRAPH_VERSION
+			readonly type: "end"
+			readonly nodeCount: number
+			readonly edgeCount: number
+	  }
+
+export function* graphJsonlRecords(
+	graph: AgencyGraph,
+): Generator<GraphJsonlRecord> {
+	const { nodes, edges, ...metadata } = graph
+	yield { version: GRAPH_VERSION, type: "meta", graph: metadata }
+	for (const node of nodes) {
+		yield { version: GRAPH_VERSION, type: "node", node }
+	}
+	for (const edge of edges) {
+		yield { version: GRAPH_VERSION, type: "edge", edge }
+	}
+	yield {
+		version: GRAPH_VERSION,
+		type: "end",
+		nodeCount: nodes.length,
+		edgeCount: edges.length,
+	}
+}

package/src/protocol.ts

@@ -90,6 +90,11 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 		remediation:
 			"Run the command from an Agency entity or provide a valid target.",
 	},
+	GraphError: {
+		code: "GRAPH_ERROR",
+		retryable: false,
+		remediation: "Correct the workbase graph data or filters and retry.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",