ai-summon 0.0.1

package/specs/001-cloud-login-feature/data-model.md

@@ -0,0 +1,269 @@
+# Data Model: Cloud Login Configuration
+
+**Generated**: 2025-10-11 | **Phase**: 1 | **Feature**: Cloud Login Command
+
+## Overview
+
+Data model definitions for the cloud login feature configuration structure, entity relationships, and validation rules.
+
+## Configuration Entities
+
+### 1. CloudConfig Entity
+
+**Purpose**: Represents connection information for a single cloud instance environment.
+
+**Fields**:
+
+- `ip: string` - IP address of the cloud instance (IPv4 format)
+- `privateKeyFile: string` - Absolute path to SSH private key file
+
+**Validation Rules**:
+
+- `ip`: Must be valid IPv4 address format (e.g., "192.168.1.10")
+- `privateKeyFile`: Must be absolute path to existing file with 600 permissions
+
+**Example**:
+
+```typescript
+{
+  "ip": "192.168.1.10",
+  "privateKeyFile": "/Users/username/.ssh/todo-mini-dev.pem"
+}
+```
+
+### 2. ServiceConfig Entity
+
+**Purpose**: Contains all environment configurations for a specific service.
+
+**Fields**:
+
+- `dev: CloudConfig` - Development environment configuration
+- `staging: CloudConfig` - Staging environment configuration
+- `prod: CloudConfig` - Production environment configuration
+
+**Validation Rules**:
+
+- All three environments (dev, staging, prod) must be present
+- Each environment must contain valid CloudConfig
+
+**Example**:
+
+```typescript
+{
+  "dev": {
+    "ip": "192.168.1.10",
+    "privateKeyFile": "/path/to/todo-mini-dev.pem"
+  },
+  "staging": {
+    "ip": "192.168.1.20",
+    "privateKeyFile": "/path/to/todo-mini-staging.pem"
+  },
+  "prod": {
+    "ip": "192.168.1.30",
+    "privateKeyFile": "/path/to/todo-mini-prod.pem"
+  }
+}
+```
+
+### 3. YirenConfig Entity
+
+**Purpose**: Contains all service configurations for cloud infrastructure.
+
+**Fields**:
+
+- `[serviceName: string]: ServiceConfig` - Dynamic mapping of service names to their configurations
+
+**Validation Rules**:
+
+- Service names must be non-empty strings
+- Each service must contain valid ServiceConfig
+- Minimum one service required
+
+**Example**:
+
+```typescript
+{
+  "todo-mini": { /* ServiceConfig */ },
+  "wuhan-mall": { /* ServiceConfig */ }
+}
+```
+
+### 4. ReposConfig Entity
+
+**Purpose**: Contains repository path mappings for IDE integration (existing functionality).
+
+**Fields**:
+
+- `[groupName: string]: { [repoName: string]: string }` - Nested mapping of group and repository paths
+
+**Validation Rules**:
+
+- Group names must be non-empty strings
+- Repository names must be non-empty strings
+- Paths must be absolute directory paths
+
+**Example**:
+
+```typescript
+{
+  "personal": {
+    "project1": "/Users/username/projects/project1",
+    "project2": "/Users/username/projects/project2"
+  },
+  "work": {
+    "api-service": "/Users/username/work/api-service"
+  }
+}
+```
+
+### 5. HshConfig Entity (Root Configuration)
+
+**Purpose**: Root configuration structure containing all application settings.
+
+**Fields**:
+
+- `repos: ReposConfig` - Repository path mappings for IDE commands
+- `yiren: YirenConfig` - Cloud infrastructure configurations
+
+**Validation Rules**:
+
+- Both `repos` and `yiren` sections must be present (can be empty objects)
+- Must be valid JSON format
+- File must exist at `~/.ai/config.json`
+
+**Complete Example**:
+
+```typescript
+{
+  "repos": {
+    "personal": {
+      "hsh-tool": "/Users/username/projects/hsh"
+    }
+  },
+  "yiren": {
+    "todo-mini": {
+      "dev": {
+        "ip": "192.168.1.10",
+        "privateKeyFile": "/Users/username/.ssh/todo-mini-dev.pem"
+      },
+      "staging": {
+        "ip": "192.168.1.20",
+        "privateKeyFile": "/Users/username/.ssh/todo-mini-staging.pem"
+      },
+      "prod": {
+        "ip": "192.168.1.30",
+        "privateKeyFile": "/Users/username/.ssh/todo-mini-prod.pem"
+      }
+    },
+    "wuhan-mall": {
+      "dev": {
+        "ip": "192.168.2.10",
+        "privateKeyFile": "/Users/username/.ssh/wuhan-mall-dev.pem"
+      },
+      "staging": {
+        "ip": "192.168.2.20",
+        "privateKeyFile": "/Users/username/.ssh/wuhan-mall-staging.pem"
+      },
+      "prod": {
+        "ip": "192.168.2.30",
+        "privateKeyFile": "/Users/username/.ssh/wuhan-mall-prod.pem"
+      }
+    }
+  }
+}
+```
+
+## Entity Relationships
+
+```mermaid
+graph TD
+    A[HshConfig] --> B[ReposConfig]
+    A --> C[YirenConfig]
+    C --> D[ServiceConfig: todo-mini]
+    C --> E[ServiceConfig: wuhan-mall]
+    D --> F[CloudConfig: dev]
+    D --> G[CloudConfig: staging]
+    D --> H[CloudConfig: prod]
+    E --> I[CloudConfig: dev]
+    E --> J[CloudConfig: staging]
+    E --> K[CloudConfig: prod]
+    B --> L[Group: personal]
+    B --> M[Group: work]
+    L --> N[Repo: project1]
+    L --> O[Repo: project2]
+```
+
+## State Transitions
+
+### Configuration Migration States
+
+1. **Legacy State**: Flat configuration structure (repos directly under root)
+2. **Transition State**: Mixed configuration (some old, some new structure)
+3. **Modern State**: Full nested structure with repos and yiren sections
+
+**Migration Flow**:
+
+```
+Legacy Config → Auto-Detection → Automatic Migration → Modern Config
+     ↓                ↓                    ↓               ↓
+ Flat structure → Check for repos key → Wrap in repos → Full structure
+```
+
+### Connection States
+
+1. **Disconnected**: No active SSH connection
+2. **Connecting**: SSH connection in progress
+3. **Connected**: SSH session established
+4. **Failed**: Connection attempt failed
+
+**Connection Flow**:
+
+```
+User Command → Parameter Validation → Config Lookup → SSH Execution → Connected/Failed
+```
+
+## Validation Rules Summary
+
+### Configuration File Validation
+
+- **Format**: Valid JSON syntax
+- **Location**: Must exist at `~/.ai/config.json`
+- **Structure**: Must contain `repos` and `yiren` objects
+- **Permissions**: File must be readable by user
+
+### Cloud Configuration Validation
+
+- **IP Address**: Valid IPv4 format, reachable network address
+- **Private Key**: File exists, has 600 permissions, valid SSH key format
+- **Service Names**: Non-empty, alphanumeric with hyphens allowed
+- **Environment Names**: Must be exactly "dev", "staging", or "prod"
+
+### Runtime Validation
+
+- **SSH Connectivity**: Network reachability, port 22 accessible
+- **Authentication**: Private key matches cloud instance public key
+- **User Permissions**: SSH user (root) has necessary access rights
+
+## Error States
+
+### Configuration Errors
+
+- **File Not Found**: `~/.ai/config.json` does not exist
+- **Invalid JSON**: Malformed JSON syntax
+- **Missing Sections**: Required `repos` or `yiren` sections missing
+- **Invalid Structure**: Incorrect nesting or field types
+
+### Runtime Errors
+
+- **Service Not Found**: Requested service not in configuration
+- **Environment Not Found**: Requested environment not configured for service
+- **Key File Missing**: Private key file does not exist
+- **Permission Denied**: Incorrect private key file permissions
+- **Connection Failed**: Network connectivity or authentication failure
+
+### Recovery Strategies
+
+- **Auto-Migration**: Automatically migrate legacy configuration format
+- **User Prompts**: Interactive selection when parameters missing
+- **Validation Warnings**: Helpful messages for fixing configuration issues
+- **Graceful Fallback**: Maintain existing functionality when cloud features unavailable

package/specs/001-cloud-login-feature/plan.md

@@ -0,0 +1,91 @@
+# Implementation Plan: Cloud Login Command
+
+**Branch**: `001-cloud-login-feature` | **Date**: 2025-10-11 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/001-cloud-login-feature/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+Add a new `hsh cloud login` command that enables SSH connections to cloud instances based on environment (dev/staging/prod) and service (todo-mini, wuhan-mall) parameters. The feature includes restructuring the configuration file to support both existing IDE commands and new cloud infrastructure mappings, ensuring backward compatibility while enabling scalable cloud access management.
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: TypeScript 5.0+ with ES2020 target and ESNext modules
+**Primary Dependencies**: commander (CLI), inquirer (prompts), zx (shell), chalk (colors), ora (progress)
+**Storage**: JSON config files (~/.ai/config.json) with nested structure for repos and cloud infrastructure
+**Testing**: Manual CLI testing for SSH connections and configuration validation
+**Target Platform**: Node.js CLI (global installation via npm/yarn)
+**Project Type**: Single CLI application extending existing command structure
+**Performance Goals**: Command execution <2 seconds (excluding SSH connection time), instant config validation
+**Constraints**: SSH client system dependency, private key files per environment configuration, backward compatibility with existing config structure
+**Scale/Scope**: Support for multiple services (todo-mini, wuhan-mall), 3 environments per service, existing IDE command migration
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+✅ **TypeScript-First**: All code written in TypeScript with strict mode, fully typed
+✅ **Shell Integration**: Uses zx library for all shell operations with async/await
+✅ **Interactive CLI**: Uses inquirer prompts with validation and chalk/ora for feedback
+✅ **Modular Architecture**: Commands organized by domain in separate modules
+✅ **Yarn Package Management**: Uses Yarn with standard script patterns
+
+## Project Structure
+
+### Documentation (this feature)
+
+```
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```
+src/
+├── commands/
+│   ├── git.ts          # Existing git workflow commands
+│   ├── mono.ts         # Existing monorepo management
+│   ├── ide.ts          # Existing IDE integration (cursor, surf) - NEEDS UPDATE
+│   └── cloud.ts        # NEW: Cloud infrastructure commands
+├── types/
+│   └── index.ts        # Type definitions - NEEDS UPDATE for config structure
+├── util.ts             # Utility functions - NEEDS UPDATE for config reading
+└── hsh.ts              # Main CLI entry point - NEEDS UPDATE for cloud command
+
+dist/                   # Compiled TypeScript output
+└── [mirrors src structure]
+
+# Configuration
+~/.ai/config.json      # User configuration with new nested structure
+```
+
+**Structure Decision**: Using the existing TypeScript CLI project structure. Adding a new `cloud.ts` command module following the established pattern of domain-specific modules (git, mono, ide). The existing `ide.ts`, `types/index.ts`, and `util.ts` files require updates to support the new configuration structure while maintaining backward compatibility.
+
+## Complexity Tracking
+
+_Fill ONLY if Constitution Check has violations that must be justified_
+
+| Violation                  | Why Needed         | Simpler Alternative Rejected Because |
+| -------------------------- | ------------------ | ------------------------------------ |
+| [e.g., 4th project]        | [current need]     | [why 3 projects insufficient]        |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient]  |