@cliangdev/flux-plugin 0.3.1 → 0.4.0

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

@@ -0,0 +1,422 @@
+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 SharedConfig {
+  owner: string;
+  repo: string;
+  projectId: string;
+  refPrefix: string;
+}
+
+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,
+): 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 },
+  );
+
+  return projectResult.createProjectV2.projectV2 as unknown as {
+    id: string;
+    url: string;
+  };
+}
+
+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;
+}): 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,
+    },
+  };
+
+  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}`,
+  );
+
+  const sharedConfig: SharedConfig = {
+    owner: params.owner,
+    repo: params.repo,
+    projectId: project.id,
+    refPrefix: params.refPrefix,
+  };
+
+  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,
+  });
+
+  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,
+  });
+
+  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,
+};

package/src/server/tools/index.ts

@@ -64,7 +64,7 @@ export function createProjectNotInitializedError(
           params: {
             name: "Project name (required)",
             vision: "Brief project description (required)",
-            adapter: "local | linear (default: local)",
+            adapter: "local | linear | github (default: local)",
           },
         },
       ],
@@ -140,6 +140,7 @@ export function registerTools(server: Server, tools: ToolDefinition[]) {
   });
 }
 
+export { configureGithubTool } from "./configure-github.js";
 export { configureLinearTool } from "./configure-linear.js";
 export { createEpicTool } from "./create-epic.js";
 export { createPrdTool } from "./create-prd.js";

package/src/server/tools/init-project.ts

@@ -48,7 +48,13 @@ function setupClaudeSettings(projectRoot: string): void {
   }
 }
 
-const adapterTypes = ["local", "specflux", "linear", "notion"] as const;
+const adapterTypes = [
+  "local",
+  "specflux",
+  "linear",
+  "notion",
+  "github",
+] as const;
 
 const inputSchema = z.object({
   name: z.string().min(1, "Project name is required"),
@@ -80,29 +86,37 @@ async function handler(input: unknown) {
   writeFileSync(config.projectJsonPath, JSON.stringify(projectJson, null, 2));
   config.clearCache();
 
-  initDb();
-
-  const projectId = generateId("proj");
-  const db = getDb();
-  insert(db, "projects", {
-    id: projectId,
-    name: parsed.name,
-    ref_prefix: refPrefix,
-  });
+  if (parsed.adapter === "local") {
+    initDb();
+    const projectId = generateId("proj");
+    const db = getDb();
+    insert(db, "projects", {
+      id: projectId,
+      name: parsed.name,
+      ref_prefix: refPrefix,
+    });
+  }
 
   setupClaudeSettings(config.projectRoot);
 
+  const nextStep =
+    parsed.adapter === "github"
+      ? "Run configure_github to connect your GitHub tracking repository."
+      : parsed.adapter === "linear"
+        ? "Run configure_linear to connect your Linear workspace."
+        : "Run /flux:prd to start planning.";
+
   return {
     success: true,
     project: projectJson,
-    message: `Flux project initialized. Run /flux:prd to start planning.`,
+    message: `Flux project initialized. ${nextStep}`,
   };
 }
 
 export const initProjectTool: ToolDefinition = {
   name: "init_project",
   description:
-    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|specflux|linear|notion, default 'local'). Creates .flux/ directory with project.json and SQLite database. Returns {success, project, message}. Fails if .flux/ already exists.",
+    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|linear|github, default 'local'). Creates .flux/ directory with project.json. For local adapter, also initializes SQLite database. For github or linear, run configure_github or configure_linear next. Returns {success, project, message}. Fails if .flux/ already exists.",
   inputSchema,
   handler,
 };