@markjaquith/agency 1.11.1 → 2.0.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/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,
+})

package/src/commands/base.test.ts

@@ -1,198 +0,0 @@
-import { describe, test, expect, beforeEach, afterEach } from "bun:test"
-import { base } from "./base"
-import {
-	createTempDir,
-	cleanupTempDir,
-	initGitRepo,
-	getGitConfig,
-	runTestEffect,
-} from "../test-utils"
-import { getBaseBranchFromMetadata, writeAgencyMetadata } from "../types"
-
-describe("base", () => {
-	let testDir: string
-	let originalCwd: string
-
-	beforeEach(async () => {
-		originalCwd = process.cwd()
-		testDir = await createTempDir()
-		await initGitRepo(testDir)
-		process.chdir(testDir)
-	})
-
-	afterEach(async () => {
-		process.chdir(originalCwd)
-		await cleanupTempDir(testDir)
-	})
-
-	describe("base set", () => {
-		test("sets base branch for current branch", async () => {
-			// Create a feature branch
-			await Bun.spawn(["git", "checkout", "-b", "feature"], {
-				cwd: testDir,
-				stdout: "pipe",
-				stderr: "pipe",
-			}).exited
-
-			// Create agency.json first
-			await writeAgencyMetadata(testDir, {
-				version: 1 as const,
-				template: "test",
-				injectedFiles: [],
-				createdAt: new Date().toISOString(),
-			} as any)
-
-			// Set base branch
-			await runTestEffect(
-				base({
-					subcommand: "set",
-					args: ["main"],
-					silent: true,
-				}),
-			)
-
-			// Verify it was saved
-			const savedBase = await getBaseBranchFromMetadata(testDir)
-			expect(savedBase).toBe("main")
-		})
-
-		test("sets repository-level default base branch", async () => {
-			// Set repo-level base branch
-			await runTestEffect(
-				base({
-					subcommand: "set",
-					args: ["main"],
-					repo: true,
-					silent: true,
-				}),
-			)
-
-			// Verify it was saved to git config
-			const savedBase = await getGitConfig("agency.baseBranch", testDir)
-			expect(savedBase).toBe("main")
-		})
-
-		test("throws error if base branch does not exist", async () => {
-			await expect(
-				runTestEffect(
-					base({
-						subcommand: "set",
-						args: ["nonexistent"],
-						silent: true,
-					}),
-				),
-			).rejects.toThrow("does not exist")
-		})
-	})
-
-	describe("base get", () => {
-		test("gets base branch for current branch", async () => {
-			// Create a feature branch
-			await Bun.spawn(["git", "checkout", "-b", "feature"], {
-				cwd: testDir,
-				stdout: "pipe",
-				stderr: "pipe",
-			}).exited
-
-			// Create agency.json with base branch
-			await writeAgencyMetadata(testDir, {
-				version: 1,
-				template: "test",
-				injectedFiles: [],
-				baseBranch: "main",
-				createdAt: new Date().toISOString(),
-			} as any)
-
-			// Mock console.log to capture output
-			const logs: string[] = []
-			const originalLog = console.log
-			console.log = (...args: any[]) => logs.push(args.join(" "))
-
-			try {
-				await runTestEffect(
-					base({
-						subcommand: "get",
-						args: [],
-						silent: false,
-					}),
-				)
-				expect(logs[0]).toBe("main")
-			} finally {
-				console.log = originalLog
-			}
-		})
-
-		test("throws error if no base branch configured", async () => {
-			// Create a feature branch
-			await Bun.spawn(["git", "checkout", "-b", "feature"], {
-				cwd: testDir,
-				stdout: "pipe",
-				stderr: "pipe",
-			}).exited
-
-			// Create agency.json without base branch
-			await writeAgencyMetadata(testDir, {
-				version: 1,
-				template: "test",
-				injectedFiles: [],
-				createdAt: new Date().toISOString(),
-			} as any)
-
-			await expect(
-				runTestEffect(
-					base({
-						subcommand: "get",
-						args: [],
-						silent: true,
-					}),
-				),
-			).rejects.toThrow("No base branch configured")
-		})
-	})
-
-	describe("base command", () => {
-		test("requires subcommand", async () => {
-			await expect(
-				runTestEffect(base({ args: [], silent: true })),
-			).rejects.toThrow("Subcommand is required")
-		})
-
-		test("handles 'set' subcommand", async () => {
-			await Bun.spawn(["git", "checkout", "-b", "feature"], {
-				cwd: testDir,
-				stdout: "pipe",
-				stderr: "pipe",
-			}).exited
-
-			await writeAgencyMetadata(testDir, {
-				version: 1,
-				template: "test",
-				injectedFiles: [],
-				createdAt: new Date().toISOString(),
-			} as any)
-
-			await runTestEffect(
-				base({
-					subcommand: "set",
-					args: ["main"],
-					silent: true,
-				}),
-			)
-
-			const savedBase = await getBaseBranchFromMetadata(testDir)
-			expect(savedBase).toBe("main")
-		})
-
-		test("throws error for unknown subcommand", async () => {
-			await expect(
-				runTestEffect(
-					base({
-						subcommand: "unknown",
-						args: [],
-						silent: true,
-					}),
-				),
-			).rejects.toThrow("Unknown subcommand")
-		})
-	})
-})