@markjaquith/agency 2.7.3 → 2.9.0

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

@@ -0,0 +1,144 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { chmod, lstat, mkdir, readdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { epic } from "./epic"
+import { integration } from "./integration"
+import { phase } from "./phase"
+import { repo } from "./repo"
+import { status } from "./status"
+import { task } from "./task"
+import { validate } from "./validate"
+
+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 setReadOnly = async (path: string, readOnly: boolean): Promise<void> => {
+	const metadata = await lstat(path)
+	if (!metadata.isDirectory()) {
+		await chmod(path, readOnly ? 0o444 : 0o644)
+		return
+	}
+
+	if (!readOnly) await chmod(path, 0o755)
+	for (const entry of await readdir(path)) {
+		await setReadOnly(join(path, entry), readOnly)
+	}
+	if (readOnly) await chmod(path, 0o555)
+}
+
+describe("observational commands", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await write(
+			root,
+			"epics/example/EPIC.md",
+			`---
+ticketUrl: https://example.com/epics/example
+repos:
+  - repo: agency
+    ref: main
+tasks:
+  - id: example-task
+---
+
+# Example
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/TASK.md",
+			`---
+ticketUrl: null
+epic: example
+phases:
+  - id: implementation
+---
+
+# Example task
+`,
+		)
+		await write(
+			root,
+			"tasks/example-task/phases/implementation/PHASE.md",
+			`---
+repo: agency
+branch: feat/example
+base: main
+pr: null
+status: open
+---
+
+# Implementation
+`,
+		)
+	})
+
+	afterEach(async () => {
+		await setReadOnly(root, false)
+		await cleanupTempDir(root)
+	})
+
+	test("remain usable when the workbase is read-only", async () => {
+		await setReadOnly(root, true)
+
+		await runTestEffect(
+			WorkbaseService.pipe(Effect.flatMap((service) => service.discover(root))),
+		)
+		await runTestEffect(
+			integration({ subcommand: "status", cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			epic({ subcommand: "list", args: [], cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			epic({ subcommand: "show", args: ["example"], cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			task({ subcommand: "list", args: [], cwd: root, silent: true }),
+		)
+		await runTestEffect(
+			task({
+				subcommand: "show",
+				args: ["example-task"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "list",
+				args: ["example-task"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			phase({
+				subcommand: "show",
+				args: ["example-task", "implementation"],
+				cwd: root,
+				silent: true,
+			}),
+		)
+		await runTestEffect(
+			repo({ subcommand: "list", args: [], cwd: root, silent: true }),
+		)
+		await runTestEffect(status({ cwd: root, silent: true }))
+		await runTestEffect(validate({ path: root, silent: true }))
+
+		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/validate.ts

@@ -15,6 +15,11 @@ interface ValidateOptions extends BaseCommandOptions {
 
 class ValidationFailedError extends Data.TaggedError("ValidationFailedError")<{
 	readonly message: string
+	readonly root: string
+	readonly issues: readonly {
+		readonly path: string
+		readonly message: string
+	}[]
 }> {}
 
 export const validate = (
@@ -46,6 +51,8 @@ export const validate = (
 				.join("\n")
 			return yield* new ValidationFailedError({
 				message: `Workbase validation failed with ${report.issues.length} issue${report.issues.length === 1 ? "" : "s"}:\n${details}`,
+				root: report.root,
+				issues: report.issues,
 			})
 		}
 

package/src/commands/work.test.ts

@@ -6,7 +6,7 @@ import { EpicService } from "../services/EpicService"
 import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
-import { captureLogs } from "../test-utils"
+import { captureErrors, captureLogs } from "../test-utils"
 import { work } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
 import type { PickWorkbase } from "../workbase/workbase-choice"
@@ -568,7 +568,7 @@ describe("work command", () => {
 
 	test("respects silent and verbose logging options", async () => {
 		const verboseHarness = createHarness()
-		const verboseLogs = await captureLogs(() =>
+		const verboseLogs = await captureErrors(() =>
 			verboseHarness.run({ taskId: "example", verbose: true }),
 		)
 		expect(verboseLogs).toEqual([
@@ -577,7 +577,7 @@ describe("work command", () => {
 		expect(verboseHarness.materializeOptions[0]?.verbose).toBe(true)
 
 		const silentHarness = createHarness()
-		const silentLogs = await captureLogs(() =>
+		const silentLogs = await captureErrors(() =>
 			silentHarness.run({
 				taskId: "example",
 				verbose: true,

package/src/protocol.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "@effect/schema"
+import errorFixture from "../fixtures/protocol/error.json"
+import successFixture from "../fixtures/protocol/success.json"
+import jsonSchema from "../schemas/agency-envelope-v1.schema.json"
+import {
+	AgencyEnvelope,
+	collectCommandResult,
+	emitCommandResult,
+	errorEnvelope,
+	successEnvelope,
+} from "./protocol"
+
+describe("machine protocol", () => {
+	test("accepts the representative success and error fixtures", () => {
+		for (const fixture of [successFixture, errorFixture]) {
+			const decoded = Schema.decodeUnknownSync(AgencyEnvelope, {
+				onExcessProperty: "error",
+			})(fixture)
+			expect(JSON.stringify(decoded)).toBe(JSON.stringify(fixture))
+		}
+	})
+
+	test("publishes the matching v1 JSON Schema", () => {
+		expect(jsonSchema).toMatchObject({
+			$schema: "https://json-schema.org/draft/2020-12/schema",
+			title: "Agency machine result envelope v1",
+			oneOf: [
+				{ properties: { version: { const: 1 }, ok: { const: true } } },
+				{ properties: { version: { const: 1 }, ok: { const: false } } },
+			],
+		})
+	})
+
+	test("collects one command result without writing it", async () => {
+		const result = await collectCommandResult(async () => {
+			emitCommandResult('{"value":42}')
+		})
+		expect(successEnvelope(result)).toEqual({
+			version: 1,
+			ok: true,
+			result: { value: 42 },
+		})
+		expect(successEnvelope(undefined).result).toBeNull()
+	})
+
+	test("rejects commands that emit multiple machine results", async () => {
+		await expect(
+			collectCommandResult(async () => {
+				emitCommandResult("first")
+				emitCommandResult("second")
+			}),
+		).rejects.toThrow("more than one result")
+	})
+
+	test("normalizes unknown failures into stable error details", () => {
+		expect(errorEnvelope(new Error("boom"))).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "COMMAND_FAILED",
+				message: "boom",
+				fields: {},
+				retryable: false,
+			},
+		})
+	})
+
+	test("preserves relevant fields from classified errors", () => {
+		expect(
+			errorEnvelope({
+				_tag: "ValidationFailedError",
+				message: "invalid workbase",
+				root: "/work/agency",
+				issues: [{ path: "TASK.md", message: "invalid status" }],
+			}),
+		).toMatchObject({
+			error: {
+				code: "VALIDATION_FAILED",
+				fields: {
+					root: "/work/agency",
+					issues: [{ path: "TASK.md", message: "invalid status" }],
+				},
+			},
+		})
+	})
+})

package/src/protocol.ts

@@ -0,0 +1,211 @@
+import { Schema } from "@effect/schema"
+
+export const PROTOCOL_VERSION = 1 as const
+
+const ErrorFields = Schema.Record({
+	key: Schema.String,
+	value: Schema.Unknown,
+})
+
+export const SuccessEnvelope = Schema.Struct({
+	version: Schema.Literal(PROTOCOL_VERSION),
+	ok: Schema.Literal(true),
+	result: Schema.Unknown,
+})
+
+export const ErrorDetail = Schema.Struct({
+	code: Schema.String,
+	message: Schema.String,
+	fields: ErrorFields,
+	retryable: Schema.Boolean,
+	remediation: Schema.optional(Schema.String),
+})
+
+export const ErrorEnvelope = Schema.Struct({
+	version: Schema.Literal(PROTOCOL_VERSION),
+	ok: Schema.Literal(false),
+	error: ErrorDetail,
+})
+
+export const AgencyEnvelope = Schema.Union(SuccessEnvelope, ErrorEnvelope)
+
+export type SuccessEnvelope = Schema.Schema.Type<typeof SuccessEnvelope>
+export type ErrorEnvelope = Schema.Schema.Type<typeof ErrorEnvelope>
+export type AgencyEnvelope = Schema.Schema.Type<typeof AgencyEnvelope>
+
+interface ErrorMetadata {
+	readonly code: string
+	readonly retryable: boolean
+	readonly remediation?: string
+}
+
+const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
+	CliUsageError: {
+		code: "CLI_USAGE",
+		retryable: false,
+		remediation: "Correct the arguments using the usage value in error.fields.",
+	},
+	WorkbaseNotFoundError: {
+		code: "WORKBASE_NOT_FOUND",
+		retryable: false,
+		remediation:
+			"Run the command from an Agency workbase or provide an explicit workbase path.",
+	},
+	WorkbaseConfigError: {
+		code: "WORKBASE_CONFIG_INVALID",
+		retryable: false,
+		remediation: "Correct the workbase configuration and retry the command.",
+	},
+	WorkbaseRegistryError: {
+		code: "WORKBASE_REGISTRY_ERROR",
+		retryable: false,
+		remediation: "Correct the registered workbase entry and retry the command.",
+	},
+	FileNotFoundError: {
+		code: "FILE_NOT_FOUND",
+		retryable: false,
+		remediation: "Restore the required file or correct the supplied path.",
+	},
+	FileSystemError: { code: "FILESYSTEM_ERROR", retryable: false },
+	FrontmatterParseError: {
+		code: "FRONTMATTER_INVALID",
+		retryable: false,
+		remediation: "Correct the document frontmatter and retry the command.",
+	},
+	ValidationFailedError: {
+		code: "VALIDATION_FAILED",
+		retryable: false,
+		remediation: "Resolve the validation issues in error.fields and retry.",
+	},
+	RepositoryError: { code: "REPOSITORY_ERROR", retryable: false },
+	EpicError: { code: "EPIC_ERROR", retryable: false },
+	TaskError: { code: "TASK_ERROR", retryable: false },
+	PhaseError: { code: "PHASE_ERROR", retryable: false },
+	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
+	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
+	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
+	ProcessError: { code: "PROCESS_ERROR", retryable: true },
+	ProtocolOutputError: {
+		code: "PROTOCOL_OUTPUT_ERROR",
+		retryable: false,
+		remediation: "Report this Agency protocol violation.",
+	},
+}
+
+class ProtocolOutputError extends Error {
+	readonly _tag = "ProtocolOutputError"
+}
+
+let resultCollector: ((value: unknown) => void) | undefined
+
+const parseCommandResult = (value: unknown): unknown => {
+	if (typeof value !== "string") return value
+	try {
+		return JSON.parse(value)
+	} catch {
+		return value
+	}
+}
+
+export const emitCommandResult = (value: unknown): void => {
+	if (resultCollector) {
+		resultCollector(parseCommandResult(value))
+		return
+	}
+	console.log(value)
+}
+
+export const collectCommandResult = async (
+	run: () => Promise<void>,
+): Promise<unknown> => {
+	if (resultCollector) {
+		throw new ProtocolOutputError(
+			"A machine result collector is already active.",
+		)
+	}
+
+	let emitted = false
+	let result: unknown = null
+	const originalLog = console.log
+	resultCollector = (value) => {
+		if (emitted) {
+			throw new ProtocolOutputError(
+				"A machine command emitted more than one result.",
+			)
+		}
+		emitted = true
+		result = value
+	}
+	console.log = (...values) => {
+		resultCollector?.(
+			parseCommandResult(values.length === 1 ? values[0] : values.join(" ")),
+		)
+	}
+
+	try {
+		await run()
+		return result
+	} finally {
+		console.log = originalLog
+		resultCollector = undefined
+	}
+}
+
+const errorTag = (error: unknown): string | undefined => {
+	if (typeof error !== "object" || error === null) return undefined
+	if ("_tag" in error && typeof error._tag === "string") return error._tag
+	if (error instanceof Error && error.name !== "Error") return error.name
+	return undefined
+}
+
+const errorMessage = (error: unknown): string => {
+	if (
+		typeof error === "object" &&
+		error !== null &&
+		"message" in error &&
+		typeof error.message === "string"
+	) {
+		return error.message
+	}
+	return String(error)
+}
+
+const errorFields = (error: unknown): Record<string, unknown> => {
+	if (typeof error !== "object" || error === null) return {}
+	return Object.fromEntries(
+		Object.entries(error).filter(
+			([key, value]) =>
+				!key.startsWith("_") &&
+				key !== "name" &&
+				key !== "message" &&
+				key !== "cause" &&
+				value !== undefined,
+		),
+	)
+}
+
+export const successEnvelope = (result: unknown): SuccessEnvelope => ({
+	version: PROTOCOL_VERSION,
+	ok: true,
+	result: result === undefined ? null : result,
+})
+
+export const errorEnvelope = (error: unknown): ErrorEnvelope => {
+	const metadata = errorMetadata[errorTag(error) ?? ""] ?? {
+		code: "COMMAND_FAILED",
+		retryable: false,
+	}
+	return {
+		version: PROTOCOL_VERSION,
+		ok: false,
+		error: {
+			...metadata,
+			message: errorMessage(error),
+			fields: errorFields(error),
+		},
+	}
+}
+
+export const writeEnvelope = (envelope: AgencyEnvelope): void => {
+	process.stdout.write(`${JSON.stringify(envelope)}\n`)
+}

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")
+	})
+})