@markjaquith/agency 2.7.3 → 2.9.0

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

@@ -3,7 +3,7 @@ import { Effect } from "effect"
 import { mkdir, rm } from "node:fs/promises"
 import { join } from "node:path"
 import {
-	captureLogs,
+	captureErrors,
 	cleanupTempDir,
 	createTempDir,
 	runTestEffect,
@@ -287,7 +287,7 @@ describe("WorktreeService", () => {
 			),
 		)
 
-		const logs = await captureLogs(() =>
+		const logs = await captureErrors(() =>
 			runTestEffect(
 				WorktreeService.pipe(
 					Effect.flatMap((service) =>

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>(
@@ -43,17 +45,24 @@ export async function runTestEffect<A, E>(
 	return Effect.runPromise(program)
 }
 
-export async function captureLogs(
+async function captureConsole(
+	method: "log" | "error",
 	run: () => Promise<unknown>,
 ): Promise<string[]> {
 	const logs: string[] = []
-	const log = spyOn(console, "log").mockImplementation((...args) => {
+	const output = spyOn(console, method).mockImplementation((...args) => {
 		logs.push(args.join(" "))
 	})
 	try {
 		await run()
 		return logs
 	} finally {
-		log.mockRestore()
+		output.mockRestore()
 	}
 }
+
+export const captureLogs = (run: () => Promise<unknown>) =>
+	captureConsole("log", run)
+
+export const captureErrors = (run: () => Promise<unknown>) =>
+	captureConsole("error", run)

package/src/utils/effect.test.ts

@@ -1,24 +1,30 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, spyOn, test } from "bun:test"
 import { captureLogs } from "../test-utils"
 import { createLoggers } from "./effect"
 
 describe("createLoggers", () => {
 	test("keeps JSON output machine-readable when verbose is enabled", async () => {
+		const errors: string[] = []
+		const error = spyOn(console, "error").mockImplementation((...args) => {
+			errors.push(args.join(" "))
+		})
 		const logs = await captureLogs(async () => {
 			const { log, verboseLog } = createLoggers({ json: true, verbose: true })
 			verboseLog("debug")
 			log('{"ok":true}')
 		})
+		error.mockRestore()
 
 		expect(logs).toEqual(['{"ok":true}'])
+		expect(errors).toEqual(["debug"])
 	})
 
-	test("lets silent suppress JSON output", async () => {
+	test("lets JSON output override silent", async () => {
 		const logs = await captureLogs(async () => {
 			const { log } = createLoggers({ json: true, silent: true })
 			log('{"ok":true}')
 		})
 
-		expect(logs).toEqual([])
+		expect(logs).toEqual(['{"ok":true}'])
 	})
 })

package/src/utils/effect.ts

@@ -1,3 +1,5 @@
+import { emitCommandResult } from "../protocol"
+
 export function createLoggers(options: {
 	readonly silent?: boolean
 	readonly verbose?: boolean
@@ -5,7 +7,7 @@ export function createLoggers(options: {
 }) {
 	const { silent = false, verbose = false, json = false } = options
 	return {
-		log: silent ? () => {} : console.log,
-		verboseLog: verbose && !silent && !json ? console.log : () => {},
+		log: json ? emitCommandResult : silent ? () => {} : console.log,
+		verboseLog: verbose && !silent ? console.error : () => {},
 	}
 }

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