goalbuddy 0.2.21 → 0.2.22

package/plugins/goalbuddy/skills/goalbuddy/extend/local-goal-board/scripts/local-goal-board.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { existsSync, readFileSync, realpathSync, watch } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createBoardPayload, writeBoardApp } from "./lib/goal-board.mjs";
+
+const textTypes = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".svg": "image/svg+xml; charset=utf-8",
+  ".png": "image/png",
+};
+
+if (isDirectRun()) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}
+
+function isDirectRun() {
+  if (!process.argv[1]) return false;
+  return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+}
+
+export async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const goalDir = resolve(options.goal || "");
+  if (!options.goal) throw new Error("Missing --goal docs/goals/<slug>");
+  if (!existsSync(join(goalDir, "state.yaml"))) {
+    throw new Error(`Missing state.yaml in ${goalDir}`);
+  }
+
+  const appDir = writeBoardApp(goalDir);
+  const board = createBoardPayload(goalDir);
+
+  if (options.once) {
+    if (options.json) {
+      console.log(JSON.stringify({ goalDir, appDir, board }, null, 2));
+    } else {
+      console.log(`Generated GoalBuddy board app at ${appDir}`);
+    }
+    return { goalDir, appDir, board };
+  }
+
+  const server = await startBoardServer({
+    goalDir,
+    appDir,
+    host: options.host,
+    port: options.port,
+  });
+
+  if (options.json) {
+    console.log(JSON.stringify({ goalDir, appDir, url: server.url }, null, 2));
+  } else {
+    console.log(`GoalBuddy local board: ${server.url}`);
+    console.log(`Watching: ${join(goalDir, "state.yaml")}`);
+    console.log("Press Ctrl-C to stop.");
+  }
+
+  return server;
+}
+
+export function parseArgs(args) {
+  const options = {
+    goal: "",
+    host: "127.0.0.1",
+    port: 41737,
+    once: false,
+    json: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--goal") {
+      options.goal = args[++index] || "";
+    } else if (arg.startsWith("--goal=")) {
+      options.goal = arg.slice("--goal=".length);
+    } else if (arg === "--host") {
+      options.host = args[++index] || options.host;
+    } else if (arg.startsWith("--host=")) {
+      options.host = arg.slice("--host=".length);
+    } else if (arg === "--port") {
+      options.port = Number(args[++index] || options.port);
+    } else if (arg.startsWith("--port=")) {
+      options.port = Number(arg.slice("--port=".length));
+    } else if (arg === "--once") {
+      options.once = true;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      usage();
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) {
+    throw new Error(`Invalid --port: ${options.port}`);
+  }
+
+  return options;
+}
+
+export async function startBoardServer({ goalDir, appDir = writeBoardApp(goalDir), host = "127.0.0.1", port = 0 }) {
+  const root = resolve(goalDir);
+  const clients = new Set();
+  let lastPayload = safePayload(root);
+
+  const notify = () => {
+    lastPayload = safePayload(root);
+    for (const client of clients) sendEvent(client, lastPayload);
+  };
+
+  const watcher = watchGoal(root, notify);
+  const server = createServer((request, response) => {
+    const url = new URL(request.url || "/", `http://${request.headers.host || "127.0.0.1"}`);
+    if (url.pathname === "/api/board") {
+      sendJson(response, safePayload(root));
+      return;
+    }
+    if (url.pathname === "/events") {
+      response.writeHead(200, {
+        "Content-Type": "text/event-stream; charset=utf-8",
+        "Cache-Control": "no-cache, no-transform",
+        "Connection": "keep-alive",
+        "X-Accel-Buffering": "no",
+      });
+      response.write("retry: 1000\n\n");
+      clients.add(response);
+      sendEvent(response, lastPayload);
+      request.on("close", () => clients.delete(response));
+      return;
+    }
+
+    serveStatic(appDir, url.pathname, response);
+  });
+
+  await new Promise((resolveListen, rejectListen) => {
+    server.once("error", rejectListen);
+    server.listen(port, host, () => {
+      server.off("error", rejectListen);
+      resolveListen();
+    });
+  });
+
+  const address = server.address();
+  const actualPort = typeof address === "object" && address ? address.port : port;
+
+  return {
+    url: `http://${host}:${actualPort}/`,
+    close: () => new Promise((resolveClose, rejectClose) => {
+      watcher.close();
+      for (const client of clients) client.end();
+      server.close((error) => error ? rejectClose(error) : resolveClose());
+    }),
+  };
+}
+
+function watchGoal(goalDir, onChange) {
+  const watchers = [];
+  const schedule = debounce(onChange, 80);
+  watchers.push(watch(goalDir, { persistent: true }, (_event, filename) => {
+    if (!filename) return schedule();
+    if (filename === "state.yaml" || filename === "notes") schedule();
+  }));
+  const notesDir = join(goalDir, "notes");
+  if (existsSync(notesDir)) {
+    watchers.push(watch(notesDir, { persistent: true }, schedule));
+  }
+  return {
+    close() {
+      for (const watcher of watchers) watcher.close();
+    },
+  };
+}
+
+function safePayload(goalDir) {
+  try {
+    return createBoardPayload(goalDir);
+  } catch (error) {
+    return {
+      generatedAt: new Date().toISOString(),
+      error: error.message,
+      goal: { title: "GoalBuddy Board", slug: "", status: "error", activeTask: "", tranche: "" },
+      columns: [
+        { id: "todo", title: "Todo", description: "Queued work ready to pull", tasks: [] },
+        { id: "in-progress", title: "In Progress", description: "The active task", tasks: [] },
+        { id: "blocked", title: "Blocked", description: "Needs unblock or a smaller slice", tasks: [] },
+        { id: "completed", title: "Completed", description: "Receipted work", tasks: [] },
+      ],
+      tasks: [],
+      notes: [],
+    };
+  }
+}
+
+function sendJson(response, payload) {
+  response.writeHead(200, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+  });
+  response.end(JSON.stringify(payload, null, 2));
+}
+
+function sendEvent(response, payload) {
+  response.write(`event: board\ndata: ${JSON.stringify(payload)}\n\n`);
+}
+
+function serveStatic(appDir, pathname, response) {
+  const cleanPath = pathname === "/" ? "/index.html" : pathname;
+  if (!/^\/[A-Za-z0-9_.-]+$/.test(cleanPath)) {
+    response.writeHead(404);
+    response.end("Not found");
+    return;
+  }
+
+  const file = join(appDir, cleanPath.slice(1));
+  if (!existsSync(file)) {
+    response.writeHead(404);
+    response.end("Not found");
+    return;
+  }
+
+  const extension = cleanPath.match(/\.[^.]+$/)?.[0] || "";
+  response.writeHead(200, {
+    "Content-Type": textTypes[extension] || "application/octet-stream",
+    "Cache-Control": "no-store",
+  });
+  response.end(readFileSync(file));
+}
+
+function debounce(fn, delay) {
+  let timer = null;
+  return () => {
+    clearTimeout(timer);
+    timer = setTimeout(fn, delay);
+  };
+}
+
+function usage() {
+  console.log(`GoalBuddy Local Goal Board
+
+Usage:
+  node extend/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug>
+  node extend/local-goal-board/scripts/local-goal-board.mjs --goal docs/goals/<slug> --once --json
+
+Options:
+  --goal <path>   Goal directory containing state.yaml.
+  --host <host>   Local server host. Default: 127.0.0.1.
+  --port <port>   Local server port. Use 0 for an ephemeral port.
+  --once          Generate .goalbuddy-board and exit.
+  --json          Print structured output.
+`);
+}

package/plugins/goalbuddy/skills/goalbuddy/extend/local-goal-board/test/local-goal-board.test.mjs

@@ -0,0 +1,146 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createBoardPayload, writeBoardApp } from "../scripts/lib/goal-board.mjs";
+import { parseArgs, startBoardServer } from "../scripts/local-goal-board.mjs";
+
+test("normalizes a dense goal into local board columns", () => {
+  const payload = createBoardPayload(resolve("extend/local-goal-board/examples/sample-goal"));
+
+  assert.equal(payload.goal.title, "Local Kanban Board Extension");
+  assert.equal(payload.goal.activeTask, "");
+  assert.equal(payload.counts.total, 14);
+  assert.equal(payload.counts.todo, 0);
+  assert.equal(payload.counts.inProgress, 0);
+  assert.equal(payload.counts.blocked, 5);
+  assert.equal(payload.counts.completed, 9);
+  assert.deepEqual(payload.columns.map((column) => column.title), ["Todo", "In Progress", "Blocked", "Completed"]);
+
+  const scout = payload.tasks.find((task) => task.id === "T001");
+  assert.equal(scout.receipt.summary, "T001 completed during the progressive board motion demo.");
+});
+
+test("writes a minimal GoalBuddy web app into the goal directory", () => {
+  const appDir = writeBoardApp(resolve("extend/local-goal-board/examples/sample-goal"));
+  const html = readFileSync(join(appDir, "index.html"), "utf8");
+  const css = readFileSync(join(appDir, "styles.css"), "utf8");
+  const js = readFileSync(join(appDir, "app.js"), "utf8");
+  const logo = readFileSync(join(appDir, "goalbuddy-mark.png"));
+
+  assert.match(html, /goalbuddy-mark\.png/);
+  assert.match(css, /--canvas: #f7f6f3/);
+  assert.doesNotMatch(css, /gradient/i);
+  assert.match(js, /new EventSource\("\.\/events"\)/);
+  assert.match(js, /animateCardMoves/);
+  assert.match(js, /card\.animate/);
+  assert.match(js, /highlightMovingCards/);
+  assert.match(js, /duration: changedColumn \? 980 : 520/);
+  assert.equal(logo.subarray(1, 4).toString("ascii"), "PNG");
+});
+
+test("parses CLI options", () => {
+  assert.deepEqual(parseArgs(["--goal", "docs/goals/demo", "--port", "0", "--once", "--json"]), {
+    goal: "docs/goals/demo",
+    host: "127.0.0.1",
+    port: 0,
+    once: true,
+    json: true,
+  });
+});
+
+test("runs when installed under a symlinked temp path", () => {
+  const root = mkdtempSync("/tmp/goalbuddy-local-board-direct-");
+  try {
+    cpSync("extend/local-goal-board/scripts", join(root, "scripts"), { recursive: true });
+    cpSync("extend/local-goal-board/assets", join(root, "assets"), { recursive: true });
+
+    const result = spawnSync(process.execPath, [
+      join(root, "scripts", "local-goal-board.mjs"),
+      "--goal",
+      resolve("extend/local-goal-board/examples/sample-goal"),
+      "--once",
+      "--json",
+    ], { encoding: "utf8" });
+
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+    const report = JSON.parse(result.stdout);
+    assert.equal(report.board.goal.title, "Local Kanban Board Extension");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("serves board JSON and streams live state changes over SSE", async () => {
+  const root = mkdtempSync(join(tmpdir(), "goalbuddy-local-board-"));
+  const goalDir = join(root, "demo-goal");
+  try {
+    mkdirSync(join(goalDir, "notes"), { recursive: true });
+    writeFileSync(join(goalDir, "state.yaml"), stateYaml("active"));
+    writeFileSync(join(goalDir, "notes", "T001-note.md"), "# Live Note\n\nInitial note.\n");
+
+    const server = await startBoardServer({ goalDir, host: "127.0.0.1", port: 0 });
+    try {
+      const boardResponse = await fetch(`${server.url}api/board`);
+      assert.equal(boardResponse.status, 200);
+      const board = await boardResponse.json();
+      assert.equal(board.tasks[0].status, "active");
+
+      const controller = new AbortController();
+      const events = await fetch(`${server.url}events`, { signal: controller.signal });
+      assert.equal(events.status, 200);
+      const reader = events.body.getReader();
+
+      await readUntil(reader, /"status":"active"/);
+      writeFileSync(join(goalDir, "state.yaml"), stateYaml("blocked"));
+      const update = await readUntil(reader, /"status":"blocked"/);
+      assert.match(update, /"title":"Blocked"/);
+
+      controller.abort();
+      await reader.cancel().catch(() => {});
+    } finally {
+      await server.close();
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+async function readUntil(reader, pattern) {
+  const decoder = new TextDecoder();
+  let text = "";
+  const deadline = Date.now() + 3000;
+
+  while (Date.now() < deadline) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    text += decoder.decode(value, { stream: true });
+    if (pattern.test(text)) return text;
+  }
+
+  assert.fail(`Timed out waiting for ${pattern}. Received:\n${text}`);
+}
+
+function stateYaml(status) {
+  return `version: 2
+goal:
+  title: "Live board"
+  slug: "live-board"
+  kind: specific
+  tranche: "Verify live updates."
+  status: active
+active_task: T001
+tasks:
+  - id: T001
+    type: worker
+    assignee: Worker
+    status: ${status}
+    objective: "Render live changes."
+    receipt:
+      result: done
+      summary: "Rendered safely."
+      note: notes/T001-note.md
+`;
+}

package/plugins/goalbuddy/skills/goalbuddy/scripts/check-goal-state.mjs

@@ -169,16 +169,16 @@ function receiptCommandStatuses(raw) {
 }
 
 function rootEntryErrors() {
-  const allowed = new Set(["goal.md", "state.yaml", "notes"]);
+  const allowed = new Set(["goal.md", "state.yaml", "notes", ".goalbuddy-board"]);
   const unexpected = [];
   for (const entry of readdirSync(root).filter((item) => item !== ".DS_Store")) {
     const path = join(root, entry);
     const stats = statSync(path);
     if (!allowed.has(entry)) {
       unexpected.push(entry);
-    } else if (entry === "notes" && !stats.isDirectory()) {
-      unexpected.push("notes (must be a directory)");
-    } else if (entry !== "notes" && !stats.isFile()) {
+    } else if ((entry === "notes" || entry === ".goalbuddy-board") && !stats.isDirectory()) {
+      unexpected.push(`${entry} (must be a directory)`);
+    } else if (entry !== "notes" && entry !== ".goalbuddy-board" && !stats.isFile()) {
       unexpected.push(`${entry} (must be a file)`);
     }
   }
@@ -188,10 +188,11 @@ function rootEntryErrors() {
 const version = topScalar("version");
 const goalStatus = nestedScalar("goal", "status");
 const activeTask = topScalar("active_task");
-const installedAgents = ["scout", "worker", "judge"].map((agent) => ({
+const agentStatuses = ["scout", "worker", "judge"].map((agent) => ({
   agent,
   status: nestedScalar("agents", agent),
 }));
+const allowedAgentStatuses = new Set(["installed", "bundled_not_installed", "missing", "unknown"]);
 const continuousUntilFullOutcome = nestedScalar("rules", "continuous_until_full_outcome") === true;
 const missingInputOrCredentialsDoNotStopGoal =
   nestedScalar("rules", "missing_input_or_credentials_do_not_stop_goal") === true;
@@ -214,9 +215,22 @@ if (!["active", "blocked", "done"].includes(goalStatus)) {
   errors.push(`goal.status must be active, blocked, or done; got ${goalStatus || "<missing>"}`);
 }
 
-for (const { agent, status } of installedAgents) {
-  if (status !== "installed") {
-    errors.push(`agents.${agent} must be installed; got ${status || "<missing>"}`);
+function agentStatusWarning(agent, status) {
+  const agentLabel = agent[0].toUpperCase() + agent.slice(1);
+  if (status === "bundled_not_installed") {
+    return `agents.${agent} is bundled_not_installed; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation is unavailable until installed. If dedicated agents are required before /goal, run: npx goalbuddy agents`;
+  }
+  if (status === "missing") {
+    return `agents.${agent} is missing; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation is unavailable. If dedicated agents are required before /goal, run: npx goalbuddy install`;
+  }
+  return `agents.${agent} is unknown; /goal can continue through PM fallback, but dedicated ${agentLabel} delegation was not verified. To check before /goal, run: npx goalbuddy doctor`;
+}
+
+for (const { agent, status } of agentStatuses) {
+  if (!allowedAgentStatuses.has(status)) {
+    errors.push(`agents.${agent} must be one of installed, bundled_not_installed, missing, or unknown; got ${status || "<missing>"}`);
+  } else if (status !== "installed") {
+    warnings.push(agentStatusWarning(agent, status));
   }
 }
 
@@ -227,7 +241,7 @@ if (!existsSync(join(root, "notes")) || !statSync(join(root, "notes")).isDirecto
 
 const unexpected = rootEntryErrors();
 if (unexpected.length > 0) {
-  errors.push(`unexpected root entries; v2 goal roots may contain only goal.md, state.yaml, and notes/: ${unexpected.join(", ")}`);
+  errors.push(`unexpected root entries; v2 goal roots may contain only goal.md, state.yaml, notes/, and .goalbuddy-board/: ${unexpected.join(", ")}`);
 }
 
 const tasks = parseTasks();
@@ -361,6 +375,7 @@ const result = {
   state_path: statePath,
   goal_status: goalStatus,
   active_task: activeTask,
+  agent_statuses: Object.fromEntries(agentStatuses.map(({ agent, status }) => [agent, status])),
   task_count: tasks.length,
   errors,
   warnings,

package/plugins/goalbuddy/skills/goalbuddy/templates/state.yaml

@@ -35,9 +35,24 @@ rules:
   intake_misfire_must_be_audited: true
 
 agents:
-  scout: installed
-  worker: installed
-  judge: installed
+  # installed | bundled_not_installed | missing | unknown
+  # If non-installed, /goal can continue through PM fallback; install agents before /goal only when dedicated delegation is required.
+  scout: unknown
+  worker: unknown
+  judge: unknown
+
+visual_board:
+  # none | local | github_projects | both | unknown
+  selected: unknown
+  local:
+    status: not_requested # not_requested | starting | live | generated | blocked
+    url: null
+    command: "npx goalbuddy board docs/goals/<goal-slug>"
+  github_projects:
+    status: not_requested # not_requested | needs_approval | dry_run_ready | synced | blocked
+    url: null
+    command: "npx goalbuddy extend github-projects"
+    missing: []
 
 active_task: T001