@markjaquith/agency 1.11.1 → 2.1.0

package/src/workbase/schemas.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "@effect/schema"
+import {
+	EntityId,
+	EpicFrontmatter,
+	PhaseFrontmatter,
+	TaskFrontmatter,
+	WorkbaseConfig,
+} from "./schemas"
+
+describe("body-of-work descriptions", () => {
+	test("accepts descriptions on epics, tasks, and phases", () => {
+		const epic = Schema.decodeUnknownSync(EpicFrontmatter)({
+			ticketUrl: "https://example.com/epic",
+			description: "Coordinate the rollout.",
+			repos: [{ repo: "agency", ref: "main" }],
+			tasks: [],
+		})
+		const singlePhaseTask = Schema.decodeUnknownSync(TaskFrontmatter)({
+			ticketUrl: "https://example.com/task",
+			description: "Deliver the rollout.",
+			repo: "agency",
+			branch: "task/rollout",
+			base: "main",
+			pr: null,
+		})
+		const multiPhaseTask = Schema.decodeUnknownSync(TaskFrontmatter)({
+			ticketUrl: "https://example.com/task",
+			description: "Deliver the rollout in phases.",
+			phases: [],
+		})
+		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+			description: "Introduce the service contract.",
+			repo: "agency",
+			branch: "task/contract",
+			base: "main",
+			pr: null,
+		})
+
+		expect(epic.description).toBe("Coordinate the rollout.")
+		expect(singlePhaseTask.description).toBe("Deliver the rollout.")
+		expect(multiPhaseTask.description).toBe("Deliver the rollout in phases.")
+		expect(phase.description).toBe("Introduce the service contract.")
+	})
+
+	test("allows omitted descriptions for existing documents", () => {
+		const epic = Schema.decodeUnknownSync(EpicFrontmatter)({
+			ticketUrl: "https://example.com/epic",
+			repos: [{ repo: "agency", ref: "main" }],
+			tasks: [],
+		})
+
+		expect(epic.description).toBeUndefined()
+	})
+
+	test("rejects an empty description when present", () => {
+		expect(() =>
+			Schema.decodeUnknownSync(PhaseFrontmatter)({
+				description: "",
+				repo: "agency",
+				branch: "task/contract",
+				base: "main",
+				pr: null,
+			}),
+		).toThrow()
+	})
+})
+
+describe("schema boundaries", () => {
+	const rejects = <S extends Schema.Schema.AnyNoContext>(
+		schema: S,
+		input: unknown,
+	) => {
+		expect(() =>
+			Schema.decodeUnknownSync(schema, { onExcessProperty: "error" })(input),
+		).toThrow()
+	}
+
+	test("rejects invalid boundary values", () => {
+		const cases = [
+			{
+				name: "unsupported config version",
+				schema: WorkbaseConfig,
+				input: { version: 1 },
+			},
+			{
+				name: "excess config fields",
+				schema: WorkbaseConfig,
+				input: { version: 2, legacy: true },
+			},
+			{
+				name: "invalid entity ID",
+				schema: EntityId,
+				input: "invalid/id",
+			},
+			{
+				name: "empty epic repositories",
+				schema: EpicFrontmatter,
+				input: {
+					ticketUrl: "https://example.com/epic",
+					repos: [],
+					tasks: [],
+				},
+			},
+			{
+				name: "mixed task union",
+				schema: TaskFrontmatter,
+				input: {
+					ticketUrl: "https://example.com/task",
+					phases: [],
+					repo: "agency",
+					branch: "task/mixed",
+					base: "main",
+					pr: null,
+				},
+			},
+			{
+				name: "single-phase task missing pr",
+				schema: TaskFrontmatter,
+				input: {
+					ticketUrl: "https://example.com/task",
+					repo: "agency",
+					branch: "task/missing-pr",
+					base: "main",
+				},
+			},
+			{
+				name: "invalid phase PR URL",
+				schema: PhaseFrontmatter,
+				input: {
+					repo: "agency",
+					branch: "task/invalid-pr",
+					base: "main",
+					pr: "https://example.com/pull/1",
+				},
+			},
+		] as const
+
+		for (const fixture of cases) {
+			expect(
+				() => rejects(fixture.schema, fixture.input),
+				fixture.name,
+			).not.toThrow()
+		}
+	})
+})

package/src/workbase/schemas.ts

@@ -0,0 +1,78 @@
+import { Schema } from "@effect/schema"
+
+const NonEmptyString = Schema.String.pipe(Schema.minLength(1))
+
+const Description = Schema.optional(NonEmptyString)
+
+const IdPattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+
+export const EntityId = NonEmptyString.pipe(Schema.pattern(IdPattern))
+
+export const RepositoryAlias = NonEmptyString.pipe(Schema.pattern(IdPattern))
+
+export const RepositoryReference = Schema.Struct({
+	repo: RepositoryAlias,
+	ref: NonEmptyString,
+})
+
+const Url = NonEmptyString.pipe(Schema.pattern(/^[a-zA-Z][a-zA-Z0-9+.-]*:/))
+
+const GitHubPullRequestUrl = NonEmptyString.pipe(
+	Schema.pattern(/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/),
+)
+
+export const WorkbaseConfig = Schema.Struct({
+	version: Schema.Literal(2),
+	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
+})
+
+export const Dependency = Schema.Struct({
+	id: EntityId,
+	dependsOn: Schema.optional(Schema.Array(EntityId)),
+})
+
+const ExecutionUnit = {
+	repo: RepositoryAlias,
+	repos: Schema.optional(Schema.Array(RepositoryReference)),
+	branch: NonEmptyString,
+	base: NonEmptyString,
+	pr: Schema.NullOr(GitHubPullRequestUrl),
+}
+
+export const EpicFrontmatter = Schema.Struct({
+	ticketUrl: Url,
+	description: Description,
+	repos: Schema.NonEmptyArray(RepositoryReference),
+	tasks: Schema.Array(Dependency),
+})
+
+const SinglePhaseTaskFrontmatter = Schema.Struct({
+	ticketUrl: Url,
+	description: Description,
+	epic: Schema.optional(EntityId),
+	...ExecutionUnit,
+})
+
+const MultiPhaseTaskFrontmatter = Schema.Struct({
+	ticketUrl: Url,
+	description: Description,
+	epic: Schema.optional(EntityId),
+	phases: Schema.Array(Dependency),
+})
+
+export const TaskFrontmatter = Schema.Union(
+	SinglePhaseTaskFrontmatter,
+	MultiPhaseTaskFrontmatter,
+)
+
+export const PhaseFrontmatter = Schema.Struct({
+	description: Description,
+	...ExecutionUnit,
+})
+
+export type WorkbaseConfig = Schema.Schema.Type<typeof WorkbaseConfig>
+export type Dependency = Schema.Schema.Type<typeof Dependency>
+export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
+export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
+export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
+export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>

package/src/workbase/work-target.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test"
+import { buildWorkTargetChoices } from "./work-target"
+
+describe("work target choices", () => {
+	test("builds an ordered hierarchy with standalone tasks", () => {
+		const choices = buildWorkTargetChoices(
+			[
+				{
+					id: "delivery",
+					path: "/workbase/epics/delivery/EPIC.md",
+					data: {
+						description: "Ship the release",
+						tasks: [{ id: "multi" }, { id: "single" }],
+					},
+				},
+			],
+			[
+				{
+					id: "multi",
+					path: "/workbase/tasks/multi/TASK.md",
+					data: {
+						phases: [{ id: "build" }, { id: "verify" }],
+					},
+				},
+				{
+					id: "single",
+					path: "/workbase/tasks/single/TASK.md",
+					data: {},
+				},
+				{
+					id: "standalone",
+					path: "/workbase/tasks/standalone/TASK.md",
+					data: { description: "Independent work" },
+				},
+			],
+			[
+				{
+					taskId: "multi",
+					id: "verify",
+					path: "/workbase/tasks/multi/phases/verify/PHASE.md",
+					data: {},
+				},
+				{
+					taskId: "multi",
+					id: "build",
+					path: "/workbase/tasks/multi/phases/build/PHASE.md",
+					data: {},
+				},
+				{
+					taskId: "multi",
+					id: "unlisted",
+					path: "/workbase/tasks/multi/phases/unlisted/PHASE.md",
+					data: {},
+				},
+			],
+		)
+
+		expect(choices.map((choice) => choice.label)).toEqual([
+			"epic  delivery - Ship the release",
+			"  task  multi",
+			"    phase  build",
+			"    phase  verify",
+			"    phase  unlisted",
+			"  task  single",
+			"task  standalone - Independent work",
+		])
+		expect(choices.map((choice) => choice.target.kind)).toEqual([
+			"epic",
+			"task",
+			"phase",
+			"phase",
+			"phase",
+			"task",
+			"task",
+		])
+	})
+})

package/src/workbase/work-target.ts

@@ -0,0 +1,180 @@
+import { Effect } from "effect"
+
+export type WorkTarget =
+	| {
+			readonly kind: "epic"
+			readonly epicId: string
+			readonly path: string
+	  }
+	| {
+			readonly kind: "task"
+			readonly taskId: string
+			readonly path: string
+			readonly multiPhase: boolean
+	  }
+	| {
+			readonly kind: "phase"
+			readonly taskId: string
+			readonly phaseId: string
+			readonly path: string
+	  }
+
+interface EpicRecord {
+	readonly id: string
+	readonly path: string
+	readonly data: {
+		readonly description?: string
+		readonly tasks: readonly { readonly id: string }[]
+	}
+}
+
+interface TaskRecord {
+	readonly id: string
+	readonly path: string
+	readonly data:
+		| {
+				readonly description?: string
+				readonly phases: readonly { readonly id: string }[]
+		  }
+		| { readonly description?: string }
+}
+
+interface PhaseRecord {
+	readonly taskId: string
+	readonly id: string
+	readonly path: string
+	readonly data: { readonly description?: string }
+}
+
+export interface WorkTargetChoice {
+	readonly label: string
+	readonly target: WorkTarget
+}
+
+const label = (
+	indent: string,
+	kind: WorkTarget["kind"],
+	id: string,
+	description?: string,
+) =>
+	`${indent}${kind}  ${id}${description === undefined ? "" : ` - ${description}`}`
+
+const taskChoices = (
+	task: TaskRecord,
+	phaseRecords: readonly PhaseRecord[],
+	indent: string,
+): readonly WorkTargetChoice[] => {
+	const multiPhase = "phases" in task.data
+	const choices: WorkTargetChoice[] = [
+		{
+			label: label(indent, "task", task.id, task.data.description),
+			target: {
+				kind: "task",
+				taskId: task.id,
+				path: task.path,
+				multiPhase,
+			},
+		},
+	]
+	if (!multiPhase) return choices
+
+	const phases = new Map(phaseRecords.map((phase) => [phase.id, phase]))
+	const renderedPhases = new Set<string>()
+	for (const phase of task.data.phases) {
+		const record = phases.get(phase.id)
+		if (!record) continue
+		renderedPhases.add(record.id)
+		choices.push({
+			label: label(`${indent}  `, "phase", record.id, record.data.description),
+			target: {
+				kind: "phase",
+				taskId: task.id,
+				phaseId: record.id,
+				path: record.path,
+			},
+		})
+	}
+	for (const record of phaseRecords) {
+		if (renderedPhases.has(record.id)) continue
+		choices.push({
+			label: label(`${indent}  `, "phase", record.id, record.data.description),
+			target: {
+				kind: "phase",
+				taskId: task.id,
+				phaseId: record.id,
+				path: record.path,
+			},
+		})
+	}
+	return choices
+}
+
+export const buildWorkTargetChoices = (
+	epicRecords: readonly EpicRecord[],
+	taskRecords: readonly TaskRecord[],
+	phaseRecords: readonly PhaseRecord[],
+): readonly WorkTargetChoice[] => {
+	const choices: WorkTargetChoice[] = []
+	const tasks = new Map(taskRecords.map((task) => [task.id, task]))
+	const phases = new Map<string, PhaseRecord[]>()
+	for (const phase of phaseRecords) {
+		const records = phases.get(phase.taskId) ?? []
+		records.push(phase)
+		phases.set(phase.taskId, records)
+	}
+	const nestedTasks = new Set<string>()
+
+	for (const epic of epicRecords) {
+		choices.push({
+			label: label("", "epic", epic.id, epic.data.description),
+			target: { kind: "epic", epicId: epic.id, path: epic.path },
+		})
+		for (const child of epic.data.tasks) {
+			const task = tasks.get(child.id)
+			if (!task || nestedTasks.has(task.id)) continue
+			nestedTasks.add(task.id)
+			choices.push(...taskChoices(task, phases.get(task.id) ?? [], "  "))
+		}
+	}
+
+	for (const task of taskRecords) {
+		if (nestedTasks.has(task.id)) continue
+		choices.push(...taskChoices(task, phases.get(task.id) ?? [], ""))
+	}
+
+	return choices
+}
+
+export type PickWorkTarget = (
+	choices: readonly WorkTargetChoice[],
+) => Effect.Effect<WorkTarget | null, Error>
+
+const parseWorkTargetSelection = (
+	output: string,
+	choices: readonly WorkTargetChoice[],
+) => {
+	const index = Number.parseInt(output.split("\t", 1)[0] ?? "", 10)
+	return choices[index]?.target ?? null
+}
+
+export const pickWorkTarget: PickWorkTarget = (choices) =>
+	Effect.tryPromise({
+		try: async () => {
+			const input = choices
+				.map((choice, index) => `${index}\t${choice.label}`)
+				.join("\n")
+			const process = Bun.spawn(
+				["fzf", "--delimiter=\t", "--with-nth=2..", "--prompt=Work on> "],
+				{ stdin: new Blob([input]), stdout: "pipe", stderr: "inherit" },
+			)
+			const [exitCode, output] = await Promise.all([
+				process.exited,
+				new Response(process.stdout).text(),
+			])
+			if (exitCode === 1 || exitCode === 130) return null
+			if (exitCode !== 0) throw new Error(`fzf exited with code ${exitCode}`)
+			return parseWorkTargetSelection(output, choices)
+		},
+		catch: (cause) =>
+			new Error("Failed to select a work target with fzf", { cause }),
+	})

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

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test"
+import {
+	expandWorktreeCreateCommand,
+	worktreeCommandEnvironment,
+} from "./worktree-command"
+
+const variables = {
+	repo: "/work/repos/app",
+	worktree: "/work/tasks/example/code/app",
+	branch: "task/example",
+	base: "main",
+}
+
+describe("worktree command templates", () => {
+	test("expands argv placeholders without shell interpolation", () => {
+		expect(
+			expandWorktreeCreateCommand(
+				[
+					"tool",
+					"--repo={repo}",
+					"--worktree",
+					"{worktree}",
+					"{branch}",
+					"{base}",
+				],
+				variables,
+			),
+		).toEqual([
+			"tool",
+			"--repo=/work/repos/app",
+			"--worktree",
+			"/work/tasks/example/code/app",
+			"task/example",
+			"main",
+		])
+	})
+
+	test("requires repo and worktree placeholders", () => {
+		expect(() =>
+			expandWorktreeCreateCommand(["tool", "{repo}"], variables),
+		).toThrow("{worktree}")
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			expandWorktreeCreateCommand(
+				["tool", "{repo}", "{worktree}", "{unknown}"],
+				variables,
+			),
+		).toThrow("{unknown}")
+	})
+
+	test("provides equivalent environment variables", () => {
+		expect(worktreeCommandEnvironment(variables)).toEqual({
+			AGENCY_REPO: variables.repo,
+			AGENCY_WORKTREE: variables.worktree,
+			AGENCY_BRANCH: variables.branch,
+			AGENCY_BASE: variables.base,
+		})
+	})
+})

package/src/workbase/worktree-command.ts

@@ -0,0 +1,52 @@
+interface WorktreeCommandVariables {
+	readonly repo: string
+	readonly worktree: string
+	readonly branch: string
+	readonly base: string
+}
+
+const REQUIRED_PLACEHOLDERS = ["repo", "worktree"] as const
+const PLACEHOLDERS = new Set(["repo", "worktree", "branch", "base"])
+
+export const validateWorktreeCreateCommand = (command: readonly string[]) => {
+	const template = command.join("\u0000")
+	for (const placeholder of REQUIRED_PLACEHOLDERS) {
+		if (!template.includes(`{${placeholder}}`)) {
+			throw new Error(
+				`worktreeCreateCommand must include the {${placeholder}} placeholder`,
+			)
+		}
+	}
+	for (const argument of command) {
+		for (const match of argument.matchAll(/\{([^{}]+)\}/g)) {
+			const placeholder = match[1]!
+			if (!PLACEHOLDERS.has(placeholder)) {
+				throw new Error(
+					`Unknown worktreeCreateCommand placeholder: {${placeholder}}`,
+				)
+			}
+		}
+	}
+}
+
+export const expandWorktreeCreateCommand = (
+	command: readonly string[],
+	variables: WorktreeCommandVariables,
+): string[] => {
+	validateWorktreeCreateCommand(command)
+
+	return command.map((argument) =>
+		argument.replaceAll(/\{([^{}]+)\}/g, (match, placeholder: string) => {
+			return variables[placeholder as keyof WorktreeCommandVariables] ?? match
+		}),
+	)
+}
+
+export const worktreeCommandEnvironment = (
+	variables: WorktreeCommandVariables,
+): Record<string, string> => ({
+	AGENCY_REPO: variables.repo,
+	AGENCY_WORKTREE: variables.worktree,
+	AGENCY_BRANCH: variables.branch,
+	AGENCY_BASE: variables.base,
+})