Merge pull request #4 from OpenPathfinder/faet/projects

Changes:

- New Features
  - Introduced a new CLI command to add a project with optional GitHub organization URLs.
- Bug Fixes
  - Improved error messages for API failures, providing more detailed feedback.
- Tests
  - Added comprehensive tests for project creation and GitHub organization association scenarios.
- Chores
  - Added a new runtime dependency for string-to-array conversion.
  - Introduced reusable test fixtures for consistent API response mocking.
- Documentation
  - Expanded type definitions for API responses and error handling.

Author: UlisesGascon

.github/workflows/pr-test.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macOS-latest]
-        node-version: [18.x, 20.x, 22.x, 24.x]
+        node-version: [20.x, 22.x, 24.x]
       fail-fast: false
 
     steps:

package-lock.json

@@ -38,6 +38,7 @@
     "typescript": "5.8.3"
   },
   "dependencies": {
+    "@ulisesgascon/string-to-array": "2.0.0",
     "commander": "14.0.0",
     "got": "14.4.7",
     "nock": "14.0.5",

package.json

@@ -1,8 +1,9 @@
 /* eslint-env jest */
 
-import { getVersion, runDoctor } from '../cli-commands.js'
+import { getVersion, runDoctor, addProjectWithGithubOrgs } from '../cli-commands.js'
 import { getPackageJson } from '../utils.js'
-import { APIHealthResponse } from '../types.js'
+import { APIHealthResponse, APIProjectDetails, APIGithubOrgDetails, APIErrorResponse } from '../types.js'
+import { mockApiHealthResponse, mockAPIProjectResponse, mockAPIGithubOrgResponse } from './fixtures.js'
 import nock from 'nock'
 
 const pkg = getPackageJson()
@@ -32,12 +33,7 @@ describe('CLI Commands', () => {
     let apiHealthResponse: APIHealthResponse
     beforeEach(() => {
       nock.cleanAll()
-      apiHealthResponse = {
-        status: 'ok',
-        timestamp: new Date().toISOString(),
-        version: '0.1.0-beta3',
-        name: 'visionBoard'
-      }
+      apiHealthResponse = mockApiHealthResponse
     })
 
     it('should return success when API is available and compatible', async () => {
@@ -88,4 +84,95 @@ describe('CLI Commands', () => {
       expect(result.messages).toHaveLength(1)
     })
   })
+
+  describe('addProjectWithGithubOrgs', () => {
+    let mockProject: APIProjectDetails
+    let mockGithubOrg1: APIGithubOrgDetails
+    let mockGithubOrg2: APIGithubOrgDetails
+
+    beforeEach(() => {
+      nock.cleanAll()
+
+      // Setup mock project data using fixtures
+      mockProject = { ...mockAPIProjectResponse }
+
+      // Create simplified GitHub org responses for tests
+      mockGithubOrg1 = { ...mockAPIGithubOrgResponse }
+
+      mockGithubOrg2 = {
+        ...mockAPIGithubOrgResponse,
+        id: 789,
+        name: 'org2',
+        login: 'org2'
+      }
+    })
+
+    it('should create a project and add GitHub organizations successfully', async () => {
+      // Mock API calls
+      nock('http://localhost:3000')
+        .post('/api/v1/project', { name: 'Test Project' })
+        .reply(201, mockProject)
+
+      nock('http://localhost:3000')
+        .post('/api/v1/project/123/gh-org', { githubOrgUrl: 'https://github.com/org1' })
+        .reply(201, mockGithubOrg1)
+
+      nock('http://localhost:3000')
+        .post('/api/v1/project/123/gh-org', { githubOrgUrl: 'https://github.com/org2' })
+        .reply(201, mockGithubOrg2)
+
+      // Execute the function
+      const result = await addProjectWithGithubOrgs('Test Project', [
+        'https://github.com/org1',
+        'https://github.com/org2'
+      ])
+
+      // Verify the result
+      expect(result.success).toBe(true)
+      expect(result.messages).toContain('✅ Project created successfully')
+      expect(result.messages).toHaveLength(1)
+      expect(nock.isDone()).toBe(true) // Verify all mocked endpoints were called
+    })
+
+    it('should handle failure when project creation fails', async () => {
+      // Mock failed project creation
+      nock('http://localhost:3000')
+        .post('/api/v1/project', { name: 'Existing Project' })
+        .reply(409, { errors: [{ message: 'Project already exists' }] } as APIErrorResponse)
+
+      // Execute the function
+      const result = await addProjectWithGithubOrgs('Existing Project', [
+        'https://github.com/org1'
+      ])
+
+      // Verify the result
+      expect(result.success).toBe(false)
+      expect(result.messages[0]).toContain('❌ Failed to create the project')
+      expect(result.messages[0]).toContain('Project (Existing Project) already exists')
+      expect(result.messages).toHaveLength(1)
+    })
+
+    it('should handle failure when adding GitHub organization fails', async () => {
+      // Mock API calls
+      nock('http://localhost:3000')
+        .post('/api/v1/project', { name: 'Test Project' })
+        .reply(201, mockProject)
+
+      // Mock failed GitHub org addition (already exists)
+      nock('http://localhost:3000')
+        .post('/api/v1/project/123/gh-org', { githubOrgUrl: 'https://github.com/existing-org' })
+        .reply(409, { errors: [{ message: 'GitHub organization already exists in the project' }] } as APIErrorResponse)
+
+      // Execute the function
+      const result = await addProjectWithGithubOrgs('Test Project', [
+        'https://github.com/existing-org'
+      ])
+
+      // Verify the result
+      expect(result.success).toBe(false)
+      expect(result.messages[0]).toContain('❌ Failed to create the project')
+      expect(result.messages[0]).toContain('GitHub organization (https://github.com/existing-org) already exists in the project')
+      expect(result.messages).toHaveLength(1)
+    })
+  })
 })

src/__tests__/cli-commands.test.ts

@@ -0,0 +1,95 @@
+import { APIHealthResponse, APIProjectDetails, APIGithubOrgDetails } from '../types.js'
+
+export const mockApiHealthResponse: APIHealthResponse = {
+  status: 'ok',
+  timestamp: new Date().toISOString(),
+  version: '0.1.0-beta3',
+  name: 'visionBoard'
+}
+
+export const mockAPIProjectResponse: APIProjectDetails = {
+  id: 123,
+  name: 'Test Project',
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+  has_defineFunctionalRoles_policy: null,
+  has_orgToolingMFA_policy: null,
+  has_softwareArchitectureDocs_policy: null,
+  has_MFAImpersonationDefense_policy: null,
+  has_includeCVEInReleaseNotes_policy: null,
+  has_assignCVEForKnownVulns_policy: null,
+  has_incidentResponsePlan_policy: null,
+  has_regressionTestsForVulns_policy: null,
+  has_vulnResponse14Days_policy: null,
+  has_useCVDToolForVulns_policy: null,
+  has_securityMdMeetsOpenJSCVD_policy: null,
+  has_consistentBuildProcessDocs_policy: null,
+  has_machineReadableDependencies_policy: null,
+  has_identifyModifiedDependencies_policy: null,
+  has_ciAndCdPipelineAsCode_policy: null,
+  has_npmOrgMFA_policy: null,
+  has_npmPublicationMFA_policy: null,
+  has_upgradePathDocs_policy: null,
+  has_patchNonCriticalVulns90Days_policy: null,
+  has_patchCriticalVulns30Days_policy: null,
+  has_twoOrMoreOwnersForAccess_policy: null,
+  has_injectedSecretsAtRuntime_policy: null,
+  has_preventScriptInjection_policy: null,
+  has_resolveLinterWarnings_policy: null,
+  has_annualDependencyRefresh_policy: null
+}
+
+export const mockAPIGithubOrgResponse: APIGithubOrgDetails = {
+  id: 456,
+  login: 'test-org',
+  github_org_id: 789,
+  node_id: 'O_kgDOBjYYyw',
+  url: 'https://api.github.com/orgs/test-org',
+  avatar_url: 'https://avatars.githubusercontent.com/u/12345678?v=4',
+  description: 'Test organization for OpenPathfinder',
+  name: 'Test Organization',
+  company: null,
+  blog: 'https://test-org.github.io',
+  location: 'Worldwide',
+  twitter_username: 'testorg',
+  is_verified: true,
+  has_organization_projects: true,
+  has_repository_projects: true,
+  public_repos: 42,
+  public_gists: 0,
+  followers: 100,
+  following: 0,
+  html_url: 'https://github.com/test-org',
+  total_private_repos: 10,
+  owned_private_repos: 10,
+  private_gists: 0,
+  disk_usage: 1000,
+  collaborators: 5,
+  default_repository_permission: 'read',
+  members_can_create_repositories: true,
+  two_factor_requirement_enabled: true,
+  members_allowed_repository_creation_type: 'all',
+  members_can_create_public_repositories: true,
+  members_can_create_private_repositories: true,
+  members_can_create_internal_repositories: false,
+  members_can_create_pages: true,
+  members_can_create_public_pages: true,
+  members_can_create_private_pages: true,
+  members_can_fork_private_repositories: false,
+  web_commit_signoff_required: true,
+  deploy_keys_enabled_for_repositories: true,
+  dependency_graph_enabled_for_new_repositories: true,
+  dependabot_alerts_enabled_for_new_repositories: true,
+  dependabot_security_updates_enabled_for_new_repositories: true,
+  advanced_security_enabled_for_new_repositories: false,
+  secret_scanning_enabled_for_new_repositories: true,
+  secret_scanning_push_protection_enabled_for_new_repositories: true,
+  secret_scanning_push_protection_custom_link: null,
+  secret_scanning_push_protection_custom_link_enabled: false,
+  github_created_at: '2020-01-01T00:00:00Z',
+  github_updated_at: '2025-06-19T13:48:29Z',
+  github_archived_at: null,
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+  project_id: 123
+}

src/__tests__/fixtures.ts

@@ -1,6 +1,6 @@
 import { getConfig } from './utils.js'
 import { got } from 'got'
-import { APIHealthResponse } from './types.js'
+import { APIHealthResponse, APIProjectDetails, APIGithubOrgDetails } from './types.js'
 
 export const apiClient = () => {
   const config = getConfig()
@@ -13,7 +13,42 @@ export const getAPIDetails = async (): Promise<APIHealthResponse> => {
   const client = apiClient()
   const response = await client.get('__health', { responseType: 'json' })
   if (response.statusCode !== 200) {
-    throw new Error('Failed to get the data from the API')
+    throw new Error(`Failed to get the data from the API: ${response.statusCode} ${response.body}`)
   }
   return response.body as APIHealthResponse
 }
+
+export const createProject = async (name: string): Promise<APIProjectDetails> => {
+  const client = apiClient()
+  const response = await client.post('project', {
+    json: { name },
+    responseType: 'json',
+    throwHttpErrors: false
+  })
+  if (response.statusCode === 409) {
+    throw new Error(`Project (${name}) already exists`)
+  }
+  if (response.statusCode !== 201) {
+    throw new Error(`Failed to create the project: ${response.statusCode} ${response.body}`)
+  }
+  return response.body as APIProjectDetails
+}
+
+export const addGithubOrgToProject = async (projectId: number, githubOrgUrl: string): Promise<APIGithubOrgDetails> => {
+  const client = apiClient()
+  const response = await client.post(`project/${projectId}/gh-org`, {
+    json: { githubOrgUrl },
+    responseType: 'json',
+    throwHttpErrors: false
+  })
+  if (response.statusCode === 409) {
+    throw new Error(`GitHub organization (${githubOrgUrl}) already exists in the project`)
+  }
+  if (response.statusCode === 404) {
+    throw new Error(`Project (${projectId}) not found`)
+  }
+  if (response.statusCode !== 201) {
+    throw new Error(`Failed to add the GitHub organization (${githubOrgUrl}) to the project: ${response.statusCode} ${response.body}`)
+  }
+  return response.body as APIGithubOrgDetails
+}

src/api-client.ts

@@ -1,6 +1,6 @@
 import { CommandResult } from './types.js'
 import { isApiAvailable, isApiCompatible, getPackageJson } from './utils.js'
-import { getAPIDetails } from './api-client.js'
+import { getAPIDetails, createProject, addGithubOrgToProject } from './api-client.js'
 
 const pkg = getPackageJson()
 
@@ -36,3 +36,24 @@ export const runDoctor = async (): Promise<CommandResult> => {
     success
   }
 }
+
+export const addProjectWithGithubOrgs = async (name: string, githubOrgUrls: string[]): Promise<CommandResult> => {
+  const messages: string[] = []
+  let success = true
+  try {
+    const project = await createProject(name)
+    // Add GitHub organizations sequentially to avoid race conditions
+    for (const githubOrgUrl of githubOrgUrls) {
+      await addGithubOrgToProject(project.id, githubOrgUrl)
+    }
+    messages.push('✅ Project created successfully')
+  } catch (error) {
+    messages.push(`❌ Failed to create the project: ${error instanceof Error ? error.message : 'Unknown error'}`)
+    success = false
+  }
+
+  return {
+    messages,
+    success
+  }
+}

src/cli-commands.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander'
-
+// @ts-ignore
+import { stringToArray } from '@ulisesgascon/string-to-array'
 import { handleCommandResult } from './utils.js'
-import { getVersion, runDoctor } from './cli-commands.js'
+import { getVersion, runDoctor, addProjectWithGithubOrgs } from './cli-commands.js'
 
 const program = new Command()
 
@@ -22,4 +23,15 @@ program
     handleCommandResult(result)
   })
 
+program
+  .command('add-project')
+  .description('Add a project with GitHub organizations')
+  .requiredOption('-n, --name <name>', 'Project name')
+  .option('-g, --github-orgs <githubOrgUrls...>', 'GitHub organization URLs')
+  .action(async (options) => {
+    const githubOrgs = options.githubOrgs ? stringToArray(options.githubOrgs[0]) : []
+    const result = await addProjectWithGithubOrgs(options.name, githubOrgs)
+    handleCommandResult(result)
+  })
+
 program.parse(process.argv)