@markjaquith/agency 2.22.0 → 2.24.0

package/src/commands/epic.test.ts

@@ -40,9 +40,12 @@ describe("epic command", () => {
 			),
 		)
 
-		expect(JSON.parse(logs[0]!)).toEqual({
+		const created = JSON.parse(logs[0]!)
+		expect(created.revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(created).toEqual({
 			id: "example",
 			path: join(root, "epics/example/EPIC.md"),
+			revision: created.revision,
 			data: {
 				ticketUrl: "https://example.com/epic",
 				repos: [{ repo: "agency", ref: "main" }],
@@ -68,10 +71,13 @@ describe("epic command", () => {
 				epic({ subcommand: "list", args: [], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				id: "example",
 				path: join(root, "epics/example/EPIC.md"),
+				revision: listed[0].revision,
 				data: {
 					ticketUrl: "https://example.com/epic",
 					repos: [{ repo: "agency", ref: "main" }],
@@ -90,9 +96,12 @@ describe("epic command", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			id: "example",
 			path: join(root, "epics/example/EPIC.md"),
+			revision: shown.revision,
 			data: {
 				ticketUrl: "https://example.com/epic",
 				repos: [{ repo: "agency", ref: "main" }],

package/src/commands/epic.ts

@@ -13,6 +13,7 @@ interface EpicOptions extends BaseCommandOptions {
 	readonly ticketUrl?: string
 	readonly description?: string
 	readonly clearDescription?: boolean
+	readonly ifRevision?: string
 	readonly repos?: readonly string[]
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
@@ -122,6 +123,7 @@ export const epic = (options: EpicOptions) =>
 								: parseRepositoryReferences(options.repos),
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -138,7 +140,12 @@ export const epic = (options: EpicOptions) =>
 						new Error("Epic ID and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renameEpic(id, newId, cwd)
+				const output = yield* mutations.renameEpic(
+					id,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -177,6 +184,9 @@ Update options:
   --clear-description   Remove the description
   --repo <alias>:<ref>  Replace repository references; repeatable
 
+Mutation options:
+  --if-revision <hash>  Require the target's current revision
+
 Options:
   --json                Output results as JSON
   --status <status>     Filter list by status; repeatable

package/src/commands/phase.ts

@@ -19,6 +19,7 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly clearReferences?: boolean
 	readonly prUrl?: string
 	readonly clearPr?: boolean
+	readonly ifRevision?: string
 	readonly dependsOn?: readonly string[]
 	readonly firstPhase?: string
 	readonly json?: boolean
@@ -181,6 +182,7 @@ export const phase = (options: PhaseOptions) =>
 						pr: options.clearPr ? null : options.prUrl,
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -196,7 +198,13 @@ export const phase = (options: PhaseOptions) =>
 						new Error("Task ID, phase ID, and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renamePhase(taskId, phaseId, newId, cwd)
+				const output = yield* mutations.renamePhase(
+					taskId,
+					phaseId,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -225,6 +233,7 @@ export const phase = (options: PhaseOptions) =>
 					dependencyPhaseId,
 					dependencyId,
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -257,6 +266,9 @@ Subcommands:
   dependency <operation> <task> <phase> <dependency>
                         Add or remove a phase dependency
 
+Mutation option:
+  --if-revision <hash>  Require the target's current revision
+
 Create options:
   --description <text>  Short description of the phase
   --repo <alias>        Writable repository

package/src/commands/restore.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { archive } from "./archive"
+import { restore } from "./restore"
+import { task } from "./task"
+
+describe("restore command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		const initialized = Bun.spawnSync([
+			"git",
+			"init",
+			"--bare",
+			join(root, "repos/agency"),
+		])
+		if (initialized.exitCode !== 0)
+			throw new Error(new TextDecoder().decode(initialized.stderr))
+		await runTestEffect(
+			task({
+				subcommand: "create",
+				args: ["example"],
+				repo: "agency",
+				branch: "task/example",
+				base: "main",
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("dry-runs then restores an archived task", async () => {
+		const preview = await captureLogs(() =>
+			runTestEffect(
+				restore({
+					type: "task",
+					args: ["example"],
+					cwd: root,
+					dryRun: true,
+				}),
+			),
+		)
+		expect(preview[0]).toContain("Would restore task 'example'")
+		expect(await Bun.file(join(root, "tasks/example/TASK.md")).exists()).toBe(
+			false,
+		)
+
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				restore({ type: "task", args: ["example"], cwd: root, json: true }),
+			),
+		)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "restore",
+			kind: "task",
+			id: "example",
+			dryRun: false,
+		})
+		expect(await Bun.file(join(root, "tasks/example/TASK.md")).exists()).toBe(
+			true,
+		)
+	})
+
+	test("lists and shows archived work", async () => {
+		const listed = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					type: "list",
+					args: [],
+					kinds: ["task"],
+					repositories: ["agency"],
+					cwd: root,
+				}),
+			),
+		)
+		expect(listed).toEqual(["task\texample"])
+
+		const shown = await captureLogs(() =>
+			runTestEffect(
+				archive({ type: "show", args: ["task", "example"], cwd: root }),
+			),
+		)
+		expect(shown[0]).toContain("# Example")
+	})
+})

package/src/commands/restore.ts

@@ -0,0 +1,73 @@
+import { Effect } from "effect"
+import { ArchiveService } from "../services/ArchiveService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface RestoreOptions extends BaseCommandOptions {
+	readonly type?: string
+	readonly args: readonly string[]
+	readonly json?: boolean
+	readonly dryRun?: boolean
+}
+
+export const restore = (options: RestoreOptions) =>
+	Effect.gen(function* () {
+		const archives = yield* ArchiveService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		const [id, phaseId] = options.args
+		let result
+		switch (options.type) {
+			case "epic":
+				if (!id)
+					return yield* Effect.fail(
+						new Error("Usage: agency restore epic <epic-id>"),
+					)
+				result = yield* archives.restoreEpic(id, cwd, {
+					dryRun: options.dryRun,
+				})
+				break
+			case "task":
+				if (!id)
+					return yield* Effect.fail(
+						new Error("Usage: agency restore task <task-id>"),
+					)
+				result = yield* archives.restoreTask(id, cwd, {
+					dryRun: options.dryRun,
+				})
+				break
+			case "phase":
+				if (!id || !phaseId)
+					return yield* Effect.fail(
+						new Error("Usage: agency restore phase <task-id> <phase-id>"),
+					)
+				result = yield* archives.restorePhase(id, phaseId, cwd, {
+					dryRun: options.dryRun,
+				})
+				break
+			default:
+				return yield* Effect.fail(
+					new Error("Work item type is required. Available: epic, task, phase"),
+				)
+		}
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `${result.dryRun ? "Would restore" : "Restored"} ${result.kind} '${result.id}' to ${result.path}`,
+		)
+	})
+
+export const help = `
+Usage: agency restore <epic|task|phase>
+
+Restore archived work after preflighting IDs, backlinks, dependencies, and paths.
+
+Commands:
+  epic <epic-id>                         Restore an epic and its tasks
+  task <task-id>                         Restore a task
+  phase <task-id> <phase-id>             Restore a phase
+
+Options:
+  --dry-run                              Preflight without changing files
+  --json                                 Output results as JSON
+`

package/src/commands/task-phase.test.ts

@@ -48,10 +48,13 @@ describe("task and phase command JSON output", () => {
 				task({ subcommand: "list", args: [], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				id: "multi",
 				path: join(root, "tasks/multi/TASK.md"),
+				revision: listed[0].revision,
 				data: {
 					ticketUrl: "https://example.com/task",
 					phases: [{ id: "first" }],
@@ -69,9 +72,12 @@ describe("task and phase command JSON output", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			id: "multi",
 			path: join(root, "tasks/multi/TASK.md"),
+			revision: shown.revision,
 			data: {
 				ticketUrl: "https://example.com/task",
 				phases: [{ id: "first" }],
@@ -85,11 +91,14 @@ describe("task and phase command JSON output", () => {
 				phase({ subcommand: "list", args: ["multi"], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				taskId: "multi",
 				id: "first",
 				path: join(root, "tasks/multi/phases/first/PHASE.md"),
+				revision: listed[0].revision,
 				data: {
 					repo: "agency",
 					branch: "task/first",
@@ -110,10 +119,13 @@ describe("task and phase command JSON output", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			taskId: "multi",
 			id: "first",
 			path: join(root, "tasks/multi/phases/first/PHASE.md"),
+			revision: shown.revision,
 			data: {
 				repo: "agency",
 				branch: "task/first",

package/src/commands/task.ts

@@ -27,6 +27,7 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly clearReferences?: boolean
 	readonly prUrl?: string
 	readonly clearPr?: boolean
+	readonly ifRevision?: string
 	readonly noEpic?: boolean
 	readonly multiPhase?: boolean
 	readonly json?: boolean
@@ -318,6 +319,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						pr: options.clearPr ? null : options.prUrl,
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -333,7 +335,12 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						new Error("Task ID and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renameTask(id, newId, cwd)
+				const output = yield* mutations.renameTask(
+					id,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -348,6 +355,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 					id,
 					options.noEpic ? null : (options.epic ?? null),
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -376,6 +384,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 					id,
 					dependencyId,
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -408,6 +417,9 @@ Subcommands:
   dependency <operation> <task> <dependency>
                         Add or remove a task dependency
 
+Mutation option:
+  --if-revision <hash>  Require the target's current revision
+
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task

package/src/protocol.test.ts

@@ -108,5 +108,24 @@ describe("machine protocol", () => {
 				},
 			},
 		})
+		expect(
+			errorEnvelope({
+				_tag: "RevisionConflictError",
+				message: "revision conflict",
+				path: "tasks/example/TASK.md",
+				expectedRevision: "a".repeat(64),
+				currentRevision: "b".repeat(64),
+			}),
+		).toMatchObject({
+			error: {
+				code: "REVISION_CONFLICT",
+				retryable: true,
+				fields: {
+					path: "tasks/example/TASK.md",
+					expectedRevision: "a".repeat(64),
+					currentRevision: "b".repeat(64),
+				},
+			},
+		})
 	})
 })