tlc-claude-code 2.4.10 → 2.6.0

package/server/lib/github/config.js

@@ -0,0 +1,458 @@
+/**
+ * GitHub Config — configuration management, setup detection, and offline queue
+ * Phase 97 Task 5
+ *
+ * All functions accept `{ fs }` for dependency injection,
+ * defaulting to the Node.js `fs` module.
+ *
+ * Error handling: no silent failures. Every catch logs with context or rethrows.
+ *
+ * @module github/config
+ */
+
+const nodeFs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const TLC_JSON = '.tlc.json';
+const QUEUE_DIR = '.tlc';
+const QUEUE_FILE = '.github-sync-queue.json';
+
+/**
+ * Resolve the .tlc.json path for a project directory.
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function tlcJsonPath(projectDir) {
+  return path.join(projectDir, TLC_JSON);
+}
+
+/**
+ * Resolve the sync queue file path.
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function queueFilePath(projectDir) {
+  return path.join(projectDir, QUEUE_DIR, QUEUE_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// getDefaultConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the default GitHub integration config object.
+ * @returns {object}
+ */
+function getDefaultConfig() {
+  return {
+    autoSync: true,
+    phasePrefix: 'Phase',
+    sprintField: 'Sprint',
+    statusField: 'Status',
+    statusMapping: {
+      todo: 'Backlog',
+      in_progress: 'In progress',
+      in_review: 'In review',
+      done: 'Done',
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// loadGitHubConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Read `.tlc.json` from projectDir and return the `github` section.
+ * Validates required fields and collects warnings.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} [options]
+ * @param {object} [options.fs] - Injected fs module
+ * @returns {{ config: object|null, warnings: string[] }}
+ */
+function loadGitHubConfig(projectDir, { fs = nodeFs } = {}) {
+  const filePath = tlcJsonPath(projectDir);
+  const warnings = [];
+
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return { config: null, warnings: [] };
+    }
+    console.error(`[TLC] loadGitHubConfig: failed to read ${filePath}: ${err.message}`);
+    throw err;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`[TLC] loadGitHubConfig: invalid JSON in ${filePath}: ${err.message}`);
+    return { config: null, warnings: [`Invalid JSON in ${TLC_JSON}: ${err.message}`] };
+  }
+
+  if (!parsed.github) {
+    return { config: null, warnings: [] };
+  }
+
+  const config = parsed.github;
+
+  // Validate expected fields
+  if (!config.project) {
+    warnings.push('Missing "project" field in github config — GitHub Projects integration will not work');
+  }
+
+  return { config, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// isGitHubEnabled
+// ---------------------------------------------------------------------------
+
+/**
+ * Quick synchronous check: does `.tlc.json` have `github.autoSync` set to true?
+ * Designed to be fast (<1ms). Returns false on any error.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} [options]
+ * @param {object} [options.fs] - Injected fs module
+ * @returns {boolean}
+ */
+function isGitHubEnabled(projectDir, { fs = nodeFs } = {}) {
+  const filePath = tlcJsonPath(projectDir);
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      return false;
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return parsed.github?.autoSync === true;
+  } catch (err) {
+    console.error(`[TLC] isGitHubEnabled: error reading ${filePath}: ${err.message}`);
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// detectAndSuggestConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-detection flow for `/tlc:issues setup`.
+ *
+ * 1. Calls ghClient.detectRepo() to get owner/repo
+ * 2. Calls ghClient.checkAuth() to verify auth and scopes
+ * 3. If missing `project` scope, returns `{ needsScope, command }`
+ * 4. Tries to find a matching GitHub Project (by repo name or org)
+ * 5. Returns `{ owner, repo, project, fields, suggestedConfig }`
+ *
+ * @param {object} params
+ * @param {object} params.ghClient - GitHub client (detectRepo, checkAuth)
+ * @param {object} params.ghProjects - GitHub Projects client (discoverProject)
+ * @param {string} params.projectDir - Absolute path to the project root
+ * @param {object} [params.fs] - Injected fs module
+ * @returns {object} Detection result
+ */
+function detectAndSuggestConfig({ ghClient, ghProjects, projectDir, fs = nodeFs }) {
+  // Step 1: Detect repo
+  const repoInfo = ghClient.detectRepo();
+  if (!repoInfo) {
+    return { error: 'Could not detect a GitHub repo in this directory. Run from a git repository with a GitHub remote.' };
+  }
+
+  const { owner, repo } = repoInfo;
+
+  // Step 2: Check auth + scopes
+  const authResult = ghClient.checkAuth();
+  if (!authResult.authenticated) {
+    return { error: `GitHub CLI not authenticated: ${authResult.error || 'unknown'}`, code: authResult.code };
+  }
+
+  const scopes = authResult.scopes || [];
+  if (!scopes.includes('project')) {
+    return {
+      needsScope: true,
+      command: 'gh auth refresh -s project',
+      owner,
+      repo,
+      message: 'Missing "project" scope. Run the command below to add it.',
+    };
+  }
+
+  // Step 3: Try to discover a matching GitHub Project
+  let project = null;
+  let fields = [];
+
+  // Try by org first, then by user
+  const discovered = ghProjects.discoverProject({ org: owner, projectTitle: repo });
+  if (discovered && !discovered.error) {
+    project = discovered;
+    fields = discovered.fields || [];
+  } else {
+    // Try as user
+    const discoveredUser = ghProjects.discoverProject({ user: owner, projectTitle: repo });
+    if (discoveredUser && !discoveredUser.error) {
+      project = discoveredUser;
+      fields = discoveredUser.fields || [];
+    }
+  }
+
+  // Step 4: Build suggested config
+  const defaults = getDefaultConfig();
+  const suggestedConfig = {
+    ...defaults,
+    owner,
+    repo,
+    project: project ? project.title : null,
+    projectId: project ? project.projectId : null,
+  };
+
+  return {
+    owner,
+    repo,
+    project,
+    fields,
+    suggestedConfig,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// writeGitHubConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Read existing `.tlc.json`, add/update the `github` key, write back.
+ * Preserves all other configuration.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} githubConfig - The github config object to write
+ * @param {object} [options]
+ * @param {object} [options.fs] - Injected fs module
+ * @returns {{ written: boolean }}
+ */
+function writeGitHubConfig(projectDir, githubConfig, { fs = nodeFs } = {}) {
+  const filePath = tlcJsonPath(projectDir);
+
+  let existing = {};
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    existing = JSON.parse(raw);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.error(`[TLC] writeGitHubConfig: error reading ${filePath}: ${err.message}`);
+      throw err;
+    }
+    // File doesn't exist yet, start from empty object
+  }
+
+  existing.github = githubConfig;
+
+  fs.writeFileSync(filePath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+  return { written: true };
+}
+
+// ---------------------------------------------------------------------------
+// queueSyncAction
+// ---------------------------------------------------------------------------
+
+/**
+ * Append an action to the offline sync queue.
+ * Creates the queue file and directory if they don't exist.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} action - `{ type, payload, timestamp }`
+ * @param {object} [options]
+ * @param {object} [options.fs] - Injected fs module
+ */
+function queueSyncAction(projectDir, action, { fs = nodeFs } = {}) {
+  const dirPath = path.join(projectDir, QUEUE_DIR);
+  const filePath = queueFilePath(projectDir);
+
+  try {
+    // Ensure directory exists
+    fs.mkdirSync(dirPath, { recursive: true });
+  } catch (err) {
+    console.error(`[TLC] queueSyncAction: cannot create queue dir ${dirPath}: ${err.message}`);
+    return { error: `Cannot create queue directory: ${err.message}`, code: 'QUEUE_WRITE_ERROR' };
+  }
+
+  // Load existing queue
+  let queue = [];
+  try {
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      queue = JSON.parse(raw);
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      queue = [];
+    } else {
+      console.error(`[TLC] queueSyncAction: error reading queue at ${filePath}: ${err.message}. Refusing to overwrite.`);
+      return { error: 'Queue file corrupted', code: 'QUEUE_CORRUPT' };
+    }
+  }
+
+  queue.push(action);
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(queue, null, 2), 'utf-8');
+  } catch (err) {
+    console.error(`[TLC] queueSyncAction: cannot write queue at ${filePath}: ${err.message}`);
+    return { error: `Cannot write queue file: ${err.message}`, code: 'QUEUE_WRITE_ERROR' };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// loadSyncQueue
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and return the sync queue array, or empty array if no file exists.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} [options]
+ * @param {object} [options.fs] - Injected fs module
+ * @returns {Array | { queue: Array, error: string }}
+ */
+function loadSyncQueue(projectDir, { fs = nodeFs } = {}) {
+  const filePath = queueFilePath(projectDir);
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      return [];
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error(`[TLC] loadSyncQueue: error reading queue at ${filePath}: ${err.message}`);
+    return { queue: [], error: 'Queue file corrupted or unreadable' };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// flushSyncQueue
+// ---------------------------------------------------------------------------
+
+/**
+ * Replay action dispatcher — maps queue action types to client calls.
+ * @param {object} action - Queue action `{ type, payload }`
+ * @param {object} ghClient - GitHub client
+ * @param {object} ghProjects - GitHub Projects client
+ * @returns {{ success: boolean, result?: object }}
+ */
+function replayAction(action, ghClient, ghProjects) {
+  const { type, payload } = action;
+
+  try {
+    let result;
+    switch (type) {
+      case 'create_issue':
+        result = ghClient.createIssue(payload);
+        break;
+      case 'close_issue':
+        result = ghClient.closeIssue(payload);
+        break;
+      case 'assign_issue':
+        result = ghClient.assignIssue(payload);
+        break;
+      case 'add_labels':
+        result = ghClient.addLabels(payload);
+        break;
+      case 'add_to_project':
+        result = ghProjects.addItemToProject(payload);
+        break;
+      case 'set_field':
+        result = ghProjects.setFieldValue(payload);
+        break;
+      default:
+        console.error(`[TLC] flushSyncQueue: unknown action type "${type}"`);
+        return { success: false };
+    }
+
+    // Check for structured error responses
+    if (result && result.error) {
+      console.error(`[TLC] flushSyncQueue: action "${type}" failed: ${result.error} (code: ${result.code})`);
+      return { success: false, result };
+    }
+
+    return { success: true, result };
+  } catch (err) {
+    console.error(`[TLC] flushSyncQueue: action "${type}" threw: ${err.message}`);
+    return { success: false };
+  }
+}
+
+/**
+ * Read queue, replay each action, remove successful ones, keep failed ones.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} params
+ * @param {object} params.ghClient - GitHub client
+ * @param {object} params.ghProjects - GitHub Projects client
+ * @param {object} [params.fs] - Injected fs module
+ * @returns {{ flushed: number, failed: number, remaining: number }}
+ */
+function flushSyncQueue(projectDir, { ghClient, ghProjects, fs = nodeFs }) {
+  const loaded = loadSyncQueue(projectDir, { fs });
+
+  // loadSyncQueue returns an array on success, or { queue, error } on corruption
+  if (loaded && loaded.error) {
+    console.error(`[TLC] flushSyncQueue: ${loaded.error}`);
+    return { flushed: 0, failed: 0, remaining: 0, error: loaded.error };
+  }
+
+  const queue = loaded;
+
+  if (queue.length === 0) {
+    return { flushed: 0, failed: 0, remaining: 0 };
+  }
+
+  let flushed = 0;
+  let failed = 0;
+  const remaining = [];
+
+  for (const action of queue) {
+    const { success } = replayAction(action, ghClient, ghProjects);
+    if (success) {
+      flushed++;
+    } else {
+      failed++;
+      remaining.push(action);
+    }
+  }
+
+  // Write back remaining (failed) actions
+  const filePath = queueFilePath(projectDir);
+  const dirPath = path.join(projectDir, QUEUE_DIR);
+  try {
+    fs.mkdirSync(dirPath, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(remaining, null, 2), 'utf-8');
+  } catch (err) {
+    console.error(`[TLC] flushSyncQueue: cannot write remaining queue at ${filePath}: ${err.message}`);
+    return { flushed, failed, remaining: remaining.length, error: `Cannot write queue file: ${err.message}` };
+  }
+
+  return { flushed, failed, remaining: remaining.length };
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  loadGitHubConfig,
+  isGitHubEnabled,
+  detectAndSuggestConfig,
+  writeGitHubConfig,
+  getDefaultConfig,
+  queueSyncAction,
+  flushSyncQueue,
+  loadSyncQueue,
+};