@porchestra/cli 1.0.0

package/src/commands/explore.ts

@@ -0,0 +1,160 @@
+import { Command } from 'commander';
+import { select, checkbox, confirm, Separator } from '@inquirer/prompts';
+import pc from 'picocolors';
+import ora from 'ora';
+import { ApiClient } from '../core/api/client.js';
+import { ConfigManager } from '../core/config/config-manager.js';
+import { ProjectTracker } from '../core/config/project-tracker.js';
+import { formatDate } from '../utils/date.js';
+
+interface ExploreOptions {
+  project?: string;
+}
+
+interface ProjectChoice {
+  name: string;
+  value: any;
+  short?: string;
+}
+
+export function createExploreCommand(
+  configManager: ConfigManager,
+  apiClient: ApiClient
+): Command {
+  const projectTracker = new ProjectTracker(configManager);
+
+  return new Command('explore')
+    .description('Explore and select projects/agents to track')
+    .option('-p, --project <id>', 'Start with specific project')
+    .action(async (options: ExploreOptions) => {
+      const spinner = ora('Fetching projects...').start();
+      
+      try {
+        // Fetch all projects
+        const response = await apiClient.getProjectsBrief();
+        const projects = response.projects;
+        spinner.stop();
+
+        if (projects.length === 0) {
+          console.log(pc.yellow('No projects found. Create one in the web app first.'));
+          return;
+        }
+
+        // Project selection loop
+        let exploring = true;
+        while (exploring) {
+          const projectChoices: ProjectChoice[] = projects.map((p) => ({
+            name: `${p.name} ${pc.gray(`(${p.agentCount} agents, last modified ${formatDate(p.lastModifiedAt)})`)}`,
+            value: p,
+            short: p.name
+          }));
+
+          let selectedProject: any;
+          if (options.project) {
+            selectedProject = projects.find((p) => p.id === options.project || p.slug === options.project);
+          } else {
+            const choices: any[] = [
+              ...projectChoices,
+              new Separator(),
+              { name: pc.yellow('Done exploring'), value: 'DONE' }
+            ];
+            selectedProject = await select({
+              message: 'Select a project to explore:',
+              choices
+            });
+          }
+
+          if (selectedProject === 'DONE') {
+            exploring = false;
+            break;
+          }
+
+          if (!selectedProject) {
+            console.log(pc.red('Project not found'));
+            continue;
+          }
+
+          // Fetch agents for selected project
+          const agentSpinner = ora(`Fetching agents for ${selectedProject.name}...`).start();
+          const agentsResponse = await apiClient.getProjectAgents(selectedProject.id);
+          const agents = agentsResponse;
+          agentSpinner.succeed(`Found ${agents.agents.length} agents`);
+
+          // Display agents with folder paths
+          console.log(pc.bold(`\n📁 ${selectedProject.name}\n`));
+          
+          agents.agents.forEach((agent) => {
+            const isPublished = agent.isPublished 
+              ? pc.green('●') 
+              : pc.gray('○');
+            const versionInfo = `${agent.version} ${pc.gray(`(${agents.versionResolution.source})`)}`;
+            
+            console.log(`  ${isPublished} ${pc.cyan(agent.name)}`);
+            console.log(`     ${pc.gray('Path:')} ${agent.folderPath}`);
+            console.log(`     ${pc.gray('Version:')} ${versionInfo}`);
+            console.log(`     ${pc.gray('Tools:')} ${agent.toolCount}`);
+            if (agents.versionResolution.source !== 'PRODUCTION') {
+              console.log(`     ${pc.yellow('⚠')} ${agents.versionResolution.note}`);
+            }
+            console.log();
+          });
+
+          // Agent selection
+          const currentlyTracked = await projectTracker.getTrackedAgents(selectedProject.id);
+          const trackedIds = new Set(currentlyTracked.map(a => a.agentId));
+
+          const selectedAgentIds = await checkbox({
+            message: 'Select agents to track (space to toggle, enter to confirm):',
+            choices: agents.agents.map((agent) => ({
+              name: `${agent.name} ${pc.gray(`(${agent.folderPath})`)}`,
+              value: agent.id,
+              checked: trackedIds.has(agent.id)
+            }))
+          });
+
+          // Update tracking - IMMEDIATE AUTO-SAVE
+          if (selectedAgentIds.length > 0) {
+            const selectedAgents = agents.agents.filter((a) => selectedAgentIds.includes(a.id));
+            try {
+              await projectTracker.trackProject(selectedProject, selectedAgents);
+              console.log(pc.green(`\n✓ Auto-saved: Tracking ${selectedAgents.length} agents from ${selectedProject.name}`));
+            } catch (error) {
+              console.error(pc.red(`\n✗ Failed to save tracking: ${(error as Error).message}`));
+              throw error; // RETHROW - don't silently fail
+            }
+          } else {
+            try {
+              await projectTracker.untrackProject(selectedProject.id);
+              console.log(pc.yellow(`\n✓ Auto-saved: No longer tracking ${selectedProject.name}`));
+            } catch (error) {
+              console.error(pc.red(`\n✗ Failed to untrack: ${(error as Error).message}`));
+              throw error; // RETHROW - don't silently fail
+            }
+          }
+
+          // Continue?
+          if (!options.project) {
+            const continueExploring = await confirm({
+              message: 'Explore another project?',
+              default: true
+            });
+            if (!continueExploring) exploring = false;
+          } else {
+            exploring = false;
+          }
+        }
+
+        // Summary
+        const summary = await projectTracker.getSummary();
+        console.log(pc.bold('\n📊 Tracking Summary\n'));
+        console.log(`  Projects: ${summary.projectCount}`);
+        console.log(`  Agents:   ${summary.agentCount}`);
+        console.log(pc.gray('\nRun `porchestra pull` to generate code for tracked agents\n'));
+
+      } catch (error) {
+        spinner.fail('Failed to fetch projects');
+        console.error(pc.red(`\n✗ ${(error as Error).message}`));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/login.ts

@@ -0,0 +1,101 @@
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { input, password } from '@inquirer/prompts';
+import { ConfigManager } from '../core/config/config-manager.js';
+import { AuthService } from '../core/auth/auth-service.js';
+
+interface LoginOptions {
+  apiUrl?: string;
+  skipTlsVerify?: boolean;
+}
+
+export function createLoginCommand(
+  configManager: ConfigManager,
+  authService: AuthService
+): Command {
+  return new Command('login')
+    .description('Authenticate with your Porchestra account')
+    .option('--api-url <url>', 'Override API URL')
+    .option('--skip-tls-verify', 'Skip TLS certificate verification (insecure)')
+    .action(async (options: LoginOptions) => {
+      console.log(pc.bold('\n  \uD83D\uDD10 Porchestra CLI Login\n'));
+
+      const apiUrl = options.apiUrl || process.env.PORCHESTRA_API_URL;
+      
+      if (options.skipTlsVerify) {
+        console.log(pc.yellow('\n  \u26A0\uFE0F  WARNING: TLS verification disabled. Not recommended for production.\n'));
+      }
+
+      const email = await input({
+        message: '  Email:',
+        validate: (value) => value.includes('@') || 'Please enter a valid email'
+      });
+
+      const pwd = await password({
+        message: '  Password:',
+        mask: '*'
+      });
+
+      try {
+        const result = await authService.login({
+        email,
+        password: pwd,
+        apiUrl,
+        skipTlsVerify: options.skipTlsVerify
+      });
+
+        // DEBUG: Log raw API response
+        console.log(pc.yellow('\n  [DEBUG] Raw API response:'));
+        console.log(pc.yellow(`    token: ${result.token?.substring(0, 20)}...`));
+        console.log(pc.yellow(`    tokenId: ${result.tokenId}`));
+        console.log(pc.yellow(`    expiresAt: ${result.expiresAt}`));
+        console.log(pc.yellow(`    issuedAt: ${result.issuedAt}`));
+        console.log(pc.yellow(`    deviceName: ${result.deviceName}`));
+
+        try {
+          await configManager.update((cfg) => ({
+            ...cfg,
+            auth: {
+              token: result.token,
+              tokenId: result.tokenId,
+              expiresAt: result.expiresAt,
+              deviceName: result.deviceName
+            },
+            api: {
+              baseUrl: apiUrl || cfg.api?.baseUrl || 'https://api.porchestra.io/v1',
+              skipTlsVerify: options.skipTlsVerify || false
+            },
+            cli: {
+              ...cfg.cli,
+              lastLoginAt: new Date().toISOString()
+            }
+          }));
+          
+          // DEBUG: Verify config was saved
+          const savedConfig = await configManager.get();
+          console.log(pc.yellow('\n  [DEBUG] Saved config auth:'));
+          console.log(pc.yellow(`    ${JSON.stringify(savedConfig.auth, null, 2)}`));
+        } catch (saveError) {
+          console.error(pc.red('\n  [DEBUG] Save error:'), saveError);
+          throw saveError;
+        }
+
+        const expiresAt = new Date(result.expiresAt);
+        const daysUntilExpiry = Math.ceil((expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+
+        console.log(pc.green(`
+  ✓ Login successful
+        `));
+        console.log(pc.gray(`  Token expires in ${daysUntilExpiry} days (${result.expiresAt})`));
+        console.log(pc.gray(`  Device: ${result.deviceName}`));
+        if (apiUrl) {
+          console.log(pc.gray(`  API: ${apiUrl}`));
+        }
+        console.log(pc.gray(`  Auto-refresh: 7 days before expiry`));
+        console.log();
+      } catch (error) {
+        console.error(pc.red(`\n  \u2717 Login failed: ${(error as Error).message}`));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/logout.ts

@@ -0,0 +1,52 @@
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { confirm } from '@inquirer/prompts';
+import { AuthService } from '../core/auth/auth-service.js';
+import { ConfigManager } from '../core/config/config-manager.js';
+
+interface LogoutOptions {
+  all?: boolean;
+}
+
+export function createLogoutCommand(
+  configManager: ConfigManager,
+  authService: AuthService
+): Command {
+  return new Command('logout')
+    .description('Logout and revoke CLI token')
+    .option('--all', 'Revoke all device tokens (logout everywhere)')
+    .action(async (options: LogoutOptions) => {
+      const config = await configManager.get();
+      
+      if (!config.auth?.token) {
+        console.log(pc.yellow('Not currently logged in'));
+        return;
+      }
+
+      if (options.all) {
+        const confirmed = await confirm({
+          message: 'This will revoke ALL your CLI tokens on ALL devices. Continue?',
+          default: false
+        });
+        if (!confirmed) return;
+      }
+
+      try {
+        // Revoke on server
+        await authService.revokeToken(config.auth.token, options.all);
+        
+        // Clear local config
+        await configManager.clear();
+
+        if (options.all) {
+          console.log(pc.green('✓ Revoked all tokens and logged out all devices'));
+        } else {
+          console.log(pc.green('✓ Logged out successfully'));
+        }
+      } catch (error) {
+        // Even if server revoke fails, clear local config
+        await configManager.clear();
+        console.log(pc.yellow('✓ Cleared local credentials (server revoke may have failed)'));
+      }
+    });
+}

package/src/commands/pull.ts

@@ -0,0 +1,220 @@
+import { Command } from 'commander';
+import path from 'path';
+import pc from 'picocolors';
+import ora from 'ora';
+import { ApiClient } from '../core/api/client.js';
+import { ConfigManager } from '../core/config/config-manager.js';
+import { CodeGenerator } from '../core/generators/code-generator.js';
+import { ProjectTracker } from '../core/config/project-tracker.js';
+
+interface PullOptions {
+  project?: string;
+  agent?: string;
+  version?: string;
+  env?: 'PRODUCTION' | 'STAGING' | 'DEVELOPMENT';
+  output?: string;
+  force?: boolean;
+}
+
+export function createPullCommand(
+  configManager: ConfigManager,
+  apiClient: ApiClient,
+  codeGenerator: CodeGenerator
+): Command {
+  const projectTracker = new ProjectTracker(configManager);
+
+  return new Command('pull')
+    .description('Generate tool code for tracked agents')
+    .option('-p, --project <id>', 'Pull specific project only')
+    .option('-a, --agent <id>', 'Pull specific agent only')
+    .option('-e, --env <environment>', 'Target environment (production|staging|development)')
+    .option('-o, --output <path>', 'Override output directory')
+    .option('--force', 'Overwrite implementation files (WARNING: may lose code)')
+    .action(async (options: PullOptions) => {
+      // Check if logged in
+      const config = await configManager.get();
+      if (!config.auth?.token) {
+        console.log(pc.red('Not logged in. Run `porchestra login` first.'));
+        process.exit(1);
+      }
+
+      // Get tracked projects
+      let trackedProjects = await projectTracker.getTrackedProjects();
+
+      // Auto-trigger explore if no projects tracked
+      if (trackedProjects.length === 0) {
+        console.log(pc.yellow('\n⚠ No projects selected for tracking.\n'));
+        console.log(pc.gray('Starting project explorer...\n'));
+        
+        // Import and run explore dynamically
+        const { createExploreCommand } = await import('./explore.js');
+        const exploreCmd = createExploreCommand(configManager, apiClient);
+        // Execute the explore command to let user select projects
+        await exploreCmd.parseAsync(['node', 'script', 'explore']);
+        
+        // Re-check tracking after explore
+        trackedProjects = await projectTracker.getTrackedProjects();
+        
+        if (trackedProjects.length === 0) {
+          console.log(pc.red('\n❌ No projects selected. Run `porchestra explore` to select projects.'));
+          process.exit(1);
+        }
+      }
+
+      // Filter by options
+      if (options.project) {
+        trackedProjects = trackedProjects.filter(
+          p => p.projectId === options.project || p.projectSlug === options.project
+        );
+        if (trackedProjects.length === 0) {
+          console.log(pc.red(`Project "${options.project}" not found in tracked projects`));
+          process.exit(1);
+        }
+      }
+
+      // Pull each project
+      const baseOutputDir = options.output || config.output?.baseDir || path.resolve(process.cwd(), 'src/porchestra/agents');
+      let totalAgents = 0;
+      let successCount = 0;
+
+      for (const project of trackedProjects) {
+        // Filter agents if specified
+        let agents = project.agents;
+        if (options.agent) {
+          agents = agents.filter(
+            a => a.agentId === options.agent || a.agentSlug === options.agent
+          );
+        }
+
+        if (agents.length === 0) continue;
+
+        console.log(pc.bold(`\n📦 ${project.projectName}\n`));
+        totalAgents += agents.length;
+
+        // Process each agent with progress
+        for (let i = 0; i < agents.length; i++) {
+          const agent = agents[i];
+          const progress = `[${i + 1}/${agents.length}]`;
+          const spinner = ora(`${progress} Fetching ${agent.agentName}...`).start();
+
+          try {
+            // Fetch agent tools
+            const toolsResponse = await apiClient.getAgentTools(
+              project.projectId,
+              agent.agentId,
+              options.env
+            );
+
+            spinner.text = `${progress} Generating code...`;
+
+            const normalizeToolset = (toolset: any[] = []) =>
+              toolset.map((t, idx) => ({
+                id: t.id ?? `toolset-${idx}`,
+                name: t.name,
+                description: t.description ?? '',
+                parameters: t.parameters ?? {},
+                returns: t.returns ?? null,
+                isBuiltin: t.isBuiltin ?? false,
+                builtinType: t.builtinType,
+              }));
+
+            const rawToolConfig = toolsResponse?.components?.toolConfig?.content as any;
+            const parsedToolConfig = (() => {
+              if (typeof rawToolConfig === 'string') {
+                try {
+                  return JSON.parse(rawToolConfig);
+                } catch {
+                  return undefined;
+                }
+              }
+              return rawToolConfig;
+            })();
+
+            const findToolArray = (value: any): any[] | undefined => {
+              if (Array.isArray(value)) {
+                const hasNamedObjects = value.every(v => v && typeof v === 'object' && 'name' in v);
+                return hasNamedObjects ? value : undefined;
+              }
+              if (value && typeof value === 'object') {
+                if (Array.isArray(value.toolset)) return value.toolset;
+                if (Array.isArray(value.tools)) return value.tools;
+                for (const key of Object.keys(value)) {
+                  const found = findToolArray((value as any)[key]);
+                  if (found) return found;
+                }
+              }
+              return undefined;
+            };
+
+            const toolsetFromConfig = findToolArray(parsedToolConfig) ?? [];
+
+            const resolvedTools = (toolsResponse?.tools && toolsResponse.tools.length > 0)
+              ? toolsResponse.tools
+              : (Array.isArray(toolsResponse?.toolset)
+                  ? normalizeToolset(toolsResponse.toolset)
+                  : normalizeToolset(toolsetFromConfig));
+
+            if (!toolsResponse?.agent || !toolsResponse?.components) {
+              throw new Error('Invalid tools response from API');
+            }
+
+            // Generate code
+            const outputDir = codeGenerator.calculateOutputPath(
+              baseOutputDir,
+              agent.folderPath,
+              toolsResponse.agent.name
+            );
+
+            await codeGenerator.generate({
+              agent: toolsResponse.agent,
+              tools: resolvedTools,
+              components: toolsResponse.components,
+              outputDir,
+              forceOverwrite: options.force || false
+            });
+
+            spinner.succeed(`${progress} ${agent.agentName} → ${pc.gray(outputDir)}`);
+            successCount++;
+
+            // Update last pulled info
+            await projectTracker.updateLastPulled(
+              project.projectId,
+              agent.agentId,
+              toolsResponse.agent.version
+            );
+
+          } catch (error) {
+            spinner.fail(`${progress} ${agent.agentName}`);
+            console.error(pc.red(`   ✗ ${(error as Error).message}`));
+          }
+        }
+      }
+
+      // Summary
+      console.log(pc.bold('\n✨ Pull Complete\n'));
+      
+      if (successCount === totalAgents) {
+        console.log(`  ${pc.green('✓')} Generated: ${successCount} / ${totalAgents} agents`);
+      } else if (successCount > 0) {
+        console.log(`  ${pc.yellow('⚠')} Generated: ${successCount} / ${totalAgents} agents`);
+        console.log(`  ${pc.red('✗')} Failed: ${totalAgents - successCount} agents`);
+      } else {
+        console.log(`  ${pc.red('✗')} Failed: All ${totalAgents} agents`);
+      }
+      
+      console.log(`  Output: ${pc.gray(baseOutputDir)}`);
+      
+      if (successCount > 0) {
+        console.log(pc.gray('\nNext steps:'));
+        console.log(pc.gray('  1. Implement tool functions in tool-impl.ts files'));
+        console.log(pc.gray('  2. Import and use the tool dispatcher in your code'));
+      }
+      
+      console.log();
+      
+      // Exit with error if any agents failed
+      if (successCount < totalAgents) {
+        process.exit(1);
+      }
+    });
+}

package/src/commands/status.ts

@@ -0,0 +1,78 @@
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { ConfigManager } from '../core/config/config-manager.js';
+import { ProjectTracker } from '../core/config/project-tracker.js';
+import { formatDistanceToNow } from '../utils/date.js';
+
+export function createStatusCommand(
+  configManager: ConfigManager
+): Command {
+  const projectTracker = new ProjectTracker(configManager);
+
+  return new Command('status')
+    .description('Show CLI status and tracked projects')
+    .action(async () => {
+      const config = await configManager.get();
+      
+      console.log(pc.bold('\n📊 Porchestra CLI Status\n'));
+
+      // Auth status
+      if (config.auth?.token) {
+        const expiresAt = new Date(config.auth.expiresAt!);
+        const daysUntilExpiry = Math.ceil(
+          (expiresAt.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
+        );
+        const expiryColor = daysUntilExpiry < 7 ? pc.yellow : pc.green;
+        
+        console.log(pc.bold('🔑 Authentication'));
+        console.log(`  Status:   ${pc.green('✓ Logged in')}`);
+        console.log(`  Device:   ${config.auth.deviceName}`);
+        console.log(`  Expires:  ${expiryColor(daysUntilExpiry + ' days')} (${config.auth.expiresAt})`);
+      } else {
+        console.log(pc.bold('🔑 Authentication'));
+        console.log(`  Status:   ${pc.yellow('✗ Not logged in')}`);
+        console.log(pc.gray('  Run `porchestra login` to authenticate'));
+      }
+
+      // API Configuration
+      console.log(pc.bold('\n🔗 API Configuration'));
+      console.log(`  URL:      ${config.api?.baseUrl || pc.gray('(default)')}`);
+      if (config.api?.skipTlsVerify) {
+        console.log(pc.yellow(`  ⚠️ TLS verification disabled`));
+      }
+
+      // Tracked Projects
+      const projects = await projectTracker.getTrackedProjects();
+      console.log(pc.bold('\n📁 Tracked Projects'));
+      
+      if (projects.length === 0) {
+        console.log(pc.gray('  No projects tracked'));
+        console.log(pc.gray('  Run `porchestra explore` to select projects'));
+      } else {
+        console.log(`  Projects: ${projects.length}`);
+        console.log(`  Agents:   ${projects.reduce((sum, p) => sum + p.agents.length, 0)}`);
+        
+        projects.forEach(project => {
+          const lastPulled = project.lastPulledAt 
+            ? formatDistanceToNow(new Date(project.lastPulledAt))
+            : pc.gray('never');
+          
+          console.log(pc.gray(`\n  ${project.projectName}`));
+          project.agents.forEach(agent => {
+            const agentPulled = agent.lastPulledAt
+              ? formatDistanceToNow(new Date(agent.lastPulledAt))
+              : pc.gray('pending');
+            console.log(pc.gray(`    └─ ${agent.agentName} ${pc.cyan(agent.folderPath)} (${agentPulled})`));
+          });
+          console.log(pc.gray(`    Last pulled: ${lastPulled}`));
+        });
+      }
+
+      // Output Configuration
+      console.log(pc.bold('\n📂 Output Configuration'));
+      console.log(`  Base dir: ${config.output?.baseDir || './src/agents'}`);
+      console.log(`  Index files: ${config.output?.createIndexFiles ? 'yes' : 'no'}`);
+
+      console.log();
+    });
+}

package/src/commands/whoami.ts

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import pc from 'picocolors';
+import { AuthService } from '../core/auth/auth-service.js';
+import { ConfigManager } from '../core/config/config-manager.js';
+import { ProjectTracker } from '../core/config/project-tracker.js';
+
+export function createWhoamiCommand(
+  configManager: ConfigManager,
+  authService: AuthService
+): Command {
+  const projectTracker = new ProjectTracker(configManager);
+
+  return new Command('whoami')
+    .description('Show current user and token information')
+    .action(async () => {
+      const config = await configManager.get();
+      
+      if (!config.auth?.token) {
+        console.log(pc.yellow('Not logged in. Run `porchestra login`'));
+        return;
+      }
+
+      try {
+        const userInfo = await authService.getCurrentUser(config.auth.token);
+        const expiresAt = new Date(config.auth.expiresAt!);
+        const isExpiringSoon = expiresAt.getTime() - Date.now() < 7 * 24 * 60 * 60 * 1000;
+
+        console.log(pc.bold('\n👤 User Information\n'));
+        console.log(`  Email:    ${pc.cyan(userInfo.email)}`);
+        console.log(`  Name:     ${userInfo.name || 'N/A'}`);
+        
+        console.log(pc.bold('\n🔑 Token Information\n'));
+        console.log(`  Device:   ${config.auth.deviceName || 'N/A'}`);
+        console.log(`  Expires:  ${isExpiringSoon ? pc.yellow(expiresAt.toISOString()) : pc.green(expiresAt.toISOString())}`);
+        
+        if (isExpiringSoon) {
+          console.log(pc.yellow('  ⚠️  Expires within 7 days - will auto-refresh'));
+        }
+        
+        if (config.api?.baseUrl !== 'https://api.porchestra.io/v1') {
+          console.log(pc.bold('\n🔗 API Configuration\n'));
+          console.log(`  URL:      ${config.api?.baseUrl}`);
+        }
+
+        // Show tracked projects summary
+        const summary = await projectTracker.getSummary();
+        console.log(pc.bold('\n📁 Tracked Projects\n'));
+        console.log(`  Projects: ${summary.projectCount}`);
+        console.log(`  Agents:   ${summary.agentCount}`);
+
+      } catch (error) {
+        console.log(pc.red('Failed to fetch user info. Token may be invalid.'));
+        console.log(pc.gray('Run `porchestra login` to re-authenticate.'));
+      }
+    });
+}