@cliangdev/flux-plugin 0.3.0 → 0.3.1-dev.8c219d5

package/bin/install.cjs

@@ -327,10 +327,10 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 			mcpConfig.mcpServers = {};
 		}
 
-		const versionTag = pkg.version.includes("-dev.") ? "latest" : pkg.version;
+		const tag = pkg.version.includes("-dev.") ? "next" : "latest";
 		mcpConfig.mcpServers.flux = {
 			command: "bunx",
-			args: [`@cliangdev/flux-plugin@${versionTag}`, "serve"],
+			args: [`@cliangdev/flux-plugin@${tag}`, "serve"],
 		};
 
 		writeJson(mcpConfigPath, mcpConfig);

package/commands/dashboard.md

@@ -13,7 +13,7 @@ Launch the Flux Dashboard web interface to visualize project status.
 Run the dashboard server:
 
 ```bash
-bunx @cliangdev/flux-plugin dashboard
+bunx --force @cliangdev/flux-plugin@latest dashboard
 ```
 
 This will:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.3.0",
+  "version": "0.3.1-dev.8c219d5",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",
@@ -59,6 +59,8 @@
   "dependencies": {
     "@linear/sdk": "^70.0.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
+    "@octokit/graphql": "^9.0.3",
+    "@octokit/rest": "^22.0.1",
     "chalk": "^5.4.1",
     "zod": "^4.3.5"
   },

package/src/server/adapters/factory.ts

@@ -1,12 +1,7 @@
-/**
- * Adapter Factory
- *
- * Creates the appropriate adapter based on project configuration.
- * Supports LocalAdapter and LinearAdapter; future adapters will be added here.
- */
-
 import { existsSync, readFileSync } from "node:fs";
 import { config } from "../config.js";
+import { GitHubAdapter } from "./github/adapter.js";
+import { loadGithubConfig } from "./github/config.js";
 import { LinearAdapter } from "./linear/adapter.js";
 import { linearConfigExists, loadLinearConfig } from "./linear/config.js";
 import { LocalAdapter } from "./local-adapter.js";
@@ -14,12 +9,8 @@ import type { AdapterConfig, BackendAdapter } from "./types.js";
 
 let cachedAdapter: BackendAdapter | null = null;
 
-/**
- * Get the adapter configuration from project.json
- */
 function getAdapterConfig(): AdapterConfig {
   if (!existsSync(config.projectJsonPath)) {
-    // Default to local adapter if project not initialized
     return { type: "local" };
   }
 
@@ -32,12 +23,6 @@ function getAdapterConfig(): AdapterConfig {
   }
 }
 
-/**
- * Create an adapter instance based on configuration.
- *
- * @param adapterConfig - Optional override for adapter configuration
- * @returns The appropriate BackendAdapter implementation
- */
 export function createAdapter(adapterConfig?: AdapterConfig): BackendAdapter {
   const cfg = adapterConfig ?? getAdapterConfig();
 
@@ -60,6 +45,10 @@ export function createAdapter(adapterConfig?: AdapterConfig): BackendAdapter {
     case "notion":
       // TODO: Implement NotionAdapter
       throw new Error("Notion adapter not yet implemented");
+    case "github": {
+      const githubConfig = loadGithubConfig();
+      return new GitHubAdapter(githubConfig);
+    }
     default: {
       const _exhaustive: never = cfg.type;
       throw new Error(`Unknown adapter type: ${cfg.type}`);
@@ -67,13 +56,6 @@ export function createAdapter(adapterConfig?: AdapterConfig): BackendAdapter {
   }
 }
 
-/**
- * Get or create a cached adapter instance.
- * Uses singleton pattern to avoid creating multiple adapter instances.
- *
- * @param forceNew - If true, creates a new adapter even if one is cached
- * @returns The cached or newly created adapter
- */
 export function getAdapter(forceNew = false): BackendAdapter {
   if (forceNew || !cachedAdapter) {
     cachedAdapter = createAdapter();
@@ -81,10 +63,6 @@ export function getAdapter(forceNew = false): BackendAdapter {
   return cachedAdapter;
 }
 
-/**
- * Clear the cached adapter instance.
- * Useful for testing or when project configuration changes.
- */
 export function clearAdapterCache(): void {
   cachedAdapter = null;
 }

package/src/server/adapters/github/__tests__/criteria-deps.test.ts

@@ -0,0 +1,579 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import {
+  addCriterionToDescription,
+  generateCriteriaId,
+  parseCriteriaFromDescription,
+  updateCriterionInDescription,
+} from "../helpers/criteria.js";
+
+// ============================================================
+// Unit tests: criteria helper functions
+// ============================================================
+
+describe("parseCriteriaFromDescription", () => {
+  test("extracts criteria with correct isMet state", () => {
+    const body = `## Acceptance Criteria
+
+- [ ] First criterion
+- [x] Second criterion
+- [ ] Third criterion`;
+
+    const criteria = parseCriteriaFromDescription(body);
+    expect(criteria).toHaveLength(3);
+    expect(criteria[0].text).toBe("First criterion");
+    expect(criteria[0].isMet).toBe(false);
+    expect(criteria[1].text).toBe("Second criterion");
+    expect(criteria[1].isMet).toBe(true);
+    expect(criteria[2].text).toBe("Third criterion");
+    expect(criteria[2].isMet).toBe(false);
+  });
+
+  test("returns empty array when no Acceptance Criteria section present", () => {
+    const body = `Some description without criteria`;
+    const criteria = parseCriteriaFromDescription(body);
+    expect(criteria).toHaveLength(0);
+  });
+
+  test("returns empty array for undefined input", () => {
+    const criteria = parseCriteriaFromDescription(undefined);
+    expect(criteria).toHaveLength(0);
+  });
+
+  test("stops parsing at next section header", () => {
+    const body = `## Acceptance Criteria
+
+- [ ] First criterion
+
+## Other Section
+
+- [ ] Should not be parsed`;
+
+    const criteria = parseCriteriaFromDescription(body);
+    expect(criteria).toHaveLength(1);
+    expect(criteria[0].text).toBe("First criterion");
+  });
+});
+
+describe("updateCriterionInDescription", () => {
+  test("flips [ ] to [x] for matching criterion ID", () => {
+    const body = `## Acceptance Criteria
+
+- [ ] First criterion
+- [ ] Second criterion`;
+
+    const id = generateCriteriaId("First criterion");
+    const updated = updateCriterionInDescription(body, id, true);
+    expect(updated).toContain("- [x] First criterion");
+    expect(updated).toContain("- [ ] Second criterion");
+  });
+
+  test("flips [x] to [ ] for matching criterion ID", () => {
+    const body = `## Acceptance Criteria
+
+- [x] Already met
+- [ ] Not met`;
+
+    const id = generateCriteriaId("Already met");
+    const updated = updateCriterionInDescription(body, id, false);
+    expect(updated).toContain("- [ ] Already met");
+  });
+
+  test("throws when criterion ID not found", () => {
+    const body = `## Acceptance Criteria
+
+- [ ] Some criterion`;
+
+    expect(() =>
+      updateCriterionInDescription(body, "ac_nonexist", true),
+    ).toThrow("Criterion not found: ac_nonexist");
+  });
+});
+
+describe("addCriterionToDescription", () => {
+  test("appends to existing Acceptance Criteria section", () => {
+    const body = `## Acceptance Criteria
+
+- [ ] Existing criterion`;
+
+    const updated = addCriterionToDescription(body, "New criterion");
+    expect(updated).toContain("- [ ] Existing criterion");
+    expect(updated).toContain("- [ ] New criterion");
+    const lines = updated.split("\n");
+    const existingIdx = lines.findIndex((l) =>
+      l.includes("Existing criterion"),
+    );
+    const newIdx = lines.findIndex((l) => l.includes("New criterion"));
+    expect(newIdx).toBeGreaterThan(existingIdx);
+  });
+
+  test("creates Acceptance Criteria section if absent", () => {
+    const body = `Some description without criteria`;
+    const updated = addCriterionToDescription(body, "New criterion");
+    expect(updated).toContain("## Acceptance Criteria");
+    expect(updated).toContain("- [ ] New criterion");
+  });
+
+  test("creates section from empty/undefined description", () => {
+    const updated = addCriterionToDescription(undefined, "First criterion");
+    expect(updated).toBe("## Acceptance Criteria\n\n- [ ] First criterion");
+  });
+});
+
+describe("generateCriteriaId", () => {
+  test("produces stable ID for same text", () => {
+    const id1 = generateCriteriaId("some criterion text");
+    const id2 = generateCriteriaId("some criterion text");
+    expect(id1).toBe(id2);
+  });
+
+  test("produces different IDs for different text", () => {
+    const id1 = generateCriteriaId("criterion A");
+    const id2 = generateCriteriaId("criterion B");
+    expect(id1).not.toBe(id2);
+  });
+
+  test("has ac_ prefix and 8-char hex suffix", () => {
+    const id = generateCriteriaId("test text");
+    expect(id).toMatch(/^ac_[0-9a-f]{8}$/);
+  });
+
+  test("trims whitespace before hashing", () => {
+    const id1 = generateCriteriaId("  test  ");
+    const id2 = generateCriteriaId("test");
+    expect(id1).toBe(id2);
+  });
+});
+
+// ============================================================
+// Adapter method tests (mock Octokit)
+// ============================================================
+
+let mockIssuesUpdate: any = null;
+let mockIssuesGet: Record<number, any> = {};
+let mockIssuesList: any[] = [];
+let mockGetContent: any = null;
+let lastUpdateParams: any = null;
+
+mock.module("@octokit/rest", () => ({
+  Octokit: class MockOctokit {
+    repos = {
+      getContent: async (_params: any) => {
+        if (mockGetContent === null) {
+          const err: any = new Error("Not Found");
+          err.status = 404;
+          throw err;
+        }
+        return mockGetContent;
+      },
+      createOrUpdateFileContents: async () => {
+        return { data: { content: { sha: "new-sha" } } };
+      },
+    };
+
+    issues = {
+      update: async (params: any) => {
+        lastUpdateParams = params;
+        const num = params.issue_number;
+        if (mockIssuesGet[num]) {
+          const updated = {
+            ...mockIssuesGet[num],
+            body: params.body ?? mockIssuesGet[num].body,
+          };
+          return { data: updated };
+        }
+        return { data: mockIssuesUpdate };
+      },
+      get: async (params: any) => {
+        const num = params.issue_number;
+        if (mockIssuesGet[num]) return { data: mockIssuesGet[num] };
+        const err: any = new Error("Not Found");
+        err.status = 404;
+        throw err;
+      },
+      listForRepo: async (_params: any) => {
+        return { data: mockIssuesList };
+      },
+    };
+  },
+}));
+
+mock.module("@octokit/graphql", () => ({
+  graphql: {
+    defaults: (_opts: any) => {
+      return async () => ({});
+    },
+  },
+}));
+
+function makeIssue(
+  overrides: Partial<{
+    number: number;
+    title: string;
+    body: string;
+    labels: string[];
+    state: "open" | "closed";
+    created_at: string;
+    updated_at: string;
+    node_id: string;
+  }> = {},
+) {
+  const number = overrides.number ?? 1;
+  return {
+    number,
+    title: overrides.title ?? "Test Issue",
+    body: overrides.body ?? "",
+    labels: (overrides.labels ?? []).map((name) => ({ name })),
+    state: overrides.state ?? "open",
+    created_at: overrides.created_at ?? "2026-01-01T00:00:00Z",
+    updated_at: overrides.updated_at ?? "2026-01-01T00:00:00Z",
+    node_id: overrides.node_id ?? `MDU6SXNzdWU${number}`,
+  };
+}
+
+function encodeIndex(index: Record<string, number>): string {
+  return Buffer.from(JSON.stringify(index)).toString("base64");
+}
+
+function makeAdapter() {
+  const { GitHubAdapter } = require("../adapter.js");
+  const adapter = new GitHubAdapter({
+    token: "ghp_test",
+    owner: "test-owner",
+    repo: "test-repo",
+    projectId: "PVT_kwDO123",
+    refPrefix: "FP",
+  });
+
+  (adapter as any).client.rest.issues = {
+    update: async (params: any) => {
+      lastUpdateParams = params;
+      const num = params.issue_number;
+      if (mockIssuesGet[num]) {
+        const updated = {
+          ...mockIssuesGet[num],
+          body: params.body ?? mockIssuesGet[num].body,
+        };
+        return { data: updated };
+      }
+      return { data: mockIssuesUpdate };
+    },
+    get: async (params: any) => {
+      const num = params.issue_number;
+      if (mockIssuesGet[num]) return { data: mockIssuesGet[num] };
+      const err: any = new Error("Not Found");
+      err.status = 404;
+      throw err;
+    },
+    listForRepo: async (_params: any) => {
+      return { data: mockIssuesList };
+    },
+  };
+
+  (adapter as any).client.rest.repos = {
+    getContent: async (_params: any) => {
+      if (mockGetContent === null) {
+        const err: any = new Error("Not Found");
+        err.status = 404;
+        throw err;
+      }
+      return mockGetContent;
+    },
+    createOrUpdateFileContents: async () => {
+      return { data: { content: { sha: "new-sha" } } };
+    },
+  };
+
+  (adapter as any).client.rest.request = async (url: string, params: any) => {
+    if (url.includes("sub_issues") && url.startsWith("GET")) {
+      return { data: [] };
+    }
+    if (url.includes("sub_issues") && url.startsWith("POST")) {
+      return { data: {} };
+    }
+    throw new Error(`Unmocked request: ${url}`);
+  };
+
+  return adapter;
+}
+
+beforeEach(() => {
+  mockIssuesUpdate = null;
+  mockIssuesGet = {};
+  mockIssuesList = [];
+  mockGetContent = null;
+  lastUpdateParams = null;
+});
+
+afterEach(() => {
+  mockIssuesUpdate = null;
+  mockIssuesGet = {};
+  mockIssuesList = [];
+  mockGetContent = null;
+  lastUpdateParams = null;
+});
+
+// Helper: make index content returning given mapping
+function makeIndexContent(index: Record<string, number>) {
+  return {
+    data: {
+      sha: "abc123",
+      content: encodeIndex(index),
+      encoding: "base64",
+    },
+  };
+}
+
+describe("adapter.addCriterion", () => {
+  test("returns AcceptanceCriterion with isMet: false", async () => {
+    const epicBody = `Some description
+
+<!-- flux-meta
+{"ref":"FP-E5","prd_ref":"FP-P1","dependencies":[]}
+-->`;
+    mockIssuesGet[5] = makeIssue({
+      number: 5,
+      body: epicBody,
+      labels: ["flux:epic"],
+    });
+    mockGetContent = makeIndexContent({ "FP-E5": 5 });
+
+    const adapter = makeAdapter();
+    const result = await adapter.addCriterion({
+      parentRef: "FP-E5",
+      criteria: "New acceptance criterion",
+    });
+
+    expect(result.isMet).toBe(false);
+    expect(result.criteria).toBe("New acceptance criterion");
+    expect(result.parentType).toBe("epic");
+    expect(result.id).toBe(generateCriteriaId("New acceptance criterion"));
+  });
+
+  test("body is updated with new checkbox", async () => {
+    const epicBody = `Some description
+
+<!-- flux-meta
+{"ref":"FP-E5","prd_ref":"FP-P1","dependencies":[]}
+-->`;
+    mockIssuesGet[5] = makeIssue({
+      number: 5,
+      body: epicBody,
+      labels: ["flux:epic"],
+    });
+    mockGetContent = makeIndexContent({ "FP-E5": 5 });
+
+    const adapter = makeAdapter();
+    await adapter.addCriterion({
+      parentRef: "FP-E5",
+      criteria: "New acceptance criterion",
+    });
+
+    expect(lastUpdateParams).not.toBeNull();
+    expect(lastUpdateParams.body).toContain("- [ ] New acceptance criterion");
+    expect(lastUpdateParams.body).toContain("## Acceptance Criteria");
+  });
+});
+
+describe("adapter.markCriterionMet", () => {
+  test("returns AcceptanceCriterion with isMet: true", async () => {
+    const criterionText = "Must handle errors";
+    const criterionId = generateCriteriaId(criterionText);
+
+    const taskBody = `Task description
+
+## Acceptance Criteria
+
+- [ ] ${criterionText}
+
+<!-- flux-meta
+{"ref":"FP-T10","epic_ref":"FP-E5","prd_ref":"FP-P1","dependencies":[]}
+-->`;
+    mockIssuesGet[10] = makeIssue({
+      number: 10,
+      body: taskBody,
+      labels: ["flux:task"],
+    });
+    mockIssuesList = [
+      makeIssue({ number: 10, body: taskBody, labels: ["flux:task"] }),
+    ];
+
+    const adapter = makeAdapter();
+    const result = await adapter.markCriterionMet(criterionId);
+
+    expect(result.isMet).toBe(true);
+    expect(result.criteria).toBe(criterionText);
+  });
+
+  test("throws when criterionId not found in any issue", async () => {
+    const taskBody = `## Acceptance Criteria
+
+- [ ] Some other criterion
+
+<!-- flux-meta
+{"ref":"FP-T10","epic_ref":"FP-E5","prd_ref":"FP-P1","dependencies":[]}
+-->`;
+    mockIssuesList = [
+      makeIssue({ number: 10, body: taskBody, labels: ["flux:task"] }),
+      makeIssue({
+        number: 11,
+        body: `<!-- flux-meta\n{"ref":"FP-E2","prd_ref":"FP-P1","dependencies":[]}\n-->`,
+        labels: ["flux:epic"],
+      }),
+    ];
+
+    const adapter = makeAdapter();
+    await expect(adapter.markCriterionMet("ac_notfound")).rejects.toThrow(
+      "Criterion not found",
+    );
+  });
+});
+
+describe("adapter.getCriteria", () => {
+  test("returns all criteria in order with correct isMet state", async () => {
+    const epicBody = `Epic description
+
+## Acceptance Criteria
+
+- [ ] First criterion
+- [x] Second criterion
+- [ ] Third criterion
+
+<!-- flux-meta
+{"ref":"FP-E5","prd_ref":"FP-P1","dependencies":[]}
+-->`;
+    mockIssuesGet[5] = makeIssue({
+      number: 5,
+      body: epicBody,
+      labels: ["flux:epic"],
+    });
+    mockGetContent = makeIndexContent({ "FP-E5": 5 });
+
+    const adapter = makeAdapter();
+    const criteria = await adapter.getCriteria("FP-E5");
+
+    expect(criteria).toHaveLength(3);
+    expect(criteria[0].criteria).toBe("First criterion");
+    expect(criteria[0].isMet).toBe(false);
+    expect(criteria[1].criteria).toBe("Second criterion");
+    expect(criteria[1].isMet).toBe(true);
+    expect(criteria[2].criteria).toBe("Third criterion");
+    expect(criteria[2].isMet).toBe(false);
+  });
+
+  test("returns empty array when no criteria in body", async () => {
+    const epicBody = `Epic description without criteria
+
+<!-- flux-meta
+{"ref":"FP-E5","prd_ref":"FP-P1","dependencies":[]}
+-->`;
+    mockIssuesGet[5] = makeIssue({
+      number: 5,
+      body: epicBody,
+      labels: ["flux:epic"],
+    });
+    mockGetContent = makeIndexContent({ "FP-E5": 5 });
+
+    const adapter = makeAdapter();
+    const criteria = await adapter.getCriteria("FP-E5");
+    expect(criteria).toHaveLength(0);
+  });
+});
+
+describe("adapter.addDependency", () => {
+  test("adds dependsOnRef to flux-meta dependencies array", async () => {
+    const taskBody = `Task description
+
+<!-- flux-meta
+{"ref":"FP-T10","epic_ref":"FP-E5","prd_ref":"FP-P1","priority":"HIGH","dependencies":[]}
+-->`;
+    mockIssuesGet[10] = makeIssue({
+      number: 10,
+      body: taskBody,
+      labels: ["flux:task"],
+    });
+    mockGetContent = makeIndexContent({ "FP-T10": 10 });
+
+    const adapter = makeAdapter();
+    await adapter.addDependency("FP-T10", "FP-T9");
+
+    expect(lastUpdateParams).not.toBeNull();
+    expect(lastUpdateParams.body).toContain('"FP-T9"');
+    expect(lastUpdateParams.body).toContain("dependencies");
+  });
+
+  test("throws when ref and dependsOnRef are different entity types", async () => {
+    const adapter = makeAdapter();
+    await expect(adapter.addDependency("FP-T10", "FP-E5")).rejects.toThrow(
+      "Dependencies must be between entities of the same type",
+    );
+  });
+
+  test("throws on self-dependency", async () => {
+    const adapter = makeAdapter();
+    await expect(adapter.addDependency("FP-T10", "FP-T10")).rejects.toThrow(
+      "Cannot add self-dependency",
+    );
+  });
+});
+
+describe("adapter.removeDependency", () => {
+  test("removes the ref from the dependencies array", async () => {
+    const taskBody = `Task description
+
+<!-- flux-meta
+{"ref":"FP-T10","epic_ref":"FP-E5","prd_ref":"FP-P1","priority":"HIGH","dependencies":["FP-T9","FP-T8"]}
+-->`;
+    mockIssuesGet[10] = makeIssue({
+      number: 10,
+      body: taskBody,
+      labels: ["flux:task"],
+    });
+    mockGetContent = makeIndexContent({ "FP-T10": 10 });
+
+    const adapter = makeAdapter();
+    await adapter.removeDependency("FP-T10", "FP-T9");
+
+    expect(lastUpdateParams).not.toBeNull();
+    expect(lastUpdateParams.body).not.toContain('"FP-T9"');
+    expect(lastUpdateParams.body).toContain('"FP-T8"');
+  });
+});
+
+describe("adapter.getDependencies", () => {
+  test("returns empty array when no dependencies in meta", async () => {
+    const taskBody = `Task description
+
+<!-- flux-meta
+{"ref":"FP-T10","epic_ref":"FP-E5","prd_ref":"FP-P1","priority":"MEDIUM","dependencies":[]}
+-->`;
+    mockIssuesGet[10] = makeIssue({
+      number: 10,
+      body: taskBody,
+      labels: ["flux:task"],
+    });
+    mockGetContent = makeIndexContent({ "FP-T10": 10 });
+
+    const adapter = makeAdapter();
+    const deps = await adapter.getDependencies("FP-T10");
+    expect(deps).toEqual([]);
+  });
+
+  test("returns existing dependencies", async () => {
+    const taskBody = `Task description
+
+<!-- flux-meta
+{"ref":"FP-T10","epic_ref":"FP-E5","prd_ref":"FP-P1","priority":"MEDIUM","dependencies":["FP-T9","FP-T8"]}
+-->`;
+    mockIssuesGet[10] = makeIssue({
+      number: 10,
+      body: taskBody,
+      labels: ["flux:task"],
+    });
+    mockGetContent = makeIndexContent({ "FP-T10": 10 });
+
+    const adapter = makeAdapter();
+    const deps = await adapter.getDependencies("FP-T10");
+    expect(deps).toEqual(["FP-T9", "FP-T8"]);
+  });
+});