ai-summon 0.0.1

package/specs/001-cloud-scp-command/research.md

@@ -0,0 +1,345 @@
+# Research: Cloud SCP Command
+
+**Feature**: 001-cloud-scp-command
+**Date**: 2025-10-11
+**Status**: Complete
+
+## Research Overview
+
+This document consolidates research findings for implementing the `hsh cloud scp` command. Since this feature extends existing cloud infrastructure functionality, research focuses on SCP best practices, path validation approaches, and integration patterns with the existing codebase.
+
+## Decision 1: SCP Command Pattern
+
+### Decision
+
+Use `scp -i {privateKey} scp [flags] {source} {user}@{host}:{dest}` pattern for SCP execution.
+
+### Rationale
+
+- **Consistency**: Matches the SSH approach used in `cloud login` command
+- **Key Management**: Ensures proper private key authentication flow
+- **Error Handling**: SSH error patterns can be handled by existing `handleSSHError` function
+- **Platform Compatibility**: Works across all platforms supported by the SSH suite
+
+### Alternatives Considered
+
+1. **Direct SCP command**: `scp -i {privateKey} [flags] {source} {user}@{host}:{dest}`
+   - **Rejected**: While simpler, inconsistent with cloud login's SSH-first approach
+   - **Concern**: May have different error handling requirements
+
+2. **rsync over SSH**: `rsync -avz -e "scp -i {privateKey}" {source} {user}@{host}:{dest}`
+   - **Rejected**: Adds external dependency (rsync)
+   - **Overkill**: Feature doesn't require rsync's advanced sync capabilities
+   - **Complexity**: More flags and options to manage
+
+### Implementation Details
+
+```typescript
+// For files
+await $`scp -i ${privateKeyFile} scp ${localPath} root@${ip}:${remotePath}`;
+
+// For directories (-r flag)
+await $`scp -i ${privateKeyFile} scp -r ${localPath} root@${ip}:${remotePath}`;
+```
+
+## Decision 2: Path Validation Strategy
+
+### Decision
+
+Use Node.js `fs/promises` API with `stat()` for comprehensive path validation before SCP execution.
+
+### Rationale
+
+- **Early Failure**: Detect invalid paths before expensive SSH/SCP operations
+- **Type Detection**: `stat()` provides file vs directory information
+- **Permission Checking**: Can detect read permission issues early
+- **Synchronous Path Check**: Validates source exists, preventing ambiguous SCP errors
+
+### Alternatives Considered
+
+1. **No validation, rely on SCP errors**
+   - **Rejected**: Poor user experience with cryptic SCP error messages
+   - **Delayed feedback**: Only fails after SSH connection established
+
+2. **Simple `access()` check only**
+   - **Rejected**: Doesn't provide file vs directory information
+   - **Missing context**: Can't auto-detect if `-r` flag is needed
+
+### Implementation Details
+
+```typescript
+import { stat } from 'fs/promises';
+
+async function validateLocalPath(path: string): Promise<{ exists: boolean; isDirectory: boolean }> {
+  try {
+    const stats = await stat(path);
+    return { exists: true, isDirectory: stats.isDirectory() };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { exists: false, isDirectory: false };
+    }
+    throw error; // Permission or other errors
+  }
+}
+```
+
+## Decision 3: Recursive Flag Handling
+
+### Decision
+
+Require explicit `-r` flag for directory copies, error if missing.
+
+### Rationale
+
+- **SCP Standard**: Follows standard SCP behavior and conventions
+- **Explicit Intent**: Forces user to be explicit about recursive operations
+- **Error Prevention**: Prevents accidental large directory transfers
+- **User Education**: Clear error message teaches correct flag usage
+
+### Alternatives Considered
+
+1. **Auto-detect and add `-r` flag**
+   - **Rejected**: Too implicit, hides important flag from user
+   - **Learning barrier**: Users won't learn correct SCP usage
+
+2. **Prompt user when directory detected**
+   - **Rejected**: Adds friction to CLI workflow
+   - **Automation unfriendly**: Breaks non-interactive script usage
+
+### Implementation Details
+
+```typescript
+// Validation logic
+if (pathInfo.isDirectory && !options.recursive) {
+  console.error(chalk.red('❌ Cannot copy directory without -r flag'));
+  console.log(chalk.yellow('Hint: Use -r flag for recursive directory copy'));
+  process.exit(1);
+}
+```
+
+## Decision 4: Function Reuse Strategy
+
+### Decision
+
+Reuse existing cloud.ts helper functions for all shared functionality.
+
+### Functions to Reuse
+
+1. **validatePrivateKey()**: SSH key validation and permission checking
+2. **promptForService()**: Interactive service selection
+3. **promptForEnvironment()**: Interactive environment selection
+4. **handleSSHError()**: SSH/SCP error handling with user-friendly messages
+
+### Rationale
+
+- **DRY Principle**: Eliminates code duplication
+- **Consistency**: Same user experience across cloud commands
+- **Maintainability**: Bug fixes benefit all cloud commands
+- **Testing**: Shared functions already tested through cloud login
+
+### New Functions Required
+
+1. **validateLocalPath()**: Path existence and type checking (SCP-specific)
+2. **cloudScp()**: Main SCP command execution (new subcommand)
+
+### Implementation Pattern
+
+```typescript
+export async function cloudScp(
+  localPath: string,
+  remotePath: string,
+  options: { env?: Environment; service?: string; recursive?: boolean }
+): Promise<void> {
+  // Reuse existing patterns from cloudLogin
+  const config = readConfig();
+
+  // Reuse: Service selection
+  const service = options.service || (await promptForService(Object.keys(config.yiren)));
+
+  // Reuse: Environment selection
+  const env = options.env || (await promptForEnvironment(Object.keys(config.yiren[service])));
+
+  // Reuse: Key validation
+  await validatePrivateKey(cloudConfig.privateKeyFile);
+
+  // New: Path validation
+  const pathInfo = await validateLocalPath(localPath);
+
+  // Reuse: Production confirmation (from cloudLogin pattern)
+  if (env === 'prod') {
+    // ... confirmation prompt logic
+  }
+
+  // New: SCP execution
+  await $`scp -i ${cloudConfig.privateKeyFile} scp ${flags} ${localPath} root@${cloudConfig.ip}:${remotePath}`;
+}
+```
+
+## Decision 5: Production Safety Confirmation
+
+### Decision
+
+Implement same production confirmation prompt as `cloud login`.
+
+### Rationale
+
+- **Consistency**: Matches user expectations from cloud login
+- **Safety**: Prevents accidental production file overwrites
+- **Explicit Consent**: Requires active confirmation for prod operations
+- **Audit Trail**: User explicitly acknowledges production access
+
+### Implementation Details
+
+```typescript
+if (env === 'prod') {
+  const { confirmProduction } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirmProduction',
+      message: chalk.red(`⚠️  You are about to copy files to PRODUCTION (${service}). Continue?`),
+      default: false,
+    },
+  ]);
+
+  if (!confirmProduction) {
+    console.log(chalk.yellow('⏸️  Production operation cancelled.'));
+    return;
+  }
+}
+```
+
+## Decision 6: Error Handling Strategy
+
+### Decision
+
+Layer error handling with specific messages for each failure point.
+
+### Error Categories
+
+1. **Path Errors**: Local file/directory not found, permission denied
+2. **Configuration Errors**: Service/environment not configured
+3. **Validation Errors**: Missing -r flag for directories
+4. **SSH/SCP Errors**: Connection failures, authentication failures
+
+### Error Handling Flow
+
+```typescript
+try {
+  // Layer 1: Path validation
+  const pathInfo = await validateLocalPath(localPath);
+  if (!pathInfo.exists) {
+    console.error(chalk.red(`❌ Local path not found: ${localPath}`));
+    return;
+  }
+
+  // Layer 2: Recursive flag validation
+  if (pathInfo.isDirectory && !options.recursive) {
+    console.error(chalk.red('❌ Cannot copy directory without -r flag'));
+    console.log(chalk.yellow('Hint: Use -r flag for recursive directory copy'));
+    return;
+  }
+
+  // Layer 3: Configuration validation (reuse existing logic)
+  // ...
+
+  // Layer 4: SCP execution
+  await $`scp -i ${privateKey} scp ${flags} ${localPath} root@${ip}:${remotePath}`;
+  console.log(chalk.green(`✅ Successfully copied to ${service} (${env}): ${remotePath}`));
+} catch (error) {
+  // Reuse handleSSHError for SSH/SCP connection errors
+  handleSSHError(error);
+  process.exit(1);
+}
+```
+
+### Rationale
+
+- **Clear Feedback**: Each error type has specific, actionable message
+- **Early Failure**: Validation errors caught before SCP execution
+- **Reuse Existing**: SSH errors handled by existing handleSSHError function
+- **User Experience**: Helpful hints guide users to correct usage
+
+## Technology Best Practices
+
+### TypeScript Best Practices
+
+- **Strict Mode**: All code follows strict TypeScript typing
+- **Interface Reuse**: Use existing `CloudConfig`, `Environment` types
+- **Async/Await**: All file system and shell operations use async/await
+- **Error Types**: Properly type catch blocks and error handling
+
+### zx Library Usage
+
+- **Template Literals**: Use `$` template literals for all shell commands
+- **Variable Escaping**: zx automatically handles path escaping
+- **Error Propagation**: zx throws on non-zero exit codes by default
+- **Process Handling**: Proper async/await with shell operations
+
+### Commander.js Patterns
+
+- **Option Definition**: Use `.option()` for flags with proper descriptions
+- **Argument Definition**: Use `.argument()` for positional parameters
+- **Action Handler**: Async action handlers for all commands
+- **Delegation Pattern**: Main file defines interface, delegates to domain modules
+
+## Integration Patterns
+
+### Configuration Access
+
+- Reuse `readConfig()` from util.ts
+- Access `config.yiren` structure (established by cloud login)
+- Validate service and environment existence before use
+
+### Interactive Prompts
+
+- Reuse `promptForService()` and `promptForEnvironment()`
+- Maintain consistent prompt styling with inquirer
+- Provide helpful validation messages
+
+### Command Registration
+
+```typescript
+// In hsh.ts - following existing cloud command pattern
+cloudCommand
+  .command('scp')
+  .description('Copy files to cloud instances')
+  .option('-r, --recursive', 'Copy directories recursively')
+  .option('--env <environment>', 'Environment: dev, staging, or prod')
+  .option('--service <service>', 'Service name')
+  .argument('<local-path>', 'Local file or directory path')
+  .argument('<remote-path>', 'Remote destination path')
+  .action(async (localPath, remotePath, options) => {
+    await cloudScp(localPath, remotePath, options);
+  });
+```
+
+## Open Questions & Resolutions
+
+### Q1: Should we support SCP options like -P (port)?
+
+**Resolution**: No, not in initial implementation. Current cloud config doesn't include custom SSH ports. Can add later if needed.
+
+### Q2: Should we validate remote path format?
+
+**Resolution**: No, let SCP/SSH handle remote path validation. Remote filesystem structure varies, hard to validate without SSH connection.
+
+### Q3: Should we support bidirectional SCP (download from remote)?
+
+**Resolution**: No, out of scope for this feature. Current requirement is upload only. Can be separate command later (e.g., `hsh cloud download`).
+
+### Q4: Should we show progress for large file transfers?
+
+**Resolution**: Not in initial version. SCP provides basic progress output by default. Enhanced progress indication can be added in future iteration if needed.
+
+## Summary
+
+This research establishes a clear implementation path for the `hsh cloud scp` command:
+
+1. **SCP via SSH wrapper** for consistency with cloud login
+2. **Node.js fs/promises** for path validation and type detection
+3. **Explicit -r flag** requirement following SCP standards
+4. **Maximum function reuse** from existing cloud.ts helpers
+5. **Production safety** with confirmation prompts
+6. **Layered error handling** with specific, actionable messages
+
+All decisions align with the project's constitution (TypeScript-first, zx for shell, inquirer for prompts, modular architecture) and reuse existing patterns from the cloud login implementation.

package/specs/001-cloud-scp-command/spec.md

@@ -0,0 +1,248 @@
+# Feature Specification: Cloud SCP Command
+
+**Feature ID**: 001-cloud-scp-command
+**Created**: 2025-10-11
+**Type**: CLI Enhancement
+**Depends On**: 001-cloud-login-feature (cloud configuration structure)
+
+## Overview
+
+Add a new `hsh cloud scp` command that enables users to securely copy files and directories to cloud instances using SCP. The command extends the existing cloud infrastructure management functionality by leveraging the same environment and service configuration used by `hsh cloud login`.
+
+## Functional Requirements
+
+### FR-1: Cloud SCP Command Structure
+
+- **Main Command**: `hsh cloud` - Cloud infrastructure management (existing)
+- **New Subcommand**: `hsh cloud scp [options] <local-path> <remote-path>`
+- **Options**:
+  - `-r, --recursive`: Copy directories recursively (required for folders)
+  - `--env <environment>`: Environment selection (dev/staging/prod)
+  - `--service <service-name>`: Service name (todo-mini, wuhan-mall, etc.)
+- **Parameters**:
+  - `<local-path>`: Local file or directory path to copy
+  - `<remote-path>`: Remote destination path on the target server
+- **Behavior**: Execute SCP command to copy local files/directories to remote server
+
+### FR-2: Interactive Prompts
+
+When `--env` or `--service` options are not provided, the command should:
+
+- **Service Selection**: Prompt user to select from available services in configuration
+- **Environment Selection**: Prompt user to select from available environments for the chosen service
+- **Reuse Existing Patterns**: Use the same prompt functions from cloud login (`promptForService`, `promptForEnvironment`)
+
+### FR-3: Configuration Reuse
+
+- **Configuration File**: `~/.ai/config.json` (same as cloud login)
+- **Configuration Structure**: Uses existing `yiren` section from cloud login feature
+  ```json
+  {
+    "yiren": {
+      "[service-name]": {
+        "dev": {
+          "ip": "IP",
+          "privateKeyFile": "path/to/private-key-file"
+        },
+        "staging": { ... },
+        "prod": { ... }
+      }
+    }
+  }
+  ```
+
+### FR-4: SCP Command Execution
+
+The command should construct and execute different SCP commands based on the input type:
+
+**For Files**:
+
+```bash
+scp -i /path/to/privateKey scp local-file-path root@IP:remote-folder-path
+```
+
+**For Directories** (with `-r` flag):
+
+```bash
+scp -i /path/to/privateKey scp -r local-folder-path root@IP:remote-folder-path
+```
+
+**Command Resolution**:
+
+- Private key: `config.yiren[service][env].privateKeyFile`
+- IP address: `config.yiren[service][env].ip`
+- User: Always `root` (consistent with cloud login)
+
+### FR-5: Path Validation
+
+- **Local Path**: Validate that local path exists before attempting copy
+- **Directory Detection**: Automatically detect if local path is a directory
+- **Recursive Flag**: Require `-r` flag for directory copies
+- **Error Messages**: Clear feedback for missing paths or incorrect flag usage
+
+## Technical Requirements
+
+### TR-1: Command Integration
+
+- Add `scp` subcommand to existing `cloud` command group in `hsh.ts`
+- Implement `cloudScp` function in `src/commands/cloud.ts`
+- Follow Commander.js patterns for option and argument parsing
+- Reuse existing cloud helper functions for configuration and validation
+
+### TR-2: File System Operations
+
+- Use Node.js `fs/promises` API for path validation
+- Detect file vs directory using `stat` or `lstat`
+- Validate local path exists before SCP execution
+- Provide clear error messages for invalid paths
+
+### TR-3: SCP Execution
+
+- Use zx library for shell command execution (following constitution)
+- Construct SCP command with proper flag handling (`-r` for directories)
+- Include SSH options for key authentication and connection settings
+- Handle SCP-specific errors and exit codes
+
+### TR-4: Error Handling
+
+- **Path Errors**: Local path not found, permission issues
+- **Configuration Errors**: Missing service/environment configuration
+- **SCP Errors**: Connection failures, permission denied, file transfer issues
+- **Flag Errors**: Missing `-r` flag for directory copy
+- Reuse `handleSSHError` function for connection-related errors
+
+### TR-5: Production Safety
+
+- Implement same production confirmation prompt as cloud login
+- Warn users before copying to production environments
+- Require explicit confirmation for production operations
+
+## User Stories
+
+### US-1: Quick File Deploy
+
+**As a** developer
+**I want to** quickly copy a local file to a remote server
+**So that** I can deploy configuration changes without manual SCP commands
+
+**Acceptance Criteria**:
+
+- Command accepts local file path and remote destination
+- Automatically detects it's a file and uses appropriate SCP command
+- Prompts for service and environment if not provided
+- Successfully copies file to remote server
+
+**Example**:
+
+```bash
+hsh cloud scp ./config.json /etc/myapp/config.json
+# Prompts for service and environment, then copies file
+```
+
+### US-2: Directory Upload
+
+**As a** developer
+**I want to** upload an entire directory to a remote server
+**So that** I can deploy multiple files in one command
+
+**Acceptance Criteria**:
+
+- Command requires `-r` flag for directory copy
+- Recursively copies entire directory structure
+- Provides clear error if `-r` flag is missing for directories
+
+**Example**:
+
+```bash
+hsh cloud scp -r ./dist /var/www/html --env prod --service wuhan-mall
+```
+
+### US-3: Interactive Service Selection
+
+**As a** developer managing multiple services
+**I want to** be prompted for service and environment if not specified
+**So that** I can quickly select without remembering exact names
+
+**Acceptance Criteria**:
+
+- Displays available services when `--service` is omitted
+- Displays available environments when `--env` is omitted
+- Uses same interactive prompts as cloud login command
+
+**Example**:
+
+```bash
+hsh cloud scp ./app.js /opt/app/
+# Interactive prompts guide service and environment selection
+```
+
+## Usage Examples
+
+### Basic File Copy
+
+```bash
+hsh cloud scp ./config.json /etc/app/config.json --env dev --service todo-mini
+```
+
+### Directory Copy with Recursive Flag
+
+```bash
+hsh cloud scp -r ./build /var/www/html --env staging --service wuhan-mall
+```
+
+### Interactive Mode (No Flags)
+
+```bash
+hsh cloud scp ./deploy.sh /root/scripts/
+# Prompts: Select service → Select environment → Executes SCP
+```
+
+### Production Copy with Confirmation
+
+```bash
+hsh cloud scp -r ./dist /var/www/html --env prod --service todo-mini
+# Shows production warning → Requires confirmation → Executes SCP
+```
+
+## Dependencies
+
+- **Existing**: commander, zx, chalk, inquirer, fs/promises (already in project)
+- **New**: None required
+- **External**: SCP command (system dependency, part of SSH suite)
+- **Internal**: Reuses cloud.ts helper functions and configuration structure
+
+## Success Criteria
+
+1. Command successfully copies files to specified environment and service
+2. Automatic detection of file vs directory with appropriate flag validation
+3. Interactive prompts work consistently with cloud login command
+4. Production confirmation prevents accidental deployments
+5. Clear error messages for all failure scenarios
+6. Follows project's TypeScript and CLI design principles
+7. Code reuses existing cloud infrastructure patterns
+
+## Non-Functional Requirements
+
+- **Security**: SSH keys properly managed, not exposed in logs or error messages
+- **Performance**: Command executes within 2 seconds (excluding actual file transfer time)
+- **Usability**: Clear error messages, helpful validation, intuitive flag usage
+- **Maintainability**: Code follows existing patterns, reuses helper functions, minimal duplication
+- **Compatibility**: Works with existing cloud configuration without modifications
+
+## Design Decisions
+
+### Reuse Over Duplication
+
+- Reuse `validatePrivateKey`, `promptForService`, `promptForEnvironment` from cloud login
+- Reuse `handleSSHError` for consistent error handling
+- Reuse configuration reading and validation patterns
+
+### SCP via SSH Wrapper
+
+The command pattern `scp -i {key} scp ...` is used instead of direct `scp -i {key} ...` for consistency with cloud login's SSH approach and to ensure proper key authentication flow.
+
+### Flag Consistency
+
+- `-r` flag follows standard SCP convention for recursive copy
+- `--env` and `--service` flags match cloud login for consistency
+- Position of local and remote paths follows standard SCP argument order