@markjaquith/agency 2.28.1 → 2.30.0

package/src/services/SyncService.test.ts

@@ -68,6 +68,42 @@ JSON
 		await cleanupTempDir(root)
 	})
 
+	test("validates before applying repository setup", async () => {
+		await rm(join(root, "repos/agency"), { recursive: true, force: true })
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: { remote: "https://example.com/agency.git" },
+				},
+			}),
+		)
+		await mkdir(join(root, "tasks/invalid"), { recursive: true })
+		await Bun.write(
+			join(root, "tasks/invalid/TASK.md"),
+			`---
+ticketUrl: null
+repo: unknown
+branch: task/invalid
+base: main
+pr: null
+---
+`,
+		)
+
+		await expect(
+			runTestEffect(
+				SyncService.pipe(
+					Effect.flatMap((service) =>
+						service.reconcile({ cwd: root, apply: true }),
+					),
+				),
+			),
+		).rejects.toThrow("Unknown repository alias 'unknown'")
+		expect(await Bun.file(join(root, "repos/agency")).exists()).toBe(false)
+	})
+
 	test("observes drift without mutation and applies only safe transitions", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/SyncService.ts

@@ -21,6 +21,10 @@ import { PhaseService } from "./PhaseService"
 import { TaskService } from "./TaskService"
 import { WorkbaseService } from "./WorkbaseService"
 import { WorktreeService } from "./WorktreeService"
+import {
+	RepositoryService,
+	type RepositorySetupResult,
+} from "./RepositoryService"
 
 class SyncError extends Data.TaggedError("SyncError")<{
 	readonly message: string
@@ -93,6 +97,7 @@ interface SyncResult {
 	readonly warnings: readonly SyncNotice[]
 	readonly unresolved: readonly SyncNotice[]
 	readonly executions: readonly ExecutionSyncState[]
+	readonly repositories: RepositorySetupResult
 }
 
 const parseWorktrees = (output: string): RegisteredWorktree[] => {
@@ -150,6 +155,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const phases = yield* PhaseService
 				const worktrees = yield* WorktreeService
 				const claims = yield* ClaimService
+				const repositories = yield* RepositoryService
 				const { root, config } = yield* workbase.loadConfig(options.cwd)
 				const validation = yield* workbase.validate(root)
 				if (!validation.valid) {
@@ -159,12 +165,24 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							.join("\n"),
 					})
 				}
+				const repositorySetup = yield* repositories.setup({
+					cwd: root,
+					apply: options.apply === true,
+				})
 
 				const apply = options.apply === true
 				const now = options.now ?? new Date()
 				const changes: SyncChange[] = []
 				const warnings: SyncNotice[] = []
 				const unresolved: SyncNotice[] = []
+				for (const issue of repositorySetup.unresolved) {
+					unresolved.push({
+						kind: `repository-${issue.state}`,
+						target: `repository:${issue.alias}`,
+						message: issue.message,
+						action: issue.action,
+					})
+				}
 				const executions: ExecutionSyncState[] = []
 				const runExternal = (
 					args: readonly string[],
@@ -240,7 +258,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								kind: "missing-repository",
 								target: record.key,
 								message: `Repository alias '${checkout.repo}' is missing`,
-								action: "Restore or relink the repository alias",
+								action: "Run 'agency repo setup --apply' or relink the alias",
 							})
 							workspaceConflict = true
 							continue
@@ -822,6 +840,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					warnings,
 					unresolved,
 					executions,
+					repositories: repositorySetup,
 				} satisfies SyncResult
 			}),
 	}),

package/src/services/TaskService.ts

@@ -140,7 +140,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					})
 				}
 				for (const alias of referencedRepos) {
-					if (!(yield* fs.exists(join(root, "repos", alias)))) {
+					if (!(yield* workbase.hasRepositoryAlias(alias, root))) {
 						return yield* new TaskError({
 							message: `Unknown repository alias '${alias}'`,
 						})

package/src/services/WorkbaseService.test.ts

@@ -41,6 +41,38 @@ describe("WorkbaseService", () => {
 		).toBe(false)
 	})
 
+	test("treats declared but missing repositories as valid aliases", async () => {
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				repositories: {
+					agency: { remote: "https://example.com/agency.git" },
+				},
+			}),
+		)
+		await write(
+			root,
+			"tasks/portable/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: task/portable
+base: main
+pr: null
+---
+`,
+		)
+
+		const report = await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.validate(root))),
+		)
+
+		expect(report.valid).toBe(true)
+		expect(report.issues).toEqual([])
+	})
+
 	test("registers canonical workbase paths without duplicates", async () => {
 		const workbaseRoot = join(root, "workbase")
 		const nested = join(workbaseRoot, "nested")

package/src/services/WorkbaseService.ts

@@ -323,6 +323,27 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 					return { root, config: decoded.value }
 				}),
 
+			repositoryAliases: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* WorkbaseService
+					const fs = yield* FileSystemService
+					const { root, config } = yield* service.loadConfig(startPath)
+					const aliases = new Set(Object.keys(config.repositories ?? {}))
+					const reposPath = join(root, "repos")
+					if (yield* fs.isDirectory(reposPath)) {
+						for (const entry of yield* fs.readDirectory(reposPath)) {
+							if (!entry.name.startsWith(".agency-")) aliases.add(entry.name)
+						}
+					}
+					return [...aliases].sort()
+				}),
+
+			hasRepositoryAlias: (alias: string, startPath: string = process.cwd()) =>
+				WorkbaseService.pipe(
+					Effect.flatMap((service) => service.repositoryAliases(startPath)),
+					Effect.map((aliases) => aliases.includes(alias)),
+				),
+
 			register: (startPath: string, configDirectory?: string, name?: string) =>
 				Effect.gen(function* () {
 					const service = yield* WorkbaseService
@@ -584,20 +605,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								.sort()
 						})
 
-					const readAliases = Effect.gen(function* () {
-						const reposPath = join(root, "repos")
-						if (!(yield* fs.isDirectory(reposPath))) {
-							return new Set<string>()
-						}
-						const entries = yield* fs.readDirectory(reposPath)
-						return new Set(
-							entries
-								.filter((entry) => entry.isDirectory || entry.isSymlink)
-								.map((entry) => entry.name),
-						)
-					})
-
-					const aliases = yield* readAliases
+					const aliases = new Set(yield* service.repositoryAliases(root))
 
 					const readDocument = <S extends Schema.Schema.AnyNoContext>(
 						path: string,

package/src/services/WorktreeLock.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdtemp, readdir, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { withWorktreeLocks } from "./WorktreeLock"
+
+const createTempDir = () => mkdtemp(join(tmpdir(), "agency-lock-test-"))
+const cleanupTempDir = (path: string) =>
+	rm(path, { recursive: true, force: true })
+
+describe("withWorktreeLocks", () => {
+	const tempDirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(tempDirs.splice(0).map(cleanupTempDir))
+	})
+
+	test("rejects a concurrent operation for the same target", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		let entered!: () => void
+		let release!: () => void
+		const enteredPromise = new Promise<void>((resolve) => {
+			entered = resolve
+		})
+		const releasePromise = new Promise<void>((resolve) => {
+			release = resolve
+		})
+		const held = Effect.runPromise(
+			withWorktreeLocks(
+				root,
+				[{ taskId: "alpha" }],
+				Effect.promise(async () => {
+					entered()
+					await releasePromise
+				}),
+			),
+		)
+		await enteredPromise
+
+		const conflict = await Effect.runPromise(
+			Effect.either(
+				withWorktreeLocks(root, [{ taskId: "alpha" }], Effect.void),
+			),
+		)
+		release()
+		await held
+		expect(conflict).toMatchObject({
+			_tag: "Left",
+			left: {
+				_tag: "WorktreeLockError",
+				message: "Another worktree operation is in progress for 'alpha'",
+			},
+		})
+	})
+
+	test("releases locks when the protected operation fails", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		const failure = new Error("operation failed")
+
+		const result = await Effect.runPromise(
+			Effect.either(
+				withWorktreeLocks(
+					root,
+					[{ taskId: "alpha", phaseId: "build" }],
+					Effect.fail(failure),
+				),
+			),
+		)
+		expect(result._tag).toBe("Left")
+		if (result._tag === "Left") expect(result.left).toBe(failure)
+		await expect(
+			Effect.runPromise(
+				withWorktreeLocks(
+					root,
+					[{ taskId: "alpha", phaseId: "build" }],
+					Effect.succeed("reacquired"),
+				),
+			),
+		).resolves.toBe("reacquired")
+	})
+
+	test("deduplicates targets while keeping task and phase locks distinct", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		let entered!: () => void
+		let release!: () => void
+		const enteredPromise = new Promise<void>((resolve) => {
+			entered = resolve
+		})
+		const releasePromise = new Promise<void>((resolve) => {
+			release = resolve
+		})
+		const held = Effect.runPromise(
+			withWorktreeLocks(
+				root,
+				[
+					{ taskId: "alpha" },
+					{ taskId: "alpha" },
+					{ taskId: "alpha", phaseId: "build" },
+				],
+				Effect.promise(async () => {
+					entered()
+					await releasePromise
+				}),
+			),
+		)
+		await enteredPromise
+
+		expect(
+			(await readdir(root)).filter((path) => path.endsWith(".lock")),
+		).toHaveLength(2)
+
+		release()
+		await held
+		expect(
+			(await readdir(root)).filter((path) => path.endsWith(".lock")),
+		).toEqual([])
+	})
+})

package/src/services/WorktreeService.test.ts

@@ -26,8 +26,16 @@ const git = async (args: string[], cwd?: string) => {
 describe("WorktreeService", () => {
 	let root: string
 	let source: string
+	let effectRepositoryInitialized: boolean
+
+	const ensureEffectRepository = async () => {
+		if (effectRepositoryInitialized) return
+		await git(["clone", "--bare", source, join(root, "repos/effect")])
+		effectRepositoryInitialized = true
+	}
 
 	beforeEach(async () => {
+		effectRepositoryInitialized = false
 		root = await createTempDir()
 		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
 		source = join(root, "source")
@@ -40,12 +48,12 @@ describe("WorktreeService", () => {
 		await git(["-c", "commit.gpgsign=false", "commit", "-m", "initial"], source)
 		await mkdir(join(root, "repos"), { recursive: true })
 		await git(["clone", "--bare", source, join(root, "repos/agency")])
-		await git(["clone", "--bare", source, join(root, "repos/effect")])
 	})
 
 	afterEach(async () => cleanupTempDir(root))
 
 	test("materializes writable and reference worktrees", async () => {
+		await ensureEffectRepository()
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -127,6 +135,7 @@ describe("WorktreeService", () => {
 	})
 
 	test("reuses an immutable reference checkout without fetching", async () => {
+		await ensureEffectRepository()
 		const commit = new TextDecoder()
 			.decode(
 				Bun.spawnSync(
@@ -393,7 +402,7 @@ describe("WorktreeService", () => {
 						{
 							id: "single",
 							ticketUrl: "https://example.com/task",
-							repo: "effect",
+							repo: "agency",
 							branch: "task/single",
 							base: "main",
 						},
@@ -760,6 +769,7 @@ pr: null
 	})
 
 	test("fetches a moving ref before checking a reused reference checkout", async () => {
+		await ensureEffectRepository()
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -801,6 +811,7 @@ pr: null
 	})
 
 	test("rejects a reference checkout attached to a branch", async () => {
+		await ensureEffectRepository()
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -858,6 +869,7 @@ pr: null
 	})
 
 	test("removes worktrees without deleting branches", async () => {
+		await ensureEffectRepository()
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -924,6 +936,7 @@ pr: null
 	})
 
 	test("reports dry-run fetch and worktree changes without mutating", async () => {
+		await ensureEffectRepository()
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -983,6 +996,7 @@ pr: null
 	})
 
 	test("dry-run resolves a reference that exists only on the remote", async () => {
+		await ensureEffectRepository()
 		await git(["checkout", "-b", "remote-only"], source)
 		await Bun.write(join(source, "remote.txt"), "remote\n")
 		await git(["add", "remote.txt"], source)
@@ -1316,6 +1330,7 @@ pr: null
 	})
 
 	test("dry-runs and rebuilds every clean declared checkout", async () => {
+		await ensureEffectRepository()
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>

package/src/services/WorktreeService.ts

@@ -277,7 +277,7 @@ const inspectExecution = (
 			if (!(yield* fs.exists(repositoryPath))) {
 				conflict(
 					"missing-repository",
-					`Repository alias '${checkout.repo}' does not exist`,
+					`Repository alias '${checkout.repo}' is not materialized; run 'agency repo setup --apply'`,
 				)
 				checkouts.push({
 					repo: checkout.repo,
@@ -654,7 +654,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							const checkoutPath = join(codePath, alias)
 							if (!(yield* fs.exists(repositoryPath))) {
 								return yield* new WorktreeError({
-									message: `Repository alias '${alias}' does not exist`,
+									message: `Repository alias '${alias}' is not materialized; run 'agency repo setup --apply'`,
 								})
 							}
 							const listed = yield* fs.runCommand(
@@ -861,7 +861,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								const checkoutPath = join(codePath, alias)
 								if (!(yield* fs.exists(repositoryPath))) {
 									return yield* new WorktreeError({
-										message: `Repository alias '${alias}' does not exist`,
+										message: `Repository alias '${alias}' is not materialized; run 'agency repo setup --apply'`,
 									})
 								}
 

package/src/utils/process.test.ts

@@ -42,9 +42,10 @@ describe("spawnProcess", () => {
 
 	test("captures large stdout and stderr without hanging", async () => {
 		const line = "x".repeat(4096)
+		const lineCount = 256
 		const script = [
 			`const line = ${JSON.stringify(line)}`,
-			"for (let i = 0; i < 2000; i++) {",
+			`for (let i = 0; i < ${lineCount}; i++) {`,
 			"console.log(`out:${i}:${line}`)",
 			"console.error(`err:${i}:${line}`)",
 			"}",
@@ -56,8 +57,8 @@ describe("spawnProcess", () => {
 
 		expect(result.exitCode).toBe(0)
 		expect(result.stdout).toContain("out:0:")
-		expect(result.stdout).toContain("out:1999:")
+		expect(result.stdout).toContain(`out:${lineCount - 1}:`)
 		expect(result.stderr).toContain("err:0:")
-		expect(result.stderr).toContain("err:1999:")
+		expect(result.stderr).toContain(`err:${lineCount - 1}:`)
 	})
 })

package/src/workbase/AGENTS.md

@@ -16,6 +16,11 @@ Use the returned target, document paths and revisions, dependency readiness,
 authority, checkout state, PR state, and validation result. Do not infer these
 from directory names or stale prose.
 
+If context or doctor reports a declared but missing repository, run
+`agency repo setup --dry-run` and obtain explicit approval before
+`agency repo setup --apply`. Missing declared aliases are setup state, not a
+reason to edit `agency.json` or `repos/` by hand.
+
 ## Authority
 
 - An epic or multi-phase task is orchestration context and has no implementation

package/src/workbase/dependency-graph.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test"
+import { findDependencyCycles, validateDependencies } from "./dependency-graph"
+
+describe("dependency graph", () => {
+	test("accepts empty and acyclic dependency graphs", () => {
+		expect(validateDependencies([], "Tasks")).toBeUndefined()
+		expect(
+			validateDependencies(
+				[
+					{ id: "build" },
+					{ id: "test", dependsOn: ["build"] },
+					{ id: "ship", dependsOn: ["build", "test"] },
+				],
+				"Tasks",
+			),
+		).toBeUndefined()
+		expect(
+			findDependencyCycles([
+				{ id: "build" },
+				{ id: "test", dependsOn: ["build"] },
+			]),
+		).toEqual([])
+	})
+
+	test("reports duplicate, self, and unknown dependencies precisely", () => {
+		expect(validateDependencies([{ id: "one" }, { id: "one" }], "Tasks")).toBe(
+			"Tasks IDs must be unique",
+		)
+		expect(
+			validateDependencies([{ id: "one", dependsOn: ["one"] }], "Tasks"),
+		).toBe("Task 'one' cannot depend on itself")
+		expect(
+			validateDependencies([{ id: "one", dependsOn: ["missing"] }], "Phases"),
+		).toBe("Unknown phase dependency 'missing'")
+	})
+
+	test("detects cycles deterministically across disconnected graphs", () => {
+		const nodes = [
+			{ id: "delta", dependsOn: ["charlie"] },
+			{ id: "bravo", dependsOn: ["alpha"] },
+			{ id: "charlie", dependsOn: ["delta"] },
+			{ id: "alpha", dependsOn: ["bravo"] },
+		]
+
+		expect(findDependencyCycles(nodes)).toEqual(["bravo", "delta"])
+		expect(validateDependencies(nodes, "Tasks")).toBe(
+			"Task dependency cycle includes 'bravo'",
+		)
+	})
+})

package/src/workbase/schemas.test.ts

@@ -9,8 +9,60 @@ import {
 	WorkStatus,
 	WorkbaseConfig,
 	WorkbaseRegistry,
+	RepositoryRemote,
 } from "./schemas"
 
+describe("portable repository declarations", () => {
+	test("accepts provider-neutral network Git remotes", () => {
+		for (const remote of [
+			"https://example.com/team/repository.git",
+			"ssh://git@example.com/team/repository.git",
+			"git://example.com/team/repository.git",
+			"git@example.com:team/repository.git",
+			"ssh://[2001:db8::1]/team/repository.git",
+		]) {
+			expect(Schema.decodeUnknownSync(RepositoryRemote)(remote)).toBe(remote)
+		}
+	})
+
+	test("rejects local paths, unsupported protocols, and credential-bearing URLs", () => {
+		for (const remote of [
+			"/Users/person/repository.git",
+			"../repository.git",
+			"file:///tmp/repository.git",
+			"https://token@example.com/team/repository.git",
+			"https://user:password@example.com/team/repository.git",
+			"ssh://user:password@example.com/team/repository.git",
+			"ftp://example.com/team/repository.git",
+			"custom://example.com/team/repository.git",
+			"C:/repository.git",
+			"https://example.com/repository.git?token=secret",
+			"ext::printf",
+			"foo::bar",
+			"-host:repository.git",
+			"-oProxyCommand=x@host:repository.git",
+		]) {
+			expect(() => Schema.decodeUnknownSync(RepositoryRemote)(remote)).toThrow()
+		}
+	})
+
+	test("decodes repository declarations in version 2 configs", () => {
+		expect(
+			Schema.decodeUnknownSync(WorkbaseConfig)({
+				version: 2,
+				repositories: {
+					agency: { remote: "https://example.com/agency.git" },
+				},
+			}),
+		).toEqual({
+			version: 2,
+			repositories: {
+				agency: { remote: "https://example.com/agency.git" },
+			},
+		})
+	})
+})
+
 describe("body-of-work descriptions", () => {
 	test("accepts descriptions on epics, tasks, and phases", () => {
 		const epic = Schema.decodeUnknownSync(EpicFrontmatter)({

package/src/workbase/schemas.ts

@@ -13,6 +13,19 @@ export const EntityId = NonEmptyString.pipe(Schema.pattern(IdPattern))
 
 export const RepositoryAlias = NonEmptyString.pipe(Schema.pattern(IdPattern))
 
+// Portable declarations must be usable after cloning the workbase elsewhere.
+// Local paths, file URLs, and credential-bearing HTTP URLs are intentionally
+// excluded; SSH usernames are identities and remain supported.
+export const RepositoryRemote = NonEmptyString.pipe(
+	Schema.pattern(
+		/^(?!-)(?![a-zA-Z]:[\\/])(?!https?:\/\/[^/@\s]+@)(?![a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/@\s]*:[^/@\s]*@)(?:(?:https?|ssh|git):\/\/[^\s?#]+|(?![^\s]*::)(?:[^@\s/:]+@)?[a-zA-Z0-9_.][^@\s/:]*:(?!\/\/)[^\s?#]+)$/,
+	),
+)
+
+export const RepositoryDeclaration = Schema.Struct({
+	remote: RepositoryRemote,
+})
+
 export const RepositoryReference = Schema.Struct({
 	repo: RepositoryAlias,
 	ref: NonEmptyString,
@@ -73,6 +86,9 @@ const DeliveryProvider = Schema.Struct({
 
 export const WorkbaseConfig = Schema.Struct({
 	version: Schema.Literal(2),
+	repositories: Schema.optional(
+		Schema.Record({ key: RepositoryAlias, value: RepositoryDeclaration }),
+	),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	runners: Schema.optional(
@@ -160,6 +176,9 @@ export type WorkbaseRegistration = Schema.Schema.Type<
 >
 export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
+export type RepositoryDeclaration = Schema.Schema.Type<
+	typeof RepositoryDeclaration
+>
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
 export type ClaimRecord = Schema.Schema.Type<typeof ClaimRecord>
 export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>