@markjaquith/agency 2.7.2 → 2.8.0

package/src/services/IntegrationService.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { createHash } from "node:crypto"
+import { mkdir, symlink, unlink } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { managedWorkbaseAgents } from "../workbase/agents-file"
+import { managedWorkbaseOpencode } from "../workbase/opencode-file"
+import { IntegrationService } from "./IntegrationService"
+
+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 managed = (prefix: string, body: string, suffix = "") => {
+	const checksum = createHash("sha256").update(body).digest("hex")
+	return `${prefix}${checksum}${suffix}\n\n${body}`
+}
+
+const status = (root: string) =>
+	runTestEffect(
+		IntegrationService.pipe(Effect.flatMap((service) => service.status(root))),
+	)
+
+const sync = (root: string) =>
+	runTestEffect(
+		IntegrationService.pipe(Effect.flatMap((service) => service.sync(root))),
+	)
+
+describe("IntegrationService", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("reports missing and current managed files without writing", async () => {
+		expect((await status(root)).files.map(({ state }) => state)).toEqual([
+			"missing",
+			"missing",
+		])
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+
+		await write(root, "AGENTS.md", managedWorkbaseAgents)
+		await write(root, ".opencode/opencode.jsonc", managedWorkbaseOpencode(root))
+		expect((await status(root)).files.map(({ state }) => state)).toEqual([
+			"managed",
+			"managed",
+		])
+	})
+
+	test("reports customized and checksum-safe drifted files", async () => {
+		await write(root, "AGENTS.md", "# Custom instructions\n")
+		await write(
+			root,
+			".opencode/opencode.jsonc",
+			managed("// agency-managed: sha256=", '{"references":{}}\n'),
+		)
+
+		expect((await status(root)).files.map(({ state }) => state)).toEqual([
+			"customized",
+			"drifted",
+		])
+	})
+
+	test("treats an existing JSON OpenCode config as customized", async () => {
+		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
+
+		const result = await status(root)
+		expect(result.files[1]).toEqual({
+			name: "opencode",
+			path: join(root, ".opencode/opencode.json"),
+			state: "customized",
+		})
+	})
+
+	test("syncs missing and drifted files while preserving customized files", async () => {
+		const customAgents = "# Custom instructions\n"
+		await write(root, "AGENTS.md", customAgents)
+		await write(
+			root,
+			".opencode/opencode.jsonc",
+			managed("// agency-managed: sha256=", '{"references":{}}\n'),
+		)
+
+		const first = await sync(root)
+		expect(first.files).toMatchObject([
+			{ name: "agents", state: "customized", changed: false },
+			{ name: "opencode", state: "managed", changed: true },
+		])
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(customAgents)
+		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
+			managedWorkbaseOpencode(root),
+		)
+
+		await unlink(join(root, "AGENTS.md"))
+		const second = await sync(root)
+		expect(second.files[0]).toMatchObject({ state: "managed", changed: true })
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
+			managedWorkbaseAgents,
+		)
+	})
+
+	test("does not overwrite managed files whose checksums no longer match", async () => {
+		const tampered = `${managed(
+			"<!-- agency-managed: sha256=",
+			"# Previous Agency instructions\n",
+			" -->",
+		)}User edit\n`
+		await write(root, "AGENTS.md", tampered)
+
+		const result = await sync(root)
+		expect(result.files[0]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(tampered)
+	})
+
+	test("does not follow symlinked integration files", async () => {
+		const target = join(root, "custom-agents.md")
+		await Bun.write(target, "# External instructions\n")
+		await symlink(target, join(root, "AGENTS.md"))
+
+		const result = await sync(root)
+		expect(result.files[0]).toMatchObject({
+			state: "customized",
+			changed: false,
+		})
+		expect(await Bun.file(target).text()).toBe("# External instructions\n")
+	})
+})

package/src/services/IntegrationService.ts

@@ -0,0 +1,136 @@
+import { Effect } from "effect"
+import { join } from "node:path"
+import { FileSystemService } from "./FileSystemService"
+import { WorkbaseService } from "./WorkbaseService"
+import {
+	canUpdateManagedWorkbaseAgents,
+	managedWorkbaseAgents,
+} from "../workbase/agents-file"
+import {
+	canUpdateManagedWorkbaseOpencode,
+	managedWorkbaseOpencode,
+} from "../workbase/opencode-file"
+
+type IntegrationFileState = "managed" | "customized" | "missing" | "drifted"
+
+interface IntegrationFileStatus {
+	readonly name: "agents" | "opencode"
+	readonly path: string
+	readonly state: IntegrationFileState
+}
+
+interface IntegrationSyncFile extends IntegrationFileStatus {
+	readonly changed: boolean
+}
+
+const classify = (
+	name: IntegrationFileStatus["name"],
+	path: string,
+	content: string,
+	managed: string,
+	canUpdate: (content: string) => boolean,
+): IntegrationFileStatus => ({
+	name,
+	path,
+	state:
+		content === managed
+			? "managed"
+			: canUpdate(content)
+				? "drifted"
+				: "customized",
+})
+
+const inspect = (root: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const agentsPath = join(root, "AGENTS.md")
+		const opencodeDirectory = join(root, ".opencode")
+		const opencodePath = join(opencodeDirectory, "opencode.jsonc")
+		const opencodeJsonPath = join(opencodeDirectory, "opencode.json")
+		const files: IntegrationFileStatus[] = []
+
+		files.push(
+			(yield* fs.readSymlinkTarget(agentsPath)) !== null
+				? { name: "agents", path: agentsPath, state: "customized" }
+				: (yield* fs.exists(agentsPath))
+					? classify(
+							"agents",
+							agentsPath,
+							yield* fs.readFile(agentsPath),
+							managedWorkbaseAgents,
+							canUpdateManagedWorkbaseAgents,
+						)
+					: { name: "agents", path: agentsPath, state: "missing" },
+		)
+
+		if ((yield* fs.readSymlinkTarget(opencodePath)) !== null) {
+			files.push({
+				name: "opencode",
+				path: opencodePath,
+				state: "customized",
+			})
+		} else if (yield* fs.exists(opencodePath)) {
+			files.push(
+				classify(
+					"opencode",
+					opencodePath,
+					yield* fs.readFile(opencodePath),
+					managedWorkbaseOpencode(root),
+					canUpdateManagedWorkbaseOpencode,
+				),
+			)
+		} else if (yield* fs.exists(opencodeJsonPath)) {
+			files.push({
+				name: "opencode",
+				path: opencodeJsonPath,
+				state: "customized",
+			})
+		} else {
+			files.push({ name: "opencode", path: opencodePath, state: "missing" })
+		}
+
+		return files
+	})
+
+export class IntegrationService extends Effect.Service<IntegrationService>()(
+	"IntegrationService",
+	{
+		sync: () => ({
+			status: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const workbase = yield* WorkbaseService
+					const root = yield* workbase.discover(startPath)
+					return { root, files: yield* inspect(root) }
+				}),
+
+			sync: (startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const root = yield* workbase.discover(startPath)
+					const statuses = yield* inspect(root)
+					const files: IntegrationSyncFile[] = []
+
+					for (const status of statuses) {
+						const changed =
+							status.state === "missing" || status.state === "drifted"
+						if (changed) {
+							if (status.name === "agents") {
+								yield* fs.writeFile(status.path, managedWorkbaseAgents)
+							} else {
+								yield* fs.createDirectory(join(root, ".opencode"))
+								yield* fs.writeFile(status.path, managedWorkbaseOpencode(root))
+							}
+						}
+						files.push({
+							...status,
+							state: changed ? "managed" : status.state,
+							changed,
+						})
+					}
+
+					return { root, files }
+				}),
+		}),
+	},
+) {}

package/src/services/WorkbaseService.test.ts

@@ -1,11 +1,8 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { createHash } from "node:crypto"
 import { mkdir, realpath } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
-import { managedWorkbaseAgents } from "../workbase/agents-file"
-import { managedWorkbaseOpencode } from "../workbase/opencode-file"
 import { WorkbaseService } from "./WorkbaseService"
 
 const write = async (root: string, path: string, content: string) => {
@@ -14,16 +11,6 @@ const write = async (root: string, path: string, content: string) => {
 	await Bun.write(fullPath, content)
 }
 
-const managedAgents = (body: string) => {
-	const checksum = createHash("sha256").update(body).digest("hex")
-	return `<!-- agency-managed: sha256=${checksum} -->\n\n${body}`
-}
-
-const managedOpencode = (body: string) => {
-	const checksum = createHash("sha256").update(body).digest("hex")
-	return `// agency-managed: sha256=${checksum}\n\n${body}`
-}
-
 describe("WorkbaseService", () => {
 	let root: string
 
@@ -48,12 +35,10 @@ describe("WorkbaseService", () => {
 		)
 
 		expect(discovered).toBe(root)
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
-			managedWorkbaseAgents,
-		)
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode(root),
-		)
+		expect(await Bun.file(join(root, "AGENTS.md")).exists()).toBe(false)
+		expect(
+			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
+		).toBe(false)
 	})
 
 	test("registers canonical workbase paths without duplicates", async () => {
@@ -88,105 +73,6 @@ describe("WorkbaseService", () => {
 		).toEqual({ version: 1, workbases: [first] })
 	})
 
-	test("preserves an unmanaged workbase OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(root, ".opencode/opencode.jsonc", '{"model":"test/model"}\n')
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			'{"model":"test/model"}\n',
-		)
-	})
-
-	test("does not override an existing JSON OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(root, ".opencode/opencode.json", '{"model":"test/model"}\n')
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(
-			await Bun.file(join(root, ".opencode/opencode.jsonc")).exists(),
-		).toBe(false)
-	})
-
-	test("updates an unmodified managed workbase OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(
-			root,
-			".opencode/opencode.jsonc",
-			managedOpencode('{"references":{}}\n'),
-		)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			managedWorkbaseOpencode(root),
-		)
-	})
-
-	test("preserves a modified managed workbase OpenCode config", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		const content = `${managedOpencode('{"references":{}}\n')}\n// User edit\n`
-		await write(root, ".opencode/opencode.jsonc", content)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, ".opencode/opencode.jsonc")).text()).toBe(
-			content,
-		)
-	})
-
-	test("preserves an unmanaged workbase AGENTS.md", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(root, "AGENTS.md", "# Custom instructions\n")
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
-			"# Custom instructions\n",
-		)
-	})
-
-	test("updates an unmodified managed workbase AGENTS.md", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		await write(
-			root,
-			"AGENTS.md",
-			managedAgents("# Previous Agency instructions\n"),
-		)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(
-			managedWorkbaseAgents,
-		)
-	})
-
-	test("preserves a modified managed workbase AGENTS.md", async () => {
-		await write(root, "agency.json", '{"version":2}\n')
-		const content = `${managedAgents("# Previous Agency instructions\n")}\nUser edit\n`
-		await write(root, "AGENTS.md", content)
-
-		await runTestEffect(
-			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
-		)
-
-		expect(await Bun.file(join(root, "AGENTS.md")).text()).toBe(content)
-	})
-
 	test("rejects an invalid worktree command template", async () => {
 		await write(
 			root,

package/src/services/WorkbaseService.ts

@@ -17,14 +17,6 @@ import {
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
-import {
-	canUpdateManagedWorkbaseAgents,
-	managedWorkbaseAgents,
-} from "../workbase/agents-file"
-import {
-	canUpdateManagedWorkbaseOpencode,
-	managedWorkbaseOpencode,
-} from "../workbase/opencode-file"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -119,48 +111,6 @@ const readRegistry = (configDirectory?: string) =>
 		return { path, registry: decoded.value }
 	})
 
-const ensureWorkbaseAgents = (root: string) =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystemService
-		const path = join(root, "AGENTS.md")
-		if (!(yield* fs.exists(path))) {
-			yield* fs.writeFile(path, managedWorkbaseAgents)
-			return
-		}
-
-		const content = yield* fs.readFile(path)
-		if (
-			content !== managedWorkbaseAgents &&
-			canUpdateManagedWorkbaseAgents(content)
-		) {
-			yield* fs.writeFile(path, managedWorkbaseAgents)
-		}
-	})
-
-const ensureWorkbaseOpencode = (root: string) =>
-	Effect.gen(function* () {
-		const fs = yield* FileSystemService
-		const directory = join(root, ".opencode")
-		const path = join(directory, "opencode.jsonc")
-		const managed = managedWorkbaseOpencode(root)
-		if (!(yield* fs.exists(path))) {
-			if (yield* fs.exists(join(directory, "opencode.json"))) return
-			yield* fs.createDirectory(directory)
-			yield* fs.writeFile(path, managed)
-			return
-		}
-
-		const content = yield* fs.readFile(path)
-		if (content !== managed && canUpdateManagedWorkbaseOpencode(content)) {
-			yield* fs.writeFile(path, managed)
-		}
-	})
-
-const ensureWorkbaseAgentFiles = (root: string) =>
-	Effect.all([ensureWorkbaseAgents(root), ensureWorkbaseOpencode(root)], {
-		concurrency: "unbounded",
-	})
-
 const findCycles = (nodes: readonly Dependency[]): readonly string[] => {
 	const dependencies = new Map(
 		nodes.map((node) => [node.id, [...(node.dependsOn ?? [])]]),
@@ -239,8 +189,6 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 							`${existing}${prefix}${missing.join("\n")}\n`,
 						)
 					}
-					yield* ensureWorkbaseAgentFiles(root)
-
 					return root
 				}),
 
@@ -296,7 +244,6 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 										})
 									}
 								}
-								yield* ensureWorkbaseAgentFiles(current)
 								return current
 							}
 						}

package/src/test-utils.ts

@@ -12,6 +12,7 @@ import { PhaseService } from "./services/PhaseService"
 import { WorktreeService } from "./services/WorktreeService"
 import { PullRequestService } from "./services/PullRequestService"
 import { ArchiveService } from "./services/ArchiveService"
+import { IntegrationService } from "./services/IntegrationService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -28,6 +29,7 @@ const TestLayer = Layer.mergeAll(
 	WorktreeService.Default,
 	PullRequestService.Default,
 	ArchiveService.Default,
+	IntegrationService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/utils/command.ts

@@ -5,6 +5,8 @@ export interface BaseCommandOptions {
 	readonly silent?: boolean
 	readonly verbose?: boolean
 	readonly json?: boolean
+	/** Whether this invocation may open prompts or selectors. */
+	readonly inputAllowed?: boolean
 	/**
 	 * Working directory to use instead of process.cwd().
 	 * Primarily used for testing to enable concurrent test execution.

package/src/workbase/AGENTS.md

@@ -22,6 +22,8 @@ field. Repositories listed in plural `repos` are read-only references.
 
 ## Safety
 
+- Discovery and observational commands are read-only; use
+  `agency integration sync` to update managed agent files explicitly.
 - Keep task-level decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`.
 - Keep execution-unit `status` current with `agency task status` or

package/src/workbase/workbase-choice.ts

@@ -34,6 +34,7 @@ export const resolveWorkbase = (
 	startPath: string,
 	log: (message: string) => void,
 	pick: PickWorkbase = pickWorkbase,
+	inputAllowed = true,
 ) =>
 	Effect.gen(function* () {
 		const fs = yield* FileSystemService
@@ -50,6 +51,13 @@ export const resolveWorkbase = (
 							),
 						)
 					}
+					if (!inputAllowed) {
+						return yield* Effect.fail(
+							new Error(
+								"Workbase selection requires interactive input; provide an explicit path or run Agency from a workbase",
+							),
+						)
+					}
 
 					const fzf = yield* fs.runCommand(["which", "fzf"], {
 						captureOutput: true,