@markjaquith/agency 2.20.0 → 2.22.0

package/src/commands/task.ts

@@ -10,17 +10,24 @@ import { WorkbaseService } from "../services/WorkbaseService"
 import { choose } from "../utils/chooser"
 import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
+import { GraphMutationService } from "../services/GraphMutationService"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
 	readonly args: readonly string[]
 	readonly ticketUrl?: string
 	readonly description?: string
+	readonly clearDescription?: boolean
+	readonly clearTicket?: boolean
 	readonly epic?: string
 	readonly repo?: string
 	readonly references?: readonly string[]
 	readonly branch?: string
 	readonly base?: string
+	readonly clearReferences?: boolean
+	readonly prUrl?: string
+	readonly clearPr?: boolean
+	readonly noEpic?: boolean
 	readonly multiPhase?: boolean
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
@@ -74,6 +81,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 		const epics = yield* EpicService
 		const repositories = yield* RepositoryService
 		const workbase = yield* WorkbaseService
+		const mutations = yield* GraphMutationService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 
@@ -291,10 +299,95 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 				)
 				return
 			}
+			case "update": {
+				const id = options.args[0]
+				if (!id) return yield* Effect.fail(new Error("Task ID is required"))
+				const output = yield* mutations.updateTask(
+					id,
+					{
+						description: options.clearDescription ? null : options.description,
+						ticketUrl: options.clearTicket ? null : options.ticketUrl,
+						repo: options.repo,
+						repos: options.clearReferences
+							? null
+							: options.references === undefined
+								? undefined
+								: parseRepositoryReferences(options.references),
+						branch: options.branch,
+						base: options.base,
+						pr: options.clearPr ? null : options.prUrl,
+					},
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Updated task '${id}'`,
+				)
+				return
+			}
+			case "rename": {
+				const [id, newId] = options.args
+				if (!id || !newId) {
+					return yield* Effect.fail(
+						new Error("Task ID and new ID are required"),
+					)
+				}
+				const output = yield* mutations.renameTask(id, newId, cwd)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `Renamed task '${id}' to '${newId}'`,
+				)
+				return
+			}
+			case "move": {
+				const id = options.args[0]
+				if (!id) return yield* Effect.fail(new Error("Task ID is required"))
+				const output = yield* mutations.moveTask(
+					id,
+					options.noEpic ? null : (options.epic ?? null),
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: options.noEpic
+							? `Removed task '${id}' from its epic`
+							: `Moved task '${id}' to epic '${options.epic}'`,
+				)
+				return
+			}
+			case "dependency": {
+				const [operation, id, dependencyId] = options.args
+				if (
+					(operation !== "add" && operation !== "remove") ||
+					!id ||
+					!dependencyId
+				) {
+					return yield* Effect.fail(
+						new Error(
+							"Usage: agency task dependency <add|remove> <task-id> <dependency-id>",
+						),
+					)
+				}
+				const output = yield* mutations.mutateTaskDependency(
+					operation,
+					id,
+					dependencyId,
+					cwd,
+				)
+				log(
+					options.json
+						? JSON.stringify(output, null, 2)
+						: `${operation === "add" ? "Added" : "Removed"} dependency '${dependencyId}' ${operation === "add" ? "to" : "from"} task '${id}'`,
+				)
+				return
+			}
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Subcommand is required. Available: new, create, list, show, status",
+						"Subcommand is required. Available: new, create, list, show, status, update, rename, move, dependency",
 					),
 				)
 		}
@@ -309,6 +402,11 @@ Subcommands:
   list                  List tasks
   show <id>             Show a task
   status <id> <status>  Set open, done, or dropped
+  update <id>           Update task metadata
+  rename <id> <new-id>  Rename a task and update graph references
+  move <id>             Move a task with --epic or --no-epic
+  dependency <operation> <task> <dependency>
+                        Add or remove a task dependency
 
 Create options:
   --ticket-url <url>    External ticket URL (optional)
@@ -321,6 +419,15 @@ Create options:
   --base <name>         Base branch (default: main)
   --multi-phase         Create a task container for phases
 
+Update options:
+  --ticket-url <url> / --clear-ticket
+  --description <text> / --clear-description
+  --repo <alias>        Replace the writable repository
+  --reference <alias>:<ref> / --clear-references
+  --branch <name>       Replace the working branch
+  --base <name>         Replace the base branch
+  --pr-url <url> / --clear-pr
+
 Task creation is noninteractive. Single-phase tasks require --repo; use
 --multi-phase instead for a task container. Guided input is available only
 through task new, which fails when --no-input is set or no TTY is available.

package/src/graph-schema.ts

@@ -2,6 +2,7 @@ import { Schema } from "@effect/schema"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
+	PullRequestRecord,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -109,16 +110,7 @@ export const GraphExecutionGit = Schema.Struct({
 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,
-	}),
+	PullRequestRecord,
 )
 
 const NodeIdentity = {

package/src/services/ClaimService.ts

@@ -23,6 +23,7 @@ import {
 	PhaseFrontmatter,
 	TaskFrontmatter,
 	type ClaimRecord,
+	type PullRequestRecord,
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
@@ -98,7 +99,7 @@ interface ReconcileInput {
 	readonly taskId: string
 	readonly phaseId?: string
 	readonly revision: string
-	readonly pr?: string
+	readonly pr?: string | PullRequestRecord
 	readonly status?: "done"
 }
 
@@ -341,7 +342,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 
 			reconcile: (input: ReconcileInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
-					if (input.pr !== undefined && !PR_URL.test(input.pr)) {
+					if (
+						typeof input.pr === "string" &&
+						input.pr !== undefined &&
+						!PR_URL.test(input.pr)
+					) {
 						return yield* new ClaimError({
 							message: `Invalid GitHub pull request URL: ${input.pr}`,
 						})

package/src/services/ContextService.ts

@@ -3,6 +3,7 @@ import { Data, Effect, Either } from "effect"
 import { join, relative, resolve, sep } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
+import { normalizePullRequestRecord } from "../workbase/delivery-command"
 import { RepositoryService } from "./RepositoryService"
 import { aggregateProgress, readinessState } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
@@ -857,10 +858,9 @@ export class ContextService extends Effect.Service<ContextService>()(
 									references: referenceCheckouts,
 									warnings: inspectionWarnings,
 								},
-						pr: {
-							url: executionData?.pr ?? null,
-							state: executionData?.pr ? "recorded" : "none",
-						},
+						pr: executionData?.pr
+							? normalizePullRequestRecord(executionData.pr)
+							: { url: null, state: "none" },
 						validation: {
 							valid: validation.valid,
 							warnings: validation.issues,

package/src/services/GraphMutationService.test.ts

@@ -0,0 +1,336 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { Effect } from "effect"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { EpicService } from "./EpicService"
+import { GraphMutationService } from "./GraphMutationService"
+import { PhaseService } from "./PhaseService"
+import { TaskService } from "./TaskService"
+import {
+	formatMarkdownDocument,
+	parseFrontmatter,
+} from "../workbase/frontmatter"
+
+describe("GraphMutationService", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await mkdir(join(root, "repos/docs"), { recursive: true })
+		await runTestEffect(
+			Effect.gen(function* () {
+				const epics = yield* EpicService
+				const tasks = yield* TaskService
+				const phases = yield* PhaseService
+				yield* epics.create(
+					"first-epic",
+					"https://example.com/first",
+					[{ repo: "agency", ref: "main" }],
+					root,
+				)
+				yield* epics.create(
+					"second-epic",
+					"https://example.com/second",
+					[{ repo: "agency", ref: "main" }],
+					root,
+				)
+				for (const id of ["alpha", "beta", "gamma"]) {
+					yield* tasks.create(
+						{
+							id,
+							ticketUrl: null,
+							epic: "first-epic",
+							repo: "agency",
+							branch: `task/${id}`,
+							base: "main",
+						},
+						root,
+					)
+				}
+				yield* tasks.create(
+					{
+						id: "multi",
+						ticketUrl: "https://example.com/multi",
+						multiPhase: true,
+					},
+					root,
+				)
+				yield* phases.create(
+					{
+						taskId: "multi",
+						id: "build",
+						repo: "agency",
+						branch: "task/multi-build",
+						base: "main",
+					},
+					root,
+				)
+				yield* phases.create(
+					{
+						taskId: "multi",
+						id: "ship",
+						repo: "agency",
+						branch: "task/multi-ship",
+						base: "main",
+					},
+					root,
+				)
+			}),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("updates descriptions, tickets, repositories, and execution metadata", async () => {
+		const output = await runTestEffect(
+			Effect.gen(function* () {
+				const mutations = yield* GraphMutationService
+				yield* mutations.updateEpic(
+					"first-epic",
+					{
+						description: "Updated epic",
+						ticketUrl: "https://example.com/revised",
+						repos: [{ repo: "docs", ref: "trunk" }],
+					},
+					root,
+				)
+				yield* mutations.updateTask(
+					"alpha",
+					{
+						description: "Updated task",
+						ticketUrl: "https://example.com/alpha",
+						repos: [{ repo: "docs", ref: "main" }],
+						branch: "feature/alpha",
+						base: "develop",
+						pr: "https://github.com/example/agency/pull/12",
+					},
+					root,
+				)
+				return yield* mutations.updatePhase(
+					"multi",
+					"build",
+					{
+						description: "Updated phase",
+						repo: "docs",
+						branch: "feature/build",
+						base: "develop",
+					},
+					root,
+				)
+			}),
+		)
+
+		expect(output).toMatchObject({
+			operation: "phase.update",
+			changed: true,
+			validation: { valid: true },
+		})
+		await runTestEffect(
+			Effect.gen(function* () {
+				const epics = yield* EpicService
+				const tasks = yield* TaskService
+				const phases = yield* PhaseService
+				expect((yield* epics.show("first-epic", root)).data).toMatchObject({
+					description: "Updated epic",
+					ticketUrl: "https://example.com/revised",
+					repos: [{ repo: "docs", ref: "trunk" }],
+				})
+				expect((yield* tasks.show("alpha", root)).data).toMatchObject({
+					description: "Updated task",
+					ticketUrl: "https://example.com/alpha",
+					repos: [{ repo: "docs", ref: "main" }],
+					branch: "feature/alpha",
+					base: "develop",
+					pr: "https://github.com/example/agency/pull/12",
+				})
+				expect((yield* phases.show("multi", "build", root)).data).toMatchObject(
+					{
+						description: "Updated phase",
+						repo: "docs",
+						branch: "feature/build",
+						base: "develop",
+					},
+				)
+			}),
+		)
+	})
+
+	test("preserves dependency order and rejects cycles", async () => {
+		await runTestEffect(
+			Effect.gen(function* () {
+				const mutations = yield* GraphMutationService
+				yield* mutations.mutateTaskDependency("add", "beta", "alpha", root)
+				yield* mutations.mutateTaskDependency("add", "beta", "gamma", root)
+				yield* mutations.mutateTaskDependency("remove", "beta", "alpha", root)
+				yield* mutations.mutatePhaseDependency(
+					"add",
+					"multi",
+					"ship",
+					"build",
+					root,
+				)
+			}),
+		)
+		await expect(
+			runTestEffect(
+				Effect.gen(function* () {
+					return yield* (yield* GraphMutationService).mutateTaskDependency(
+						"add",
+						"gamma",
+						"beta",
+						root,
+					)
+				}),
+			),
+		).rejects.toThrow("dependency cycle")
+
+		await expect(
+			runTestEffect(
+				Effect.gen(function* () {
+					return yield* (yield* GraphMutationService).mutateTaskDependency(
+						"add",
+						"beta",
+						"gamma",
+						root,
+					)
+				}),
+			),
+		).rejects.toThrow("already depends")
+
+		await runTestEffect(
+			Effect.gen(function* () {
+				const epics = yield* EpicService
+				const tasks = yield* TaskService
+				const declarations = (yield* epics.show("first-epic", root)).data.tasks
+				expect(
+					declarations.find((item) => item.id === "beta")?.dependsOn,
+				).toEqual(["gamma"])
+				expect((yield* tasks.show("multi", root)).data).toMatchObject({
+					phases: [{ id: "build" }, { id: "ship", dependsOn: ["build"] }],
+				})
+			}),
+		)
+	})
+
+	test("renames entities and rewrites every structured reference", async () => {
+		await runTestEffect(
+			Effect.gen(function* () {
+				const mutations = yield* GraphMutationService
+				yield* mutations.mutateTaskDependency("add", "beta", "alpha", root)
+				yield* mutations.mutatePhaseDependency(
+					"add",
+					"multi",
+					"ship",
+					"build",
+					root,
+				)
+				yield* mutations.renameTask("alpha", "renamed-alpha", root)
+				yield* mutations.renamePhase("multi", "build", "compile", root)
+				yield* mutations.renameEpic("first-epic", "renamed-epic", root)
+			}),
+		)
+
+		await runTestEffect(
+			Effect.gen(function* () {
+				const epics = yield* EpicService
+				const tasks = yield* TaskService
+				const phases = yield* PhaseService
+				const epic = yield* epics.show("renamed-epic", root)
+				expect(
+					epic.data.tasks.find((item) => item.id === "beta")?.dependsOn,
+				).toEqual(["renamed-alpha"])
+				expect((yield* tasks.show("renamed-alpha", root)).data.epic).toBe(
+					"renamed-epic",
+				)
+				expect((yield* tasks.show("multi", root)).data).toMatchObject({
+					phases: [{ id: "compile" }, { id: "ship", dependsOn: ["compile"] }],
+				})
+				expect((yield* phases.show("multi", "compile", root)).id).toBe(
+					"compile",
+				)
+			}),
+		)
+	})
+
+	test("moves task membership in both directions", async () => {
+		await runTestEffect(
+			Effect.gen(function* () {
+				yield* (yield* GraphMutationService).moveTask(
+					"alpha",
+					"second-epic",
+					root,
+				)
+				const epics = yield* EpicService
+				const tasks = yield* TaskService
+				expect(
+					(yield* epics.show("first-epic", root)).data.tasks.map(
+						(item) => item.id,
+					),
+				).not.toContain("alpha")
+				expect(
+					(yield* epics.show("second-epic", root)).data.tasks.map(
+						(item) => item.id,
+					),
+				).toEqual(["alpha"])
+				expect((yield* tasks.show("alpha", root)).data.epic).toBe("second-epic")
+			}),
+		)
+	})
+
+	test("refuses a rename that would invalidate a materialized worktree", async () => {
+		await mkdir(join(root, "tasks/alpha/code/agency"), { recursive: true })
+		await expect(
+			runTestEffect(
+				Effect.gen(function* () {
+					return yield* (yield* GraphMutationService).renameTask(
+						"alpha",
+						"renamed-alpha",
+						root,
+					)
+				}),
+			),
+		).rejects.toThrow("materialized worktree")
+		expect(await Bun.file(join(root, "tasks/alpha/TASK.md")).exists()).toBe(
+			true,
+		)
+		expect(
+			await Bun.file(join(root, "tasks/renamed-alpha/TASK.md")).exists(),
+		).toBe(false)
+	})
+
+	test("refuses rename when the parent backlink is inconsistent", async () => {
+		await runTestEffect(
+			Effect.gen(function* () {
+				const epic = yield* (yield* EpicService).show("first-epic", root)
+				const parsed = yield* parseFrontmatter(epic.content, epic.path)
+				yield* Effect.promise(() =>
+					Bun.write(
+						epic.path,
+						formatMarkdownDocument(
+							{
+								...epic.data,
+								tasks: epic.data.tasks.filter((item) => item.id !== "alpha"),
+							},
+							parsed.body,
+						),
+					),
+				)
+			}),
+		)
+
+		await expect(
+			runTestEffect(
+				Effect.gen(function* () {
+					return yield* (yield* GraphMutationService).renameTask(
+						"alpha",
+						"renamed-alpha",
+						root,
+					)
+				}),
+			),
+		).rejects.toThrow("parent epic 'first-epic' does not list it")
+	})
+})