tlc-claude-code 2.4.9 → 2.5.0

package/server/lib/github/gh-projects.js

@@ -0,0 +1,594 @@
+/**
+ * GitHub Projects V2 GraphQL Client
+ *
+ * Manages GitHub Projects V2 via GraphQL — discover project schema,
+ * add items, set field values.
+ *
+ * All functions accept `{ exec }` for dependency injection (defaults to
+ * child_process.execSync). GraphQL calls go through `gh api graphql`.
+ *
+ * Error handling: structured { error, code } returns, never throws.
+ * Every catch block logs with context.
+ *
+ * @module gh-projects
+ */
+
+const { execSync } = require('child_process');
+
+// ---------------------------------------------------------------------------
+// Error codes
+// ---------------------------------------------------------------------------
+
+const ERROR_CODES = {
+  GH_NOT_FOUND: 'GH_NOT_FOUND',
+  GH_AUTH_REQUIRED: 'GH_AUTH_REQUIRED',
+  GH_SCOPE_MISSING: 'GH_SCOPE_MISSING',
+  GH_PROJECT_NOT_FOUND: 'GH_PROJECT_NOT_FOUND',
+  GH_PERMISSION_DENIED: 'GH_PERMISSION_DENIED',
+  GH_API_ERROR: 'GH_API_ERROR',
+};
+
+// ---------------------------------------------------------------------------
+// Error classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify an exec error into a structured error response.
+ * @param {Error} err - Error thrown by exec
+ * @param {string} context - Description of what was being attempted
+ * @returns {{ error: string, code: string }}
+ */
+function classifyError(err, context) {
+  const stderr = err.stderr ? err.stderr.toString() : '';
+  const message = err.message || '';
+  const combined = `${stderr} ${message}`.toLowerCase();
+
+  if (combined.includes('command not found') || combined.includes('not found: gh') || combined.includes('enoent')) {
+    const errorMsg = `gh CLI not found. Install from https://cli.github.com/ (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_NOT_FOUND };
+  }
+
+  if (combined.includes('gh auth login') || combined.includes('not logged in') || combined.includes('authentication')) {
+    const errorMsg = `gh CLI not authenticated. Run: gh auth login (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_AUTH_REQUIRED };
+  }
+
+  if (combined.includes('scope') && combined.includes('project')) {
+    const errorMsg = `Missing 'project' scope. Run: gh auth refresh -s project (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_SCOPE_MISSING };
+  }
+
+  if (combined.includes('not accessible') || combined.includes('permission') || combined.includes('forbidden')) {
+    const errorMsg = `Permission denied: ${stderr.trim() || message} (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_PERMISSION_DENIED };
+  }
+
+  const errorMsg = `GitHub API error: ${stderr.trim() || message} (context: ${context})`;
+  console.error(`[gh-projects] ${errorMsg}`);
+  return { error: errorMsg, code: ERROR_CODES.GH_API_ERROR };
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL execution helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a GraphQL query/mutation via `gh api graphql`.
+ * @param {string} query - GraphQL query string
+ * @param {Function} exec - execSync-compatible function
+ * @returns {object} Parsed JSON response
+ * @throws {Error} On exec failure (caller must catch)
+ */
+function runGraphQL(query, exec) {
+  // Escape single quotes in the query for shell safety
+  const escaped = query.replace(/'/g, "'\\''");
+  const cmd = `gh api graphql -f query='${escaped}'`;
+  const output = exec(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+  return JSON.parse(output.toString());
+}
+
+/**
+ * Escape a string for safe embedding in a GraphQL string literal.
+ * Escapes double quotes, backslashes, and newlines.
+ * @param {string} str
+ * @returns {string}
+ */
+function gqlEscape(str) {
+  if (str == null) return '';
+  return String(str).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+
+// ---------------------------------------------------------------------------
+// Field extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract normalized field list from a project node.
+ * @param {object} projectNode - Raw project node from GraphQL
+ * @returns {Array<{ id: string, name: string, type: string, options?: Array<{ id: string, name: string }> }>}
+ */
+function extractFields(projectNode) {
+  if (!projectNode.fields || !projectNode.fields.nodes) return [];
+
+  return projectNode.fields.nodes.map(node => {
+    const typename = node.__typename || '';
+    if (typename === 'ProjectV2SingleSelectField' || (node.options && Array.isArray(node.options))) {
+      return {
+        id: node.id,
+        name: node.name,
+        type: 'single_select',
+        options: (node.options || []).map(o => ({ id: o.id, name: o.name })),
+      };
+    }
+    return {
+      id: node.id,
+      name: node.name,
+      type: 'field',
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// discoverProject
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover a GitHub Project V2 by title.
+ * Queries organization or user projects depending on which is provided.
+ *
+ * @param {object} params
+ * @param {string} [params.org] - Organization login (mutually exclusive with user)
+ * @param {string} [params.user] - User login (mutually exclusive with org)
+ * @param {string} params.projectTitle - Project title to find
+ * @param {Function} [params.exec] - execSync-compatible function (DI)
+ * @returns {{ projectId: string, title: string, number: number, fields: Array } | { error: string, code: string }}
+ */
+function discoverProject({ org, user, projectTitle, exec = execSync }) {
+  const owner = org || user;
+  const ownerType = org ? 'organization' : 'user';
+  const context = `discoverProject(${ownerType}=${owner}, title="${projectTitle}")`;
+
+  const query = `
+    query {
+      ${ownerType}(login: "${gqlEscape(owner)}") {
+        projectsV2(first: 20) {
+          nodes {
+            id title number
+            fields(first: 30) {
+              nodes {
+                ... on ProjectV2SingleSelectField {
+                  __typename id name options { id name }
+                }
+                ... on ProjectV2Field {
+                  __typename id name
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `;
+
+  let data;
+  try {
+    data = runGraphQL(query, exec);
+  } catch (err) {
+    return classifyError(err, context);
+  }
+
+  // Navigate to the projects list
+  const ownerData = data.data[ownerType];
+  if (!ownerData || !ownerData.projectsV2 || !ownerData.projectsV2.nodes) {
+    console.error(`[gh-projects] No projects found for ${ownerType}=${owner}`);
+    return {
+      error: `No projects found for ${ownerType} "${owner}"`,
+      code: ERROR_CODES.GH_PROJECT_NOT_FOUND,
+    };
+  }
+
+  const nodes = ownerData.projectsV2.nodes;
+  const project = nodes.find(p => p.title === projectTitle);
+
+  if (!project) {
+    const available = nodes.map(p => p.title).join(', ') || 'none';
+    const errorMsg = `Project "${projectTitle}" not found for ${ownerType} "${owner}". Available: ${available}`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_PROJECT_NOT_FOUND };
+  }
+
+  return {
+    projectId: project.id,
+    title: project.title,
+    number: project.number,
+    fields: extractFields(project),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// addItemToProject
+// ---------------------------------------------------------------------------
+
+/**
+ * Add an issue or PR to a Project V2.
+ *
+ * @param {object} params
+ * @param {string} params.projectId - Project node ID (PVT_xxx)
+ * @param {string} params.contentId - Issue or PR node ID (I_xxx or PR_xxx)
+ * @param {Function} [params.exec] - execSync-compatible function (DI)
+ * @returns {{ itemId: string } | { error: string, code: string }}
+ */
+function addItemToProject({ projectId, contentId, exec = execSync }) {
+  const context = `addItemToProject(project=${projectId}, content=${contentId})`;
+
+  const query = `
+    mutation {
+      addProjectV2ItemById(input: { projectId: "${gqlEscape(projectId)}", contentId: "${gqlEscape(contentId)}" }) {
+        item { id }
+      }
+    }
+  `;
+
+  let data;
+  try {
+    data = runGraphQL(query, exec);
+  } catch (err) {
+    return classifyError(err, context);
+  }
+
+  try {
+    const itemId = data.data.addProjectV2ItemById.item.id;
+    return { itemId };
+  } catch (parseErr) {
+    const errorMsg = `Failed to parse addItem response: ${JSON.stringify(data)} (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_API_ERROR };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// setFieldValue
+// ---------------------------------------------------------------------------
+
+/**
+ * Set a single-select field value on a project item.
+ *
+ * @param {object} params
+ * @param {string} params.projectId - Project node ID
+ * @param {string} params.itemId - Item node ID (PVTI_xxx)
+ * @param {string} params.fieldId - Field node ID (PVTSSF_xxx)
+ * @param {string} params.optionId - Option ID for the single-select value
+ * @param {Function} [params.exec] - execSync-compatible function (DI)
+ * @returns {{ success: true } | { error: string, code: string }}
+ */
+function setFieldValue({ projectId, itemId, fieldId, optionId, exec = execSync }) {
+  const context = `setFieldValue(project=${projectId}, item=${itemId}, field=${fieldId}, option=${optionId})`;
+
+  const query = `
+    mutation {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: "${gqlEscape(projectId)}"
+        itemId: "${gqlEscape(itemId)}"
+        fieldId: "${gqlEscape(fieldId)}"
+        value: { singleSelectOptionId: "${gqlEscape(optionId)}" }
+      }) {
+        projectV2Item { id }
+      }
+    }
+  `;
+
+  try {
+    runGraphQL(query, exec);
+    return { success: true };
+  } catch (err) {
+    return classifyError(err, context);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// createFieldOption
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new option on a single-select field (e.g., add a Sprint option).
+ * Requires admin permission on the project.
+ *
+ * @param {object} params
+ * @param {string} params.projectId - Project node ID
+ * @param {string} params.fieldId - Field node ID (PVTSSF_xxx)
+ * @param {string} params.name - Option name to create
+ * @param {Function} [params.exec] - execSync-compatible function (DI)
+ * @returns {{ optionId: string } | { error: string, code: string }}
+ */
+function createFieldOption({ projectId, fieldId, name, exec = execSync }) {
+  const context = `createFieldOption(project=${projectId}, field=${fieldId}, name="${name}")`;
+
+  const query = `
+    mutation {
+      createProjectV2FieldOption(input: {
+        projectId: "${gqlEscape(projectId)}"
+        fieldId: "${gqlEscape(fieldId)}"
+        name: "${gqlEscape(name)}"
+      }) {
+        projectV2Field {
+          ... on ProjectV2SingleSelectField {
+            options { id name }
+          }
+        }
+      }
+    }
+  `;
+
+  let data;
+  try {
+    data = runGraphQL(query, exec);
+  } catch (err) {
+    return classifyError(err, context);
+  }
+
+  try {
+    const options = data.data.createProjectV2FieldOption.projectV2Field.options;
+    const created = options.find(o => o.name === name);
+    if (!created) {
+      const errorMsg = `Option "${name}" was not found in response after creation (context: ${context})`;
+      console.error(`[gh-projects] ${errorMsg}`);
+      return { error: errorMsg, code: ERROR_CODES.GH_API_ERROR };
+    }
+    return { optionId: created.id };
+  } catch (parseErr) {
+    const errorMsg = `Failed to parse createFieldOption response: ${JSON.stringify(data)} (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_API_ERROR };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// getProjectItems
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch items from a Project V2 with their field values.
+ *
+ * @param {object} params
+ * @param {string} params.projectId - Project node ID
+ * @param {number} [params.first=50] - Number of items to fetch
+ * @param {Function} [params.exec] - execSync-compatible function (DI)
+ * @returns {Array<{ itemId, contentId, contentType, title, fieldValues }> | { error: string, code: string }}
+ */
+function getProjectItems({ projectId, first = 50, exec = execSync }) {
+  const context = `getProjectItems(project=${projectId}, first=${first})`;
+
+  const query = `
+    query {
+      node(id: "${gqlEscape(projectId)}") {
+        ... on ProjectV2 {
+          items(first: ${Number(first) || 50}) {
+            nodes {
+              id
+              content {
+                ... on Issue { __typename id title }
+                ... on PullRequest { __typename id title }
+                ... on DraftIssue { __typename id title }
+              }
+              fieldValues(first: 20) {
+                nodes {
+                  ... on ProjectV2ItemFieldTextValue { __typename text field { name } }
+                  ... on ProjectV2ItemFieldSingleSelectValue { __typename name field { name } }
+                  ... on ProjectV2ItemFieldNumberValue { __typename number field { name } }
+                  ... on ProjectV2ItemFieldDateValue { __typename date field { name } }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  `;
+
+  let data;
+  try {
+    data = runGraphQL(query, exec);
+  } catch (err) {
+    return classifyError(err, context);
+  }
+
+  try {
+    const items = data.data.node.items.nodes;
+    return items.map(item => {
+      const content = item.content || {};
+      const fieldValues = {};
+
+      if (item.fieldValues && item.fieldValues.nodes) {
+        for (const fv of item.fieldValues.nodes) {
+          if (!fv || !fv.field) continue;
+          const fieldName = fv.field.name;
+          const typename = fv.__typename || '';
+
+          if (typename === 'ProjectV2ItemFieldSingleSelectValue') {
+            fieldValues[fieldName] = fv.name;
+          } else if (typename === 'ProjectV2ItemFieldTextValue') {
+            fieldValues[fieldName] = fv.text;
+          } else if (typename === 'ProjectV2ItemFieldNumberValue') {
+            fieldValues[fieldName] = fv.number;
+          } else if (typename === 'ProjectV2ItemFieldDateValue') {
+            fieldValues[fieldName] = fv.date;
+          }
+        }
+      }
+
+      return {
+        itemId: item.id,
+        contentId: content.id || null,
+        contentType: content.__typename || null,
+        title: content.title || null,
+        fieldValues,
+      };
+    });
+  } catch (parseErr) {
+    const errorMsg = `Failed to parse getProjectItems response: ${parseErr.message} (context: ${context})`;
+    console.error(`[gh-projects] ${errorMsg}`);
+    return { error: errorMsg, code: ERROR_CODES.GH_API_ERROR };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a field by name in the fields array (case-insensitive).
+ *
+ * @param {Array<{ id, name, type, options? }>} fields - Fields array from discoverProject
+ * @param {string} name - Field name to find
+ * @returns {{ id, name, type, options? } | null}
+ */
+function findFieldByName(fields, name) {
+  if (!fields || !name) return null;
+  const lower = name.toLowerCase();
+  return fields.find(f => f.name.toLowerCase() === lower) || null;
+}
+
+/**
+ * Find an option by name in a field (case-insensitive).
+ *
+ * @param {{ options?: Array<{ id, name }> }} field - Field object with options
+ * @param {string} optionName - Option name to find
+ * @returns {{ id, name } | null}
+ */
+function findOptionByName(field, optionName) {
+  if (!field || !field.options || !optionName) return null;
+  const lower = optionName.toLowerCase();
+  return field.options.find(o => o.name.toLowerCase() === lower) || null;
+}
+
+// ---------------------------------------------------------------------------
+// createProjectsClient (factory with caching)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Projects V2 client that discovers the project once and caches
+ * the schema for the lifetime of the client.
+ *
+ * @param {object} params
+ * @param {string} [params.org] - Organization login
+ * @param {string} [params.user] - User login
+ * @param {string} params.projectTitle - Project title
+ * @param {Function} [params.exec] - execSync-compatible function (DI)
+ * @returns {object} Client with addItem, setField, createOption, getItems, findField, findOption, getProjectInfo
+ */
+function createProjectsClient({ org, user, projectTitle, exec = execSync }) {
+  let cached = null;
+  let discoveryError = null;
+
+  function ensureDiscovered() {
+    if (cached) return cached;
+    if (discoveryError) return null;
+
+    const result = discoverProject({ org, user, projectTitle, exec });
+    if (result.error) {
+      discoveryError = result;
+      console.error(`[gh-projects] Client discovery failed: ${result.error}`);
+      return null;
+    }
+
+    cached = result;
+    return cached;
+  }
+
+  return {
+    /**
+     * Get discovered project info (triggers discovery if needed).
+     * @returns {{ projectId, title, number, fields } | { error, code }}
+     */
+    getProjectInfo() {
+      const project = ensureDiscovered();
+      if (!project) return discoveryError;
+      return { projectId: project.projectId, title: project.title, number: project.number, fields: project.fields };
+    },
+
+    /**
+     * Add an issue/PR to the project.
+     * @param {{ contentId: string }} params
+     * @returns {{ itemId } | { error, code }}
+     */
+    addItem({ contentId }) {
+      const project = ensureDiscovered();
+      if (!project) return discoveryError;
+      return addItemToProject({ projectId: project.projectId, contentId, exec });
+    },
+
+    /**
+     * Set a single-select field value on a project item.
+     * @param {{ itemId: string, fieldId: string, optionId: string }} params
+     * @returns {{ success: true } | { error, code }}
+     */
+    setField({ itemId, fieldId, optionId }) {
+      const project = ensureDiscovered();
+      if (!project) return discoveryError;
+      return setFieldValue({ projectId: project.projectId, itemId, fieldId, optionId, exec });
+    },
+
+    /**
+     * Create a new option on a single-select field.
+     * @param {{ fieldId: string, name: string }} params
+     * @returns {{ optionId } | { error, code }}
+     */
+    createOption({ fieldId, name }) {
+      const project = ensureDiscovered();
+      if (!project) return discoveryError;
+      return createFieldOption({ projectId: project.projectId, fieldId, name, exec });
+    },
+
+    /**
+     * Get project items with field values.
+     * @param {{ first?: number }} [params]
+     * @returns {Array | { error, code }}
+     */
+    getItems({ first } = {}) {
+      const project = ensureDiscovered();
+      if (!project) return discoveryError;
+      return getProjectItems({ projectId: project.projectId, first, exec });
+    },
+
+    /**
+     * Find a field by name (case-insensitive) in cached schema.
+     * @param {string} name
+     * @returns {{ id, name, type, options? } | null}
+     */
+    findField(name) {
+      const project = ensureDiscovered();
+      if (!project) return null;
+      return findFieldByName(project.fields, name);
+    },
+
+    /**
+     * Find an option by name in a field (case-insensitive).
+     * @param {{ options?: Array }} field
+     * @param {string} optionName
+     * @returns {{ id, name } | null}
+     */
+    findOption(field, optionName) {
+      return findOptionByName(field, optionName);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  discoverProject,
+  addItemToProject,
+  setFieldValue,
+  createFieldOption,
+  getProjectItems,
+  findFieldByName,
+  findOptionByName,
+  createProjectsClient,
+  ERROR_CODES,
+};