tlc-claude-code 2.4.10 → 2.5.0

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

@@ -0,0 +1,583 @@
+/**
+ * @file gh-projects.test.js
+ * @description Tests for GitHub Projects V2 GraphQL client (Phase 97, Task 2).
+ *
+ * Tests the module that manages GitHub Projects V2 via GraphQL —
+ * discover project schema, add items, set field values.
+ *
+ * All exec calls are mocked via DI. GraphQL calls go through `gh api graphql`.
+ *
+ * TDD: RED phase — these tests are written BEFORE the implementation.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  discoverProject,
+  addItemToProject,
+  setFieldValue,
+  createFieldOption,
+  getProjectItems,
+  findFieldByName,
+  findOptionByName,
+  createProjectsClient,
+} from './gh-projects.js';
+
+// ---------------------------------------------------------------------------
+// Mock data factories
+// ---------------------------------------------------------------------------
+
+function makeProjectNode({ id = 'PVT_abc123', title = 'TLC Board', number = 1 } = {}) {
+  return {
+    id,
+    title,
+    number,
+    fields: {
+      nodes: [
+        { __typename: 'ProjectV2Field', id: 'PVTF_title', name: 'Title' },
+        {
+          __typename: 'ProjectV2SingleSelectField',
+          id: 'PVTSSF_status',
+          name: 'Status',
+          options: [
+            { id: 'opt_todo', name: 'Todo' },
+            { id: 'opt_inprogress', name: 'In Progress' },
+            { id: 'opt_done', name: 'Done' },
+          ],
+        },
+        {
+          __typename: 'ProjectV2SingleSelectField',
+          id: 'PVTSSF_sprint',
+          name: 'Sprint',
+          options: [
+            { id: 'opt_phase96', name: 'Phase-96' },
+          ],
+        },
+        { __typename: 'ProjectV2Field', id: 'PVTF_assignees', name: 'Assignees' },
+      ],
+    },
+  };
+}
+
+function makeOrgDiscoveryResponse(projects = [makeProjectNode()]) {
+  return JSON.stringify({
+    data: {
+      organization: {
+        projectsV2: {
+          nodes: projects,
+        },
+      },
+    },
+  });
+}
+
+function makeUserDiscoveryResponse(projects = [makeProjectNode()]) {
+  return JSON.stringify({
+    data: {
+      user: {
+        projectsV2: {
+          nodes: projects,
+        },
+      },
+    },
+  });
+}
+
+function makeAddItemResponse(itemId = 'PVTI_item1') {
+  return JSON.stringify({
+    data: {
+      addProjectV2ItemById: {
+        item: { id: itemId },
+      },
+    },
+  });
+}
+
+function makeSetFieldResponse(itemId = 'PVTI_item1') {
+  return JSON.stringify({
+    data: {
+      updateProjectV2ItemFieldValue: {
+        projectV2Item: { id: itemId },
+      },
+    },
+  });
+}
+
+function makeCreateOptionResponse(optionId = 'opt_new1') {
+  return JSON.stringify({
+    data: {
+      createProjectV2FieldOption: {
+        projectV2Field: {
+          options: [
+            { id: 'opt_existing', name: 'Existing' },
+            { id: optionId, name: 'Phase-97' },
+          ],
+        },
+      },
+    },
+  });
+}
+
+function makeProjectItemsResponse() {
+  return JSON.stringify({
+    data: {
+      node: {
+        items: {
+          nodes: [
+            {
+              id: 'PVTI_item1',
+              content: {
+                __typename: 'Issue',
+                id: 'I_issue1',
+                title: 'Fix login bug',
+              },
+              fieldValues: {
+                nodes: [
+                  { __typename: 'ProjectV2ItemFieldTextValue', text: 'Fix login bug', field: { name: 'Title' } },
+                  { __typename: 'ProjectV2ItemFieldSingleSelectValue', name: 'In Progress', field: { name: 'Status' } },
+                  { __typename: 'ProjectV2ItemFieldSingleSelectValue', name: 'Phase-96', field: { name: 'Sprint' } },
+                ],
+              },
+            },
+            {
+              id: 'PVTI_item2',
+              content: {
+                __typename: 'PullRequest',
+                id: 'PR_pr1',
+                title: 'Add auth module',
+              },
+              fieldValues: {
+                nodes: [
+                  { __typename: 'ProjectV2ItemFieldTextValue', text: 'Add auth module', field: { name: 'Title' } },
+                  { __typename: 'ProjectV2ItemFieldSingleSelectValue', name: 'Done', field: { name: 'Status' } },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    },
+  });
+}
+
+function makeExec(response) {
+  return vi.fn().mockReturnValue(Buffer.from(response));
+}
+
+function makeExecThrowing(stderr, exitCode = 1) {
+  return vi.fn().mockImplementation(() => {
+    const err = new Error(`Command failed with exit code ${exitCode}`);
+    err.stderr = Buffer.from(stderr);
+    err.status = exitCode;
+    throw err;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// discoverProject
+// ---------------------------------------------------------------------------
+
+describe('discoverProject', () => {
+  it('finds project by title in org', async () => {
+    const exec = makeExec(makeOrgDiscoveryResponse());
+    const result = discoverProject({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    expect(result.projectId).toBe('PVT_abc123');
+    expect(result.title).toBe('TLC Board');
+    expect(result.number).toBe(1);
+    expect(result.fields).toBeInstanceOf(Array);
+    expect(result.fields.length).toBeGreaterThan(0);
+
+    // Verify the exec was called with a graphql query containing organization
+    const call = exec.mock.calls[0][0];
+    expect(call).toContain('gh api graphql');
+    expect(call).toContain('organization');
+    expect(call).toContain('KashaTech');
+  });
+
+  it('finds project by title for personal user', () => {
+    const exec = makeExec(makeUserDiscoveryResponse());
+    const result = discoverProject({ user: 'octocat', projectTitle: 'TLC Board', exec });
+
+    expect(result.projectId).toBe('PVT_abc123');
+    expect(result.title).toBe('TLC Board');
+
+    const call = exec.mock.calls[0][0];
+    expect(call).toContain('user');
+    expect(call).toContain('octocat');
+  });
+
+  it('returns error when project not found', () => {
+    const response = JSON.stringify({
+      data: {
+        organization: {
+          projectsV2: { nodes: [] },
+        },
+      },
+    });
+    const exec = makeExec(response);
+    const result = discoverProject({ org: 'KashaTech', projectTitle: 'Nonexistent', exec });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBe('GH_PROJECT_NOT_FOUND');
+    expect(result.error).toContain('Nonexistent');
+  });
+
+  it('extracts fields with options correctly', () => {
+    const exec = makeExec(makeOrgDiscoveryResponse());
+    const result = discoverProject({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    // Status field should have options
+    const statusField = result.fields.find(f => f.name === 'Status');
+    expect(statusField).toBeDefined();
+    expect(statusField.type).toBe('single_select');
+    expect(statusField.options).toEqual([
+      { id: 'opt_todo', name: 'Todo' },
+      { id: 'opt_inprogress', name: 'In Progress' },
+      { id: 'opt_done', name: 'Done' },
+    ]);
+
+    // Title field should NOT have options
+    const titleField = result.fields.find(f => f.name === 'Title');
+    expect(titleField).toBeDefined();
+    expect(titleField.type).toBe('field');
+    expect(titleField.options).toBeUndefined();
+  });
+
+  it('returns error when gh is not installed', () => {
+    const exec = makeExecThrowing('command not found: gh');
+    const result = discoverProject({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBe('GH_NOT_FOUND');
+  });
+
+  it('returns error when not authenticated', () => {
+    const exec = makeExecThrowing('gh auth login');
+    const result = discoverProject({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBe('GH_AUTH_REQUIRED');
+  });
+
+  it('returns actionable error when project scope is missing', () => {
+    const exec = makeExecThrowing('Your token does not have the required scopes: project');
+    const result = discoverProject({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBe('GH_SCOPE_MISSING');
+    expect(result.error).toContain('gh auth refresh');
+    expect(result.error).toContain('project');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// addItemToProject
+// ---------------------------------------------------------------------------
+
+describe('addItemToProject', () => {
+  it('constructs correct GraphQL mutation', () => {
+    const exec = makeExec(makeAddItemResponse());
+    addItemToProject({ projectId: 'PVT_abc123', contentId: 'I_issue1', exec });
+
+    const call = exec.mock.calls[0][0];
+    expect(call).toContain('addProjectV2ItemById');
+    expect(call).toContain('PVT_abc123');
+    expect(call).toContain('I_issue1');
+  });
+
+  it('returns itemId from response', () => {
+    const exec = makeExec(makeAddItemResponse('PVTI_xyz'));
+    const result = addItemToProject({ projectId: 'PVT_abc123', contentId: 'I_issue1', exec });
+
+    expect(result.itemId).toBe('PVTI_xyz');
+  });
+
+  it('returns error on failure', () => {
+    const exec = makeExecThrowing('Something went wrong');
+    const result = addItemToProject({ projectId: 'PVT_abc123', contentId: 'I_issue1', exec });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setFieldValue
+// ---------------------------------------------------------------------------
+
+describe('setFieldValue', () => {
+  it('constructs correct mutation with optionId', () => {
+    const exec = makeExec(makeSetFieldResponse());
+    const result = setFieldValue({
+      projectId: 'PVT_abc123',
+      itemId: 'PVTI_item1',
+      fieldId: 'PVTSSF_status',
+      optionId: 'opt_inprogress',
+      exec,
+    });
+
+    const call = exec.mock.calls[0][0];
+    expect(call).toContain('updateProjectV2ItemFieldValue');
+    expect(call).toContain('PVT_abc123');
+    expect(call).toContain('PVTI_item1');
+    expect(call).toContain('PVTSSF_status');
+    expect(call).toContain('opt_inprogress');
+    expect(call).toContain('singleSelectOptionId');
+
+    expect(result.success).toBe(true);
+  });
+
+  it('returns error on failure', () => {
+    const exec = makeExecThrowing('Resource not accessible by integration');
+    const result = setFieldValue({
+      projectId: 'PVT_abc123',
+      itemId: 'PVTI_item1',
+      fieldId: 'PVTSSF_status',
+      optionId: 'opt_inprogress',
+      exec,
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createFieldOption
+// ---------------------------------------------------------------------------
+
+describe('createFieldOption', () => {
+  it('constructs correct mutation', () => {
+    const exec = makeExec(makeCreateOptionResponse());
+    const result = createFieldOption({
+      projectId: 'PVT_abc123',
+      fieldId: 'PVTSSF_sprint',
+      name: 'Phase-97',
+      exec,
+    });
+
+    const call = exec.mock.calls[0][0];
+    expect(call).toContain('createProjectV2FieldOption');
+    expect(call).toContain('PVT_abc123');
+    expect(call).toContain('PVTSSF_sprint');
+    expect(call).toContain('Phase-97');
+
+    expect(result.optionId).toBe('opt_new1');
+  });
+
+  it('returns error on permission denied', () => {
+    const exec = makeExecThrowing('Resource not accessible by integration');
+    const result = createFieldOption({
+      projectId: 'PVT_abc123',
+      fieldId: 'PVTSSF_sprint',
+      name: 'Phase-97',
+      exec,
+    });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBe('GH_PERMISSION_DENIED');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getProjectItems
+// ---------------------------------------------------------------------------
+
+describe('getProjectItems', () => {
+  it('returns items with field values', () => {
+    const exec = makeExec(makeProjectItemsResponse());
+    const result = getProjectItems({ projectId: 'PVT_abc123', first: 50, exec });
+
+    expect(result).toBeInstanceOf(Array);
+    expect(result).toHaveLength(2);
+
+    const item1 = result[0];
+    expect(item1.itemId).toBe('PVTI_item1');
+    expect(item1.contentId).toBe('I_issue1');
+    expect(item1.contentType).toBe('Issue');
+    expect(item1.title).toBe('Fix login bug');
+    expect(item1.fieldValues).toBeDefined();
+    expect(item1.fieldValues.Status).toBe('In Progress');
+    expect(item1.fieldValues.Sprint).toBe('Phase-96');
+
+    const item2 = result[1];
+    expect(item2.itemId).toBe('PVTI_item2');
+    expect(item2.contentId).toBe('PR_pr1');
+    expect(item2.contentType).toBe('PullRequest');
+    expect(item2.title).toBe('Add auth module');
+    expect(item2.fieldValues.Status).toBe('Done');
+  });
+
+  it('returns error on failure', () => {
+    const exec = makeExecThrowing('not found');
+    const result = getProjectItems({ projectId: 'PVT_abc123', exec });
+
+    expect(result.error).toBeDefined();
+    expect(result.code).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findFieldByName (pure helper)
+// ---------------------------------------------------------------------------
+
+describe('findFieldByName', () => {
+  const fields = [
+    { id: 'PVTF_title', name: 'Title', type: 'field' },
+    { id: 'PVTSSF_status', name: 'Status', type: 'single_select', options: [{ id: 'opt_todo', name: 'Todo' }] },
+    { id: 'PVTSSF_sprint', name: 'Sprint', type: 'single_select', options: [] },
+  ];
+
+  it('returns correct field by name', () => {
+    const result = findFieldByName(fields, 'Status');
+    expect(result).toBeDefined();
+    expect(result.id).toBe('PVTSSF_status');
+    expect(result.name).toBe('Status');
+  });
+
+  it('returns null for missing field', () => {
+    const result = findFieldByName(fields, 'Priority');
+    expect(result).toBeNull();
+  });
+
+  it('is case-insensitive', () => {
+    const result = findFieldByName(fields, 'status');
+    expect(result).toBeDefined();
+    expect(result.id).toBe('PVTSSF_status');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findOptionByName (pure helper)
+// ---------------------------------------------------------------------------
+
+describe('findOptionByName', () => {
+  const field = {
+    id: 'PVTSSF_status',
+    name: 'Status',
+    type: 'single_select',
+    options: [
+      { id: 'opt_todo', name: 'Todo' },
+      { id: 'opt_inprogress', name: 'In Progress' },
+      { id: 'opt_done', name: 'Done' },
+    ],
+  };
+
+  it('returns correct option by name', () => {
+    const result = findOptionByName(field, 'In Progress');
+    expect(result).toBeDefined();
+    expect(result.id).toBe('opt_inprogress');
+  });
+
+  it('returns null for missing option', () => {
+    const result = findOptionByName(field, 'Cancelled');
+    expect(result).toBeNull();
+  });
+
+  it('is case-insensitive', () => {
+    const result = findOptionByName(field, 'done');
+    expect(result).toBeDefined();
+    expect(result.id).toBe('opt_done');
+  });
+
+  it('returns null for field without options', () => {
+    const plainField = { id: 'PVTF_title', name: 'Title', type: 'field' };
+    const result = findOptionByName(plainField, 'anything');
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createProjectsClient (factory with caching)
+// ---------------------------------------------------------------------------
+
+describe('createProjectsClient', () => {
+  it('caches schema after first call', () => {
+    const exec = vi.fn()
+      .mockReturnValueOnce(Buffer.from(makeOrgDiscoveryResponse()))
+      .mockReturnValueOnce(Buffer.from(makeAddItemResponse()));
+
+    const client = createProjectsClient({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    // First call triggers discovery
+    const addResult = client.addItem({ contentId: 'I_issue1' });
+    expect(addResult.itemId).toBe('PVTI_item1');
+
+    // exec should have been called twice: once for discover, once for addItem
+    expect(exec).toHaveBeenCalledTimes(2);
+    // First call should be the discovery query
+    expect(exec.mock.calls[0][0]).toContain('projectsV2');
+  });
+
+  it('re-uses cached fields on subsequent calls', () => {
+    const exec = vi.fn()
+      .mockReturnValueOnce(Buffer.from(makeOrgDiscoveryResponse()))
+      .mockReturnValueOnce(Buffer.from(makeAddItemResponse('PVTI_a')))
+      .mockReturnValueOnce(Buffer.from(makeSetFieldResponse()))
+      .mockReturnValueOnce(Buffer.from(makeAddItemResponse('PVTI_b')));
+
+    const client = createProjectsClient({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    // First call — triggers discovery + addItem
+    client.addItem({ contentId: 'I_1' });
+    // Second call — setFieldValue, no re-discovery
+    client.setField({ itemId: 'PVTI_a', fieldId: 'PVTSSF_status', optionId: 'opt_done' });
+    // Third call — another addItem, still no re-discovery
+    client.addItem({ contentId: 'I_2' });
+
+    // Discovery should only happen once (first call in exec.mock.calls)
+    const discoveryCalls = exec.mock.calls.filter(c => c[0].includes('projectsV2'));
+    expect(discoveryCalls).toHaveLength(1);
+
+    // Total exec calls: 1 discover + 3 operations
+    expect(exec).toHaveBeenCalledTimes(4);
+  });
+
+  it('exposes project info after discovery', () => {
+    const exec = vi.fn()
+      .mockReturnValueOnce(Buffer.from(makeOrgDiscoveryResponse()));
+
+    const client = createProjectsClient({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+    const info = client.getProjectInfo();
+
+    expect(info.projectId).toBe('PVT_abc123');
+    expect(info.title).toBe('TLC Board');
+    expect(info.fields).toBeInstanceOf(Array);
+  });
+
+  it('returns error if project discovery fails', () => {
+    const exec = makeExecThrowing('command not found: gh');
+    const client = createProjectsClient({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    const info = client.getProjectInfo();
+    expect(info.error).toBeDefined();
+    expect(info.code).toBe('GH_NOT_FOUND');
+  });
+
+  it('provides findField and findOption helpers bound to cached schema', () => {
+    const exec = vi.fn()
+      .mockReturnValueOnce(Buffer.from(makeOrgDiscoveryResponse()));
+
+    const client = createProjectsClient({ org: 'KashaTech', projectTitle: 'TLC Board', exec });
+
+    const statusField = client.findField('Status');
+    expect(statusField).toBeDefined();
+    expect(statusField.id).toBe('PVTSSF_status');
+
+    const option = client.findOption(statusField, 'In Progress');
+    expect(option).toBeDefined();
+    expect(option.id).toBe('opt_inprogress');
+  });
+
+  it('works with user instead of org', () => {
+    const exec = vi.fn()
+      .mockReturnValueOnce(Buffer.from(makeUserDiscoveryResponse()));
+
+    const client = createProjectsClient({ user: 'octocat', projectTitle: 'TLC Board', exec });
+    const info = client.getProjectInfo();
+
+    expect(info.projectId).toBe('PVT_abc123');
+    const call = exec.mock.calls[0][0];
+    expect(call).toContain('user');
+    expect(call).toContain('octocat');
+  });
+});

package/server/lib/github/index.js

@@ -0,0 +1,19 @@
+/**
+ * GitHub integration barrel export
+ * Phase 97
+ *
+ * Re-exports all functions from the github/ directory modules.
+ */
+
+const ghClient = require('./gh-client');
+const ghProjects = require('./gh-projects');
+const config = require('./config');
+
+const planSync = require('./plan-sync');
+
+module.exports = {
+  ...ghClient,
+  ...ghProjects,
+  ...planSync,
+  ...config,
+};