@dp-pcs/ogp 0.3.3 → 0.4.2

package/docs/MIGRATION.md

@@ -0,0 +1,202 @@
+# OGP Migration Guide
+
+## Overview
+
+The OGP migration system helps users transition from legacy single-framework installations to the new multi-framework meta-configuration system introduced in OGP 0.4.0+.
+
+## What Gets Migrated
+
+The migration system automatically detects and migrates:
+
+1. **OpenClaw installations** at `~/.ogp/`
+2. **Hermes installations** at `~/.ogp-hermes/`
+3. **Standalone OGP installations** at `~/.ogp/`
+
+## Migration Logic
+
+### Framework Detection
+
+The migration system determines framework type by checking:
+
+1. **Explicit `platform` field** in config.json (takes precedence)
+   - `"platform": "openclaw"` → OpenClaw
+   - `"platform": "hermes"` → Hermes
+
+2. **Framework-specific fields** (heuristics)
+   - Has `hermesWebhookUrl` or `hermesWebhookSecret` → Hermes
+   - Has `openclawUrl` and `openclawToken` → OpenClaw
+   - Otherwise → Standalone
+
+### Migration Actions
+
+#### Single Installation Scenarios
+
+**Scenario 1: Only `~/.ogp/` exists (OpenClaw)**
+```
+Actions:
+1. Rename ~/.ogp → ~/.ogp-openclaw
+2. Create meta config at ~/.ogp-meta/config.json
+3. Register OpenClaw framework
+4. Set default to 'openclaw'
+```
+
+**Scenario 2: Only `~/.ogp/` exists (Standalone)**
+```
+Actions:
+1. Keep ~/.ogp as-is (no rename)
+2. Create meta config at ~/.ogp-meta/config.json
+3. Register standalone framework
+4. Set default to 'standalone'
+```
+
+**Scenario 3: Only `~/.ogp-hermes/` exists**
+```
+Actions:
+1. Keep ~/.ogp-hermes as-is
+2. Create meta config at ~/.ogp-meta/config.json
+3. Register Hermes framework
+4. Set default to 'hermes'
+```
+
+#### Multi-Installation Scenario
+
+**Scenario 4: Both `~/.ogp/` and `~/.ogp-hermes/` exist**
+```
+Actions:
+1. Rename ~/.ogp → ~/.ogp-openclaw (if OpenClaw)
+2. Keep ~/.ogp-hermes as-is
+3. Create meta config at ~/.ogp-meta/config.json
+4. Register both frameworks
+5. Set default to 'openclaw'
+```
+
+## Usage
+
+### Programmatic API
+
+```typescript
+import {
+  detectExistingInstallations,
+  executeMigration,
+  checkMigrationStatus,
+  type MigrationPlan
+} from '@dp-pcs/ogp/dist/shared/migration.js';
+
+// Check if migration is needed
+const status = checkMigrationStatus();
+if (status.migrationNeeded) {
+  console.log(status.summary);
+
+  // Get detailed plan
+  const plan = detectExistingInstallations();
+
+  // Execute migration
+  await executeMigration(plan);
+}
+```
+
+### Testing Scripts
+
+Two test scripts are provided:
+
+#### 1. Detection Test (Read-only)
+```bash
+node scripts/test-migration.js
+```
+
+Shows what would be migrated without making changes.
+
+#### 2. Execution Test
+```bash
+# Dry run (shows plan, no changes)
+node scripts/test-migration-execute.js --dry-run
+
+# Execute migration
+node scripts/test-migration-execute.js
+```
+
+## Migration Plan Structure
+
+```typescript
+interface MigrationPlan {
+  needed: boolean;                    // Is migration required?
+  existingInstalls: Array<{
+    path: string;                     // e.g., "/Users/alice/.ogp"
+    framework: FrameworkType;         // 'openclaw' | 'hermes' | 'standalone'
+    config: OGPConfig;                // Full config object
+  }>;
+  actions: Array<{
+    type: 'rename' | 'create-meta' | 'register';
+    from?: string;                    // Source path (for rename)
+    to?: string;                      // Target path (for rename)
+    framework?: FrameworkType;        // Framework being operated on
+    description: string;              // Human-readable description
+  }>;
+}
+```
+
+## Safety Features
+
+1. **Backup Creation**: Before renaming, creates timestamped backup
+   ```
+   ~/.ogp.backup-1712345678901
+   ```
+
+2. **Rollback on Error**: If rename fails, automatically restores from backup
+
+3. **Validation**: Checks target doesn't exist before renaming
+
+4. **Idempotency**: Safe to run multiple times - detects if already migrated
+
+## Post-Migration
+
+After migration, users have:
+
+1. **Meta Config** at `~/.ogp-meta/config.json`
+   ```json
+   {
+     "version": "1.0.0",
+     "frameworks": [
+       {
+         "id": "openclaw",
+         "name": "OpenClaw",
+         "enabled": true,
+         "configDir": "/Users/alice/.ogp-openclaw",
+         "daemonPort": 18790,
+         "gatewayUrl": "https://alice.example.com",
+         "displayName": "Alice @ OpenClaw",
+         "platform": "openclaw"
+       },
+       {
+         "id": "hermes",
+         "name": "Hermes",
+         "enabled": true,
+         "configDir": "/Users/alice/.ogp-hermes",
+         "daemonPort": 18793,
+         "gatewayUrl": "https://hermes.alice.example.com",
+         "displayName": "Alice @ Hermes",
+         "platform": "hermes"
+       }
+     ],
+     "default": "openclaw"
+   }
+   ```
+
+2. **Framework-specific configs** preserved in their directories
+
+3. **All existing data** (peers.json, keypair.json, etc.) intact
+
+## Integration with Setup Flow
+
+The migration will be integrated into the setup flow:
+
+```bash
+ogp setup
+```
+
+Will:
+1. Detect existing installations
+2. Show migration plan
+3. Prompt user to confirm
+4. Execute migration if approved
+5. Continue with multi-framework setup

package/docs/MULTI-FRAMEWORK-DEMO.md

@@ -0,0 +1,352 @@
+# Multi-Framework User Experience Demo
+
+## Scenario 1: Fresh Install (Both Frameworks Detected)
+
+```bash
+$ ogp setup
+
+   ___   ____  ____
+  / _ \ / ___|  _ \
+ | | | | |  _| |_) |
+ | |_| | |_| |  __/
+  \___/ \____|_|
+
+  Open Gateway Protocol v0.3.4
+
+🔍 Detecting installed AI frameworks...
+  ✓ Found OpenClaw at ~/.openclaw/
+  ✓ Found Hermes at ~/.hermes/
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Which frameworks do you want to enable OGP for?
+Use ↑↓ to navigate, space to select, enter to continue
+
+  [x] OpenClaw - AI agent framework by OpenClaw
+  [x] Hermes - Multi-platform AI orchestration system
+  [ ] Standalone (no framework integration)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ Selected: OpenClaw, Hermes
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Configure OpenClaw
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Gateway URL: https://ogp.sarcastek.com
+Display Name: Junior @ OpenClaw
+Email: david@theproctors.cloud
+
+✓ OpenClaw configured
+  Config: ~/.ogp-openclaw/
+  Daemon: http://localhost:18790
+  Keychain: ogp-federation-83751d84
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Configure Hermes
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Gateway URL: https://hermes.sarcastek.com
+Display Name: Apollo @ Hermes
+Email: david@example.com
+Platform: hermes (detected)
+
+Hermes webhook configuration:
+  URL: http://localhost:8644/webhooks/ogp_federation
+  Secret: ************ (auto-generated)
+
+✓ Hermes configured
+  Config: ~/.ogp-hermes/
+  Daemon: http://localhost:18793
+  Keychain: ogp-federation-79055744
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ OGP configured for 2 frameworks:
+  - OpenClaw (Junior @ OpenClaw)
+  - Hermes (Apollo @ Hermes)
+
+Default framework: openclaw
+
+Next steps:
+  1. Start daemons:
+     ogp start --all
+
+  2. Send a federation request:
+     ogp --for hermes federation request https://ogp.sarcastek.com
+
+  3. Manage peers:
+     ogp federation list            # Lists peers for default framework
+     ogp --for hermes federation list   # Lists peers for Hermes
+     ogp --for all federation list      # Lists peers for all frameworks
+
+Tips:
+  - Set a different default: ogp config set-default hermes
+  - Create aliases: ogp alias add oc openclaw
+  - Enable tab completion: ogp completion install
+  - Get help anytime: ogp federation ?
+
+Happy federating! 🚀
+```
+
+## Scenario 2: Day-to-Day Usage
+
+### Starting daemons
+```bash
+$ ogp start --all
+✓ Started OpenClaw daemon (PID: 12345) on http://localhost:18790
+✓ Started Hermes daemon (PID: 12346) on http://localhost:18793
+
+$ ogp status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OGP Daemon Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Framework   Status    PID     Port    Uptime    Gateway
+─────────────────────────────────────────────────────────────
+OpenClaw    Running   12345   18790   2m 34s    https://ogp.sarcastek.com
+Hermes      Running   12346   18793   2m 34s    https://hermes.sarcastek.com
+
+Rendezvous: https://rendezvous.elelem.expert (⚠️  503 unavailable)
+```
+
+### Using default framework (no --for needed)
+```bash
+$ ogp federation list
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Federation Peers (OpenClaw)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ALIAS    DISPLAY NAME           STATUS     SCOPES
+──────────────────────────────────────────────────────────────
+apollo   Apollo @ Hermes        approved   message, agent-comms, project.*
+
+  Gateway: https://hermes.sarcastek.com
+  ID: 302a300506032b6570032100e9dc2284
+  Agent-comms: general → summary
+
+Tip: Use `--for all` to see peers across all frameworks
+```
+
+### Using specific framework
+```bash
+$ ogp --for hermes federation list
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Federation Peers (Hermes)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ALIAS    DISPLAY NAME           STATUS     SCOPES
+──────────────────────────────────────────────────────────────
+junior   Junior @ OpenClaw      approved   message, agent-comms, project.*
+
+  Gateway: https://ogp.sarcastek.com
+  ID: 302a300506032b6570032100c3068604
+  Agent-comms: general → summary
+```
+
+### Using `--for all` for cross-framework view
+```bash
+$ ogp --for all federation list
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Federation Peers (All Frameworks)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+OpenClaw (Junior @ OpenClaw)
+  apollo   Apollo @ Hermes        approved   message, agent-comms, project.*
+
+Hermes (Apollo @ Hermes)
+  junior   Junior @ OpenClaw      approved   message, agent-comms, project.*
+
+Total: 2 peers across 2 frameworks
+```
+
+### Tab completion in action
+```bash
+$ ogp <TAB><TAB>
+setup       start       stop        status
+federation  agent-comms config      completion
+
+$ ogp fed<TAB>
+$ ogp federation <TAB><TAB>
+list     request  approve  reject   remove
+send     agent    scopes   alias
+
+$ ogp --for <TAB><TAB>
+openclaw  hermes  all
+
+$ ogp --for hermes federation agent <TAB><TAB>
+junior   302a300506032b6570032100c3068604
+
+$ ogp federation agent junior<TAB> <TAB><TAB>
+general  debug  alerts  status
+```
+
+### `?` style help
+```bash
+$ ogp ?
+Available commands:
+  setup       Initialize OGP configuration
+  start       Start OGP daemon(s)
+  stop        Stop OGP daemon(s)
+  status      Show daemon status
+  federation  Manage federation peers
+  agent-comms Configure agent-to-agent messaging
+  config      Manage configuration
+  completion  Install shell completion
+
+Options:
+  --for <framework>  Select framework (openclaw, hermes, all)
+  --help            Show help
+  --version         Show version
+
+Examples:
+  ogp setup                         # Interactive setup wizard
+  ogp start --all                   # Start all framework daemons
+  ogp --for hermes federation list  # List Hermes peers
+  ogp federation ?                  # Show federation commands
+
+$ ogp federation ?
+Available commands:
+  list     List all peers
+  request  Send federation request to another gateway
+  approve  Approve a pending peer
+  reject   Reject a pending peer
+  remove   Remove a peer
+  send     Send a message to a peer
+  agent    Send agent-comms message
+  scopes   View or update peer scopes
+  alias    Set an alias for a peer
+
+Examples:
+  ogp federation list --status pending
+  ogp federation request https://peer.example.com
+  ogp federation agent apollo general "Hello!"
+
+$ ogp federation agent ?
+Usage: ogp federation agent <peer> <topic> <message> [options]
+
+Send an agent-comms message to a federated peer.
+
+Arguments:
+  peer      Peer identifier (alias, ID, or display name)
+  topic     Message topic (e.g., general, debug, alerts)
+  message   Message text
+
+Options:
+  --priority <level>       Message priority (low, normal, high)
+  --conversation-id <id>   Thread conversation ID
+  --wait-for-reply         Wait for peer response
+
+Available peers (OpenClaw):
+  apollo   Apollo @ Hermes   (approved)
+
+Examples:
+  ogp federation agent apollo general "Status update"
+  ogp federation agent apollo debug "Error in module X" --priority high
+  ogp --for hermes federation agent junior general "Hello from Hermes!"
+```
+
+## Scenario 3: Switching Default Framework
+
+```bash
+$ ogp config set-default hermes
+✓ Default framework: hermes
+
+$ ogp federation list
+# Now automatically uses Hermes instead of OpenClaw
+
+$ ogp config set-default openclaw
+✓ Default framework: openclaw
+
+$ ogp config show
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OGP Configuration
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Default framework: openclaw
+
+Enabled frameworks:
+  openclaw  OpenClaw          ~/.ogp-openclaw    :18790
+  hermes    Hermes            ~/.ogp-hermes      :18793
+
+Aliases:
+  (none)
+
+Meta config: ~/.ogp-meta/config.json
+```
+
+## Scenario 4: Migration from Existing Setup
+
+```bash
+$ ogp setup
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Migration Detected
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I found existing OGP installations:
+  ~/.ogp/           (OpenClaw - detected)
+  ~/.ogp-hermes/    (Hermes - detected)
+
+Would you like to migrate to the new multi-framework setup?
+This will:
+  - Create ~/.ogp-meta/ for central configuration
+  - Rename ~/.ogp/ → ~/.ogp-openclaw/
+  - Keep ~/.ogp-hermes/ as-is
+  - Enable both frameworks with OpenClaw as default
+
+Your existing configuration and peers will be preserved.
+
+Migrate now? (Y/n): y
+
+✓ Created ~/.ogp-meta/
+✓ Migrated ~/.ogp/ → ~/.ogp-openclaw/
+✓ Registered Hermes framework
+✓ Set default framework: openclaw
+
+Migration complete! New commands:
+  Old: OGP_HOME=~/.ogp ogp federation list
+  New: ogp federation list
+
+  Old: OGP_HOME=~/.ogp-hermes ogp federation list
+  New: ogp --for hermes federation list
+
+Note: Your old commands with OGP_HOME still work!
+
+Run `ogp completion install` to enable tab completion.
+```
+
+## Scenario 5: Power User with Aliases
+
+```bash
+$ ogp alias add oc openclaw
+✓ Alias 'oc' → openclaw
+
+$ ogp alias add ap hermes
+✓ Alias 'ap' → hermes
+
+$ ogp --for oc federation list
+# Uses OpenClaw
+
+$ ogp --for ap federation list
+# Uses Hermes
+
+$ ogp alias list
+Aliases:
+  oc → openclaw
+  ap → hermes
+```
+
+## Scenario 6: Single Framework User (No Change!)
+
+```bash
+# User only has OpenClaw, never installed Hermes
+$ ogp federation list
+# Automatically uses the only configured framework
+# No --for flag needed, no framework selection prompt
+# Works exactly like before!
+```