goalbuddy 0.2.21 → 0.3.0

package/goalbuddy/extend/github-projects/test/github-projects.test.mjs

@@ -0,0 +1,267 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { GoalStateError, normalizeGoalBoard, parseGoalStateText } from "../scripts/lib/goal-state.mjs";
+import {
+  GITHUB_PROJECT_FIELDS,
+  GITHUB_PROJECT_VIEWS,
+  agentLaneForTask,
+  buildDraftIssueBody,
+  buildFieldUpdates,
+  ensureGoalProjectViews,
+  planGitHubProjectSync,
+  priorityForTask,
+  projectStatusForTask,
+  workTypeForTask,
+} from "../scripts/lib/github-projects.mjs";
+
+describe("goal state parsing", () => {
+  it("normalizes a GoalBuddy v2 board", async () => {
+    const text = await readFile(resolve("extend/github-projects/examples/goal-board-sync/state.yaml"), "utf8");
+    const board = normalizeGoalBoard(parseGoalStateText(text));
+
+    assert.equal(board.title, "Goal board sync MVP");
+    assert.equal(board.activeTask, "T002");
+    assert.equal(board.tasks.length, 3);
+    assert.equal(board.tasks[0].title, "Map external board API requirements");
+    assert.equal(board.tasks[1].priority, "P1");
+    assert.equal(board.tasks[0].receiptSummary, "The board sync can read GoalBuddy state.yaml and mirror tasks into an external board.");
+    assert.equal(board.tasks[0].goalRole, "Scout");
+    assert.equal(board.tasks[1].agentResponsible, "Worker");
+    assert.equal(board.tasks[1].credentialGate, "Credentials");
+    assert.equal(board.tasks[1].parentId, "T001");
+    assert.deepEqual(board.tasks[1].dependsOn, ["T001"]);
+    assert.deepEqual(board.tasks[1].verify, [
+      "node --test extend/github-projects/test/*.test.mjs",
+      "node extend/github-projects/scripts/sync-github-project.mjs --state extend/github-projects/examples/goal-board-sync/state.yaml --dry-run",
+    ]);
+  });
+
+  it("rejects malformed task status", () => {
+    const parsed = parseGoalStateText(`
+version: 2
+goal:
+  title: "Bad board"
+  slug: "bad-board"
+tasks:
+  - id: T001
+    status: moving
+    objective: "Bad status"
+`);
+
+    assert.throws(() => normalizeGoalBoard(parsed), GoalStateError);
+  });
+});
+
+describe("GitHub Projects mapping", () => {
+  it("plans GitHub draft issue creates and updates by task id", () => {
+    const tasks = [
+      {
+        id: "T001",
+        title: "T001: Existing",
+        objective: "Existing",
+        status: "done",
+        type: "scout",
+        assignee: "Scout",
+        receiptSummary: "Done",
+        verify: [],
+        allowedFiles: [],
+        updatedLabel: "receipt:done",
+      },
+      {
+        id: "T002",
+        title: "T002: New",
+        objective: "New",
+        status: "queued",
+        type: "worker",
+        assignee: "Worker",
+        receiptSummary: "",
+        verify: [],
+        allowedFiles: [],
+        updatedLabel: "receipt:none",
+      },
+    ];
+
+    const operations = planGitHubProjectSync(tasks, [
+      {
+        id: "PVTI_existing",
+        taskId: { text: "T001" },
+        content: { __typename: "DraftIssue", id: "DI_existing" },
+      },
+    ]);
+
+    assert.equal(operations[0].type, "update");
+    assert.equal(operations[0].itemId, "PVTI_existing");
+    assert.equal(operations[0].draftIssueId, "DI_existing");
+    assert.equal(operations[1].type, "create");
+  });
+
+  it("builds GitHub field updates for text and single-select fields", () => {
+    const fields = {
+      taskId: { id: "F_task" },
+      status: { id: "F_status", name: GITHUB_PROJECT_FIELDS.status, options: [{ id: "O_progress", name: "In Progress" }] },
+      priority: { id: "F_priority", name: GITHUB_PROJECT_FIELDS.priority, options: [{ id: "O_p1", name: "P1" }] },
+      workType: { id: "F_type", name: GITHUB_PROJECT_FIELDS.workType, options: [{ id: "O_execution", name: "Execution" }] },
+      agentLane: { id: "F_lane", name: GITHUB_PROJECT_FIELDS.agentLane, options: [{ id: "O_worker", name: "Worker" }] },
+      owner: { id: "F_owner" },
+      goalRole: { id: "F_goal_role" },
+      agentResponsible: { id: "F_agent" },
+      credentialGate: { id: "F_gate" },
+      parentId: { id: "F_parent" },
+      dependsOn: { id: "F_depends" },
+      receiptSummary: { id: "F_receipt" },
+      verify: { id: "F_verify" },
+      allowedFiles: { id: "F_allowed" },
+      updated: { id: "F_updated" },
+    };
+    const task = {
+      id: "T002",
+      status: "active",
+      type: "worker",
+      assignee: "Worker",
+      goalRole: "Worker",
+      agentResponsible: "Worker",
+      credentialGate: "None",
+      receiptSummary: "",
+      verify: ["npm test"],
+      allowedFiles: ["scripts/**"],
+      parentId: "T001",
+      dependsOn: ["T001"],
+      updatedLabel: "receipt:none",
+    };
+
+    const updates = buildFieldUpdates(task, fields);
+    assert.equal(updates.length, 15);
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_status").value, {
+      singleSelectOptionId: "O_progress",
+    });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_task").value, {
+      text: "T002",
+    });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_lane").value, {
+      singleSelectOptionId: "O_worker",
+    });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_goal_role").value, { text: "Worker" });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_agent").value, { text: "Worker" });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_gate").value, { text: "None" });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_parent").value, { text: "T001" });
+    assert.deepEqual(updates.find((update) => update.fieldId === "F_depends").value, { text: "T001" });
+  });
+
+  it("builds a draft issue body that points back to the state file", () => {
+    const body = buildDraftIssueBody(
+      {
+        id: "T002",
+        objective: "Run sync.",
+        status: "active",
+        type: "worker",
+        assignee: "Worker",
+        receiptSummary: "",
+        verify: ["npm test"],
+        allowedFiles: ["scripts/**"],
+        parentId: "T001",
+        dependsOn: ["T001"],
+      },
+      {
+        sourcePath: "extend/github-projects/examples/goal-board-sync/state.yaml",
+      }
+    );
+
+    assert.match(body, /YAML remains the source of truth/);
+    assert.match(body, /Task ID: T002/);
+    assert.match(body, /Parent: T001/);
+    assert.match(body, /Depends on:/);
+    assert.match(body, /extend\/github-projects\/examples\/goal-board-sync\/state\.yaml/);
+  });
+
+  it("creates only the Goal Board GitHub Project view with visible fields when missing", async () => {
+    const restCalls = [];
+    const views = await ensureGoalProjectViews({
+      client: {
+        rest: async (path, options) => {
+          restCalls.push({ path, options });
+          return {
+            html_url: "https://github.com/users/example/projects/1/views/2",
+          };
+        },
+      },
+      project: {
+        number: 1,
+        owner: { __typename: "User", login: "example" },
+        views: { nodes: [] },
+      },
+      fields: {
+        taskId: { databaseId: 1 },
+        status: { databaseId: 2 },
+        priority: { databaseId: 3 },
+        workType: { databaseId: 4 },
+        owner: { databaseId: 5 },
+        agentLane: { databaseId: 13 },
+        goalRole: { databaseId: 10 },
+        agentResponsible: { databaseId: 11 },
+        credentialGate: { databaseId: 12 },
+        receiptSummary: { databaseId: 6 },
+        verify: { databaseId: 7 },
+        allowedFiles: { databaseId: 8 },
+        updated: { databaseId: 9 },
+      },
+    });
+
+    assert.equal(views.board.html_url, "https://github.com/users/example/projects/1/views/2");
+    assert.equal(views.agentWorkboard, undefined);
+    assert.equal(restCalls.length, 1);
+    assert.equal(restCalls[0].path, "users/example/projectsV2/1/views");
+    assert.equal(restCalls[0].options.body.layout, "board");
+    assert.equal(restCalls[0].options.body.name, GITHUB_PROJECT_VIEWS.board.name);
+    assert.deepEqual(restCalls[0].options.body.visible_fields, [3, 2, 4, 5, 10, 11, 13, 12]);
+    assert.equal(restCalls[0].options.body.group_by, undefined);
+  });
+
+  it("reuses an existing Goal Board view without creating extra views", async () => {
+    const views = await ensureGoalProjectViews({
+      client: {
+        rest: async () => {
+          throw new Error("REST should not be called for existing views.");
+        },
+      },
+      project: {
+        number: 1,
+        owner: { __typename: "User", login: "example" },
+        views: {
+          nodes: [
+            { id: "PVTV_board", name: "Goal Board", layout: "BOARD_LAYOUT" },
+            { id: "PVTV_agent", name: "Agent Workboard", layout: "BOARD_LAYOUT" },
+          ],
+        },
+      },
+      fields: {},
+    });
+
+    assert.equal(views.board.id, "PVTV_board");
+    assert.equal(views.agentWorkboard, undefined);
+  });
+
+  it("maps GoalBuddy task statuses to native GitHub board statuses", () => {
+    assert.equal(projectStatusForTask("queued"), "Todo");
+    assert.equal(projectStatusForTask("active"), "In Progress");
+    assert.equal(projectStatusForTask("blocked"), "Blocked");
+    assert.equal(projectStatusForTask("done"), "Done");
+  });
+
+  it("maps GoalBuddy task types and priorities to lean PM fields", () => {
+    assert.equal(workTypeForTask("scout"), "Discovery");
+    assert.equal(workTypeForTask("judge"), "Decision");
+    assert.equal(workTypeForTask("worker"), "Execution");
+    assert.equal(priorityForTask({ status: "blocked", type: "worker" }), "P0");
+    assert.equal(priorityForTask({ status: "active", type: "worker" }), "P1");
+    assert.equal(priorityForTask({ status: "queued", type: "scout" }), "P2");
+    assert.equal(priorityForTask({ status: "done", type: "worker" }), "P3");
+    assert.equal(priorityForTask({ status: "queued", type: "scout", priority: "P0" }), "P0");
+    assert.equal(agentLaneForTask({ assignee: "PM" }), "PM");
+    assert.equal(agentLaneForTask({ agentResponsible: "Scout" }), "Scout");
+    assert.equal(agentLaneForTask({ goalRole: "Judge" }), "Judge");
+    assert.equal(agentLaneForTask({ agentResponsible: "Worker" }), "Worker");
+    assert.equal(agentLaneForTask({ agentResponsible: "User" }), "User");
+  });
+});

package/goalbuddy/extend/local-goal-board/README.md

@@ -0,0 +1,75 @@
+# Local Goal Board
+
+Generate a small local GoalBuddy board for a goal directory and watch it update live while agents work.
+
+The extension keeps `state.yaml` authoritative. It writes static web app files into the goal directory and serves them from a local-only Node server. The browser subscribes to Server-Sent Events, so cards update as `state.yaml` or `notes/` changes without a manual reload.
+
+## Use When
+
+- A human wants a local board view during a GoalBuddy run.
+- The team wants GitHub-Projects-like visibility without GitHub credentials.
+- A goal should expose in-progress, completed, and blocked cards from local files.
+
+## Generate And Serve
+
+```bash
+node extend/local-goal-board/scripts/local-goal-board.mjs \
+  --goal docs/goals/<slug>
+```
+
+The generated app includes the bundled `assets/goalbuddy-mark.png`, so the board keeps the GoalBuddy mark after the extension is installed or copied elsewhere.
+
+The command writes:
+
+```text
+docs/goals/<slug>/.goalbuddy-board/
+  index.html
+  styles.css
+  app.js
+```
+
+Then it starts a server on `127.0.0.1` and prints the local URL.
+
+## Check Without A Long-Running Server
+
+```bash
+node extend/local-goal-board/scripts/local-goal-board.mjs \
+  --goal docs/goals/<slug> \
+  --once \
+  --json
+```
+
+## Live Updates
+
+The server watches:
+
+- `docs/goals/<slug>/state.yaml`
+- `docs/goals/<slug>/notes/`
+
+When either changes, the server re-reads the goal board and pushes a fresh board payload to connected browsers over `/events`.
+
+## Board Mapping
+
+- `queued` tasks appear under **Todo**.
+- `active` tasks appear under **In Progress**.
+- `blocked` tasks appear under **Blocked**.
+- `done` tasks appear under **Completed**, the right-most column.
+
+Clicking a card opens a detail modal with the task objective, status, assignee, inputs, constraints, expected output, verify commands, allowed files, stop conditions, and receipt details. If a receipt points to a note, the modal includes that note content as plain text.
+
+## Verification
+
+```bash
+node --test extend/local-goal-board/test/*.test.mjs
+node extend/local-goal-board/scripts/local-goal-board.mjs \
+  --goal extend/local-goal-board/examples/sample-goal \
+  --once \
+  --json
+```
+
+## Boundaries
+
+- `state.yaml` remains the source of truth.
+- The server binds to `127.0.0.1` by default.
+- The generated UI renders file content as text, not raw HTML.
+- No package dependencies are required.

package/goalbuddy/extend/local-goal-board/examples/sample-goal/notes/T001-scout.md

@@ -0,0 +1,3 @@
+# Scout Note
+
+The local board should render this note as plain text in the task detail modal.

package/goalbuddy/extend/local-goal-board/examples/sample-goal/state.yaml

@@ -0,0 +1,124 @@
+version: 2
+
+goal:
+  title: "Local Kanban Board Extension"
+  slug: "local-kanban-board-extension"
+  kind: specific
+  tranche: "Demonstrate local GoalBuddy board rendering."
+  status: active
+
+active_task: null
+
+tasks:
+  - id: T001
+    type: scout
+    assignee: Scout
+    status: done
+    objective: "Map the goal state inputs."
+    receipt:
+      result: done
+      summary: "T001 completed during the progressive board motion demo."
+  - id: T002
+    type: worker
+    assignee: Worker
+    status: done
+    objective: "Build the local board viewer."
+    receipt:
+      result: done
+      summary: "T002 completed during the progressive board motion demo."
+  - id: T003
+    type: worker
+    assignee: Worker
+    status: blocked
+    objective: "Catalog and document the local board extension."
+    receipt:
+      result: blocked
+      summary: "T003 is blocked during the progressive board motion demo."
+  - id: T004
+    type: judge
+    assignee: Judge
+    status: done
+    objective: "Audit the local board viewer."
+    receipt:
+      result: done
+      summary: "T004 completed during the progressive board motion demo."
+  - id: T005
+    type: scout
+    assignee: Scout
+    status: blocked
+    objective: "Review live update edge cases."
+    receipt:
+      result: blocked
+      summary: "T005 is blocked during the progressive board motion demo."
+  - id: T006
+    type: worker
+    assignee: Worker
+    status: done
+    objective: "Tune board spacing for dense card sets."
+    receipt:
+      result: done
+      summary: "T006 completed during the progressive board motion demo."
+  - id: T007
+    type: worker
+    assignee: Worker
+    status: blocked
+    objective: "Add motion timing polish."
+    receipt:
+      result: blocked
+      summary: "T007 is blocked during the progressive board motion demo."
+  - id: T008
+    type: judge
+    assignee: Judge
+    status: done
+    objective: "Confirm the board remains readable with many cards."
+    receipt:
+      result: done
+      summary: "T008 completed during the progressive board motion demo."
+  - id: T009
+    type: scout
+    assignee: Scout
+    status: done
+    objective: "List the extension launch paths."
+    receipt:
+      result: done
+      summary: "T009 completed during the progressive board motion demo."
+  - id: T010
+    type: worker
+    assignee: Worker
+    status: done
+    objective: "Exercise a queued card moving into active work."
+    receipt:
+      result: done
+      summary: "T010 completed during the progressive board motion demo."
+  - id: T011
+    type: worker
+    assignee: Worker
+    status: blocked
+    objective: "Demonstrate blocked card handling."
+    receipt:
+      result: blocked
+      summary: "T011 is blocked during the progressive board motion demo."
+  - id: T012
+    type: judge
+    assignee: Judge
+    status: done
+    objective: "Audit the animation behavior after repeated updates."
+    receipt:
+      result: done
+      summary: "T012 completed during the progressive board motion demo."
+  - id: T013
+    type: scout
+    assignee: Scout
+    status: blocked
+    objective: "Capture visual proof notes."
+    receipt:
+      result: blocked
+      summary: "T013 is blocked during the progressive board motion demo."
+  - id: T014
+    type: worker
+    assignee: Worker
+    status: done
+    objective: "Prepare final extension packaging check."
+    receipt:
+      result: done
+      summary: "T014 completed during the progressive board motion demo."

package/goalbuddy/extend/local-goal-board/extension.yaml

@@ -0,0 +1,37 @@
+id: local-goal-board
+name: Local Goal Board
+kind: visualization
+version: 0.1.0
+source_of_truth: local
+description: Generate and serve a minimal GoalBuddy-branded local Kanban board that updates live from a goal directory's state.yaml and notes.
+local_use_prompt: Run the bundled local board script for docs/goals/<slug>. It writes a tiny web app into docs/goals/<slug>/.goalbuddy-board and serves it on 127.0.0.1 with live SSE updates from state.yaml and notes. Use --once --json for generation checks and no long-running server.
+use_when:
+  - A human wants to watch a GoalBuddy run in a local board UI.
+  - The goal needs GitHub-Projects-like visibility without GitHub credentials.
+  - state.yaml and notes should remain the source of truth while the browser updates live.
+activation: user_requested
+outputs:
+  - Local GoalBuddy board web app
+  - Live state.yaml and notes viewer
+requires_approval: false
+safe_by_default: true
+reads:
+  - docs/goals/<slug>/state.yaml
+  - docs/goals/<slug>/notes
+writes:
+  - docs/goals/<slug>/.goalbuddy-board
+side_effects:
+  - Starts a local-only HTTP server when not run with --once.
+agent_instructions:
+  - Use the bundled local-goal-board script; do not build a static-only mockup.
+  - Keep state.yaml authoritative; the app is only a viewer.
+  - Require live no-manual-reload updates through the local server event stream.
+  - Keep the generated UI simple, clean, minimal, and GoalBuddy branded.
+auth:
+  env: []
+supports:
+  dry_run: true
+  live_local_board: true
+  live_updates: true
+  credentials_required: false
+  generated_goal_artifact: true