@markjaquith/agency 3.0.0 → 3.1.0

package/README.md

@@ -995,12 +995,17 @@ agency archive epic <epic-id> [--dry-run] [--json]
 agency archive task <task-id> [--dry-run] [--json]
 agency archive tasks [--dry-run] [--json]
 agency archive phase <task-id> <phase-id> [--dry-run] [--json]
+agency archive <path> [--dry-run] [--json]
 agency restore epic <epic-id> [--dry-run] [--json]
 agency restore task <task-id> [--dry-run] [--json]
 agency restore phase <task-id> <phase-id> [--dry-run] [--json]
 ```
 
-Archived work keeps its hierarchy under `archive/`. Epic archiving includes its
+An existing path within an active epic or task infers that work item, so
+`agency archive .` works from its directory. Collection roots are ambiguous,
+phase paths require the explicit `archive phase` form, and paths outside active
+epic or task trees are rejected. Archived work keeps its hierarchy under
+`archive/`. Epic archiving includes its
 listed tasks. A task can be archived only when its effective status is terminal
 (`done` or `dropped`). Multi-phase task status is derived from its phases, every
 phase must be terminal, and a task with no phases is not eligible.

package/cli-main.ts

@@ -396,10 +396,18 @@ const commands: Record<string, Command> = {
 				console.log(archiveHelp)
 				return
 			}
+			const explicitType = [
+				"list",
+				"show",
+				"epic",
+				"task",
+				"tasks",
+				"phase",
+			].includes(args[0] ?? "")
 			await runCommand(
 				archive({
-					type: args[0],
-					args: args.slice(1),
+					type: explicitType ? args[0] : undefined,
+					args: explicitType ? args.slice(1) : args,
 					json: options.json,
 					dryRun: options["dry-run"],
 					kinds: options.kind,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/cli-parser.test.ts

@@ -478,6 +478,11 @@ describe("strict CLI parsing", () => {
 	})
 
 	test("accepts archive dry-run", () => {
+		expect(parseCli(["archive", ".", "--dry-run"])).toMatchObject({
+			commandName: "archive",
+			args: ["."],
+			values: { "dry-run": true },
+		})
 		expect(parseCli(["archive", "task", "example", "--dry-run"])).toMatchObject(
 			{
 				commandName: "archive",

package/src/cli-parser.ts

@@ -763,7 +763,7 @@ const commands = {
 		},
 	},
 	archive: {
-		usage: "agency archive <list|show|epic|task|tasks|phase>",
+		usage: "agency archive <path|list|show|epic|task|tasks|phase>",
 		options: {
 			...outputOptions,
 			...entitySelectorOptions,
@@ -772,6 +772,12 @@ const commands = {
 			status: { type: "string", multiple: true },
 			repository: { type: "string", multiple: true },
 		},
+		command: {
+			usage: "agency archive <path> [--dry-run] [--json]",
+			minArgs: 1,
+			maxArgs: 1,
+			options: ["dry-run", "json"],
+		},
 		subcommands: {
 			list: {
 				usage:
@@ -1474,9 +1480,8 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			values: parsed.values,
 		}
 	}
-	const spec = definition.subcommands
-		? definition.subcommands[subcommand ?? ""]
-		: definition.command
+	const selectedSubcommand = definition.subcommands?.[subcommand ?? ""]
+	const spec = selectedSubcommand ?? definition.command
 	if (!spec) {
 		const message = subcommand
 			? `Unknown subcommand '${subcommand}' for 'agency ${commandName}'.`
@@ -1484,7 +1489,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		throw usageError(message, definition.usage)
 	}
 
-	let commandPositionals = definition.subcommands
+	let commandPositionals = selectedSubcommand
 		? parsed.positionals.slice(1)
 		: parsed.positionals
 	const allowed = new Set([...commonOptionNames, ...(spec.options ?? [])])
@@ -1535,7 +1540,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	commandPositionals = applyEntitySelectors(
 		commandName,
-		subcommand,
+		selectedSubcommand ? subcommand : undefined,
 		commandPositionals,
 		parsed.values,
 		spec,
@@ -1708,7 +1713,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 
 	return {
 		commandName: commandName as keyof typeof commands,
-		args: definition.subcommands
+		args: selectedSubcommand
 			? [subcommand!, ...commandPositionals]
 			: commandPositionals,
 		values: parsed.values,

package/src/cli.test.ts

@@ -531,9 +531,9 @@ status: dropped
 `,
 		)
 
-		expect((await runCli(["archive", "task", "example"], root)).exitCode).toBe(
-			0,
-		)
+		expect(
+			(await runCli(["archive", "."], join(root, "tasks/example"))).exitCode,
+		).toBe(0)
 		const result = await runCli(["archive", "task", "example", "--json"], root)
 
 		expect(result.exitCode).toBe(1)

package/src/commands/archive.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureLogs,
@@ -93,6 +94,75 @@ describe("archive command", () => {
 		)
 	})
 
+	test("infers a task from a filesystem path", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({
+					args: ["."],
+					cwd: join(root, "tasks/example"),
+					dryRun: true,
+					json: true,
+				}),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "task",
+			id: "example",
+			dryRun: true,
+		})
+	})
+
+	test("infers an epic from a filesystem path", async () => {
+		const directory = join(root, "epics/delivery")
+		await mkdir(directory, { recursive: true })
+		await Bun.write(
+			join(directory, "EPIC.md"),
+			`---
+ticketUrl: https://example.com/epic
+repos:
+  - repo: agency
+    ref: main
+tasks: []
+---
+
+# Delivery
+`,
+		)
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				archive({ args: ["."], cwd: directory, dryRun: true, json: true }),
+			),
+		)
+
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			operation: "archive",
+			kind: "epic",
+			id: "delivery",
+			dryRun: true,
+		})
+	})
+
+	test("rejects ambiguous and unsupported archive paths", async () => {
+		await expect(
+			runTestEffect(archive({ args: ["."], cwd: root, silent: true })),
+		).rejects.toThrow("Archive path is ambiguous")
+		await expect(
+			runTestEffect(
+				archive({ args: ["repos/agency"], cwd: root, silent: true }),
+			),
+		).rejects.toThrow("Archive path must be within an active epic or task")
+
+		const phaseDirectory = join(root, "tasks/example/phases/build")
+		await mkdir(phaseDirectory, { recursive: true })
+		await expect(
+			runTestEffect(
+				archive({ args: ["."], cwd: phaseDirectory, silent: true }),
+			),
+		).rejects.toThrow("Archive path identifies a phase")
+	})
+
 	test("reports an already archived task", async () => {
 		await runTestEffect(
 			archive({ type: "task", args: ["example"], cwd: root, silent: true }),
@@ -143,7 +213,9 @@ describe("archive command", () => {
 	test("requires a supported work item type", async () => {
 		await expect(
 			runTestEffect(archive({ args: [], cwd: root, silent: true })),
-		).rejects.toThrow("Available: list, show, epic, task, tasks, phase")
+		).rejects.toThrow(
+			"Provide a path or use: list, show, epic, task, tasks, phase",
+		)
 	})
 
 	test("rejects an extra archive show identifier", async () => {

package/src/commands/archive.ts

@@ -24,6 +24,14 @@ export const archive = (options: ArchiveOptions) =>
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const [id, phaseId] = options.args
+		let archiveType = options.type
+		let archiveId = id
+
+		if (!archiveType && id) {
+			const target = yield* archives.resolvePathTarget(id, cwd)
+			archiveType = target.kind
+			archiveId = target.id
+		}
 
 		if (options.type === "list") {
 			const records = yield* archives.list(
@@ -73,22 +81,22 @@ export const archive = (options: ArchiveOptions) =>
 		}
 
 		let result
-		switch (options.type) {
+		switch (archiveType) {
 			case "epic":
-				if (!id)
+				if (!archiveId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive epic <epic-id>"),
 					)
-				result = yield* archives.archiveEpic(id, cwd, {
+				result = yield* archives.archiveEpic(archiveId, cwd, {
 					dryRun: options.dryRun,
 				})
 				break
 			case "task":
-				if (!id)
+				if (!archiveId)
 					return yield* Effect.fail(
 						new Error("Usage: agency archive task <task-id>"),
 					)
-				result = yield* archives.archiveTask(id, cwd, {
+				result = yield* archives.archiveTask(archiveId, cwd, {
 					dryRun: options.dryRun,
 				})
 				break
@@ -109,7 +117,7 @@ export const archive = (options: ArchiveOptions) =>
 			default:
 				return yield* Effect.fail(
 					new Error(
-						"Archive operation is required. Available: list, show, epic, task, tasks, phase",
+						"Archive target is required. Provide a path or use: list, show, epic, task, tasks, phase",
 					),
 				)
 		}
@@ -141,11 +149,14 @@ export const archive = (options: ArchiveOptions) =>
 	})
 
 export const help = `
-Usage: agency archive <list|show|epic|task|tasks|phase>
+Usage: agency archive <path|list|show|epic|task|tasks|phase>
 
 Browse or archive work items after preflighting worktrees and graph references.
 
+An existing path within an active epic or task infers that work item.
+
 Commands:
+  <path>                                 Archive the containing epic or task
   list [filters]                         List archived work
   show <type> <id>                       Show an archived epic or task
   show phase <task-id> <phase-id>        Show an archived phase

package/src/services/ArchiveService.ts

@@ -1,7 +1,7 @@
 import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either, Layer } from "effect"
 import { lstat, mkdir, open, rename, rm } from "node:fs/promises"
-import { dirname, join, relative } from "node:path"
+import { dirname, join, relative, resolve, sep } from "node:path"
 import { EpicService, type EpicRecord } from "./EpicService"
 import { FileSystemService } from "./FileSystemService"
 import { PhaseService, type PhaseRecord } from "./PhaseService"
@@ -52,6 +52,11 @@ class ArchiveError extends Data.TaggedError("ArchiveError")<{
 
 export type ArchiveKind = "epic" | "task" | "phase"
 
+interface ArchivePathTarget {
+	readonly kind: "epic" | "task"
+	readonly id: string
+}
+
 const LifecycleEventSchema = Schema.Struct({
 	operation: Schema.Literal("archive", "restore"),
 	at: Schema.String,
@@ -478,6 +483,59 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 	"ArchiveService",
 	{
 		sync: () => ({
+			resolvePathTarget: (path: string, cwd: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const candidate = resolve(cwd, path)
+					if (!(yield* fs.exists(candidate))) {
+						return yield* new ArchiveError({
+							message: `Archive path does not exist: ${candidate}`,
+						})
+					}
+
+					const canonicalPath = yield* fs.realPath(candidate)
+					const root = yield* workbase.discover(canonicalPath)
+					const child = relative(root, canonicalPath)
+					const parts = child.split(sep)
+					if (child === "" || parts.length === 1) {
+						return yield* new ArchiveError({
+							message: `Archive path is ambiguous; it does not identify a single epic or task: ${canonicalPath}`,
+						})
+					}
+
+					const [collection, id] = parts
+					const kind =
+						collection === "epics"
+							? "epic"
+							: collection === "tasks"
+								? "task"
+								: undefined
+					if (!kind || !id) {
+						return yield* new ArchiveError({
+							message: `Archive path must be within an active epic or task: ${canonicalPath}`,
+						})
+					}
+					if (kind === "task" && parts[2] === "phases") {
+						return yield* new ArchiveError({
+							message: `Archive path identifies a phase; use 'agency archive phase <task-id> <phase-id>': ${canonicalPath}`,
+						})
+					}
+
+					const document = join(
+						root,
+						kind === "epic" ? "epics" : "tasks",
+						id,
+						kind === "epic" ? "EPIC.md" : "TASK.md",
+					)
+					if (!(yield* fs.exists(document))) {
+						return yield* new ArchiveError({
+							message: `Archive path does not identify an active ${kind}: ${canonicalPath}`,
+						})
+					}
+					return { kind, id } satisfies ArchivePathTarget
+				}),
+
 			list: (filters: ArchiveFilters = {}, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					const fs = yield* FileSystemService