agent-canvas 0.2.0 → 0.6.0

package/bin/lib/commands/install.ts

@@ -1,48 +1,48 @@
-import { parseArgs } from "util";
-import { existsSync, mkdirSync, cpSync, unlinkSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import { PACKAGE_ROOT } from "../config.ts";
-import { readLine } from "../helpers.ts";
+import { cpSync, existsSync, mkdirSync, unlinkSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { parseArgs } from 'util'
+import { PACKAGE_ROOT } from '../config.ts'
+import { readLine } from '../helpers.ts'
 
 export async function handleInstall(args: string[]) {
-  const { positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-  });
+	const { positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+	})
 
-  let mode = positionals[0] as "local" | "global" | undefined;
+	let mode = positionals[0] as 'local' | 'global' | undefined
 
-  if (!mode) {
-    process.stdout.write("Install canvas skill for Claude Code.\n\n");
-    process.stdout.write("  local  — install to .claude/ in current project\n");
-    process.stdout.write("  global — install to ~/.claude/ for all projects\n\n");
-    process.stdout.write("Choose [local/global]: ");
+	if (!mode) {
+		process.stdout.write('Install canvas skill for Claude Code.\n\n')
+		process.stdout.write('  local  — install to .claude/ in current project\n')
+		process.stdout.write('  global — install to ~/.claude/ for all projects\n\n')
+		process.stdout.write('Choose [local/global]: ')
 
-    const input = await readLine();
-    mode = input.trim().toLowerCase() as "local" | "global";
-  }
+		const input = await readLine()
+		mode = input.trim().toLowerCase() as 'local' | 'global'
+	}
 
-  if (mode !== "local" && mode !== "global") {
-    console.error("Error: specify 'local' or 'global'");
-    process.exit(1);
-  }
+	if (mode !== 'local' && mode !== 'global') {
+		console.error("Error: specify 'local' or 'global'")
+		process.exit(1)
+	}
 
-  const targetBase = mode === "global"
-    ? join(homedir(), ".claude")
-    : join(process.cwd(), ".claude");
+	const targetBase = mode === 'global'
+		? join(homedir(), '.claude')
+		: join(process.cwd(), '.claude')
 
-  const skillTarget = join(targetBase, "skills", "canvas");
-  mkdirSync(skillTarget, { recursive: true });
+	const skillTarget = join(targetBase, 'skills', 'canvas')
+	mkdirSync(skillTarget, { recursive: true })
 
-  cpSync(join(PACKAGE_ROOT, "skills", "canvas", "SKILL.md"), join(skillTarget, "SKILL.md"));
+	cpSync(join(PACKAGE_ROOT, 'skills', 'canvas', 'SKILL.md'), join(skillTarget, 'SKILL.md'))
 
-  // Clean up files from older versions
-  for (const old of ["components.md", "flows.md"]) {
-    const p = join(skillTarget, old);
-    if (existsSync(p)) unlinkSync(p);
-  }
+	// Clean up files from older versions
+	for (const old of ['components.md', 'flows.md']) {
+		const p = join(skillTarget, old)
+		if (existsSync(p)) unlinkSync(p)
+	}
 
-  console.log(`  Skill installed to ${skillTarget}`);
-  console.log(`\nInstalled! The /canvas command is now available in Claude Code.`);
+	console.log(`  Skill installed to ${skillTarget}`)
+	console.log(`\nInstalled! The /canvas command is now available in Claude Code.`)
 }

package/bin/lib/commands/instructions.ts

@@ -1,66 +1,66 @@
-import { existsSync, readFileSync, readdirSync } from "fs";
-import { join } from "path";
-import { PACKAGE_ROOT } from "../config.ts";
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { PACKAGE_ROOT } from '../config.ts'
 
-const INSTRUCTIONS_DIR = join(PACKAGE_ROOT, "bin", "lib", "instructions");
+const INSTRUCTIONS_DIR = join(PACKAGE_ROOT, 'bin', 'lib', 'instructions')
 
 export async function handleInstructions(args: string[]) {
-  const topic = args[0];
+	const topic = args[0]
 
-  if (!topic) {
-    // Base instructions — overview
-    const overview = readFileSync(join(INSTRUCTIONS_DIR, "overview.md"), "utf-8");
-    process.stdout.write(overview);
-    return;
-  }
+	if (!topic) {
+		// Base instructions — overview
+		const overview = readFileSync(join(INSTRUCTIONS_DIR, 'overview.md'), 'utf-8')
+		process.stdout.write(overview)
+		return
+	}
 
-  if (topic === "--list") {
-    printAvailableTopics(process.stdout);
-    return;
-  }
+	if (topic === '--list') {
+		printAvailableTopics(process.stdout)
+		return
+	}
 
-  // Try exact match: topic.md
-  const file = join(INSTRUCTIONS_DIR, `${topic}.md`);
-  if (existsSync(file)) {
-    const content = readFileSync(file, "utf-8");
-    process.stdout.write(content);
-    return;
-  }
+	// Try exact match: topic.md
+	const file = join(INSTRUCTIONS_DIR, `${topic}.md`)
+	if (existsSync(file)) {
+		const content = readFileSync(file, 'utf-8')
+		process.stdout.write(content)
+		return
+	}
 
-  // Not found
-  console.error(`Unknown topic: ${topic}\n`);
-  printAvailableTopics(process.stderr);
-  process.exit(1);
+	// Not found
+	console.error(`Unknown topic: ${topic}\n`)
+	printAvailableTopics(process.stderr)
+	process.exit(1)
 }
 
 function printAvailableTopics(out: NodeJS.WriteStream) {
-  const files = readdirSync(INSTRUCTIONS_DIR)
-    .filter(f => f.endsWith(".md") && f !== "overview.md")
-    .map(f => f.replace(".md", ""))
-    .sort();
+	const files = readdirSync(INSTRUCTIONS_DIR)
+		.filter(f => f.endsWith('.md') && f !== 'overview.md')
+		.map(f => f.replace('.md', ''))
+		.sort()
 
-  const components = files.filter(f => f.startsWith("component-"));
-  const flows = files.filter(f => f.startsWith("flow-"));
-  const other = files.filter(f => !f.startsWith("component-") && !f.startsWith("flow-"));
+	const components = files.filter(f => f.startsWith('component-'))
+	const flows = files.filter(f => f.startsWith('flow-'))
+	const other = files.filter(f => !f.startsWith('component-') && !f.startsWith('flow-'))
 
-  const lines: string[] = ["## Available Detail Topics", ""];
+	const lines: string[] = ['## Available Detail Topics', '']
 
-  if (components.length) {
-    lines.push("### Components");
-    for (const c of components) lines.push(`- \`${c}\``);
-    lines.push("");
-  }
-  if (flows.length) {
-    lines.push("### Flows");
-    for (const f of flows) lines.push(`- \`${f}\``);
-    lines.push("");
-  }
-  if (other.length) {
-    lines.push("### Other");
-    for (const o of other) lines.push(`- \`${o}\``);
-    lines.push("");
-  }
+	if (components.length) {
+		lines.push('### Components')
+		for (const c of components) lines.push(`- \`${c}\``)
+		lines.push('')
+	}
+	if (flows.length) {
+		lines.push('### Flows')
+		for (const f of flows) lines.push(`- \`${f}\``)
+		lines.push('')
+	}
+	if (other.length) {
+		lines.push('### Other')
+		for (const o of other) lines.push(`- \`${o}\``)
+		lines.push('')
+	}
 
-  lines.push("Usage: `bunx agent-canvas instructions <topic>`");
-  out.write(lines.join("\n") + "\n");
+	lines.push('Usage: `bunx agent-canvas instructions <topic>`')
+	out.write(lines.join('\n') + '\n')
 }

package/bin/lib/commands/push.ts

@@ -1,111 +1,129 @@
-import { parseArgs } from "util";
-import { existsSync, statSync } from "fs";
-import { resolve, basename } from "path";
-import { BASE_URL } from "../config.ts";
-import { ensureDaemon, stopDaemon, startDaemon } from "../daemon-lifecycle.ts";
-import { getSessionId, openBrowser } from "../helpers.ts";
+import { existsSync, statSync } from 'fs'
+import { basename, resolve } from 'path'
+import { parseArgs } from 'util'
+import { z } from 'zod'
+import { BASE_URL } from '../config.ts'
+import { ensureDaemon, startDaemon, stopDaemon } from '../daemon-lifecycle.ts'
+import { getSessionId, openBrowser } from '../helpers.ts'
+
+const pushResponseSchema = z.union([
+	z.object({
+		ok: z.literal(true),
+		browserUrl: z.string(),
+		isNew: z.boolean(),
+		revision: z.number(),
+		canvasFiles: z.array(z.string()),
+	}),
+	z.object({
+		ok: z.literal(false).optional(),
+		error: z.string().optional(),
+		errors: z.record(z.unknown()).optional(),
+		unconsumedFeedback: z.string().optional(),
+	}),
+])
 
 export async function handlePush(args: string[]) {
-  const { values, positionals } = parseArgs({
-    args,
-    options: {
-      session: { type: "string" },
-      label: { type: "string" },
-      response: { type: "string" },
-    },
-    allowPositionals: true,
-  });
+	const { values, positionals } = parseArgs({
+		args,
+		options: {
+			session: { type: 'string' },
+			label: { type: 'string' },
+			response: { type: 'string' },
+		},
+		allowPositionals: true,
+	})
 
-  const target = positionals[0];
-  if (!target) {
-    console.error("Error: No directory specified. Usage: agent-canvas push <directory>");
-    process.exit(1);
-  }
+	const target = positionals[0]
+	if (!target) {
+		console.error('Error: No directory specified. Usage: agent-canvas push <directory>')
+		process.exit(1)
+	}
 
-  const resolvedPath = resolve(target);
-  if (!existsSync(resolvedPath)) {
-    console.error(`Error: Path not found: ${resolvedPath}`);
-    process.exit(1);
-  }
+	const resolvedPath = resolve(target)
+	if (!existsSync(resolvedPath)) {
+		console.error(`Error: Path not found: ${resolvedPath}`)
+		process.exit(1)
+	}
 
-  if (statSync(resolvedPath).isFile()) {
-    console.error(`Error: Expected a directory, got a file: ${resolvedPath}`);
-    console.error("Usage: agent-canvas push <directory>");
-    process.exit(1);
-  }
+	if (statSync(resolvedPath).isFile()) {
+		console.error(`Error: Expected a directory, got a file: ${resolvedPath}`)
+		console.error('Usage: agent-canvas push <directory>')
+		process.exit(1)
+	}
 
-  const sessionId = getSessionId(values.session);
-  const projectRoot = process.env.CANVAS_PROJECT_ROOT || process.cwd();
-  const label = values.label;
-  const autoLabel = !label ? basename(resolvedPath) : undefined;
+	const sessionId = getSessionId(values.session)
+	const projectRoot = process.env.CANVAS_PROJECT_ROOT || process.cwd()
+	const label = values.label
+	const autoLabel = !label ? basename(resolvedPath) : undefined
 
-  await ensureDaemon();
+	await ensureDaemon()
 
-  const response = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      directory: resolvedPath,
-      projectRoot,
-      label: label || autoLabel,
-      ...(values.response ? { response: values.response } : {}),
-    }),
-  });
+	const response = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({
+			directory: resolvedPath,
+			projectRoot,
+			label: label || autoLabel,
+			...(values.response ? { response: values.response } : {}),
+		}),
+	})
 
-  let result = await response.json() as any;
+	let result = pushResponseSchema.parse(await response.json())
 
-  // Bun.build() / Bun.Transpiler can fail in long-running daemons due to
-  // internal state corruption, CWD unlinking, etc. Restart and retry once.
-  // Skip restart only for clear user errors (syntax errors with line/col,
-  // runtime validation errors) — those won't be fixed by a restart.
-  const isUserError = !result.ok && result.errors && Object.values(result.errors).every((e: any) =>
-    typeof e === "string" && (
-      /\(line \d+, col \d+\)/.test(e) ||
-      /Syntax Error|Parse error|Mermaid syntax error/i.test(e) ||
-      e.startsWith("Runtime error:")
-    ));
-  const shouldRestart = !result.ok && result.error === "Canvas compilation failed" && !isUserError;
-  if (shouldRestart) {
-    console.error("Compilation failed, restarting daemon and retrying...");
-    await stopDaemon();
-    await startDaemon();
-    const retryResponse = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        directory: resolvedPath,
-        projectRoot,
-        label: label || autoLabel,
-        ...(values.response ? { response: values.response } : {}),
-      }),
-    });
-    result = await retryResponse.json() as any;
-  }
+	// Bun.build() / Bun.Transpiler can fail in long-running daemons due to
+	// internal state corruption, CWD unlinking, etc. Restart and retry once.
+	// Skip restart only for clear user errors (syntax errors with line/col,
+	// runtime validation errors) — those won't be fixed by a restart.
+	const isUserError = !result.ok && result.errors && Object.values(result.errors).every((e) =>
+		typeof e === 'string' && (
+			/\(line \d+, col \d+\)/.test(e)
+			|| /Syntax Error|Parse error|Mermaid syntax error/i.test(e)
+			|| e.startsWith('Runtime error:')
+		)
+	)
+	const shouldRestart = !result.ok && result.error === 'Canvas compilation failed' && !isUserError
+	if (shouldRestart) {
+		console.error('Compilation failed, restarting daemon and retrying...')
+		await stopDaemon()
+		await startDaemon()
+		const retryResponse = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				directory: resolvedPath,
+				projectRoot,
+				label: label || autoLabel,
+				...(values.response ? { response: values.response } : {}),
+			}),
+		})
+		result = pushResponseSchema.parse(await retryResponse.json())
+	}
 
-  if (!result.ok) {
-    if (result.unconsumedFeedback) {
-      console.error(`Error: ${result.error}`);
-      console.log(result.unconsumedFeedback);
-    } else {
-      console.error(`Compilation error:\n${result.error}`);
-      if (result.errors) {
-        for (const [file, err] of Object.entries(result.errors)) {
-          console.error(`  ${file}: ${err}`);
-        }
-      }
-    }
-    process.exit(1);
-  }
+	if (!result.ok) {
+		if (result.unconsumedFeedback) {
+			console.error(`Error: ${result.error}`)
+			console.log(result.unconsumedFeedback)
+		} else {
+			console.error(`Compilation error:\n${result.error}`)
+			if (result.errors) {
+				for (const [file, err] of Object.entries(result.errors)) {
+					console.error(`  ${file}: ${err}`)
+				}
+			}
+		}
+		process.exit(1)
+	}
 
-  if (result.isNew) {
-    openBrowser(result.browserUrl);
-  }
+	if (result.isNew) {
+		openBrowser(result.browserUrl)
+	}
 
-  console.log(JSON.stringify({
-    ok: true,
-    browserUrl: result.browserUrl,
-    revision: result.revision,
-    sessionId,
-    canvasFiles: result.canvasFiles,
-  }));
+	console.log(JSON.stringify({
+		ok: true,
+		browserUrl: result.browserUrl,
+		revision: result.revision,
+		sessionId,
+		canvasFiles: result.canvasFiles,
+	}))
 }

package/bin/lib/commands/review.ts

@@ -0,0 +1,190 @@
+import { waitForEvent } from '@fabrika/daemon-kit'
+import { execFileSync } from 'child_process'
+import { basename } from 'path'
+import { parseArgs } from 'util'
+import { z } from 'zod'
+import { PROJECT_RE, reviewThreadSchema } from '../../../daemon/src/review/model.ts'
+import { BASE_URL, TIMEOUT_MS, WS_URL } from '../config.ts'
+import { ensureDaemon } from '../daemon-lifecycle.ts'
+import { openBrowser } from '../helpers.ts'
+
+const USAGE = `agent-canvas review — comments on a running application
+
+  agent-canvas review open <url> [--follow] [--no-open]
+                                            Serve the app at <url> with the review widget, open it in the
+                                            browser and print the address; --follow then watches as below
+  agent-canvas review snippet               Print the <script> tag that adds the review widget to the app
+  agent-canvas review watch                 Wait for threads the reviewer sends (blocks)
+  agent-canvas review watch --follow        Keep waiting; print every batch the reviewer sends
+  agent-canvas review fetch                 Take the threads already sent (returns immediately)
+  agent-canvas review reply <thread> <text> [--resolve]
+                                            Answer a thread; --resolve closes it
+  agent-canvas review list                  Show every thread that is not resolved
+
+Every command takes --project <name>; it defaults to CANVAS_REVIEW_PROJECT, then to the git repository's directory name.`
+
+const claimSchema = z.union([z.object({ found: z.literal(false) }), z.object({ found: z.literal(true), markdown: z.string() })])
+const threadsSchema = z.object({ threads: z.array(reviewThreadSchema) })
+const proxySchema = z.object({ url: z.string() })
+const errorSchema = z.object({ error: z.string() })
+
+function defaultProject(): string {
+	const fromEnv = process.env.CANVAS_REVIEW_PROJECT
+	if (fromEnv !== undefined && fromEnv !== '') return fromEnv
+	let root = process.cwd()
+	try {
+		root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+	} catch {}
+	return basename(root).replace(/[^A-Za-z0-9._-]/g, '-')
+}
+
+async function call(project: string, method: string, path: string, body?: unknown): Promise<unknown> {
+	const response = await fetch(`${BASE_URL}/api/review/${encodeURIComponent(project)}${path}`, {
+		method,
+		...(body === undefined ? {} : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
+	})
+	const result: unknown = await response.json()
+	if (!response.ok) {
+		const error = errorSchema.safeParse(result)
+		throw new Error(error.success ? error.data.error : `Daemon answered ${response.status}`)
+	}
+	return result
+}
+
+async function claim(project: string): Promise<string | undefined> {
+	const result = claimSchema.parse(await call(project, 'POST', '/claim'))
+	return result.found ? result.markdown : undefined
+}
+
+function waitForRequests(project: string): Promise<string> {
+	return waitForEvent<string>({
+		url: `${WS_URL}/ws/review-wait/${encodeURIComponent(project)}`,
+		// The frame only announces new threads; claiming them is what hands them over, exactly once.
+		onFrame: (frame) => (typeof frame === 'object' && frame !== null && 'type' in frame && frame.type === 'queued' ? { type: 'recheck' } : undefined),
+		probe: async () => {
+			const markdown = await claim(project)
+			return markdown === undefined ? undefined : { value: markdown }
+		},
+		alreadyProbed: true,
+		timeoutMs: TIMEOUT_MS,
+		reconnect: { attempts: 3, delayMs: 1_000 },
+		messages: {
+			timeout: 'Timeout waiting for review requests.',
+			closed: 'WebSocket closed before the reviewer sent anything.',
+			connectionFailed: 'WebSocket connection failed.',
+		},
+	})
+}
+
+const FOLLOW_RECONNECT_MS = 2_000
+const FOLLOW_GIVE_UP_MS = 60_000
+
+/**
+ * The streaming watcher for hosts that turn each output line into an event (Claude Code's Monitor). One socket stays
+ * open, so the reviewer keeps seeing an agent listening between batches. Status goes to stderr; stdout carries only
+ * batches and the line that ends the watch, so every stdout event is worth acting on.
+ */
+function followRequests(project: string): Promise<never> {
+	let claiming = Promise.resolve()
+	let unreachableSince: number | null = null
+
+	const claimAndPrint = () => {
+		claiming = claiming.then(async () => {
+			const markdown = await claim(project)
+			if (markdown !== undefined) process.stdout.write(`${markdown}\n`)
+		}).catch((error: unknown) => {
+			console.error(`review watch: claim failed: ${error instanceof Error ? error.message : String(error)}`)
+		})
+	}
+
+	const connect = () => {
+		const socket = new WebSocket(`${WS_URL}/ws/review-wait/${encodeURIComponent(project)}`)
+		socket.onopen = () => {
+			unreachableSince = null
+			console.error(`review watch: listening for ${project}`)
+			claimAndPrint()
+		}
+		socket.onmessage = (event) => {
+			// Any frame on the wait socket means "something was queued"; the claim reads what, so the frame needs no parsing.
+			if (typeof event.data === 'string') claimAndPrint()
+		}
+		socket.onclose = () => {
+			unreachableSince ??= Date.now()
+			if (Date.now() - unreachableSince > FOLLOW_GIVE_UP_MS) {
+				console.log(`review watch: the daemon at ${BASE_URL} has been unreachable for a minute; stopped watching ${project}.`)
+				process.exit(1)
+			}
+			setTimeout(connect, FOLLOW_RECONNECT_MS)
+		}
+	}
+
+	connect()
+	return new Promise<never>(() => {})
+}
+
+export async function handleReview(args: string[]) {
+	const [subcommand, ...rest] = args
+	const { values, positionals } = parseArgs({
+		args: rest,
+		allowPositionals: true,
+		options: {
+			project: { type: 'string' },
+			resolve: { type: 'boolean', default: false },
+			follow: { type: 'boolean', default: false },
+			'no-open': { type: 'boolean', default: false },
+		},
+	})
+	const project = values.project ?? defaultProject()
+	if (!PROJECT_RE.test(project)) throw new Error(`Invalid project name "${project}"; use letters, digits, ".", "_" and "-"`)
+
+	switch (subcommand) {
+		case 'open': {
+			const [target] = positionals
+			if (target === undefined) throw new Error('Usage: agent-canvas review open <url> [--follow] [--no-open]')
+			await ensureDaemon()
+			const { url } = proxySchema.parse(await call(project, 'POST', '/proxy', { target: new URL(target).href }))
+			console.log(`Review ${target} at ${url}`)
+			if (!values['no-open']) openBrowser(url)
+			if (values.follow) return followRequests(project)
+			return
+		}
+		case 'snippet':
+			console.log(`<script src="${BASE_URL}/assets/review.js" data-project="${project}"></script>`)
+			return
+		case 'watch': {
+			await ensureDaemon()
+			if (values.follow) return followRequests(project)
+			process.stdout.write((await claim(project)) ?? (await waitForRequests(project)))
+			return
+		}
+		case 'fetch': {
+			await ensureDaemon()
+			const markdown = await claim(project)
+			process.stdout.write(markdown ?? 'No review requests are waiting.\n')
+			return
+		}
+		case 'reply': {
+			const [threadId, ...words] = positionals
+			const body = words.join(' ')
+			if (threadId === undefined || body.trim() === '') throw new Error('Usage: agent-canvas review reply <thread> <text> [--resolve]')
+			await ensureDaemon()
+			await call(project, 'POST', `/threads/${encodeURIComponent(threadId)}/reply`, { body, resolve: values.resolve })
+			console.log(values.resolve ? `Replied to ${threadId} and resolved it.` : `Replied to ${threadId}.`)
+			return
+		}
+		case 'list': {
+			await ensureDaemon()
+			const { threads } = threadsSchema.parse(await call(project, 'GET', '/threads'))
+			const pending = threads.filter((thread) => thread.state !== 'resolved')
+			if (pending.length === 0) console.log('No unresolved threads.')
+			for (const thread of pending) {
+				const first = thread.comments[0]?.body.split('\n')[0] ?? ''
+				console.log(`${thread.id}  ${thread.state.padEnd(8)}  ${thread.anchor.url}\n    ${first}`)
+			}
+			return
+		}
+		default:
+			console.log(USAGE)
+			process.exit(subcommand === undefined || subcommand === '--help' ? 0 : 1)
+	}
+}