@forgehive/forge-cli 0.3.10 → 0.3.12

package/src/runner.ts

@@ -20,7 +20,6 @@ import { describe as describeTask } from './tasks/task/describe'
 import { fingerprint as fingerprintTask } from './tasks/task/fingerprint'
 import { invoke as invokeTask } from './tasks/task/invoke'
 
-
 import { create as createRunner } from './tasks/runner/create'
 import { remove as removeRunner } from './tasks/runner/remove'
 import { bundle as bundleRunner } from './tasks/runner/bundle'
@@ -33,6 +32,12 @@ import { add as addProfile } from './tasks/auth/add'
 import { switchProfile } from './tasks/auth/switch'
 import { list as listProfiles } from './tasks/auth/list'
 import { remove as removeProfile } from './tasks/auth/remove'
+import { clear as clearProfiles } from './tasks/auth/clear'
+
+import { create as createProject } from './tasks/project/create'
+import { link as linkProject } from './tasks/project/link'
+import { unlink as unlinkProject } from './tasks/project/unlink'
+import { sync as syncProject } from './tasks/project/sync'
 
 interface CliParsedArguments extends RunnerParsedArguments {
   action: string;
@@ -80,6 +85,13 @@ runner.load('auth:add', addProfile)
 runner.load('auth:switch', switchProfile)
 runner.load('auth:list', listProfiles)
 runner.load('auth:remove', removeProfile)
+runner.load('auth:clear', clearProfiles)
+
+// Project commands
+runner.load('project:create', createProject)
+runner.load('project:link', linkProject)
+runner.load('project:unlink', unlinkProject)
+runner.load('project:sync', syncProject)
 
 // Set handler
 runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
@@ -93,7 +105,7 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
   let silent = false
   const task = runner.getTask(taskName)
   if (!task) {
-    throw new Error(`Task "${taskName}" not found`)
+    throw new Error(`Forge command "${taskName}" not found`)
   }
 
   try {
@@ -101,6 +113,8 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
 
     const commandsWithDescriptor = ['task:create', 'task:remove', 'task:publish', 'task:describe', 'task:fingerprint']
     const commandsWithRunner = ['runner:create', 'runner:remove']
+    const commandsWithoutParams = ['project:unlink', 'project:sync', 'auth:clear']
+    const silentCommands = ['task:describe', 'task:list', 'auth:list', 'info']
 
     if (commandsWithDescriptor.includes(taskName)) {
       result = await task.run({ descriptorName: action })
@@ -167,7 +181,7 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
       })
     } else if (taskName === 'auth:switch' || taskName === 'auth:remove') {
       result = await task.run({
-        profileName: action
+        profileName: String(action)
       })
     } else if (taskName === 'docs:download') {
       const { path } = args as { path?: string }
@@ -175,15 +189,26 @@ runner.setHandler(async (data: ParsedArgs): Promise<unknown> => {
       result = await task.run({
         path
       })
+    } else if (taskName === 'project:create') {
+      const { projectName, description } = args as { projectName?: string, description?: string }
+
+      result = await task.run({
+        projectName,
+        description
+      })
+    } else if (taskName === 'project:link') {
+      const { uuid } = args as { uuid: string }
+      result = await task.run({
+        uuid
+      })
+    } else if (commandsWithoutParams.includes(taskName)) {
+      result = await task.run({})
     } else {
       result = await task.run(args)
 
-      if (taskName === 'info') {
-        silent = true
-      }
     }
 
-    if (taskName === 'task:describe' || taskName === 'task:list') {
+    if (silentCommands.includes(taskName)) {
       silent = true
     }
 

package/src/tasks/auth/add.ts

@@ -24,23 +24,83 @@ const boundaries = {
     const buildsPath = path.join(os.homedir(), '.forge')
     const profilesPath = path.join(buildsPath, 'profiles.json')
     await fs.writeFile(profilesPath, JSON.stringify(profiles, null, 2))
+  },
+  fetchMeInfo: async (apiKey: string, apiSecret: string, url: string): Promise<{
+    success: boolean
+    teamName?: string
+    teamUuid?: string
+    userName?: string
+    error?: string
+  }> => {
+    try {
+      const response = await fetch(`${url}/api/me`, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${apiKey}:${apiSecret}`,
+          'Content-Type': 'application/json'
+        }
+      })
+
+      if (response.ok) {
+        const data = await response.json()
+        return {
+          success: true,
+          teamName: data.team?.name,
+          teamUuid: data.team?.uuid,
+          userName: data.user?.name
+        }
+      } else {
+        const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+        return { success: false, error: errorData.error || `HTTP ${response.status}` }
+      }
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'Network error' }
+    }
   }
 }
 
 export const add = createTask({
   schema,
   boundaries,
-  fn: async function ({ name, apiKey, apiSecret, url }, { loadProfiles, persistProfiles }) {
+  fn: async function ({ name, apiKey, apiSecret, url }, { loadProfiles, persistProfiles, fetchMeInfo }) {
     const profiles = await loadProfiles({})
 
+    console.log('Verifying credentials...')
+
+    // Fetch team and user information from /me endpoint
+    const meInfo = await fetchMeInfo(apiKey, apiSecret, url)
+
+    if (!meInfo.success) {
+      throw new Error(`Failed to verify credentials: ${meInfo.error}`)
+    }
+
+    console.log('✅ Credentials verified')
+    if (meInfo.userName) {
+      console.log(`   User: ${meInfo.userName}`)
+    }
+    if (meInfo.teamName) {
+      console.log(`   Team: ${meInfo.teamName}`)
+    }
+
+    // Create profile with team information
+    const profile = {
+      name,
+      apiKey,
+      apiSecret,
+      url,
+      teamName: meInfo.teamName,
+      teamUuid: meInfo.teamUuid,
+      userName: meInfo.userName
+    }
+
     // Check if profile with same name already exists
     const existingProfileIndex = profiles.profiles.findIndex(p => p.name === name)
     if (existingProfileIndex >= 0) {
       // Replace existing profile
-      profiles.profiles[existingProfileIndex] = { name, apiKey, apiSecret, url }
+      profiles.profiles[existingProfileIndex] = profile
     } else {
       // Add new profile
-      profiles.profiles.push({ name, apiKey, apiSecret, url })
+      profiles.profiles.push(profile)
     }
 
     // Set as default profile
@@ -51,7 +111,9 @@ export const add = createTask({
 
     return {
       status: 'Ok',
-      message: `Profile '${name}' added and set as default`
+      message: `Profile '${name}' added and set as default`,
+      teamName: meInfo.teamName,
+      userName: meInfo.userName
     }
   }
 })

package/src/tasks/auth/clear.ts

@@ -0,0 +1,63 @@
+// TASK: clear
+// Run this task with:
+// forge task:run auth:clear
+
+import { createTask } from '@forgehive/task'
+import { Schema } from '@forgehive/schema'
+import path from 'path'
+import fs from 'fs/promises'
+import os from 'os'
+
+import { load as loadProfiles } from './load'
+import { type Profiles } from '../types'
+
+const schema = new Schema({})
+
+const boundaries = {
+  loadProfiles: loadProfiles.asBoundary(),
+  clearProfiles: async (): Promise<void> => {
+    const buildsPath = path.join(os.homedir(), '.forge')
+    const profilesPath = path.join(buildsPath, 'profiles.json')
+
+    // Create empty profiles structure
+    const emptyProfiles: Profiles = {
+      default: '',
+      profiles: []
+    }
+
+    await fs.writeFile(profilesPath, JSON.stringify(emptyProfiles, null, 2))
+  }
+}
+
+export const clear = createTask({
+  schema,
+  boundaries,
+  fn: async function (_argv, { loadProfiles, clearProfiles }) {
+    const profiles = await loadProfiles({})
+
+    if (profiles.profiles.length === 0) {
+      console.log('No profiles found to clear.')
+      return { status: 'Ok', message: 'No profiles found' }
+    }
+
+    const profileCount = profiles.profiles.length
+    console.log(`Found ${profileCount} profile(s) to clear:`)
+
+    profiles.profiles.forEach(profile => {
+      console.log(`  - ${profile.name} (${profile.teamName || 'Unknown team'})`)
+    })
+
+    console.log('\\nClearing all profiles...')
+
+    // Clear all profiles
+    await clearProfiles()
+
+    console.log('✅ All profiles cleared successfully')
+
+    return {
+      status: 'Ok',
+      message: `Cleared ${profileCount} profile(s)`,
+      clearedCount: profileCount
+    }
+  }
+})

package/src/tasks/auth/list.ts

@@ -25,19 +25,41 @@ export const list = createTask({
       return { status: 'Ok', profiles: [] }
     }
 
-    console.log('Available profiles:')
+    // Show current profile
+    const currentProfile = profiles.profiles.find(profile => profile.name === profiles.default)
+    if (currentProfile) {
+      console.log('Current Profile:')
+      console.log(`  Name: ${currentProfile.name}`)
+      console.log(`  API Key: ${currentProfile.apiKey}`)
+      console.log(`  URL: ${currentProfile.url}`)
+      if (currentProfile.userName) {
+        console.log(`  User: ${currentProfile.userName}`)
+      }
+      if (currentProfile.teamName) {
+        console.log(`  Team: ${currentProfile.teamName}`)
+      }
+      console.log('')
+    }
+
+    console.log('Available profiles:\n')
+
+    const tableData = profiles.profiles.map(profile => ({
+      Name: profile.name,
+      'API Key': profile.apiKey,
+      URL: profile.url,
+      Team: profile.teamName || 'Unknown',
+      User: profile.userName || 'Unknown'
+    }))
 
-    profiles.profiles.forEach(profile => {
-      const isDefault = profile.name === profiles.default
-      const prefix = isDefault ? '* ' : '  '
-      console.log(`${prefix}${profile.name} - API Key: ${profile.apiKey}`)
-    })
+    console.table(tableData, ['Name', 'API Key', 'URL', 'Team', 'User'])
 
     console.log('\nUse auth:add to create or update a profile')
-    console.log('\nUse auth:switch to switch to a profile')
+    console.log('Use auth:switch [name] or auth:switch [index] to switch profiles')
+    console.log('========================================')
 
     return {
-      default: profiles.default
+      default: profiles.default,
+      profiles: tableData
     }
   }
 })

package/src/tasks/auth/switch.ts

@@ -1,6 +1,6 @@
 // TASK: switch
 // Run this task with:
-// forge task:run auth:switch --profileName [name]
+// forge auth:switch [name] or forge auth:switch [index]
 
 import { createTask } from '@forgehive/task'
 import { Schema } from '@forgehive/schema'
@@ -31,23 +31,39 @@ export const switchProfile = createTask({
     // Load profiles
     const profiles = await loadProfiles({})
 
-    // Check if profile exists
-    const profileExists = profiles.profiles.some(profile => profile.name === profileName)
+    if (profiles.profiles.length === 0) {
+      throw new Error('No profiles found. Use auth:add to create one.')
+    }
+
+    let targetProfile: string
 
-    if (!profileExists) {
-      throw new Error(`Profile "${profileName}" not found. Use auth:list to see available profiles.`)
+    // Check if profileName is a number (index)
+    const indexInput = parseInt(profileName, 10)
+    if (!isNaN(indexInput)) {
+      // Using index
+      if (indexInput < 0 || indexInput >= profiles.profiles.length) {
+        throw new Error(`Profile index ${indexInput} is out of range. Use auth:list to see available profiles (0-${profiles.profiles.length - 1}).`)
+      }
+      targetProfile = profiles.profiles[indexInput].name
+    } else {
+      // Using profile name
+      const profileExists = profiles.profiles.some(profile => profile.name === profileName)
+      if (!profileExists) {
+        throw new Error(`Profile "${profileName}" not found. Use auth:list to see available profiles.`)
+      }
+      targetProfile = profileName
     }
 
     // Update default profile
-    profiles.default = profileName
+    profiles.default = targetProfile
 
     // Save updated profiles
     await persistProfiles(profiles)
 
-    console.log(`Switched to profile: ${profileName}`)
+    console.log(`Switched to profile: ${targetProfile}`)
 
     return {
-      default: profileName
+      default: targetProfile
     }
   }
 })

package/src/tasks/project/README.md

@@ -0,0 +1,268 @@
+# Project Commands
+
+This directory contains ForgeHive CLI commands for project management operations.
+
+## Commands
+
+### `project:create`
+
+Creates a new project in ForgeHive with automatic UUID generation and API integration.
+
+#### Usage
+
+```bash
+forge project:create [--projectName="My Project"] [--description="Project description"]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `projectName` | string | No | Name of the project to create. If not provided, uses the project name from `forge.json` |
+| `description` | string | No | Optional description for the project |
+
+#### Behavior
+
+1. **UUID Management**: Checks if the local `forge.json` has a project UUID
+   - If no UUID exists, generates a new UUID v4 and saves it to `forge.json`
+   - If UUID already exists, uses the existing one
+
+2. **Authentication**: Uses the current profile from `auth:list` for API authentication
+   - Requires a valid profile set via `auth:add` and `auth:switch`
+   - Uses profile's `apiKey`, `apiSecret`, and `url` for the request
+
+3. **API Request**: Makes a POST request to `/api/projects` with:
+   - `projectName`: The provided project name
+   - `description`: The provided description (or empty string if not provided)
+   - `uuid`: The project UUID (generated or existing)
+
+4. **Response**: Returns the created project details including:
+   - Project UUID
+   - Project name
+   - Team information
+   - Creation timestamps
+
+#### Examples
+
+```bash
+# Create a project using the name from forge.json
+forge project:create
+
+# Create a project with custom name
+forge project:create --projectName="My New Project"
+
+# Create a project with custom name and description
+forge project:create --projectName="Analytics Dashboard" --description="Customer analytics and reporting platform"
+
+# Create a project using forge.json name but with description
+forge project:create --description="Using the default project name from configuration"
+```
+
+#### Success Output
+
+```
+Generated and saved project UUID: 550e8400-e29b-41d4-a716-446655440000
+Project created successfully!
+Project UUID: 550e8400-e29b-41d4-a716-446655440000
+Project Name: My New Project
+
+🌐 View your project on the dashboard: https://api.forgehive.com/dashboard/projects/550e8400-e29b-41d4-a716-446655440000
+```
+
+#### Error Cases
+
+- **No Project Name**: If no `--projectName` is provided and `forge.json` doesn't contain a project name
+- **No Profile**: If no authentication profile is configured
+- **Invalid Profile**: If the current profile is invalid or expired
+- **API Errors**: Network issues, server errors, or validation failures
+- **Duplicate Names**: If a project with the same name already exists in the team
+
+#### File Changes
+
+When run, this command may modify:
+- `forge.json`: Adds or updates the project UUID if one doesn't exist
+
+#### Dependencies
+
+- Requires `@forgehive/task` framework
+- Requires `@forgehive/schema` for validation
+- Uses `uuid` package for UUID generation
+- Integrates with `auth:loadCurrent` for profile management
+- Integrates with `conf:load` for configuration management
+
+#### API Integration
+
+This command integrates with the ForgeHive Projects API. See the [Projects API Documentation](../../../../../../../hive/docs/projects-api.md) for detailed API specifications.
+
+---
+
+## Project Configuration
+
+Projects are configured via the `forge.json` file in your project root:
+
+```json
+{
+  "project": {
+    "name": "My Project",
+    "uuid": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+The UUID is automatically generated and managed by the CLI commands.
+
+---
+
+### `project:link`
+
+Links an existing remote project to the local project by validating the UUID and updating forge.json.
+
+#### Usage
+
+```bash
+forge project:link [uuid]
+```
+
+#### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uuid` | string (UUID) | Yes | UUID of the existing remote project to link |
+
+#### Behavior
+
+1. **UUID Validation**: Validates the provided UUID format using regex
+2. **Remote Verification**: Makes a GET request to `/api/projects/{uuid}` to verify the project exists
+3. **Authentication**: Uses the current profile for API authentication
+4. **Project Details**: Displays project information (name, description, task count) if found
+5. **Local Update**: Updates the local `forge.json` with the verified UUID
+
+#### Examples
+
+```bash
+# Link to an existing remote project
+forge project:link 550e8400-e29b-41d4-a716-446655440000
+```
+
+#### Success Output
+
+```
+Checking if project 550e8400-e29b-41d4-a716-446655440000 exists on https://api.forgehive.com...
+✓ Found project: Customer Analytics
+  Description: Analytics platform for customer behavior analysis
+  Tasks: 3 task(s)
+
+✓ Successfully linked project 550e8400-e29b-41d4-a716-446655440000 to local forge.json
+  Local project name: My Local Project
+  Remote project name: Customer Analytics
+
+🌐 View your project on the dashboard: https://api.forgehive.com/dashboard/projects/550e8400-e29b-41d4-a716-446655440000
+```
+
+#### Error Cases
+
+- **Invalid UUID Format**: If the provided UUID doesn't match the expected format
+- **Project Already Linked**: If the local project already has a UUID in forge.json
+- **Project Not Found**: If the UUID doesn't exist on the remote server (404)
+- **Authentication Failed**: If the current profile credentials are invalid (401)
+- **No Profile**: If no authentication profile is configured
+- **Network Issues**: Connection problems or server errors
+
+#### Error Examples
+
+```bash
+# Invalid UUID format
+forge project:link invalid-uuid
+# Error: Invalid UUID format: invalid-uuid. Please provide a valid UUID.
+
+# Project already linked
+forge project:link 550e8400-e29b-41d4-a716-446655440000
+# Error: Project is already linked to UUID: 123e4567-e89b-12d3-a456-426614174000. Use a different project or remove the existing UUID from forge.json first.
+
+# Project not found
+forge project:link 00000000-0000-0000-0000-000000000000
+# Error: Project with UUID 00000000-0000-0000-0000-000000000000 not found on https://api.forgehive.com. Please verify the UUID is correct.
+
+# Authentication failed
+forge project:link 550e8400-e29b-41d4-a716-446655440000
+# Error: Authentication failed. Please check your profile credentials with 'forge auth:list'.
+```
+
+#### File Changes
+
+When run successfully, this command modifies:
+- `forge.json`: Updates the `project.uuid` field with the verified remote project UUID
+
+#### Dependencies
+
+- Requires `@forgehive/task` framework
+- Requires `@forgehive/schema` for validation
+- Integrates with `auth:loadCurrent` for profile management
+- Integrates with `conf:load` for configuration management
+- Uses the ForgeHive Projects API `/api/projects/{uuid}` endpoint
+
+---
+
+### `project:unlink`
+
+Removes the project UUID link from the local forge.json, allowing the project to be linked to a different remote project.
+
+#### Usage
+
+```bash
+forge project:unlink
+```
+
+#### Parameters
+
+This command takes no parameters.
+
+#### Behavior
+
+1. **UUID Check**: Verifies that a project UUID exists in forge.json
+2. **Local Update**: Removes the UUID field from the project configuration
+3. **Confirmation**: Shows the UUID that was removed and next steps
+
+#### Examples
+
+```bash
+# Unlink the current project
+forge project:unlink
+```
+
+#### Success Output
+
+```
+✓ Successfully unlinked project from UUID: 550e8400-e29b-41d4-a716-446655440000
+  The project is no longer linked to a remote project.
+  You can now link to a different project using 'forge project:link [uuid]'
+```
+
+#### Error Cases
+
+- **No UUID Found**: If the project is not currently linked (no UUID in forge.json)
+
+#### Error Examples
+
+```bash
+# No project linked
+forge project:unlink
+# Error: No project UUID found in forge.json. The project is not currently linked to a remote project.
+```
+
+#### File Changes
+
+When run successfully, this command modifies:
+- `forge.json`: Removes the `project.uuid` field completely
+
+#### Dependencies
+
+- Requires `@forgehive/task` framework
+- Requires `@forgehive/schema` for validation
+- Integrates with `conf:load` for configuration management
+
+**Note**: This command only affects the local forge.json file. It does not make any API calls or modify anything on the remote server.
+
+---
+
+## Project Configuration