@markjaquith/agency 2.21.0 → 2.23.0

package/src/services/SyncService.ts

@@ -1,4 +1,4 @@
-import { Data, Effect } from "effect"
+import { Data, Effect, Either } from "effect"
 import { dirname, join, resolve } from "node:path"
 import { documentRevision } from "../workbase/document-revision"
 import type {
@@ -7,7 +7,14 @@ import type {
 	RepositoryReference,
 	TaskFrontmatter,
 	WorkStatus,
+	PullRequestRecord,
 } from "../workbase/schemas"
+import {
+	normalizePullRequestRecord,
+	parseOptionalPullRequestRecord,
+	recordFromGitHubJson,
+	resolveDeliveryCommand,
+} from "../workbase/delivery-command"
 import { ClaimService } from "./ClaimService"
 import { FileSystemService } from "./FileSystemService"
 import { PhaseService } from "./PhaseService"
@@ -143,7 +150,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const phases = yield* PhaseService
 				const worktrees = yield* WorktreeService
 				const claims = yield* ClaimService
-				const root = yield* workbase.discover(options.cwd)
+				const { root, config } = yield* workbase.loadConfig(options.cwd)
 				const validation = yield* workbase.validate(root)
 				if (!validation.valid) {
 					return yield* new SyncError({
@@ -161,12 +168,16 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const executions: ExecutionSyncState[] = []
 				const runExternal = (
 					args: readonly string[],
-					commandOptions?: { readonly cwd?: string },
+					commandOptions?: {
+						readonly cwd?: string
+						readonly env?: Record<string, string>
+					},
 				) =>
 					fs
 						.runCommand(args, {
 							cwd: commandOptions?.cwd,
 							captureOutput: true,
+							env: commandOptions?.env,
 						})
 						.pipe(
 							Effect.catchAll((error) =>
@@ -551,50 +562,127 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						})
 					}
 
-					let pr: Record<string, unknown> = { url: data.pr, state: "none" }
+					const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
+					let current: PullRequestRecord | null = existing
+					let pr: Record<string, unknown> = existing ?? {
+						url: null,
+						state: "none",
+					}
 					let prConflict = false
-					if (data.pr) {
-						const remote = yield* runExternal([
-							"git",
-							"-C",
-							join(root, "repos", data.repo),
-							"remote",
-							"get-url",
-							"origin",
-						])
-						const remoteRepository = remote.stdout
-							.trim()
-							.match(/(?:github\.com[/:])([^/]+\/[^/]+)$/)?.[1]
-							?.replace(/\.git$/, "")
-						const prRepository = data.pr.match(
-							/^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/\d+\/?$/,
-						)?.[1]
-						if (
-							!remoteRepository ||
-							remoteRepository.toLowerCase() !== prRepository?.toLowerCase()
-						) {
-							prConflict = true
-							unresolved.push({
-								kind: "pr-repository-conflict",
+					const repositoryPath = join(root, "repos", data.repo)
+					const remoteName = config.delivery?.remote ?? "origin"
+					const remote = yield* runExternal([
+						"git",
+						"-C",
+						repositoryPath,
+						"remote",
+						"get-url",
+						remoteName,
+					])
+					const remoteRepository = remote.stdout
+						.trim()
+						.replace(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?[^/]+\//i, "")
+						.replace(/^[^:]+:/, "")
+						.replace(/\.git\/?$/, "")
+						.replace(/\/$/, "")
+
+					if (
+						existing &&
+						remoteRepository.toLowerCase() !== existing.repository.toLowerCase()
+					) {
+						prConflict = true
+						unresolved.push({
+							kind: "pr-repository-conflict",
+							target: record.key,
+							message: `Recorded PR repository does not match writable repository remote '${remoteName}'`,
+							action: "Correct the configured remote or recorded PR",
+						})
+					}
+
+					if (config.delivery && remote.exitCode !== 0) {
+						warnings.push({
+							kind: "delivery-remote-unavailable",
+							target: record.key,
+							message: `Could not inspect delivery remote '${remoteName}': ${remote.stderr.trim()}`,
+						})
+					} else if (config.delivery) {
+						const resolved = resolveDeliveryCommand(config.delivery, "query", {
+							repository: remoteRepository,
+							branch: data.branch,
+							base: data.base,
+							draft: existing ? String(existing.draft) : "",
+							url: existing?.url ?? "",
+							identifier: existing?.identifier ?? "",
+						})
+						const queried = yield* runExternal(resolved.argv, {
+							cwd: repositoryPath,
+							env: resolved.environment,
+						})
+						if (queried.exitCode === 0) {
+							const parsed = yield* Effect.try({
+								try: () => parseOptionalPullRequestRecord(queried.stdout),
+								catch: (cause) =>
+									new SyncError({
+										message:
+											cause instanceof Error ? cause.message : String(cause),
+									}),
+							}).pipe(Effect.either)
+							if (Either.isLeft(parsed)) {
+								warnings.push({
+									kind: "pr-provider-invalid-output",
+									target: record.key,
+									message: parsed.left.message,
+								})
+							} else if (
+								parsed.right &&
+								(parsed.right.provider !== config.delivery.provider ||
+									parsed.right.repository.toLowerCase() !==
+										remoteRepository.toLowerCase())
+							) {
+								if (parsed.right) {
+									prConflict = true
+									unresolved.push({
+										kind: "pr-provider-conflict",
+										target: record.key,
+										message:
+											"Delivery provider returned a record for the wrong provider or repository",
+										action: "Correct the delivery provider output",
+									})
+								}
+							} else {
+								current = parsed.right
+								pr = parsed.right ?? { url: null, state: "none" }
+							}
+						} else {
+							pr = existing
+								? { url: existing.url, state: "unavailable" }
+								: { url: null, state: "none" }
+							warnings.push({
+								kind: existing ? "pr-unavailable" : "pr-discovery-unavailable",
 								target: record.key,
 								message:
-									"Recorded PR repository does not match the writable repository origin",
-								action: "Correct the repository origin or recorded PR URL",
+									queried.stderr.trim() || "Could not query delivery provider",
 							})
 						}
+					} else if (existing) {
 						const viewed = yield* runExternal([
 							"gh",
 							"pr",
 							"view",
-							data.pr,
+							existing.url,
 							"--json",
 							"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit",
 						])
 						if (viewed.exitCode === 0) {
-							pr = parseJson(viewed.stdout, pr)
+							const detail = parseJson<Record<string, unknown>>(
+								viewed.stdout,
+								{},
+							)
+							current = recordFromGitHubJson(detail)
+							pr = { ...detail, ...current }
 							if (
-								pr.headRefName !== data.branch ||
-								pr.baseRefName !== data.base
+								detail.headRefName !== data.branch ||
+								detail.baseRefName !== data.base
 							) {
 								prConflict = true
 								unresolved.push({
@@ -605,11 +693,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								})
 							}
 						} else {
-							pr = { url: data.pr, state: "unavailable" }
+							pr = { url: existing.url, state: "unavailable" }
 							warnings.push({
 								kind: "pr-unavailable",
 								target: record.key,
-								message: `Could not inspect ${data.pr}: ${viewed.stderr.trim()}`,
+								message: `Could not inspect ${existing.url}: ${viewed.stderr.trim()}`,
 							})
 						}
 					} else {
@@ -625,7 +713,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								"--json",
 								"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit",
 							],
-							{ cwd: join(root, "repos", data.repo) },
+							{ cwd: repositoryPath },
 						)
 						if (listed.exitCode === 0) {
 							const matches = parseJson<Record<string, unknown>[]>(
@@ -634,31 +722,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							).filter(
 								(item) =>
 									item.headRefName === data.branch &&
-									item.baseRefName === data.base &&
-									typeof item.url === "string",
+									item.baseRefName === data.base,
 							)
 							if (matches.length === 1) {
-								pr = matches[0]!
-								const url = pr.url as string
-								if (apply) {
-									const recorded = yield* claims.reconcile(
-										{
-											taskId: record.taskId,
-											phaseId: record.phaseId,
-											revision,
-											pr: url,
-										},
-										root,
-									)
-									data = recorded.data
-									revision = recorded.revision
-								}
-								changes.push({
-									kind: "record-pr",
-									target: record.key,
-									message: `Record pull request ${url}`,
-									status: apply ? "applied" : "planned",
-								})
+								current = recordFromGitHubJson(matches[0]!)
+								pr = { ...matches[0], ...current }
 							} else if (matches.length > 1) {
 								unresolved.push({
 									kind: "multiple-prs",
@@ -677,8 +745,30 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						}
 					}
 
+					if (current && JSON.stringify(current) !== JSON.stringify(existing)) {
+						if (apply) {
+							const recorded = yield* claims.reconcile(
+								{
+									taskId: record.taskId,
+									phaseId: record.phaseId,
+									revision,
+									pr: current,
+								},
+								root,
+							)
+							data = recorded.data
+							revision = recorded.revision
+						}
+						changes.push({
+							kind: "record-pr",
+							target: record.key,
+							message: `Record pull request ${current.url}`,
+							status: apply ? "applied" : "planned",
+						})
+					}
+
 					if (
-						pr.state === "MERGED" &&
+						current?.merged === true &&
 						!prConflict &&
 						data.status !== "done" &&
 						data.status !== "dropped"

package/src/services/TaskPhaseService.test.ts

@@ -211,7 +211,15 @@ describe("task and phase services", () => {
 			repos: [{ repo: "effect", ref: "main" }],
 			branch: "task/single",
 			base: "main",
-			pr: "https://github.com/example/agency/pull/42",
+			pr: {
+				provider: "github",
+				repository: "example/agency",
+				identifier: "42",
+				url: "https://github.com/example/agency/pull/42",
+				state: "open",
+				draft: false,
+				merged: false,
+			},
 			status: "open",
 		})
 	})

package/src/services/TaskService.ts

@@ -16,6 +16,7 @@ import {
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
+import { documentRevision } from "../workbase/document-revision"
 
 class TaskError extends Data.TaggedError("TaskError")<{
 	readonly message: string
@@ -25,6 +26,7 @@ interface TaskRecord {
 	readonly id: string
 	readonly path: string
 	readonly content: string
+	readonly revision: string
 	readonly data: TaskData
 }
 
@@ -158,7 +160,13 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					yield* fs.writeFile(parentEpic.path, updated)
 				}
 
-				return { id, path, content, data } satisfies TaskRecord
+				return {
+					id,
+					path,
+					content,
+					revision: documentRevision(content),
+					data,
+				} satisfies TaskRecord
 			}),
 
 		list: (startPath: string = process.cwd()) =>
@@ -178,7 +186,13 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					const content = yield* fs.readFile(path)
 					const parsed = yield* parseFrontmatter(content, path)
 					const data = yield* decodeTask(parsed.data)
-					records.push({ id: entry.name, path, content, data })
+					records.push({
+						id: entry.name,
+						path,
+						content,
+						revision: documentRevision(content),
+						data,
+					})
 				}
 				return records
 			}),
@@ -233,7 +247,12 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				const data = { ...record.data, status: validStatus }
 				const content = formatMarkdownDocument(data, parsed.body)
 				yield* fs.writeFile(record.path, content)
-				return { ...record, content, data } satisfies TaskRecord
+				return {
+					...record,
+					content,
+					revision: documentRevision(content),
+					data,
+				} satisfies TaskRecord
 			}),
 	}),
 }) {}

package/src/services/WorkbaseService.ts

@@ -22,6 +22,7 @@ import {
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
 import { validateRunners } from "../workbase/runner-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
+import { validateDelivery } from "../workbase/delivery-command"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -246,6 +247,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								}
 								try {
 									validateRunners(decoded.value.runners)
+									validateDelivery(decoded.value.delivery)
 								} catch (cause) {
 									return yield* new WorkbaseConfigError({
 										path: configPath,

package/src/work-view.ts

@@ -23,6 +23,7 @@ export interface WorkViewRow {
 	readonly kind: "epic" | "task" | "phase"
 	readonly id: string
 	readonly key: string
+	readonly revision: string
 	readonly parent: string
 	readonly status: WorkStatus
 	readonly readiness: "ready" | "blocked" | "waiting" | "terminal"
@@ -91,6 +92,7 @@ const rowFor = (
 		kind: node.kind,
 		id,
 		key: node.key,
+		revision: node.data.sha256,
 		parent,
 		status: node.status,
 		readiness: readinessLabel(node),

package/src/workbase/delivery-command.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test"
+import {
+	parsePullRequestRecord,
+	resolveDeliveryCommand,
+	validateDelivery,
+} from "./delivery-command"
+
+const delivery = {
+	provider: "forge",
+	remote: "upstream",
+	createCommand: ["forge", "create", "{repository}", "{branch}"],
+	queryCommand: ["forge", "query", "{identifier}"],
+	environment: { FORGE_BASE: "{base}" },
+} as const
+
+const variables = {
+	repository: "example/agency",
+	branch: "feat/example",
+	base: "main",
+	draft: "false",
+	url: "",
+	identifier: "",
+}
+
+describe("delivery commands", () => {
+	test("expands argv and environment without shell evaluation", () => {
+		expect(resolveDeliveryCommand(delivery, "create", variables)).toEqual({
+			argv: ["forge", "create", "example/agency", "feat/example"],
+			environment: { FORGE_BASE: "main" },
+		})
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			validateDelivery({ ...delivery, queryCommand: ["forge", "{unknown}"] }),
+		).toThrow("Unknown delivery provider 'forge' placeholder")
+	})
+
+	test("requires complete and consistent normalized records", () => {
+		const record = {
+			provider: "forge",
+			repository: "example/agency",
+			identifier: "17",
+			url: "https://forge.example/example/agency/pulls/17",
+			state: "merged",
+			draft: false,
+			merged: true,
+		} as const
+		expect(parsePullRequestRecord(JSON.stringify(record))).toEqual(record)
+		expect(() =>
+			parsePullRequestRecord(JSON.stringify({ ...record, merged: false })),
+		).toThrow("inconsistent merge state")
+	})
+})

package/src/workbase/delivery-command.ts

@@ -0,0 +1,135 @@
+import { Schema } from "@effect/schema"
+import type { PullRequestRecord, WorkbaseConfig } from "./schemas"
+import { PullRequestRecord as PullRequestRecordSchema } from "./schemas"
+
+export interface DeliveryCommandVariables {
+	readonly repository: string
+	readonly branch: string
+	readonly base: string
+	readonly draft: string
+	readonly url: string
+	readonly identifier: string
+}
+
+const PLACEHOLDERS = new Set<keyof DeliveryCommandVariables>([
+	"repository",
+	"branch",
+	"base",
+	"draft",
+	"url",
+	"identifier",
+])
+
+const validateTemplate = (provider: string, value: string) => {
+	for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+		const placeholder = match[1]!
+		if (!PLACEHOLDERS.has(placeholder as keyof DeliveryCommandVariables)) {
+			throw new Error(
+				`Unknown delivery provider '${provider}' placeholder: {${placeholder}}`,
+			)
+		}
+	}
+}
+
+export const validateDelivery = (
+	delivery: WorkbaseConfig["delivery"],
+): void => {
+	if (!delivery) return
+	for (const value of [
+		...delivery.createCommand,
+		...delivery.queryCommand,
+		...Object.values(delivery.environment ?? {}),
+	]) {
+		validateTemplate(delivery.provider, value)
+	}
+}
+
+const expand = (value: string, variables: DeliveryCommandVariables) =>
+	value.replaceAll(
+		/\{([^{}]+)\}/g,
+		(match, placeholder: string) =>
+			variables[placeholder as keyof DeliveryCommandVariables] ?? match,
+	)
+
+export const resolveDeliveryCommand = (
+	delivery: NonNullable<WorkbaseConfig["delivery"]>,
+	kind: "create" | "query",
+	variables: DeliveryCommandVariables,
+) => {
+	validateDelivery(delivery)
+	const template =
+		kind === "create" ? delivery.createCommand : delivery.queryCommand
+	return {
+		argv: template.map((argument) => expand(argument, variables)),
+		environment: Object.fromEntries(
+			Object.entries(delivery.environment ?? {}).map(([key, value]) => [
+				key,
+				expand(value, variables),
+			]),
+		),
+	}
+}
+
+const decodeRecord = Schema.decodeUnknownEither(PullRequestRecordSchema, {
+	onExcessProperty: "error",
+})
+
+export const parsePullRequestRecord = (value: string): PullRequestRecord => {
+	let input: unknown
+	try {
+		input = JSON.parse(value)
+	} catch {
+		throw new Error("Delivery provider did not return valid JSON")
+	}
+	const decoded = decodeRecord(input)
+	if (decoded._tag === "Left") {
+		throw new Error(
+			"Delivery provider did not return a valid pull request record",
+		)
+	}
+	if (decoded.right.merged !== (decoded.right.state === "merged")) {
+		throw new Error("Delivery provider returned inconsistent merge state")
+	}
+	return decoded.right
+}
+
+export const parseOptionalPullRequestRecord = (
+	value: string,
+): PullRequestRecord | null => {
+	if (value.trim() === "null") return null
+	return parsePullRequestRecord(value)
+}
+
+const GITHUB_URL = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)\/?$/
+
+export const recordFromGitHubUrl = (url: string): PullRequestRecord => {
+	const match = url.match(GITHUB_URL)
+	if (!match) throw new Error(`Invalid GitHub pull request URL: ${url}`)
+	return {
+		provider: "github",
+		repository: match[1]!,
+		identifier: match[2]!,
+		url,
+		state: "open",
+		draft: false,
+		merged: false,
+	}
+}
+
+export const recordFromGitHubJson = (value: Record<string, unknown>) => {
+	const url = typeof value.url === "string" ? value.url : ""
+	const record = recordFromGitHubUrl(url)
+	const state = String(value.state ?? "OPEN").toLowerCase()
+	return {
+		...record,
+		state:
+			state === "merged" ? "merged" : state === "closed" ? "closed" : "open",
+		draft: value.isDraft === true,
+		merged: state === "merged" || value.mergedAt != null,
+	} satisfies PullRequestRecord
+}
+
+export const normalizePullRequestRecord = (
+	record: PullRequestRecord | string,
+): PullRequestRecord =>
+	typeof record === "string" ? recordFromGitHubUrl(record) : record

package/src/workbase/document-revision.ts

@@ -1,2 +1,18 @@
+import { Data } from "effect"
+
 export const documentRevision = (content: string) =>
 	new Bun.CryptoHasher("sha256").update(content).digest("hex")
+
+export const isDocumentRevision = (revision: string) =>
+	/^[a-f0-9]{64}$/.test(revision)
+
+export class RevisionConflictError extends Data.TaggedError(
+	"RevisionConflictError",
+)<{
+	readonly message: string
+	readonly path: string
+	readonly target?: string
+	readonly expectedRevision: string
+	readonly currentRevision: string
+	readonly claim?: unknown
+}> {}

package/src/workbase/schemas.test.ts

@@ -104,6 +104,41 @@ describe("runner configuration", () => {
 	})
 })
 
+describe("delivery configuration", () => {
+	test("accepts an argv-based create and query provider", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			delivery: {
+				provider: "forge",
+				remote: "upstream",
+				createCommand: ["forge", "create", "{branch}"],
+				queryCommand: ["forge", "query", "{identifier}"],
+			},
+		})
+		expect(config.delivery?.remote).toBe("upstream")
+	})
+
+	test("accepts normalized non-GitHub pull request records", () => {
+		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+			repo: "agency",
+			branch: "feat/example",
+			base: "main",
+			pr: {
+				provider: "forge",
+				repository: "example/agency",
+				identifier: "17",
+				url: "https://forge.example/example/agency/pulls/17",
+				state: "open",
+				draft: false,
+				merged: false,
+			},
+		})
+		expect(phase.pr && typeof phase.pr !== "string" && phase.pr.provider).toBe(
+			"forge",
+		)
+	})
+})
+
 describe("work status", () => {
 	const supportedStatuses: Record<WorkStatus, true> = {
 		open: true,