@cliangdev/flux-plugin 0.3.0 → 0.3.1-dev.bdbaeae

package/src/server/adapters/github/client.ts

@@ -0,0 +1,33 @@
+import { graphql } from "@octokit/graphql";
+import { Octokit } from "@octokit/rest";
+import type { GitHubConfig } from "./types.js";
+
+export class GitHubClient {
+  readonly rest: Octokit;
+  private gql: ReturnType<typeof graphql.defaults>;
+
+  constructor(config: GitHubConfig) {
+    this.rest = new Octokit({ auth: config.token });
+    this.gql = graphql.defaults({
+      headers: {
+        authorization: `token ${config.token}`,
+      },
+    });
+  }
+
+  async graphql<T>(
+    query: string,
+    variables?: Record<string, unknown>,
+  ): Promise<T> {
+    try {
+      return await this.gql<T>(query, variables);
+    } catch (error: any) {
+      if (error.status === 401 || error.status === 403) {
+        throw new Error(
+          `GitHub API auth error: token may lack 'repo' scope (HTTP ${error.status})`,
+        );
+      }
+      throw error;
+    }
+  }
+}

package/src/server/adapters/github/config.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from "node:fs";
+import { config } from "../../config.js";
+import type { GitHubConfig } from "./types.js";
+
+export function githubConfigExists(): boolean {
+  if (!existsSync(config.projectJsonPath)) {
+    return false;
+  }
+
+  try {
+    const content = readFileSync(config.projectJsonPath, "utf-8");
+    const project = JSON.parse(content);
+    return project?.adapter?.type === "github";
+  } catch {
+    return false;
+  }
+}
+
+export function loadGithubConfig(): GitHubConfig {
+  if (!existsSync(config.projectJsonPath)) {
+    throw new Error(
+      "GitHub config not found: project.json missing. Run project init first.",
+    );
+  }
+
+  const content = readFileSync(config.projectJsonPath, "utf-8");
+  const project = JSON.parse(content);
+  const cfg = project?.adapter?.config;
+
+  if (!cfg || typeof cfg !== "object") {
+    throw new Error(
+      "GitHub config not found in project.json: adapter.config is missing.",
+    );
+  }
+
+  if (!cfg.token || typeof cfg.token !== "string") {
+    throw new Error("Invalid GitHub config: token is required");
+  }
+  if (!cfg.owner || typeof cfg.owner !== "string") {
+    throw new Error("Invalid GitHub config: owner is required");
+  }
+  if (!cfg.repo || typeof cfg.repo !== "string") {
+    throw new Error("Invalid GitHub config: repo is required");
+  }
+  if (!cfg.projectId || typeof cfg.projectId !== "string") {
+    throw new Error("Invalid GitHub config: projectId is required");
+  }
+  if (!cfg.refPrefix || typeof cfg.refPrefix !== "string") {
+    throw new Error("Invalid GitHub config: refPrefix is required");
+  }
+
+  return {
+    token: cfg.token,
+    owner: cfg.owner,
+    repo: cfg.repo,
+    projectId: cfg.projectId,
+    refPrefix: cfg.refPrefix,
+  };
+}

package/src/server/adapters/github/helpers/criteria.ts

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+
+export interface ParsedCriterion {
+  id: string;
+  text: string;
+  isMet: boolean;
+  lineIndex: number;
+}
+
+export function generateCriteriaId(text: string): string {
+  const hash = createHash("sha256").update(text.trim()).digest("hex");
+  return `ac_${hash.substring(0, 8)}`;
+}
+
+export function parseCriteriaFromDescription(
+  description: string | undefined,
+): ParsedCriterion[] {
+  if (!description) {
+    return [];
+  }
+
+  const lines = description.split("\n");
+
+  let acSectionStart = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmedLine = lines[i].trim().toLowerCase();
+    if (
+      trimmedLine.includes("acceptance criteria") &&
+      (trimmedLine.startsWith("#") || trimmedLine.startsWith("**"))
+    ) {
+      acSectionStart = i;
+      break;
+    }
+  }
+
+  const criteria: ParsedCriterion[] = [];
+  let inACSection = acSectionStart === -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmedLine = line.trim().toLowerCase();
+
+    if (i === acSectionStart) {
+      inACSection = true;
+      continue;
+    }
+
+    if (acSectionStart !== -1 && i > acSectionStart && inACSection) {
+      if (
+        trimmedLine.startsWith("#") ||
+        (trimmedLine.startsWith("**") && trimmedLine.endsWith("**"))
+      ) {
+        break;
+      }
+    }
+
+    if (inACSection) {
+      const checkboxMatch = line.match(/^[\s]*[-*]\s*\[([ xX])\]\s*(.+)$/);
+      if (checkboxMatch) {
+        const isChecked = checkboxMatch[1].toLowerCase() === "x";
+        const text = checkboxMatch[2].trim();
+
+        criteria.push({
+          id: generateCriteriaId(text),
+          text,
+          isMet: isChecked,
+          lineIndex: i,
+        });
+      }
+    }
+  }
+
+  return criteria;
+}
+
+export function updateCriterionInDescription(
+  description: string,
+  criteriaId: string,
+  isMet: boolean,
+): string {
+  const lines = description.split("\n");
+  const criteria = parseCriteriaFromDescription(description);
+
+  const criterion = criteria.find((c) => c.id === criteriaId);
+  if (!criterion) {
+    throw new Error(`Criterion not found: ${criteriaId}`);
+  }
+
+  const line = lines[criterion.lineIndex];
+  const newCheckbox = isMet ? "[x]" : "[ ]";
+  const updatedLine = line.replace(/\[([ xX])\]/, newCheckbox);
+  lines[criterion.lineIndex] = updatedLine;
+
+  return lines.join("\n");
+}
+
+export function addCriterionToDescription(
+  description: string | undefined,
+  criterionText: string,
+): string {
+  if (!description) {
+    return `## Acceptance Criteria\n\n- [ ] ${criterionText}`;
+  }
+
+  const lines = description.split("\n");
+
+  let acSectionStart = -1;
+  let acSectionEnd = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmedLine = lines[i].trim().toLowerCase();
+
+    if (
+      trimmedLine.includes("acceptance criteria") &&
+      (trimmedLine.startsWith("#") || trimmedLine.startsWith("**"))
+    ) {
+      acSectionStart = i;
+      continue;
+    }
+
+    if (acSectionStart !== -1 && i > acSectionStart) {
+      const line = lines[i].trim();
+      if (
+        line.startsWith("#") ||
+        (line.startsWith("**") && line.endsWith("**"))
+      ) {
+        acSectionEnd = i;
+        break;
+      }
+    }
+  }
+
+  let insertIndex = -1;
+  if (acSectionStart !== -1) {
+    for (let i = acSectionEnd - 1; i > acSectionStart; i--) {
+      if (lines[i].match(/^[\s]*[-*]\s*\[([ xX])\]/)) {
+        insertIndex = i + 1;
+        break;
+      }
+    }
+    if (insertIndex === -1) {
+      insertIndex = acSectionStart + 1;
+      while (insertIndex < lines.length && lines[insertIndex].trim() === "") {
+        insertIndex++;
+      }
+    }
+  } else {
+    lines.push("");
+    lines.push("## Acceptance Criteria");
+    lines.push("");
+    insertIndex = lines.length;
+  }
+
+  lines.splice(insertIndex, 0, `- [ ] ${criterionText}`);
+
+  return lines.join("\n");
+}

package/src/server/adapters/github/helpers/index-store.ts

@@ -0,0 +1,75 @@
+import type { GitHubClient } from "../client.js";
+
+export type RefIndex = Record<string, number>;
+
+const INDEX_PATH = ".flux/github-index.json";
+
+async function fetchCurrentFile(
+  client: GitHubClient,
+  owner: string,
+  repo: string,
+): Promise<{ sha: string; content: string } | null> {
+  try {
+    const response = await client.rest.repos.getContent({
+      owner,
+      repo,
+      path: INDEX_PATH,
+    });
+    const data = response.data as {
+      sha: string;
+      content: string;
+      encoding: string;
+    };
+    return { sha: data.sha, content: data.content };
+  } catch (err: any) {
+    if (err.status === 404) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+export async function readIndex(
+  client: GitHubClient,
+  owner: string,
+  repo: string,
+): Promise<RefIndex> {
+  const file = await fetchCurrentFile(client, owner, repo);
+  if (file === null) {
+    return {};
+  }
+  const json = Buffer.from(file.content, "base64").toString("utf-8");
+  return JSON.parse(json) as RefIndex;
+}
+
+export async function writeIndex(
+  client: GitHubClient,
+  owner: string,
+  repo: string,
+  index: RefIndex,
+): Promise<void> {
+  const existing = await fetchCurrentFile(client, owner, repo);
+
+  const params: Record<string, unknown> = {
+    owner,
+    repo,
+    path: INDEX_PATH,
+    message: "chore: update flux ref index",
+    content: Buffer.from(JSON.stringify(index, null, 2)).toString("base64"),
+  };
+
+  if (existing !== null) {
+    params.sha = existing.sha;
+  }
+
+  try {
+    await client.rest.repos.createOrUpdateFileContents(params as any);
+  } catch (err: any) {
+    if (err.status === 409) {
+      throw new Error(
+        "Index conflict: another operation modified the index concurrently. Retry the operation.",
+      );
+    }
+    throw err;
+  }
+}

package/src/server/adapters/github/helpers/meta.ts

@@ -0,0 +1,26 @@
+export interface FluxMeta {
+  ref: string;
+  tag?: string;
+  prd_ref?: string;
+  epic_ref?: string;
+  priority?: string;
+  dependencies?: string[];
+}
+
+export function encodeMeta(meta: FluxMeta): string {
+  return `<!-- flux-meta\n${JSON.stringify(meta)}\n-->`;
+}
+
+export function decodeMeta(body: string): FluxMeta | null {
+  const match = body.match(/<!--\s*flux-meta\n([\s\S]*?)\n-->/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[1]) as FluxMeta;
+  } catch {
+    return null;
+  }
+}
+
+export function extractDescription(body: string): string {
+  return body.replace(/<!--\s*flux-meta[\s\S]*?-->/g, "").trim();
+}

package/src/server/adapters/github/index.ts

@@ -0,0 +1,5 @@
+export { GitHubAdapter } from "./adapter.js";
+export { GitHubClient } from "./client.js";
+export { githubConfigExists, loadGithubConfig } from "./config.js";
+export type { GitHubConfig } from "./types.js";
+export { GITHUB_LABELS } from "./types.js";

package/src/server/adapters/github/mappers/epic.ts

@@ -0,0 +1,21 @@
+import type { EpicStatus } from "../../types.js";
+import { GITHUB_LABELS } from "../types.js";
+
+const STATUS_LABEL_MAP: Record<EpicStatus, string | null> = {
+  PENDING: null,
+  IN_PROGRESS: GITHUB_LABELS.STATUS_IN_PROGRESS,
+  COMPLETED: null,
+};
+
+export function epicStatusToLabel(status: EpicStatus): string | null {
+  return STATUS_LABEL_MAP[status];
+}
+
+export function labelToEpicStatus(
+  labels: string[],
+  isClosed: boolean,
+): EpicStatus {
+  if (isClosed) return "COMPLETED";
+  if (labels.includes(GITHUB_LABELS.STATUS_IN_PROGRESS)) return "IN_PROGRESS";
+  return "PENDING";
+}

package/src/server/adapters/github/mappers/index.ts

@@ -0,0 +1,15 @@
+export { epicStatusToLabel, labelToEpicStatus } from "./epic.js";
+export {
+  getAllStatusLabels,
+  labelToPrdStatus,
+  labelToTag,
+  prdStatusToLabel,
+  tagToLabel,
+} from "./prd.js";
+
+export {
+  labelToPriority,
+  labelToTaskStatus,
+  priorityToLabel,
+  taskStatusToLabel,
+} from "./task.js";

package/src/server/adapters/github/mappers/prd.ts

@@ -0,0 +1,50 @@
+import type { PrdStatus } from "../../types.js";
+import { GITHUB_LABELS } from "../types.js";
+
+const STATUS_LABEL_MAP: Record<PrdStatus, string | null> = {
+  DRAFT: GITHUB_LABELS.STATUS_DRAFT,
+  PENDING_REVIEW: GITHUB_LABELS.STATUS_PENDING_REVIEW,
+  REVIEWED: GITHUB_LABELS.STATUS_REVIEWED,
+  APPROVED: GITHUB_LABELS.STATUS_APPROVED,
+  BREAKDOWN_READY: GITHUB_LABELS.STATUS_BREAKDOWN_READY,
+  COMPLETED: GITHUB_LABELS.STATUS_COMPLETED,
+  ARCHIVED: null,
+};
+
+const ALL_STATUS_LABELS = new Set(
+  Object.values(STATUS_LABEL_MAP).filter(Boolean) as string[],
+);
+
+export function prdStatusToLabel(status: PrdStatus): string | null {
+  return STATUS_LABEL_MAP[status];
+}
+
+export function labelToPrdStatus(
+  labels: string[],
+  isClosed: boolean,
+): PrdStatus {
+  if (isClosed) return "ARCHIVED";
+
+  if (labels.includes(GITHUB_LABELS.STATUS_COMPLETED)) return "COMPLETED";
+  if (labels.includes(GITHUB_LABELS.STATUS_BREAKDOWN_READY))
+    return "BREAKDOWN_READY";
+  if (labels.includes(GITHUB_LABELS.STATUS_APPROVED)) return "APPROVED";
+  if (labels.includes(GITHUB_LABELS.STATUS_REVIEWED)) return "REVIEWED";
+  if (labels.includes(GITHUB_LABELS.STATUS_PENDING_REVIEW))
+    return "PENDING_REVIEW";
+
+  return "DRAFT";
+}
+
+export function tagToLabel(tag: string): string {
+  return `${GITHUB_LABELS.TAG_PREFIX}${tag}`;
+}
+
+export function labelToTag(labels: string[]): string | undefined {
+  const tagLabel = labels.find((l) => l.startsWith(GITHUB_LABELS.TAG_PREFIX));
+  return tagLabel ? tagLabel.slice(GITHUB_LABELS.TAG_PREFIX.length) : undefined;
+}
+
+export function getAllStatusLabels(): string[] {
+  return [...ALL_STATUS_LABELS];
+}

package/src/server/adapters/github/mappers/task.ts

@@ -0,0 +1,37 @@
+import type { Priority, TaskStatus } from "../../types.js";
+import { GITHUB_LABELS } from "../types.js";
+
+const TASK_STATUS_LABEL_MAP: Record<TaskStatus, string | null> = {
+  PENDING: null,
+  IN_PROGRESS: GITHUB_LABELS.STATUS_IN_PROGRESS,
+  COMPLETED: null,
+};
+
+export function taskStatusToLabel(status: TaskStatus): string | null {
+  return TASK_STATUS_LABEL_MAP[status];
+}
+
+export function labelToTaskStatus(
+  labels: string[],
+  isClosed: boolean,
+): TaskStatus {
+  if (isClosed) return "COMPLETED";
+  if (labels.includes(GITHUB_LABELS.STATUS_IN_PROGRESS)) return "IN_PROGRESS";
+  return "PENDING";
+}
+
+const PRIORITY_LABEL_MAP: Record<Priority, string> = {
+  LOW: GITHUB_LABELS.PRIORITY_LOW,
+  MEDIUM: GITHUB_LABELS.PRIORITY_MEDIUM,
+  HIGH: GITHUB_LABELS.PRIORITY_HIGH,
+};
+
+export function priorityToLabel(priority: Priority): string {
+  return PRIORITY_LABEL_MAP[priority];
+}
+
+export function labelToPriority(labels: string[]): Priority {
+  if (labels.includes(GITHUB_LABELS.PRIORITY_HIGH)) return "HIGH";
+  if (labels.includes(GITHUB_LABELS.PRIORITY_LOW)) return "LOW";
+  return "MEDIUM";
+}

package/src/server/adapters/github/types.ts

@@ -0,0 +1,27 @@
+export interface GitHubConfig {
+  token: string;
+  owner: string;
+  repo: string;
+  projectId: string;
+  refPrefix: string;
+}
+
+export const GITHUB_LABELS = {
+  ENTITY_PRD: "flux:prd",
+  ENTITY_EPIC: "flux:epic",
+  ENTITY_TASK: "flux:task",
+
+  STATUS_DRAFT: "status:draft",
+  STATUS_PENDING_REVIEW: "status:pending-review",
+  STATUS_REVIEWED: "status:reviewed",
+  STATUS_APPROVED: "status:approved",
+  STATUS_BREAKDOWN_READY: "status:breakdown-ready",
+  STATUS_COMPLETED: "status:completed",
+  STATUS_IN_PROGRESS: "status:in-progress",
+
+  PRIORITY_LOW: "priority:low",
+  PRIORITY_MEDIUM: "priority:medium",
+  PRIORITY_HIGH: "priority:high",
+
+  TAG_PREFIX: "tag:",
+} as const;

package/src/server/adapters/types.ts

@@ -288,6 +288,6 @@ export interface CascadeResult {
  * Adapter configuration stored in project.json
  */
 export interface AdapterConfig {
-  type: "local" | "specflux" | "linear" | "notion";
+  type: "local" | "specflux" | "linear" | "notion" | "github";
   config?: Record<string, unknown>;
 }

package/src/server/index.ts

@@ -5,6 +5,7 @@ import { fluxProjectExists, initDb } from "./db/index.js";
 import {
   addCriteriaTool,
   addDependencyTool,
+  configureGithubTool,
   configureLinearTool,
   createEpicTool,
   createPrdTool,
@@ -50,6 +51,7 @@ const tools: ToolDefinition[] = [
   getStatsTool,
   getVersionTool,
   // Configuration tools
+  configureGithubTool,
   configureLinearTool,
   // Display tools
   renderStatusTool,

package/src/server/tools/__tests__/mcp-interface.test.ts

@@ -84,6 +84,12 @@ describe("MCP Interface", () => {
       expect(toolOption?.params?.vision).toBeDefined();
       expect(toolOption?.params?.adapter).toBeDefined();
     });
+
+    test("adapter param includes github option", () => {
+      const error = createProjectNotInitializedError("/cwd", "/root");
+      const toolOption = error.setup.options.find((o) => o.method === "tool");
+      expect(toolOption?.params?.adapter).toContain("github");
+    });
   });
 
   describe("registerTools", () => {