@markjaquith/agency 2.27.0 → 2.28.1

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/init.test.ts

@@ -33,10 +33,14 @@ describe("init command", () => {
 		expect(await Bun.file(join(root, ".gitignore")).text()).toBe(
 			"/repos/\n/tasks/*/code/\n/tasks/*/phases/*/code/\n",
 		)
-		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
-		expect(
-			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
-		).toBe(false)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(true)
+		const opencode = await Bun.file(
+			join(root, ".opencode/opencode.jsonc"),
+		).text()
+		const config = JSON.parse(opencode.slice(opencode.indexOf("\n\n") + 2))
+		expect(config.permission.external_directory).toEqual({
+			"../**": "allow",
+		})
 	})
 
 	test("preserves existing gitignore entries", async () => {

package/src/commands/init.ts

@@ -1,6 +1,7 @@
 import { Effect } from "effect"
 import { resolve } from "node:path"
 import type { BaseCommandOptions } from "../utils/command"
+import { IntegrationService } from "../services/IntegrationService"
 import { WorkbaseService } from "../services/WorkbaseService"
 import { createLoggers } from "../utils/effect"
 
@@ -10,12 +11,14 @@ interface InitOptions extends BaseCommandOptions {
 
 export const init = (options: InitOptions = {}) =>
 	Effect.gen(function* () {
+		const integrations = yield* IntegrationService
 		const workbase = yield* WorkbaseService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const root = yield* workbase.initialize(
 			options.path ? resolve(cwd, options.path) : cwd,
 		)
+		yield* integrations.sync(root)
 		log(
 			options.json
 				? JSON.stringify({ root }, null, 2)

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/commands/work.test.ts

@@ -8,6 +8,7 @@ import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
 import { ClaimService } from "../services/ClaimService"
 import { ReadinessService } from "../services/ReadinessService"
+import { IntegrationService } from "../services/IntegrationService"
 import { captureErrors, captureLogs } from "../test-utils"
 import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
@@ -74,6 +75,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 	const statusUpdates: string[] = []
 	const shownTasks: string[] = []
 	const progressUpdates: string[] = []
+	let integrationSyncs = 0
 	const guards: Array<{ target: string; override?: boolean }> = []
 	const launches: Array<{
 		cli: string
@@ -210,6 +212,12 @@ const createHarness = (options: HarnessOptions = {}) => {
 				: Effect.void
 		},
 	}
+	const integrations = {
+		sync: () => {
+			integrationSyncs += 1
+			return Effect.succeed({ root: "/workbase", files: [] })
+		},
+	}
 	const fs = {
 		isDirectory: (path: string) =>
 			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
@@ -256,6 +264,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(PhaseService, phases as never),
 				Effect.provideService(ClaimService, claims as never),
 				Effect.provideService(ReadinessService, readiness as never),
+				Effect.provideService(IntegrationService, integrations as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
 	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
@@ -279,12 +288,23 @@ const createHarness = (options: HarnessOptions = {}) => {
 		shownTasks,
 		progressUpdates,
 		guards,
+		get integrationSyncs() {
+			return integrationSyncs
+		},
 		run,
 		runPrepare,
 	}
 }
 
 describe("work command", () => {
+	test("reconciles managed integration files before preparing work", async () => {
+		const harness = createHarness()
+
+		await harness.run({ taskId: "example", opencode: true })
+
+		expect(harness.integrationSyncs).toBe(1)
+	})
+
 	test("guards execution targets before materialization and honors --force", async () => {
 		const blocked = createHarness({ guardError: new Error("blocked") })
 		await expect(

package/src/commands/work.ts

@@ -9,6 +9,7 @@ import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { ClaimService } from "../services/ClaimService"
 import { ReadinessService } from "../services/ReadinessService"
+import { IntegrationService } from "../services/IntegrationService"
 import { createLoggers } from "../utils/effect"
 import { execvp } from "../utils/exec"
 import { createProgress, type Progress } from "../utils/progress"
@@ -106,6 +107,7 @@ export const work = (
 		const phases = yield* PhaseService
 		const claims = yield* ClaimService
 		const readiness = yield* ReadinessService
+		const integrations = yield* IntegrationService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const directoryPath = options.directory
@@ -118,6 +120,7 @@ export const work = (
 		const inputAllowed = options.inputAllowed ?? true
 		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
+		yield* integrations.sync(root)
 		const { config } = yield* workbase.loadConfig(root)
 
 		let target: WorkTarget | null = null