@cliangdev/flux-plugin 0.3.1 → 0.4.0-dev.38b2bd1

package/src/server/tools/__tests__/z-init-project.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+const TEST_DIR = `/tmp/flux-init-test-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+const FLUX_DIR = join(TEST_DIR, ".flux");
+process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+import { config } from "../../config.js";
+import { closeDb } from "../../db/index.js";
+import { initProjectTool } from "../init-project.js";
+
+describe("init_project", () => {
+  beforeEach(() => {
+    closeDb();
+    config.clearCache();
+    if (existsSync(FLUX_DIR)) {
+      rmSync(FLUX_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    closeDb();
+    config.clearCache();
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe("local adapter", () => {
+    test("creates .flux directory and project.json", async () => {
+      await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "local",
+      });
+
+      expect(existsSync(FLUX_DIR)).toBe(true);
+      expect(existsSync(join(FLUX_DIR, "project.json"))).toBe(true);
+    });
+
+    test("initializes SQLite database for local adapter", async () => {
+      await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "local",
+      });
+
+      expect(existsSync(join(FLUX_DIR, "flux.db"))).toBe(true);
+    });
+
+    test("returns planning message for local adapter", async () => {
+      const result = (await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+      })) as any;
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("/flux:prd");
+    });
+  });
+
+  describe("github adapter", () => {
+    test("creates .flux directory and project.json", async () => {
+      await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "github",
+      });
+
+      expect(existsSync(FLUX_DIR)).toBe(true);
+      expect(existsSync(join(FLUX_DIR, "project.json"))).toBe(true);
+    });
+
+    test("does not create SQLite database for github adapter", async () => {
+      await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "github",
+      });
+
+      expect(existsSync(join(FLUX_DIR, "flux.db"))).toBe(false);
+    });
+
+    test("project.json records adapter type as github", async () => {
+      const result = (await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "github",
+      })) as any;
+
+      expect(result.project.adapter.type).toBe("github");
+    });
+
+    test("returns configure_github next-step message", async () => {
+      const result = (await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "github",
+      })) as any;
+
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("configure_github");
+    });
+
+    test("fails if project already initialized", async () => {
+      await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "github",
+      });
+
+      await expect(
+        initProjectTool.handler({
+          name: "Test Project",
+          vision: "Test vision",
+          adapter: "github",
+        }),
+      ).rejects.toThrow(/already initialized/i);
+    });
+  });
+
+  describe("linear adapter", () => {
+    test("does not create SQLite database for linear adapter", async () => {
+      await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "linear",
+      });
+
+      expect(existsSync(join(FLUX_DIR, "flux.db"))).toBe(false);
+    });
+
+    test("returns configure_linear next-step message", async () => {
+      const result = (await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+        adapter: "linear",
+      })) as any;
+
+      expect(result.message).toContain("configure_linear");
+    });
+  });
+
+  describe("input validation", () => {
+    test("rejects missing name", async () => {
+      await expect(
+        initProjectTool.handler({ vision: "Test vision" }),
+      ).rejects.toThrow();
+    });
+
+    test("rejects missing vision", async () => {
+      await expect(
+        initProjectTool.handler({ name: "Test Project" }),
+      ).rejects.toThrow();
+    });
+
+    test("defaults to local adapter when not specified", async () => {
+      const result = (await initProjectTool.handler({
+        name: "Test Project",
+        vision: "Test vision",
+      })) as any;
+
+      expect(result.project.adapter.type).toBe("local");
+    });
+  });
+});

package/src/server/tools/configure-github.ts

@@ -0,0 +1,550 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { graphql } from "@octokit/graphql";
+import { Octokit } from "@octokit/rest";
+import { z } from "zod";
+import { GITHUB_LABELS } from "../adapters/github/types.js";
+import { clearAdapterCache } from "../adapters/index.js";
+import { config } from "../config.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  token: z.string().optional(),
+  owner: z.string(),
+  repo: z.string(),
+  ref_prefix: z.string().optional().default("FLUX"),
+  visibility: z.enum(["private", "public"]).optional().default("private"),
+});
+
+type ConfigureMode = "setup" | "join" | "update";
+
+interface StatusFieldConfig {
+  fieldId: string;
+  optionIds: Record<string, string>;
+}
+
+interface SharedConfig {
+  owner: string;
+  repo: string;
+  projectId: string;
+  refPrefix: string;
+  statusField?: StatusFieldConfig;
+}
+
+interface ConfigureResult {
+  mode: ConfigureMode;
+  board_url: string | null;
+  repo_url: string;
+  labels_created: number;
+}
+
+const LABEL_DEFINITIONS: Array<{ name: string; color: string }> = [
+  { name: GITHUB_LABELS.ENTITY_PRD, color: "0075ca" },
+  { name: GITHUB_LABELS.ENTITY_EPIC, color: "7057ff" },
+  { name: GITHUB_LABELS.ENTITY_TASK, color: "0e8a16" },
+  { name: GITHUB_LABELS.STATUS_DRAFT, color: "e4e669" },
+  { name: GITHUB_LABELS.STATUS_PENDING_REVIEW, color: "fbca04" },
+  { name: GITHUB_LABELS.STATUS_REVIEWED, color: "d4c5f9" },
+  { name: GITHUB_LABELS.STATUS_APPROVED, color: "0e8a16" },
+  { name: GITHUB_LABELS.STATUS_BREAKDOWN_READY, color: "1d76db" },
+  { name: GITHUB_LABELS.STATUS_COMPLETED, color: "0075ca" },
+  { name: GITHUB_LABELS.STATUS_IN_PROGRESS, color: "e99695" },
+  { name: GITHUB_LABELS.PRIORITY_LOW, color: "c5def5" },
+  { name: GITHUB_LABELS.PRIORITY_MEDIUM, color: "bfd4f2" },
+  { name: GITHUB_LABELS.PRIORITY_HIGH, color: "b60205" },
+];
+
+async function validateToken(octokit: Octokit): Promise<string> {
+  try {
+    const { data } = await octokit.users.getAuthenticated();
+    return data.login;
+  } catch (error: unknown) {
+    const err = error as { status?: number; message?: string };
+    const status = err.status ?? 0;
+    throw new Error(
+      `GitHub token validation failed (HTTP ${status}): ${err.message}. Ensure the token has 'repo' scope.`,
+    );
+  }
+}
+
+function detectUpdateMode(): 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" &&
+      Boolean(project?.adapter?.config?.owner)
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function fetchRemoteConfig(
+  octokit: Octokit,
+  owner: string,
+  repo: string,
+): Promise<SharedConfig | null> {
+  try {
+    const response = await octokit.request(
+      "GET /repos/{owner}/{repo}/contents/{path}",
+      {
+        owner,
+        repo,
+        path: ".flux/github-config.json",
+      },
+    );
+    const data = response.data as { content: string; encoding: string };
+    const decoded = Buffer.from(data.content, "base64").toString("utf-8");
+    return JSON.parse(decoded) as SharedConfig;
+  } catch (error: unknown) {
+    const status = (error as { status?: number }).status;
+    if (status === 404 || status === 403) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function detectMode(
+  octokit: Octokit,
+  owner: string,
+  repo: string,
+): Promise<{ mode: ConfigureMode; remoteConfig: SharedConfig | null }> {
+  if (detectUpdateMode()) {
+    return { mode: "update", remoteConfig: null };
+  }
+
+  const remoteConfig = await fetchRemoteConfig(octokit, owner, repo);
+  if (remoteConfig) {
+    return { mode: "join", remoteConfig };
+  }
+
+  return { mode: "setup", remoteConfig: null };
+}
+
+async function ensureRepo(
+  octokit: Octokit,
+  owner: string,
+  repo: string,
+  visibility: "private" | "public",
+): Promise<string> {
+  try {
+    const { data } = await octokit.repos.get({ owner, repo });
+    return data.html_url;
+  } catch (error: unknown) {
+    if ((error as { status?: number }).status !== 404) throw error;
+  }
+
+  const { data } = await octokit.repos.createForAuthenticatedUser({
+    name: repo,
+    private: visibility === "private",
+    auto_init: true,
+  });
+  return data.html_url;
+}
+
+async function ensureLabels(
+  octokit: Octokit,
+  owner: string,
+  repo: string,
+): Promise<number> {
+  const { data: existingLabels } = await octokit.issues.listLabelsForRepo({
+    owner,
+    repo,
+  });
+  const existingNames = new Set(existingLabels.map((l) => l.name));
+
+  let created = 0;
+  for (const label of LABEL_DEFINITIONS) {
+    if (!existingNames.has(label.name)) {
+      await octokit.issues.createLabel({
+        owner,
+        repo,
+        name: label.name,
+        color: label.color,
+      });
+      created++;
+    }
+  }
+  return created;
+}
+
+async function createProjectsBoard(
+  gql: (
+    query: string,
+    vars: Record<string, unknown>,
+  ) => Promise<Record<string, Record<string, unknown>>>,
+  ownerLogin: string,
+  title: string,
+  repoOwner: string,
+  repoName: string,
+): Promise<{ id: string; url: string }> {
+  const ownerResult = await gql(
+    `query GetOwnerId($login: String!) { user(login: $login) { id } }`,
+    { login: ownerLogin },
+  );
+  const ownerId = ownerResult.user.id;
+
+  const projectResult = await gql(
+    `mutation CreateProject($ownerId: ID!, $title: String!) {
+      createProjectV2(input: { ownerId: $ownerId, title: $title }) {
+        projectV2 { id url }
+      }
+    }`,
+    { ownerId, title },
+  );
+
+  const project = projectResult.createProjectV2.projectV2 as unknown as {
+    id: string;
+    url: string;
+  };
+
+  const repoResult = await gql(
+    `query GetRepoId($owner: String!, $name: String!) {
+      repository(owner: $owner, name: $name) { id }
+    }`,
+    { owner: repoOwner, name: repoName },
+  );
+  const repositoryId = repoResult.repository.id;
+
+  await gql(
+    `mutation LinkProject($projectId: ID!, $repositoryId: ID!) {
+      linkProjectV2ToRepository(input: { projectId: $projectId, repositoryId: $repositoryId }) {
+        repository { id }
+      }
+    }`,
+    { projectId: project.id, repositoryId },
+  );
+
+  return project;
+}
+
+const BOARD_STATUS_OPTIONS: Array<{
+  name: string;
+  color: string;
+  description: string;
+}> = [
+  { name: "Draft", color: "GRAY", description: "" },
+  { name: "Pending Review", color: "YELLOW", description: "" },
+  { name: "Reviewed", color: "PURPLE", description: "" },
+  { name: "Approved", color: "GREEN", description: "" },
+  { name: "Breakdown Ready", color: "BLUE", description: "" },
+  { name: "In Progress", color: "ORANGE", description: "" },
+  { name: "Completed", color: "GREEN", description: "" },
+];
+
+async function configureStatusField(
+  gql: (
+    query: string,
+    vars: Record<string, unknown>,
+  ) => Promise<Record<string, Record<string, unknown>>>,
+  projectId: string,
+): Promise<StatusFieldConfig | undefined> {
+  const result = await gql(
+    `query GetProjectFields($projectId: ID!) {
+      node(id: $projectId) {
+        ... on ProjectV2 {
+          fields(first: 20) {
+            nodes {
+              ... on ProjectV2SingleSelectField {
+                id
+                name
+                options { id name }
+              }
+            }
+          }
+        }
+      }
+    }`,
+    { projectId },
+  );
+
+  const fields = (
+    result.node as {
+      fields: {
+        nodes: Array<{
+          id?: string;
+          name?: string;
+          options?: Array<{ id: string; name: string }>;
+        }>;
+      };
+    }
+  ).fields.nodes;
+
+  const statusField = fields.find(
+    (f) => f.name === "Status" && f.options && f.id,
+  );
+  if (!statusField?.id) return undefined;
+
+  const updateResult = await gql(
+    `mutation UpdateStatusOptions($fieldId: ID!, $options: [ProjectV2SingleSelectFieldOptionInput!]!) {
+      updateProjectV2Field(input: {
+        fieldId: $fieldId
+        singleSelectOptions: $options
+      }) {
+        projectV2Field {
+          ... on ProjectV2SingleSelectField {
+            options { id name }
+          }
+        }
+      }
+    }`,
+    {
+      fieldId: statusField.id,
+      options: BOARD_STATUS_OPTIONS,
+    },
+  );
+
+  const updatedOptions = (
+    updateResult.updateProjectV2Field as {
+      projectV2Field: {
+        options: Array<{ id: string; name: string }>;
+      };
+    }
+  ).projectV2Field.options;
+
+  const optionIds: Record<string, string> = {};
+  for (const opt of updatedOptions) {
+    optionIds[opt.name] = opt.id;
+  }
+
+  return { fieldId: statusField.id, optionIds };
+}
+
+async function commitSharedConfig(
+  octokit: Octokit,
+  owner: string,
+  repo: string,
+  sharedConfig: SharedConfig,
+): Promise<void> {
+  const content = Buffer.from(JSON.stringify(sharedConfig, null, 2)).toString(
+    "base64",
+  );
+  await octokit.request("PUT /repos/{owner}/{repo}/contents/{path}", {
+    owner,
+    repo,
+    path: ".flux/github-config.json",
+    message: "chore: add Flux shared config",
+    content,
+  });
+}
+
+function writeProjectJson(params: {
+  token: string;
+  owner: string;
+  repo: string;
+  projectId: string;
+  refPrefix: string;
+  statusField?: StatusFieldConfig;
+}): void {
+  const projectJsonPath = config.projectJsonPath;
+  const existing = existsSync(projectJsonPath)
+    ? JSON.parse(readFileSync(projectJsonPath, "utf-8"))
+    : {};
+
+  existing.adapter = {
+    type: "github",
+    config: {
+      token: params.token,
+      owner: params.owner,
+      repo: params.repo,
+      projectId: params.projectId,
+      refPrefix: params.refPrefix,
+      ...(params.statusField ? { statusField: params.statusField } : {}),
+    },
+  };
+
+  writeFileSync(projectJsonPath, JSON.stringify(existing, null, 2));
+}
+
+async function runSetup(params: {
+  octokit: Octokit;
+  gql: (
+    query: string,
+    vars: Record<string, unknown>,
+  ) => Promise<Record<string, Record<string, unknown>>>;
+  ownerLogin: string;
+  owner: string;
+  repo: string;
+  refPrefix: string;
+  visibility: "private" | "public";
+  token: string;
+}): Promise<ConfigureResult> {
+  const repoUrl = await ensureRepo(
+    params.octokit,
+    params.owner,
+    params.repo,
+    params.visibility,
+  );
+  const labelsCreated = await ensureLabels(
+    params.octokit,
+    params.owner,
+    params.repo,
+  );
+  const project = await createProjectsBoard(
+    params.gql,
+    params.ownerLogin,
+    `Flux: ${params.repo}`,
+    params.owner,
+    params.repo,
+  );
+
+  const statusField = await configureStatusField(params.gql, project.id);
+
+  const sharedConfig: SharedConfig = {
+    owner: params.owner,
+    repo: params.repo,
+    projectId: project.id,
+    refPrefix: params.refPrefix,
+    ...(statusField ? { statusField } : {}),
+  };
+
+  await commitSharedConfig(
+    params.octokit,
+    params.owner,
+    params.repo,
+    sharedConfig,
+  );
+
+  writeProjectJson({
+    token: params.token,
+    owner: params.owner,
+    repo: params.repo,
+    projectId: project.id,
+    refPrefix: params.refPrefix,
+    statusField,
+  });
+
+  return {
+    mode: "setup",
+    board_url: project.url,
+    repo_url: repoUrl,
+    labels_created: labelsCreated,
+  };
+}
+
+async function runJoin(params: {
+  token: string;
+  owner: string;
+  repo: string;
+  remoteConfig: SharedConfig;
+}): Promise<ConfigureResult> {
+  writeProjectJson({
+    token: params.token,
+    owner: params.remoteConfig.owner,
+    repo: params.remoteConfig.repo,
+    projectId: params.remoteConfig.projectId,
+    refPrefix: params.remoteConfig.refPrefix,
+    statusField: params.remoteConfig.statusField,
+  });
+
+  const repoUrl = `https://github.com/${params.remoteConfig.owner}/${params.remoteConfig.repo}`;
+
+  return {
+    mode: "join",
+    board_url: null,
+    repo_url: repoUrl,
+    labels_created: 0,
+  };
+}
+
+async function runUpdate(params: {
+  token: string;
+  owner: string;
+  repo: string;
+}): Promise<ConfigureResult> {
+  const projectJsonPath = config.projectJsonPath;
+  const existing = JSON.parse(readFileSync(projectJsonPath, "utf-8"));
+  existing.adapter.config.token = params.token;
+  writeFileSync(projectJsonPath, JSON.stringify(existing, null, 2));
+
+  const repoUrl = `https://github.com/${params.owner}/${params.repo}`;
+
+  return {
+    mode: "update",
+    board_url: null,
+    repo_url: repoUrl,
+    labels_created: 0,
+  };
+}
+
+function resolveToken(inputToken?: string): string {
+  if (inputToken) return inputToken;
+  const envToken = process.env.FLUX_GITHUB_TOKEN;
+  if (envToken) return envToken;
+  throw new Error(
+    "GitHub token not found. Set the FLUX_GITHUB_TOKEN environment variable " +
+      "(recommended: export FLUX_GITHUB_TOKEN=ghp_... in your shell before starting Claude Code), " +
+      "or pass it via the token parameter.",
+  );
+}
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const token = resolveToken(parsed.token);
+
+  const octokit = new Octokit({ auth: token });
+  const gqlWithAuth = graphql.defaults({
+    headers: { authorization: `token ${token}` },
+  });
+
+  const ownerLogin = await validateToken(octokit);
+
+  const { mode, remoteConfig } = await detectMode(
+    octokit,
+    parsed.owner,
+    parsed.repo,
+  );
+
+  let result: ConfigureResult;
+
+  if (mode === "update") {
+    result = await runUpdate({
+      token,
+      owner: parsed.owner,
+      repo: parsed.repo,
+    });
+  } else if (mode === "join" && remoteConfig) {
+    result = await runJoin({
+      token,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      remoteConfig,
+    });
+  } else {
+    result = await runSetup({
+      octokit,
+      gql: gqlWithAuth,
+      ownerLogin,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      refPrefix: parsed.ref_prefix,
+      visibility: parsed.visibility,
+      token,
+    });
+  }
+
+  clearAdapterCache();
+  config.clearCache();
+
+  return result;
+}
+
+export const configureGithubTool: ToolDefinition = {
+  name: "configure_github",
+  description:
+    "Configure GitHub integration for the Flux project. " +
+    "Automatically detects the correct mode: " +
+    "'setup' (first-time: creates tracking repo, labels, Projects v2 board, commits shared config), " +
+    "'join' (remote .flux/github-config.json exists: reads shared config, writes local project.json), " +
+    "'update' (local project.json already has github adapter: rotates token only). " +
+    "Required: owner (GitHub username/org), repo (tracking repo name). " +
+    "Token resolution order: 1) FLUX_GITHUB_TOKEN environment variable (recommended — set with 'export FLUX_GITHUB_TOKEN=ghp_...' before starting Claude Code, never paste tokens in chat), " +
+    "2) token parameter (avoid — visible in chat history). " +
+    "To create a PAT: github.com → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token → select 'repo' scope. " +
+    "Optional: ref_prefix (default 'FLUX'), visibility (default 'private'). " +
+    "Returns {mode, board_url, repo_url, labels_created}.",
+  inputSchema,
+  handler,
+};