opencodekit 0.16.15 → 0.16.18

package/dist/template/.opencode/tool/action-queue.ts

@@ -0,0 +1,308 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { tool } from "@opencode-ai/plugin";
+import {
+	type ActionQueueItemInput,
+	clearActionQueueItems,
+	listActionQueueItems,
+	replaceActionQueueItems,
+} from "../plugin/lib/memory-db.js";
+
+const execFileAsync = promisify(execFile);
+const SWARM_PROGRESS_FILE = ".beads/swarm-progress.jsonl";
+
+type QueueOperation = "status" | "refresh" | "clear";
+
+interface QueueWorkerEntry {
+	timestamp?: string;
+	team_name?: string;
+	worker_id?: string;
+	phase?: string;
+	progress?: number;
+	status?: string;
+	file?: string;
+}
+
+interface QueueBeadTask {
+	id: string;
+	title: string;
+	status?: string;
+	priority?: number;
+}
+
+function parsePayload(payload: string | null): Record<string, unknown> {
+	if (!payload) return {};
+	try {
+		const parsed = JSON.parse(payload) as Record<string, unknown>;
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+
+function buildSnapshot(
+	items: ActionQueueItemInput[] | ReturnType<typeof listActionQueueItems>,
+) {
+	const normalized = items.map((item) => ({
+		id: item.id,
+		source: item.source,
+		status: item.status,
+		title: item.title,
+		owner: item.owner ?? null,
+		payload:
+			"payload" in item && typeof item.payload === "string"
+				? parsePayload(item.payload)
+				: (item.payload ?? {}),
+	}));
+
+	const pendingApprovals = normalized.filter(
+		(item) => item.source === "approval" && item.status === "pending",
+	);
+	const readyTasks = normalized.filter(
+		(item) => item.source === "bead" && item.status === "ready",
+	);
+	const idleWorkers = normalized.filter(
+		(item) => item.source === "worker" && item.status === "idle",
+	);
+
+	return {
+		generated_at: new Date().toISOString(),
+		pending_approvals: pendingApprovals,
+		ready_tasks: readyTasks,
+		idle_workers: idleWorkers,
+		counts: {
+			pending_approvals: pendingApprovals.length,
+			ready_tasks: readyTasks.length,
+			idle_workers: idleWorkers.length,
+			total: normalized.length,
+		},
+	};
+}
+
+async function readReadyTasks(worktree: string): Promise<QueueBeadTask[]> {
+	try {
+		const { stdout } = await execFileAsync("br", ["ready", "--json"], {
+			cwd: worktree,
+			timeout: 15000,
+		});
+		const parsed = JSON.parse(stdout) as QueueBeadTask[];
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		try {
+			const { stdout } = await execFileAsync("br", ["ready"], {
+				cwd: worktree,
+				timeout: 15000,
+			});
+			const tasks: QueueBeadTask[] = [];
+			for (const line of stdout.split("\n")) {
+				const match = line.match(
+					/^#?(\S+)\s+\[(\w+)\]\s+(?:\(P(\d)\))?\s*(.+)$/,
+				);
+				if (!match) continue;
+				tasks.push({
+					id: match[1],
+					status: match[2],
+					priority: match[3] ? Number.parseInt(match[3], 10) : 2,
+					title: match[4],
+				});
+			}
+			return tasks;
+		} catch {
+			return [];
+		}
+	}
+}
+
+async function readWorkerEntries(
+	worktree: string,
+): Promise<QueueWorkerEntry[]> {
+	const progressPath = path.join(worktree, SWARM_PROGRESS_FILE);
+	try {
+		const content = await fs.readFile(progressPath, "utf-8");
+		const entries = content
+			.trim()
+			.split("\n")
+			.filter(Boolean)
+			.map((line) => JSON.parse(line) as QueueWorkerEntry);
+
+		const latestByWorker = new Map<string, QueueWorkerEntry>();
+		for (const entry of entries) {
+			if (!entry.worker_id) continue;
+			const previous = latestByWorker.get(entry.worker_id);
+			if (!previous) {
+				latestByWorker.set(entry.worker_id, entry);
+				continue;
+			}
+
+			const currentEpoch = Date.parse(entry.timestamp || "");
+			const previousEpoch = Date.parse(previous.timestamp || "");
+			if (Number.isNaN(previousEpoch) || currentEpoch >= previousEpoch) {
+				latestByWorker.set(entry.worker_id, entry);
+			}
+		}
+
+		return Array.from(latestByWorker.values());
+	} catch {
+		return [];
+	}
+}
+
+function toQueueItems(
+	readyTasks: QueueBeadTask[],
+	workerEntries: QueueWorkerEntry[],
+): ActionQueueItemInput[] {
+	const items: ActionQueueItemInput[] = [];
+
+	for (const task of readyTasks) {
+		items.push({
+			id: `bead:${task.id}`,
+			source: "bead",
+			status: "ready",
+			title: task.title,
+			owner: task.id,
+			payload: {
+				bead_id: task.id,
+				priority: task.priority ?? null,
+				status: task.status ?? "ready",
+			},
+		});
+	}
+
+	for (const worker of workerEntries) {
+		const workerId = worker.worker_id || "unknown";
+		const status = (worker.status || "").toLowerCase();
+		const phase = (worker.phase || "").toLowerCase();
+		const needsApproval =
+			status.includes("approval") ||
+			status === "awaiting_approval" ||
+			status === "needs_approval" ||
+			phase.includes("approval");
+
+		if (status === "idle") {
+			items.push({
+				id: `worker:${workerId}`,
+				source: "worker",
+				status: "idle",
+				title: `Worker ${workerId} is idle`,
+				owner: workerId,
+				payload: {
+					phase: worker.phase || null,
+					progress: worker.progress ?? null,
+					file: worker.file || null,
+					timestamp: worker.timestamp || null,
+				},
+			});
+		}
+
+		if (needsApproval) {
+			items.push({
+				id: `approval:${workerId}`,
+				source: "approval",
+				status: "pending",
+				title: `Approval needed for worker ${workerId}`,
+				owner: workerId,
+				payload: {
+					phase: worker.phase || null,
+					status: worker.status || null,
+					progress: worker.progress ?? null,
+					file: worker.file || null,
+					timestamp: worker.timestamp || null,
+				},
+			});
+		}
+	}
+
+	return items;
+}
+
+async function refreshSnapshot(worktree: string) {
+	const [readyTasks, workerEntries] = await Promise.all([
+		readReadyTasks(worktree),
+		readWorkerEntries(worktree),
+	]);
+
+	const items = toQueueItems(readyTasks, workerEntries);
+	replaceActionQueueItems(items);
+
+	return buildSnapshot(items);
+}
+
+export default tool({
+	description: `Unified action queue for operators.
+
+Returns a consumable queue with:
+- pending approvals
+- ready tasks
+- idle workers
+
+Operations:
+- status: Read last stored queue snapshot
+- refresh: Recompute queue from Beads + swarm progress and store snapshot
+- clear: Clear stored queue snapshot`,
+	args: {
+		op: tool.schema
+			.enum(["status", "refresh", "clear"])
+			.optional()
+			.default("status")
+			.describe("Operation: status, refresh, clear"),
+	},
+	execute: async (args: { op?: QueueOperation }, ctx) => {
+		const op = args.op || "status";
+		const worktree = ctx.worktree || process.cwd();
+
+		if (op === "clear") {
+			clearActionQueueItems();
+			return JSON.stringify(
+				{
+					op: "clear",
+					result: "ok",
+					cleared: true,
+					queue: buildSnapshot([]),
+				},
+				null,
+				2,
+			);
+		}
+
+		if (op === "refresh") {
+			const queue = await refreshSnapshot(worktree);
+			return JSON.stringify(
+				{
+					op: "refresh",
+					result: "ok",
+					queue,
+				},
+				null,
+				2,
+			);
+		}
+
+		const stored = listActionQueueItems();
+		if (stored.length === 0) {
+			const queue = await refreshSnapshot(worktree);
+			return JSON.stringify(
+				{
+					op: "status",
+					result: "ok",
+					source: "live-refresh",
+					queue,
+				},
+				null,
+				2,
+			);
+		}
+
+		return JSON.stringify(
+			{
+				op: "status",
+				result: "ok",
+				source: "snapshot",
+				queue: buildSnapshot(stored),
+			},
+			null,
+			2,
+		);
+	},
+});

package/dist/template/.opencode/tool/swarm.ts

@@ -1,10 +1,10 @@
-import { exec } from "node:child_process";
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import { tool } from "@opencode-ai/plugin";
 
-const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 /**
  * Unified swarm orchestration tool.
@@ -38,7 +38,7 @@ Usage:
 		// Monitor args
 		team: tool.schema.string().optional().describe("Team name (monitor)"),
 		action: tool.schema
-			.string()
+			.enum(["update", "render", "status", "clear", "push", "pull"])
 			.optional()
 			.describe(
 				"Monitor action: update, render, status, clear | Sync action: push, pull",
@@ -82,7 +82,7 @@ Usage:
 			.describe("Write to file (delegate)"),
 		// Sync args
 		filter: tool.schema
-			.string()
+			.enum(["open", "in_progress", "all"])
 			.optional()
 			.describe("Filter: open, in_progress, all (sync)"),
 	},
@@ -96,7 +96,7 @@ Usage:
 			case "monitor":
 				return monitorOperation(args, worktree);
 			case "delegate":
-				return delegateOperation(args);
+				return delegateOperation(args, worktree);
 			case "sync":
 				return syncOperation(args, worktree);
 			default:
@@ -240,10 +240,21 @@ interface ProgressEntry {
 	file?: string;
 }
 
+type MonitorAction = "update" | "render" | "status" | "clear";
+type SyncAction = "push" | "pull";
+type SyncFilter = "open" | "in_progress" | "all";
+
+const MONITOR_ACTIONS = new Set<MonitorAction>([
+	"update",
+	"render",
+	"status",
+	"clear",
+]);
+
 async function monitorOperation(
 	args: {
 		team?: string;
-		action?: string;
+		action?: MonitorAction | SyncAction;
 		worker_id?: string;
 		phase?: string;
 		progress?: number;
@@ -253,7 +264,10 @@ async function monitorOperation(
 	worktree: string,
 ): Promise<string> {
 	const team = args.team || "default";
-	const action = args.action || "status";
+	if (args.action && !MONITOR_ACTIONS.has(args.action as MonitorAction)) {
+		return `Invalid monitor action: ${args.action}`;
+	}
+	const action: MonitorAction = (args.action as MonitorAction) || "status";
 
 	switch (action) {
 		case "update":
@@ -367,16 +381,19 @@ async function clearTeam(team: string, worktree: string): Promise<string> {
 // DELEGATE OPERATION (from swarm-delegate.ts)
 // ============================================================
 
-function delegateOperation(args: {
-	bead_id?: string;
-	title?: string;
-	outcome?: string;
-	must_do?: string;
-	must_not?: string;
-	checks?: string;
-	context?: string;
-	write?: boolean;
-}): string {
+async function delegateOperation(
+	args: {
+		bead_id?: string;
+		title?: string;
+		outcome?: string;
+		must_do?: string;
+		must_not?: string;
+		checks?: string;
+		context?: string;
+		write?: boolean;
+	},
+	worktree: string,
+): Promise<string> {
 	if (!args.bead_id) return "Error: bead_id required";
 	if (!args.outcome) return "Error: outcome required";
 
@@ -405,24 +422,21 @@ function delegateOperation(args: {
 
 	if (!args.write) return packet;
 
-	// Write to artifact file (sync for simplicity)
-	const artifactDir = path.join(
-		process.cwd(),
-		".beads",
-		"artifacts",
-		args.bead_id,
-	);
+	const artifactDir = path.join(worktree, ".beads", "artifacts", args.bead_id);
 	const outPath = path.join(artifactDir, "delegation.md");
-	fs.mkdir(artifactDir, { recursive: true })
-		.then(() =>
-			fs.appendFile(
-				outPath,
-				`\n---\nGenerated: ${new Date().toISOString()}\n---\n\n${packet}\n`,
-			),
-		)
-		.catch(() => {});
 
-	return `✓ Delegation packet written to ${outPath}\n\n${packet}`;
+	try {
+		await fs.mkdir(artifactDir, { recursive: true });
+		await fs.appendFile(
+			outPath,
+			`\n---\nGenerated: ${new Date().toISOString()}\n---\n\n${packet}\n`,
+			"utf-8",
+		);
+		return `✓ Delegation packet written to ${outPath}\n\n${packet}`;
+	} catch (error: unknown) {
+		const message = error instanceof Error ? error.message : String(error);
+		return `Error writing delegation packet: ${message}`;
+	}
 }
 
 // ============================================================
@@ -446,10 +460,14 @@ interface BeadTask {
 }
 
 async function syncOperation(
-	args: { action?: string; filter?: string },
+	args: { action?: MonitorAction | SyncAction; filter?: SyncFilter },
 	worktree: string,
 ): Promise<string> {
-	const action = args.action || "push";
+	if (args.action && args.action !== "push" && args.action !== "pull") {
+		return `Invalid sync action: ${args.action}`;
+	}
+
+	const action: SyncAction = (args.action as SyncAction) || "push";
 
 	if (action === "push") {
 		return pushBeadsToTodos(worktree, args.filter || "open");
@@ -462,12 +480,17 @@ async function syncOperation(
 
 async function pushBeadsToTodos(
 	worktree: string,
-	filter: string,
+	filter: SyncFilter,
 ): Promise<string> {
 	try {
-		const statusFilter = filter === "all" ? "" : `--status ${filter}`;
-		const { stdout } = await execAsync(`br list ${statusFilter} --json`, {
+		const args = ["list", "--json"];
+		if (filter !== "all") {
+			args.push("--status", filter);
+		}
+
+		const { stdout } = await execFileAsync("br", args, {
 			cwd: worktree,
+			timeout: 15000,
 		});
 
 		let tasks: BeadTask[];
@@ -532,10 +555,12 @@ async function pullTodosToBeads(worktree: string): Promise<string> {
 			for (const todo of todos) {
 				if (todo.beadId && todo.status === "completed") {
 					try {
-						await execAsync(
-							`br close ${todo.beadId} --reason "Completed via todo"`,
+						await execFileAsync(
+							"br",
+							["close", todo.beadId, "--reason", "Completed via todo"],
 							{
 								cwd: worktree,
+								timeout: 15000,
 							},
 						);
 						updated++;

package/package.json

@@ -1,8 +1,15 @@
 {
 	"name": "opencodekit",
-	"version": "0.16.15",
+	"version": "0.16.18",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
-	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
+	"keywords": [
+		"agents",
+		"cli",
+		"mcp",
+		"opencode",
+		"opencodekit",
+		"template"
+	],
 	"license": "MIT",
 	"author": "OpenCodeKit",
 	"repository": {
@@ -12,7 +19,10 @@
 	"bin": {
 		"ock": "dist/index.js"
 	},
-	"files": ["dist", "README.md"],
+	"files": [
+		"dist",
+		"README.md"
+	],
 	"type": "module",
 	"publishConfig": {
 		"access": "public",
@@ -26,6 +36,9 @@
 		"typecheck": "tsc --noEmit",
 		"test": "bun test",
 		"test:watch": "bun test --watch",
+		"validate:command-doc": "bun run src/validation/command-doc.ts --check",
+		"validate:docs-drift": "bun run src/validation/docs-drift.ts --check",
+		"validate:governance": "npm run validate:command-doc && npm run validate:docs-drift",
 		"lint": "oxlint .",
 		"lint:fix": "oxlint --fix .",
 		"format": "oxfmt",

package/dist/template/.opencode/.agents/skills/context7/SKILL.md

@@ -1,88 +0,0 @@
----
-name: context7
-description: Retrieve up-to-date documentation for software libraries, frameworks, and components via the Context7 API. This skill should be used when looking up documentation for any programming library or framework, finding code examples for specific APIs or features, verifying correct usage of library functions, or obtaining current information about library APIs that may have changed since training.
----
-
-# Context7
-
-## Overview
-
-This skill enables retrieval of current documentation for software libraries and components by querying the Context7 API via curl. Use it instead of relying on potentially outdated training data.
-
-## Workflow
-
-### Step 1: Search for the Library
-
-To find the Context7 library ID, query the search endpoint:
-
-```bash
-curl -s "https://context7.com/api/v2/libs/search?libraryName=LIBRARY_NAME&query=TOPIC" | jq '.results[0]'
-```
-
-**Parameters:**
-
-- `libraryName` (required): The library name to search for (e.g., "react", "nextjs", "fastapi", "axios")
-- `query` (required): A description of the topic for relevance ranking
-
-**Response fields:**
-
-- `id`: Library identifier for the context endpoint (e.g., `/websites/react_dev_reference`)
-- `title`: Human-readable library name
-- `description`: Brief description of the library
-- `totalSnippets`: Number of documentation snippets available
-
-### Step 2: Fetch Documentation
-
-To retrieve documentation, use the library ID from step 1:
-
-```bash
-curl -s "https://context7.com/api/v2/context?libraryId=LIBRARY_ID&query=TOPIC&type=txt"
-```
-
-**Parameters:**
-
-- `libraryId` (required): The library ID from search results
-- `query` (required): The specific topic to retrieve documentation for
-- `type` (optional): Response format - `json` (default) or `txt` (plain text, more readable)
-
-## Examples
-
-### React hooks documentation
-
-```bash
-# Find React library ID
-curl -s "https://context7.com/api/v2/libs/search?libraryName=react&query=hooks" | jq '.results[0].id'
-# Returns: "/websites/react_dev_reference"
-
-# Fetch useState documentation
-curl -s "https://context7.com/api/v2/context?libraryId=/websites/react_dev_reference&query=useState&type=txt"
-```
-
-### Next.js routing documentation
-
-```bash
-# Find Next.js library ID
-curl -s "https://context7.com/api/v2/libs/search?libraryName=nextjs&query=routing" | jq '.results[0].id'
-
-# Fetch app router documentation
-curl -s "https://context7.com/api/v2/context?libraryId=/vercel/next.js&query=app+router&type=txt"
-```
-
-### FastAPI dependency injection
-
-```bash
-# Find FastAPI library ID
-curl -s "https://context7.com/api/v2/libs/search?libraryName=fastapi&query=dependencies" | jq '.results[0].id'
-
-# Fetch dependency injection documentation
-curl -s "https://context7.com/api/v2/context?libraryId=/fastapi/fastapi&query=dependency+injection&type=txt"
-```
-
-## Tips
-
-- Use `type=txt` for more readable output
-- Use `jq` to filter and format JSON responses
-- Be specific with the `query` parameter to improve relevance ranking
-- If the first search result is not correct, check additional results in the array
-- URL-encode query parameters containing spaces (use `+` or `%20`)
-- No API key is required for basic usage (rate-limited)