@profoundlogic/coderflow-cli 0.2.1

package/lib/help.js

@@ -0,0 +1,444 @@
+/**
+ * Help text and usage information
+ */
+
+const commandHelp = {
+  apply: `
+Usage: coder apply [task-id] [options]
+
+Apply patches from a completed task to your local repositories.
+Changes are staged (git add) but not committed.
+
+Arguments:
+  task-id               Task ID to apply (optional - interactive selection if omitted)
+
+Options:
+  --include=<pattern>   Only apply files matching glob pattern
+
+Examples:
+  coder apply                              # Interactive selection from completed tasks
+  coder apply 1759542727986-3uoyf48lr      # Apply specific task
+  coder apply --include="*.js"             # Only apply JavaScript files
+`,
+
+  discard: `
+Usage: coder discard [options]
+
+Discard all uncommitted changes from repositories (unstage, restore, clean).
+Use this to undo changes applied with 'coder apply'.
+
+Options:
+  --env=<environment>   Environment to discard changes from (uses default if omitted)
+  --yes                 Skip confirmation prompt
+
+Examples:
+  coder discard                   # Discard changes in default environment
+  coder discard --env=hello       # Discard changes in specific environment
+  coder discard --yes             # Skip confirmation
+`,
+
+  attach: `
+Usage: coder attach [container-id] [options]
+
+Connect to a running container.
+
+Arguments:
+  container-id          Container ID to attach to (optional - uses last container if omitted)
+
+Options:
+  --agent=<agent>       Agent to use (claude, codex)
+  --shell               Start bash shell instead of agent
+
+Examples:
+  coder attach                          # Reconnect to last container
+  coder attach 188b8e72d656             # Connect to specific container
+  coder attach --shell                  # Connect with bash shell
+  coder attach --agent=codex            # Connect with specific agent
+`,
+
+  login: `
+Usage: coder login [options]
+
+Authenticate with the CoderFlow server.
+
+Options:
+  --sso    Use Single Sign-On (OIDC) authentication
+
+Without --sso, prompts for username and password.
+With --sso, opens browser for OIDC device flow authentication.
+
+Examples:
+  coder login          # Username/password login
+  coder login --sso    # SSO/OIDC login
+`,
+
+  config: `
+Usage: coder config <command> [key] [value]
+
+Manage CLI configuration settings.
+
+Commands:
+  show                  Show all configuration
+  get <key>             Get a configuration value
+  set <key> <value>     Set a configuration value
+  remove <key>          Remove a configuration value
+
+Keys:
+  serverUrl             Server URL
+  apiKey                API key (use 'coder login' instead)
+  defaultEnvironment    Default environment for commands
+
+Examples:
+  coder config show
+  coder config set serverUrl http://localhost:3000
+  coder config get serverUrl
+  coder config remove defaultEnvironment
+`,
+
+  profile: `
+Usage: coder profile <command> [options]
+
+Manage CLI configuration profiles for multiple servers/environments.
+
+Commands:
+  list                    List all profiles
+  show [name]             Show profile details (active if no name)
+  create <name>           Create a new profile
+  switch <name>           Switch to a different profile
+  delete <name>           Delete a profile
+  copy <source> <dest>    Copy a profile
+  set <key> <value>       Set a value in the active profile
+  get <key>               Get a value from the active profile
+  current                 Show the current active profile name
+  migrate <name>          Create profile from legacy config
+
+Examples:
+  coder profile list
+  coder profile create prod
+  coder profile switch prod
+  coder profile set serverUrl https://prod.example.com
+  coder --profile=prod list             # Use profile for single command
+`,
+
+  run: `
+Usage: coder run [task-type] [options]
+
+Create and run a task. Usually done in the Web UI, but available here
+for scripting or when browser access isn't available.
+
+Arguments:
+  task-type             Task template name (optional - interactive if omitted)
+
+Options:
+  --env=<environment>   Environment to run in
+  --<param>=<value>     Template parameters (varies by template)
+
+Examples:
+  coder run                                          # Interactive task creation
+  coder run add-function --function_name=multiply    # Run with template
+  coder run fix-test --env=hello --verbose=true      # Specify environment
+`,
+
+  status: `
+Usage: coder status <task-id>
+
+Check the status of a task.
+
+Arguments:
+  task-id               Task ID to check (required)
+
+Examples:
+  coder status 1759542727986-3uoyf48lr
+`,
+
+  results: `
+Usage: coder results <task-id>
+
+Get the results of a completed task.
+
+Arguments:
+  task-id               Task ID to get results for (required)
+
+Examples:
+  coder results 1759542727986-3uoyf48lr
+`,
+
+  logs: `
+Usage: coder logs <task-id> [options]
+
+Show logs from a task.
+
+Arguments:
+  task-id               Task ID to show logs for (required)
+
+Options:
+  --tail=<N>            Show last N lines only
+
+Examples:
+  coder logs 1759542727986-3uoyf48lr
+  coder logs 1759542727986-3uoyf48lr --tail=100
+`,
+
+  list: `
+Usage: coder list [options]
+
+List tasks with optional filters.
+
+Options:
+  --status=<status>         Filter by status (pending, running, completed, failed)
+  --environment=<name>      Filter by environment
+
+Examples:
+  coder list
+  coder list --status=completed
+  coder list --environment=hello --status=running
+`,
+
+  reject: `
+Usage: coder reject <task-id> [options]
+
+Reject task results.
+
+Arguments:
+  task-id               Task ID to reject (required)
+
+Options:
+  --cleanup             Also delete task artifacts
+
+Examples:
+  coder reject 1759542727986-3uoyf48lr
+  coder reject 1759542727986-3uoyf48lr --cleanup
+`,
+
+  start: `
+Usage: coder start <environment> [options]
+
+Start an interactive session with an AI agent.
+Usually done in the Web UI, but available here for CLI workflows.
+
+Arguments:
+  environment           Environment to start session in (required)
+
+Options:
+  --agent=<agent>               Agent to use (claude, codex)
+  --no-attach                   Start container but don't auto-connect
+  --branch <repo>=<branch>      Override branch for specific repository
+  --env=<KEY>=<value>           Pass custom environment variables
+
+Examples:
+  coder start hello
+  coder start hello --agent=codex
+  coder start hello --no-attach
+  coder start hello --branch profoundjs=feature-xyz
+`,
+
+  shell: `
+Usage: coder shell <environment> [options]
+
+Start an interactive bash shell session in an environment.
+Usually done in the Web UI, but available here for CLI workflows.
+
+Arguments:
+  environment           Environment to start shell in (required)
+
+Options:
+  --no-attach                   Start container but don't auto-connect
+  --branch <repo>=<branch>      Override branch for specific repository
+  --env=<KEY>=<value>           Pass custom environment variables
+
+Examples:
+  coder shell hello
+  coder shell hello --branch profoundjs=feature-xyz
+`,
+
+  test: `
+Usage: coder test <test-name> [options]
+
+Run tests in an ephemeral container with your local repository state.
+
+Arguments:
+  test-name             Name of the test to run (from environment's tests.json)
+
+Options:
+  --env=<environment>   Environment to run test in (uses default if omitted)
+  --cmd="<command>"     Run custom command instead of named test
+  --list                List available tests for the environment
+  --no-local-state      Don't capture local repo state
+
+Examples:
+  coder test mytest --env=hello           # Run named test
+  coder test --list --env=hello           # List available tests
+  coder test --cmd="npm test"             # Run custom command
+  coder test mytest --no-local-state      # Run without local changes
+`,
+
+  containers: `
+Usage: coder containers [command] [options]
+
+List or clean containers.
+
+Commands:
+  (none)                List all containers
+  clean                 Clean up containers
+
+Options (for clean):
+  --stopped             Clean stopped containers
+  --older-than=<time>   Clean containers older than time (e.g., 7d, 24h)
+  --dry-run             Show what would be cleaned without doing it
+  --yes                 Skip confirmation
+
+Examples:
+  coder containers
+  coder containers clean --stopped --yes
+  coder containers clean --older-than=7d --dry-run
+`
+};
+
+/**
+ * Show help for a specific command
+ */
+export function showCommandHelp(command) {
+  const help = commandHelp[command];
+  if (help) {
+    console.log(help);
+    return true;
+  }
+  return false;
+}
+
+export function showHelp() {
+  console.log(`
+CoderFlow CLI
+
+Usage: coder <command> [options]
+
+Commands:
+  coder apply [task-id]                              Apply patches from completed task to local repos
+  coder discard [--env=<environment>] [--yes]        Discard applied changes from repos
+  coder attach [container-id] [options]              Connect to a running container
+
+Setup:
+  coder login [--sso]                                Authenticate with server
+  coder config <set|get|remove|show> [key] [value]   Manage CLI configuration
+  coder profile <command> [options]                  Manage connection profiles
+
+Global Options:
+  --profile=<name>        Use a specific profile for this command
+
+Examples:
+  coder apply                           # Interactively select a completed task to apply
+  coder apply 1759542727986-3uoyf48lr   # Apply patches from specific task
+  coder discard                         # Undo applied changes in default environment
+  coder discard --env=hello             # Undo changes in specific environment
+  coder attach                          # Connect to last container
+  coder attach --shell                  # Connect and start bash shell
+
+Task creation and management is best done in the Web UI.
+For CLI alternatives to Web UI features: coder --help-all
+
+Run 'coder <command> --help' for detailed command usage.
+`);
+}
+
+export function showExtendedHelp() {
+  console.log(`
+CoderFlow CLI - All Commands
+
+================================================================================
+CORE COMMANDS
+================================================================================
+
+These are the primary CLI commands for working with your local repositories.
+
+Applying Changes:
+  coder apply [task-id]                              Apply patches from completed task to local repos
+  coder discard [--env=<environment>] [--yes]        Discard applied changes from repos
+
+Connecting to Containers:
+  coder attach [container-id] [--agent=<agent>] [--shell]   Connect to a running container
+
+Setup & Configuration:
+  coder login [--sso]                                Authenticate with server
+  coder config <set|get|remove|show> [key] [value]   Manage CLI configuration
+  coder profile <command> [options]                  Manage connection profiles
+
+================================================================================
+CLI ALTERNATIVES TO WEB UI
+================================================================================
+
+These commands provide command-line access to features typically managed
+through the Web UI. Use these when you prefer command-line workflows or
+don't have browser access.
+
+Task Management:
+  coder run <task-type> [--env=<env>] [--param=val]  Create and run a task with template
+  coder run                                          Create and run a task interactively
+  coder status <task-id>                             Check status of a task
+  coder results <task-id>                            Get results of a completed task
+  coder logs <task-id> [--tail=N]                    Show task logs
+  coder list [--status=...] [--environment=...]      List tasks with optional filters
+  coder reject <task-id> [--cleanup]                 Reject task results
+
+Interactive Sessions:
+  coder start <environment> [options]                Start interactive session with AI agent
+  coder shell <environment> [options]                Start interactive session with bash shell
+
+Testing & Containers:
+  coder test <test-name> [--env=<environment>]       Run tests in environment
+  coder containers [clean] [options]                 List or clean containers
+
+================================================================================
+PROFILE COMMANDS
+================================================================================
+
+  coder profile list                    List all profiles (shows active profile)
+  coder profile show [name]             Show profile details (active if no name)
+  coder profile create <name>           Create a new profile
+  coder profile switch <name>           Switch to a different profile
+  coder profile delete <name>           Delete a profile
+  coder profile copy <source> <dest>    Copy an existing profile
+  coder profile set <key> <value>       Set a value in the active profile
+  coder profile get <key>               Get a value from the active profile
+  coder profile current                 Show the current active profile name
+  coder profile migrate <name>          Create profile from legacy config
+
+================================================================================
+ENVIRONMENT VARIABLES
+================================================================================
+
+  CODER_SERVER_URL            Server URL (default: http://localhost:3000)
+  CODER_API_KEY               API key for authentication (use 'coder login' to generate)
+  CODER_PROFILE               Override active profile (takes precedence over config)
+
+================================================================================
+EXAMPLES
+================================================================================
+
+Core Workflow:
+  coder apply                                        # Interactively select a completed task
+  coder apply 1759542727986-3uoyf48lr                # Apply patches from specific task
+  coder discard                                      # Undo all changes in default environment
+  coder discard --env=hello --yes                    # Undo changes, skip confirmation
+  coder attach                                       # Connect to last container
+  coder attach 188b8e72d656 --shell                  # Connect to specific container with shell
+
+Setup:
+  coder login                                        # Authenticate with username/password
+  coder login --sso                                  # Authenticate with SSO/OIDC
+  coder config set serverUrl http://localhost:3000   # Set server URL
+  coder profile create prod                          # Create a new profile
+  coder profile switch prod                          # Switch to prod profile
+
+Task Management (Web UI alternative):
+  coder run add-function --function_name=multiply    # Run task with template
+  coder run add-function --env=hello --verbose=true  # Run in specific environment
+  coder status 1759542727986-3uoyf48lr               # Check task status
+  coder results 1759542727986-3uoyf48lr              # Get task results
+  coder list --status=completed                      # List completed tasks
+
+Interactive Sessions (Web UI alternative):
+  coder start hello                                  # Start AI agent in environment
+  coder start hello --agent=codex                    # Start with specific agent
+  coder shell hello                                  # Start bash shell in environment
+`);
+}

package/lib/http-client.js

@@ -0,0 +1,180 @@
+/**
+ * HTTP client for Coder Server API
+ */
+
+import { getServerUrl, getApiKey } from './config.js';
+
+/**
+ * Format a helpful error message based on error type
+ */
+function formatErrorMessage(error, url, response, serverUrl) {
+  // Connection errors
+  if (error.code === 'ECONNREFUSED' || error.cause?.code === 'ECONNREFUSED') {
+    console.error(`\nError: Cannot connect to Coder server at ${serverUrl}`);
+    console.error('\nPossible solutions:');
+    console.error('  1. Start the server:');
+    console.error('     cd packages/server && CODER_SETUP_PATH=/path/to/coder-setup npm start');
+    console.error('  2. Check if server is running on a different port');
+    console.error('  3. Set CODER_SERVER_URL environment variable if using non-default port');
+    return true;
+  }
+
+  if (error.code === 'ENOTFOUND' || error.cause?.code === 'ENOTFOUND') {
+    console.error(`\nError: Cannot resolve hostname: ${serverUrl}`);
+    console.error('\nCheck CODER_SERVER_URL environment variable');
+    return true;
+  }
+
+  // HTTP errors with response
+  if (response) {
+    const status = response.status;
+    const message = error.message;
+
+    // Special case: 404 on local-state-summary is expected (file not created yet)
+    // Don't treat as fatal error, allow retry logic to handle it
+    if (status === 404 && url.includes('/local-state-summary')) {
+      return false; // Not fatal, caller can retry
+    }
+
+    console.error(`\nError: ${message}`);
+
+    // Provide actionable guidance based on status code
+    if (status === 401) {
+      console.error('\nAuthentication required.');
+      console.error('Possible solutions:');
+      console.error('  1. Log in: coder login');
+      console.error('  2. Set API key: export CODER_API_KEY=your-key');
+      console.error('  3. Your session may have expired - log in again');
+    } else if (status === 403) {
+      console.error('\nPermission denied.');
+      console.error('You do not have permission to access this resource.');
+      console.error('Contact an administrator if you believe this is an error.');
+    } else if (status === 404) {
+      if (url.includes('/tasks/')) {
+        console.error('\nThe requested task was not found.');
+        console.error('Possible solutions:');
+        console.error('  1. Check the task ID is correct');
+        console.error('  2. Use "coder list" to see all tasks');
+        console.error('  3. Server may have been restarted (task state is not persistent)');
+      } else if (url.includes('/containers/')) {
+        console.error('\nThe requested container was not found.');
+        console.error('Possible solutions:');
+        console.error('  1. Check the container ID is correct');
+        console.error('  2. Use "coder containers" to list all containers');
+      } else if (url.includes('/environments/')) {
+        console.error('\nThe requested environment was not found.');
+        console.error('Possible solutions:');
+        console.error('  1. Check environment name spelling');
+        console.error('  2. Use "coder run --env=<name>" with a valid environment');
+        console.error('  3. Check environments/ directory in your coder-setup');
+      }
+    } else if (status === 400) {
+      console.error('\nBad request - check your command arguments');
+    } else if (status === 413) {
+      console.error('\nRequest too large.');
+      console.error('\nThe data you are trying to send is too large for the server to process.');
+      console.error('This typically occurs when capturing local state with large diffs.');
+      console.error('\nPossible solutions:');
+      console.error('  1. Commit or stash large changes before capturing local state');
+      console.error('  2. Reduce the number of modified files');
+      console.error('  3. Contact an administrator to increase server payload limits');
+    } else if (status === 500) {
+      console.error('\nServer error occurred.');
+
+      // Show detailed error message if available
+      if (error.detailedError && error.detailedError !== message) {
+        console.error(`\nServer Error Details:`);
+        console.error(`  ${error.detailedError}`);
+      }
+
+      console.error('\nPossible solutions:');
+      console.error('  1. Check server logs for details');
+      console.error('  2. Verify Docker is running: docker ps');
+      console.error('  3. Check CODER_SETUP_PATH is set correctly');
+      console.error('  4. Verify coder-setup configuration files are valid');
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Make HTTP request to Coder Server
+ */
+export async function request(path, options = {}) {
+  const serverUrl = await getServerUrl();
+  const url = `${serverUrl}${path}`;
+
+  try {
+    const { parse = 'json', ...fetchOptions } = options;
+
+    // Get API key and add to headers if available
+    const apiKey = await getApiKey();
+    const headers = {
+      'Content-Type': 'application/json',
+      ...fetchOptions.headers
+    };
+
+    if (apiKey) {
+      headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      ...fetchOptions,
+      headers
+    });
+
+    let data;
+
+    if (parse === 'text') {
+      data = await response.text();
+    } else {
+      const contentType = response.headers.get('content-type') || '';
+      if (contentType.includes('application/json')) {
+        data = await response.json();
+      } else {
+        data = await response.text();
+      }
+    }
+
+    if (!response.ok) {
+      let message;
+      let detailedError = null;
+
+      if (typeof data === 'string') {
+        message = data.trim() || `HTTP ${response.status}`;
+        // Try to parse error details from string response
+        detailedError = data.trim();
+      } else {
+        message = data?.error || data?.message || `HTTP ${response.status}`;
+        // Capture additional error details if available
+        if (data?.error && data?.message) {
+          detailedError = `${data.error}: ${data.message}`;
+        } else if (data?.message) {
+          detailedError = data.message;
+        } else if (data?.error) {
+          detailedError = data.error;
+        }
+      }
+
+      const error = new Error(message);
+      error.detailedError = detailedError;
+      error.statusCode = response.status;
+
+      if (formatErrorMessage(error, url, response, serverUrl)) {
+        process.exit(1);
+      }
+      throw error;
+    }
+
+    return data;
+  } catch (error) {
+    // Handle network/connection errors
+    if (formatErrorMessage(error, url, null, serverUrl)) {
+      process.exit(1);
+    }
+    throw error;
+  }
+}