@markjaquith/agency 2.27.0 → 2.28.0

package/cli.ts

@@ -9,6 +9,7 @@ import { pr, help as prHelp } from "./src/commands/pr"
 import { work, workPrepare, help as workHelp } from "./src/commands/work"
 import { worktree, help as worktreeHelp } from "./src/commands/worktree"
 import { status, help as statusHelp } from "./src/commands/status"
+import { doctor, help as doctorHelp } from "./src/commands/doctor"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
 import { graph, help as graphHelp } from "./src/commands/graph"
@@ -41,6 +42,7 @@ import { ClaimService } from "./src/services/ClaimService"
 import { SyncService } from "./src/services/SyncService"
 import { ReadinessService } from "./src/services/ReadinessService"
 import { GraphMutationService } from "./src/services/GraphMutationService"
+import { DoctorService } from "./src/services/DoctorService"
 import {
 	claimCommand,
 	claimHelp,
@@ -72,6 +74,7 @@ const CliLayer = Layer.mergeAll(
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
+	DoctorService.Default,
 )
 
 /**
@@ -524,6 +527,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	doctor: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(doctorHelp)
+				return
+			}
+			await runCommand(
+				doctor({
+					silent: options.silent,
+					verbose: options.verbose,
+					json: options.json,
+					cwd: options.cwd,
+				}),
+			)
+		},
+	},
 	validate: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -632,6 +651,7 @@ Commands:
   pr create              Create a pull request for an execution unit
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase
+  doctor                 Diagnose workbase health and integrations
   validate [path]        Validate a workbase
   context [target]       Return complete target context
   graph                  Export the complete workbase graph

package/package.json

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

package/src/cli-parser.test.ts

@@ -123,6 +123,7 @@ describe("strict CLI parsing", () => {
 
 	test("parses addressable resource maintenance commands", () => {
 		for (const args of [
+			["doctor", "--json"],
 			["repo", "show", "agency", "--json"],
 			["repo", "fetch", "agency"],
 			["repo", "remove", "agency"],

package/src/cli-parser.ts

@@ -804,6 +804,16 @@ const commands = {
 			conflicts: viewConflicts,
 		},
 	},
+	doctor: {
+		usage: "agency doctor [--json]",
+		options: outputOptions,
+		command: {
+			usage: "agency doctor [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["json"],
+		},
+	},
 	validate: {
 		usage: "agency validate [path] [--json] [--no-input]",
 		options: {

package/src/cli.test.ts

@@ -935,6 +935,15 @@ status: open
 			valid: true,
 			issues: [],
 		})
+		const doctor = parseJson(await runCli(["doctor", "--json"], root))
+		expect(doctor).toMatchObject({
+			version: 1,
+			root: workbaseRoot,
+			checks: expect.arrayContaining([
+				expect.objectContaining({ id: "tool.git", status: "pass" }),
+				expect.objectContaining({ id: "workbase.validation", status: "pass" }),
+			]),
+		})
 
 		const validation = parseJson(
 			await runCli(["validate", root, "--json"], parent),

package/src/commands/doctor.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { createHash } from "node:crypto"
+import { chmod, mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { doctor } from "./doctor"
+
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
+const managedAgents = (body: string) =>
+	`<!-- agency-managed: sha256=${createHash("sha256").update(body).digest("hex")} -->\n\n${body}`
+
+describe("doctor command", () => {
+	let root: string
+	let repository: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		repository = join(root, "source")
+		await mkdir(repository)
+		await Bun.$`git init -q -b main ${repository}`
+		await Bun.$`git -C ${repository} config user.email test@example.com`
+		await Bun.$`git -C ${repository} config user.name Test`
+		await write(repository, "README.md", "test\n")
+		await Bun.$`git -C ${repository} add README.md`
+		await Bun.$`git -C ${repository} commit -q -m initial`
+		await Bun.$`git -C ${repository} remote add origin https://example.com/agency.git`
+		await write(
+			root,
+			"agency.json",
+			JSON.stringify({
+				version: 2,
+				runners: { missing: { command: ["definitely-not-installed"] } },
+			}),
+		)
+		await mkdir(join(root, "repos"), { recursive: true })
+		await Bun.$`ln -s ${repository} ${join(root, "repos/agency")}`
+		await write(
+			root,
+			"tasks/example/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: feat/example
+base: main
+pr: null
+status: open
+---
+
+# Example
+`,
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("returns stable checks, severities, and remediation in JSON", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(doctor({ cwd: root, json: true })),
+		)
+		const report = JSON.parse(logs[0]!)
+
+		expect(report).toMatchObject({
+			version: 1,
+			root,
+			healthy: false,
+		})
+		expect(report.checks).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					id: "tool.git",
+					level: "error",
+					status: "pass",
+				}),
+				expect.objectContaining({
+					id: "integration.runner.missing",
+					level: "error",
+					status: "fail",
+				}),
+				expect.objectContaining({
+					id: "ref.agency.main",
+					status: "pass",
+				}),
+				expect.objectContaining({
+					id: "worktree.task.example",
+					status: "pass",
+				}),
+			]),
+		)
+		for (const check of report.checks) {
+			if (check.status === "fail") expect(check.remediation).toBeTruthy()
+		}
+	})
+
+	test("reports repository, ref, remote, and managed-file failures", async () => {
+		await Bun.$`git -C ${repository} remote remove origin`
+		await Bun.$`git -C ${repository} branch -m other`
+		await write(root, "AGENTS.md", managedAgents("old\n"))
+
+		const logs = await captureLogs(() =>
+			runTestEffect(doctor({ cwd: root, json: true })),
+		)
+		const checks = JSON.parse(logs[0]!).checks
+
+		expect(checks).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					id: "repository.agency.remote",
+					status: "fail",
+				}),
+				expect.objectContaining({
+					id: "ref.agency.main",
+					status: "fail",
+				}),
+				expect.objectContaining({
+					id: "integration.file.agents",
+					status: "fail",
+				}),
+			]),
+		)
+	})
+
+	test("is safe when the workbase is read-only", async () => {
+		for (const path of [
+			join(root, "agency.json"),
+			join(root, "tasks/example/TASK.md"),
+		]) {
+			await chmod(path, 0o444)
+		}
+		await chmod(join(root, "tasks/example"), 0o555)
+		await chmod(join(root, "tasks"), 0o555)
+		await chmod(root, 0o555)
+
+		try {
+			await runTestEffect(doctor({ cwd: root, silent: true }))
+		} finally {
+			await chmod(root, 0o755)
+			await chmod(join(root, "tasks"), 0o755)
+			await chmod(join(root, "tasks/example"), 0o755)
+		}
+
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
+		).toBe(false)
+	})
+})

package/src/commands/doctor.ts

@@ -0,0 +1,47 @@
+import { Effect } from "effect"
+import { DoctorService } from "../services/DoctorService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface DoctorOptions extends BaseCommandOptions {
+	readonly json?: boolean
+}
+
+export const doctor = (options: DoctorOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* DoctorService
+		const { log } = createLoggers(options)
+		const report = yield* service.inspect(options.cwd ?? process.cwd())
+
+		if (options.json) {
+			log(JSON.stringify(report, null, 2))
+			return
+		}
+
+		for (const check of report.checks) {
+			const marker =
+				check.status === "pass"
+					? "PASS"
+					: check.level === "error"
+						? "ERROR"
+						: check.level === "warning"
+							? "WARN"
+							: "OPTIONAL"
+			log(`${marker}\t${check.id}\t${check.message}`)
+			if (check.remediation) log(`  Remediation: ${check.remediation}`)
+		}
+		log("")
+		log(
+			`${report.healthy ? "Healthy" : "Unhealthy"}: ${report.summary.errors} error(s), ${report.summary.warnings} warning(s), ${report.summary.optional} unavailable optional capability(s)`,
+		)
+	})
+
+export const help = `
+Usage: agency doctor [options]
+
+Diagnose tools, integrations, repositories, refs, worktrees, permissions, and
+managed-file drift without changing the workbase.
+
+Options:
+  --json  Output the health report as JSON
+`

package/src/commands/read-only.test.ts

@@ -14,6 +14,7 @@ import { validate } from "./validate"
 import { context } from "./context"
 import { graph } from "./graph"
 import { next } from "./next"
+import { doctor } from "./doctor"
 
 const write = async (root: string, path: string, content: string) => {
 	const fullPath = join(root, path)
@@ -147,6 +148,7 @@ status: open
 		)
 		await runTestEffect(graph({ cwd: root, silent: true }))
 		await runTestEffect(next({ cwd: root, silent: true }))
+		await runTestEffect(doctor({ cwd: root, silent: true }))
 
 		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
 		expect(

package/src/services/DoctorService.ts

@@ -0,0 +1,419 @@
+import { Effect, Either } from "effect"
+import { constants } from "node:fs"
+import { access } from "node:fs/promises"
+import { isAbsolute, join, resolve } from "node:path"
+import { EpicService } from "./EpicService"
+import { FileSystemService } from "./FileSystemService"
+import { IntegrationService } from "./IntegrationService"
+import { PhaseService } from "./PhaseService"
+import { RepositoryService } from "./RepositoryService"
+import { TaskService } from "./TaskService"
+import { WorkbaseService } from "./WorkbaseService"
+import { WorktreeService } from "./WorktreeService"
+
+type DoctorCheckLevel = "error" | "warning" | "optional"
+
+interface DoctorCheck {
+	readonly id: string
+	readonly category:
+		| "tool"
+		| "integration"
+		| "workbase"
+		| "repository"
+		| "ref"
+		| "worktree"
+		| "permission"
+	readonly level: DoctorCheckLevel
+	readonly status: "pass" | "fail"
+	readonly message: string
+	readonly remediation: string | null
+}
+
+interface DoctorReport {
+	readonly version: 1
+	readonly root: string
+	readonly healthy: boolean
+	readonly summary: {
+		readonly passed: number
+		readonly errors: number
+		readonly warnings: number
+		readonly optional: number
+	}
+	readonly checks: readonly DoctorCheck[]
+}
+
+const executableAvailable = (executable: string, root: string) =>
+	Effect.tryPromise({
+		try: async () => {
+			if (executable.includes("/")) {
+				const path = isAbsolute(executable)
+					? executable
+					: resolve(root, executable)
+				await access(path, constants.X_OK)
+				return true
+			}
+			return Bun.which(executable) !== null
+		},
+		catch: () => false,
+	}).pipe(Effect.catchAll(() => Effect.succeed(false)))
+
+const permissionAvailable = (path: string, mode: number) =>
+	Effect.tryPromise({
+		try: () => access(path, mode).then(() => true),
+		catch: () => false,
+	}).pipe(Effect.catchAll(() => Effect.succeed(false)))
+
+const messageOf = (error: unknown) =>
+	error instanceof Error
+		? error.message
+		: typeof error === "object" &&
+			  error !== null &&
+			  "message" in error &&
+			  typeof error.message === "string"
+			? error.message
+			: String(error)
+
+export class DoctorService extends Effect.Service<DoctorService>()(
+	"DoctorService",
+	{
+		sync: () => ({
+			inspect: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const epics = yield* EpicService
+					const fs = yield* FileSystemService
+					const integrations = yield* IntegrationService
+					const phases = yield* PhaseService
+					const repositories = yield* RepositoryService
+					const tasks = yield* TaskService
+					const workbases = yield* WorkbaseService
+					const worktrees = yield* WorktreeService
+					const { root, config } = yield* workbases.loadConfig(startPath)
+					const checks: DoctorCheck[] = []
+					const add = (
+						check: Omit<DoctorCheck, "remediation"> & {
+							readonly remediation?: string
+						},
+					) =>
+						checks.push({
+							...check,
+							remediation:
+								check.status === "fail"
+									? (check.remediation ?? "Remediation is unknown.")
+									: null,
+						})
+
+					const tool = function* (
+						id: string,
+						executable: string,
+						level: DoctorCheckLevel,
+						label: string,
+					) {
+						const available = yield* executableAvailable(executable, root)
+						add({
+							id,
+							category: id.startsWith("tool.") ? "tool" : "integration",
+							level,
+							status: available ? "pass" : "fail",
+							message: available
+								? `${label} executable '${executable}' is available`
+								: `${label} executable '${executable}' is unavailable`,
+							remediation:
+								level === "optional"
+									? `Install '${executable}' to enable ${label.toLowerCase()}, or leave it unavailable if unused.`
+									: `Install '${executable}' and ensure it is executable on PATH.`,
+						})
+						return available
+					}
+
+					const gitAvailable = yield* tool("tool.git", "git", "error", "Git")
+					yield* tool(
+						"capability.runner.opencode",
+						"opencode",
+						"optional",
+						"OpenCode runner",
+					)
+					yield* tool(
+						"capability.runner.claude",
+						"claude",
+						"optional",
+						"Claude runner",
+					)
+
+					const configuredCommands: readonly (readonly [
+						string,
+						readonly string[],
+						string,
+					])[] = [
+						...(config.chooserCommand
+							? [
+									[
+										"integration.chooser",
+										config.chooserCommand,
+										"Chooser",
+									] as const,
+								]
+							: []),
+						...(config.worktreeCreateCommand
+							? [
+									[
+										"integration.worktree-create",
+										config.worktreeCreateCommand,
+										"Worktree creator",
+									] as const,
+								]
+							: []),
+						...Object.entries(config.runners ?? {}).map(
+							([name, runner]) =>
+								[
+									`integration.runner.${name}`,
+									runner.command,
+									`Configured runner '${name}'`,
+								] as const,
+						),
+						...Object.entries(config.runners ?? {}).flatMap(([name, runner]) =>
+							runner.resumeCommand
+								? [
+										[
+											`integration.runner.${name}.resume`,
+											runner.resumeCommand,
+											`Configured runner '${name}' resume`,
+										] as const,
+									]
+								: [],
+						),
+						...(config.delivery
+							? [
+									[
+										`integration.delivery.${config.delivery.provider}`,
+										config.delivery.createCommand,
+										`Delivery provider '${config.delivery.provider}'`,
+									] as const,
+									[
+										`integration.delivery.${config.delivery.provider}.query`,
+										config.delivery.queryCommand,
+										`Delivery provider '${config.delivery.provider}' query`,
+									] as const,
+								]
+							: []),
+					]
+					for (const [id, command, label] of configuredCommands) {
+						yield* tool(id, command[0]!, "error", label)
+					}
+
+					const validation = yield* workbases.validate(root)
+					add({
+						id: "workbase.validation",
+						category: "workbase",
+						level: "error",
+						status: validation.valid ? "pass" : "fail",
+						message: validation.valid
+							? "Workbase documents and relationships are valid"
+							: `Workbase validation found ${validation.issues.length} issue(s): ${validation.issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`,
+						remediation:
+							"Run 'agency validate' and correct every reported issue.",
+					})
+
+					for (const [id, mode, level, label, remediation] of [
+						[
+							"permission.workbase.read",
+							constants.R_OK,
+							"error",
+							"readable",
+							`Grant the current user read access to ${root}.`,
+						],
+						[
+							"permission.workbase.write",
+							constants.W_OK,
+							"warning",
+							"writable",
+							`Grant the current user write access to ${root} before running mutation commands.`,
+						],
+					] as const) {
+						const available = yield* permissionAvailable(root, mode)
+						add({
+							id,
+							category: "permission",
+							level,
+							status: available ? "pass" : "fail",
+							message: `Workbase root is ${available ? "" : "not "}${label}`,
+							remediation,
+						})
+					}
+
+					const integrationStatus = yield* integrations.status(root)
+					for (const file of integrationStatus.files) {
+						const failed = file.state === "missing" || file.state === "drifted"
+						add({
+							id: `integration.file.${file.name}`,
+							category: "integration",
+							level: file.state === "customized" ? "optional" : "warning",
+							status: failed ? "fail" : "pass",
+							message: `${file.name} integration file is ${file.state}: ${file.path}`,
+							remediation:
+								"Run 'agency integration sync' to restore managed content.",
+						})
+					}
+
+					const refs = new Map<string, Set<string>>()
+					const declareRef = (repo: string, ref: string) => {
+						const values = refs.get(repo) ?? new Set<string>()
+						values.add(ref)
+						refs.set(repo, values)
+					}
+					if (validation.valid) {
+						for (const epic of yield* epics.list(root)) {
+							for (const reference of epic.data.repos)
+								declareRef(reference.repo, reference.ref)
+						}
+						for (const task of yield* tasks.list(root)) {
+							if ("repo" in task.data) {
+								declareRef(task.data.repo, task.data.base)
+								for (const reference of task.data.repos ?? [])
+									declareRef(reference.repo, reference.ref)
+							} else {
+								for (const phase of yield* phases.list(task.id, root)) {
+									declareRef(phase.data.repo, phase.data.base)
+									for (const reference of phase.data.repos ?? [])
+										declareRef(reference.repo, reference.ref)
+								}
+							}
+						}
+					}
+
+					const repositoryList = gitAvailable
+						? yield* repositories.list(root)
+						: []
+					if (!gitAvailable) {
+						add({
+							id: "repository.inspection",
+							category: "repository",
+							level: "warning",
+							status: "fail",
+							message:
+								"Repository, ref, remote, and worktree checks were skipped because Git is unavailable",
+							remediation: "Install 'git' and rerun 'agency doctor'.",
+						})
+					}
+					for (const repository of repositoryList) {
+						const verified = yield* fs.runCommand(
+							["git", "-C", repository.path, "rev-parse", "--git-dir"],
+							{ captureOutput: true },
+						)
+						const repositoryValid = verified.exitCode === 0
+						add({
+							id: `repository.${repository.alias}.valid`,
+							category: "repository",
+							level: "error",
+							status: repositoryValid ? "pass" : "fail",
+							message: repositoryValid
+								? `Repository '${repository.alias}' is a valid Git repository`
+								: `Repository '${repository.alias}' is not a valid Git repository`,
+							remediation: `Run 'agency repo verify ${repository.alias}', then repair or relink the repository.`,
+						})
+						add({
+							id: `repository.${repository.alias}.remote`,
+							category: "repository",
+							level: "warning",
+							status: repository.remote ? "pass" : "fail",
+							message: repository.remote
+								? `Repository '${repository.alias}' origin is ${repository.remote}`
+								: `Repository '${repository.alias}' has no origin remote`,
+							remediation: `Run 'agency repo remote ${repository.alias} <url>' to configure origin.`,
+						})
+
+						for (const ref of [...(refs.get(repository.alias) ?? [])].sort()) {
+							const local = yield* fs.runCommand(
+								[
+									"git",
+									"-C",
+									repository.path,
+									"rev-parse",
+									"--verify",
+									`${ref}^{commit}`,
+								],
+								{ captureOutput: true },
+							)
+							const remote =
+								local.exitCode === 0
+									? local
+									: yield* fs.runCommand(
+											[
+												"git",
+												"-C",
+												repository.path,
+												"rev-parse",
+												"--verify",
+												`origin/${ref}^{commit}`,
+											],
+											{ captureOutput: true },
+										)
+							const found = local.exitCode === 0 || remote.exitCode === 0
+							add({
+								id: `ref.${repository.alias}.${ref}`,
+								category: "ref",
+								level: "error",
+								status: found ? "pass" : "fail",
+								message: `Declared ref '${ref}' for '${repository.alias}' is ${found ? "available" : "missing"}`,
+								remediation: `Run 'agency repo fetch ${repository.alias}' and verify that ref '${ref}' exists on origin.`,
+							})
+						}
+					}
+
+					if (validation.valid && gitAvailable) {
+						const inspected = yield* Effect.either(worktrees.list(root))
+						if (Either.isLeft(inspected)) {
+							add({
+								id: "worktree.inspection",
+								category: "worktree",
+								level: "warning",
+								status: "fail",
+								message: `Worktree inspection failed: ${messageOf(inspected.left)}`,
+								remediation:
+									"Remediation is unknown; inspect repositories with 'agency worktree list --json'.",
+							})
+						} else {
+							for (const inspection of inspected.right) {
+								const target =
+									inspection.owner.kind === "phase"
+										? `${inspection.owner.taskId}.${inspection.owner.phaseId}`
+										: inspection.owner.taskId
+								add({
+									id: `worktree.${inspection.owner.kind}.${target}`,
+									category: "worktree",
+									level: "error",
+									status: inspection.conflicts.length === 0 ? "pass" : "fail",
+									message:
+										inspection.conflicts.length === 0
+											? `Worktree registrations for '${target}' are consistent`
+											: inspection.conflicts
+													.map((conflict) => conflict.message)
+													.join("; "),
+									remediation: `Run 'agency worktree inspect ${inspection.owner.taskId}${inspection.owner.phaseId ? ` ${inspection.owner.phaseId}` : ""}', then use 'agency worktree repair' if appropriate.`,
+								})
+							}
+						}
+					}
+
+					const summary = {
+						passed: checks.filter((check) => check.status === "pass").length,
+						errors: checks.filter(
+							(check) => check.status === "fail" && check.level === "error",
+						).length,
+						warnings: checks.filter(
+							(check) => check.status === "fail" && check.level === "warning",
+						).length,
+						optional: checks.filter(
+							(check) => check.status === "fail" && check.level === "optional",
+						).length,
+					}
+					return {
+						version: 1,
+						root,
+						healthy: summary.errors === 0,
+						summary,
+						checks,
+					} satisfies DoctorReport
+				}),
+		}),
+	},
+) {}

package/src/test-utils.ts

@@ -19,6 +19,7 @@ import { ClaimService } from "./services/ClaimService"
 import { SyncService } from "./services/SyncService"
 import { ReadinessService } from "./services/ReadinessService"
 import { GraphMutationService } from "./services/GraphMutationService"
+import { DoctorService } from "./services/DoctorService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -42,6 +43,7 @@ const TestLayer = Layer.mergeAll(
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,
+	DoctorService.Default,
 )
 
 export async function runTestEffect<A, E>(