@dp-pcs/ogp 0.3.3 → 0.4.2

package/docs/MULTI-FRAMEWORK-DESIGN.md

@@ -0,0 +1,378 @@
+# Multi-Framework Support Design
+
+**Status:** ✅ Implemented in OGP v0.4.0+
+
+## Goal
+Make OGP feel like a native integration for multiple AI frameworks (OpenClaw, Hermes, etc.) rather than requiring manual `OGP_HOME` environment variables.
+
+## User Experience
+
+### Setup (First-time)
+```bash
+$ ogp setup
+
+🔍 Detecting installed AI frameworks...
+  ✓ Found OpenClaw at ~/.openclaw/
+  ✓ Found Hermes at ~/.hermes/
+
+Which frameworks do you want to enable OGP for?
+  [x] OpenClaw (Junior @ OpenClaw)
+  [x] Hermes (Apollo @ Hermes)
+  [ ] Standalone (no framework)
+
+Gateway configuration:
+  OpenClaw → https://ogp.sarcastek.com
+  Hermes   → https://hermes.sarcastek.com
+
+✓ OGP configured for 2 frameworks
+  OpenClaw: ~/.ogp-openclaw/
+  Hermes:   ~/.ogp-hermes/
+
+Tip: Use `ogp --for openclaw <command>` or `ogp --for hermes <command>`
+     Or set a default: `ogp config set-default openclaw`
+```
+
+### Command Execution
+
+**When only one framework is configured:**
+```bash
+$ ogp federation list
+# Automatically uses the only configured framework
+```
+
+**When multiple frameworks are configured:**
+```bash
+$ ogp federation list
+? Which framework? (use arrow keys or type to filter)
+  › openclaw
+    hermes
+    all (run on both)
+
+# OR use flag directly:
+$ ogp --for openclaw federation list
+$ ogp --for hermes federation list
+$ ogp --for all federation list  # Run on both, show combined output
+```
+
+**Set a default:**
+```bash
+$ ogp config set-default openclaw
+✓ Default framework: openclaw
+
+$ ogp federation list
+# Now automatically uses openclaw
+```
+
+### Framework Aliases
+```bash
+$ ogp alias add oc openclaw
+$ ogp alias add ap hermes
+
+$ ogp --for oc federation list   # Uses openclaw
+$ ogp --for ap federation list   # Uses hermes
+```
+
+## Tab Completion
+
+### Bash/Zsh Completion
+```bash
+$ ogp fed<TAB>
+federation
+
+$ ogp federation <TAB>
+list      request   approve   reject    remove    send
+agent     scopes    alias
+
+$ ogp --for <TAB>
+openclaw  hermes  all
+
+$ ogp federation send ?
+Usage: ogp federation send <peer> <intent> <payload>
+
+Available peers:
+  - apollo (Apollo @ Hermes)
+  - junior (Junior @ OpenClaw)
+
+Example: ogp federation send apollo message '{"text":"hello"}'
+```
+
+### `?` Style Help (Cisco IOS-inspired)
+```bash
+$ ogp ?
+Available commands:
+  setup       Initialize OGP configuration
+  start       Start OGP daemon
+  stop        Stop OGP daemon
+  status      Show daemon status
+  federation  Manage federation
+  agent-comms Configure agent-to-agent messaging
+  config      Manage configuration
+
+$ ogp federation ?
+Available commands:
+  list     List all peers
+  request  Send federation request
+  approve  Approve pending peer
+  reject   Reject pending peer
+  remove   Remove peer
+  send     Send message to peer
+  agent    Send agent-comms message
+  scopes   View/update scopes
+  alias    Manage peer aliases
+
+$ ogp federation send ?
+Usage: ogp federation send <peer> <intent> <payload>
+
+Arguments:
+  peer     Peer ID, alias, or display name
+  intent   Intent type (message, task-request, status-update, agent-comms, project.*)
+  payload  JSON payload
+
+Example:
+  ogp federation send apollo message '{"text":"Hello from OGP!"}'
+```
+
+## Implementation Plan
+
+### Phase 1: Framework Detection & Storage
+**File:** `src/shared/frameworks.ts`
+```typescript
+export interface Framework {
+  id: string;           // 'openclaw' | 'hermes' | 'standalone'
+  name: string;         // Display name
+  detected: boolean;    // Auto-detected during setup
+  enabled: boolean;     // User selected during setup
+  configDir: string;    // e.g., ~/.ogp-openclaw/
+  daemonPort: number;   // e.g., 18790
+  gatewayUrl?: string;  // User-provided during setup
+}
+
+export function detectFrameworks(): Framework[] {
+  return [
+    {
+      id: 'openclaw',
+      name: 'OpenClaw',
+      detected: fs.existsSync(expandTilde('~/.openclaw')) || commandExists('openclaw'),
+      enabled: false,
+      configDir: '~/.ogp-openclaw',
+      daemonPort: 18790
+    },
+    {
+      id: 'hermes',
+      name: 'Hermes',
+      detected: fs.existsSync(expandTilde('~/.hermes')) || commandExists('hermes'),
+      enabled: false,
+      configDir: '~/.ogp-hermes',
+      daemonPort: 18793
+    },
+    {
+      id: 'standalone',
+      name: 'Standalone (no framework)',
+      detected: true,
+      enabled: false,
+      configDir: '~/.ogp',
+      daemonPort: 18790
+    }
+  ];
+}
+```
+
+**File:** `~/.ogp-meta/config.json`
+```json
+{
+  "frameworks": [
+    {
+      "id": "openclaw",
+      "enabled": true,
+      "configDir": "~/.ogp-openclaw",
+      "daemonPort": 18790,
+      "gatewayUrl": "https://ogp.sarcastek.com",
+      "displayName": "Junior @ OpenClaw"
+    },
+    {
+      "id": "hermes",
+      "enabled": true,
+      "configDir": "~/.ogp-hermes",
+      "daemonPort": 18793,
+      "gatewayUrl": "https://hermes.sarcastek.com",
+      "displayName": "Apollo @ Hermes"
+    }
+  ],
+  "default": "openclaw",
+  "aliases": {
+    "oc": "openclaw",
+    "ap": "hermes"
+  }
+}
+```
+
+### Phase 2: CLI Flag & Auto-selection
+**File:** `src/cli.ts`
+```typescript
+program
+  .option('--for <framework>', 'Select framework (openclaw, hermes, all)')
+  .hook('preAction', (thisCommand, actionCommand) => {
+    const meta = loadMetaConfig();
+    let selectedFramework = thisCommand.opts().for;
+
+    if (!selectedFramework) {
+      const enabled = meta.frameworks.filter(f => f.enabled);
+      if (enabled.length === 0) {
+        console.error('No frameworks configured. Run `ogp setup` first.');
+        process.exit(1);
+      } else if (enabled.length === 1) {
+        selectedFramework = enabled[0].id;
+      } else if (meta.default) {
+        selectedFramework = meta.default;
+      } else {
+        // Interactive prompt
+        selectedFramework = await selectFramework(enabled);
+      }
+    }
+
+    // Resolve alias
+    selectedFramework = meta.aliases[selectedFramework] || selectedFramework;
+
+    // Set OGP_HOME for selected framework
+    const framework = meta.frameworks.find(f => f.id === selectedFramework);
+    if (!framework) {
+      console.error(`Framework not found: ${selectedFramework}`);
+      process.exit(1);
+    }
+
+    process.env.OGP_HOME = expandTilde(framework.configDir);
+  });
+```
+
+### Phase 3: Tab Completion
+**File:** `scripts/install-completion.sh`
+```bash
+#!/bin/bash
+# Generate completion script for bash/zsh
+
+if [ -n "$BASH_VERSION" ]; then
+  # Bash completion
+  cat > ~/.ogp-completion.bash <<'EOF'
+_ogp_completion() {
+  local cur prev opts
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Top-level commands
+  if [ $COMP_CWORD -eq 1 ]; then
+    opts="setup start stop status federation agent-comms config"
+    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+    return 0
+  fi
+
+  # --for flag completion
+  if [ "$prev" = "--for" ]; then
+    frameworks=$(ogp config list-frameworks --quiet)
+    COMPREPLY=( $(compgen -W "${frameworks}" -- ${cur}) )
+    return 0
+  fi
+
+  # federation subcommands
+  if [ "${COMP_WORDS[1]}" = "federation" ]; then
+    opts="list request approve reject remove send agent scopes alias"
+    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+    return 0
+  fi
+}
+
+complete -F _ogp_completion ogp
+EOF
+  echo "source ~/.ogp-completion.bash" >> ~/.bashrc
+  echo "✓ Bash completion installed. Restart your shell or run: source ~/.bashrc"
+
+elif [ -n "$ZSH_VERSION" ]; then
+  # Zsh completion (similar structure)
+  echo "✓ Zsh completion not yet implemented"
+fi
+```
+
+### Phase 4: `?` Style Help
+**File:** `src/cli.ts`
+```typescript
+// Intercept '?' as a special argument
+program.hook('preAction', (thisCommand, actionCommand) => {
+  const args = process.argv;
+  const hasQuestionMark = args.includes('?');
+
+  if (hasQuestionMark) {
+    // Show context-sensitive help
+    const commandChain = args.slice(2).filter(a => a !== '?');
+    showContextHelp(commandChain);
+    process.exit(0);
+  }
+});
+
+function showContextHelp(commandChain: string[]) {
+  if (commandChain.length === 0) {
+    // ogp ?
+    console.log('Available commands:');
+    program.commands.forEach(cmd => {
+      console.log(`  ${cmd.name().padEnd(15)} ${cmd.description()}`);
+    });
+  } else if (commandChain[0] === 'federation') {
+    // ogp federation ?
+    const fedCmd = program.commands.find(c => c.name() === 'federation');
+    console.log('Available federation commands:');
+    fedCmd?.commands.forEach(cmd => {
+      console.log(`  ${cmd.name().padEnd(15)} ${cmd.description()}`);
+    });
+  } else if (commandChain[0] === 'federation' && commandChain[1] === 'send') {
+    // ogp federation send ?
+    console.log('Usage: ogp federation send <peer> <intent> <payload>');
+    console.log('');
+    console.log('Arguments:');
+    console.log('  peer     Peer ID, alias, or display name');
+    console.log('  intent   Intent type (message, task-request, status-update, agent-comms, project.*)');
+    console.log('  payload  JSON payload');
+    console.log('');
+    console.log('Example:');
+    console.log('  ogp federation send apollo message \'{"text":"Hello from OGP!"}\'');
+  }
+}
+```
+
+## Migration Path
+
+### For Existing Users
+1. Detect existing `~/.ogp/` and `~/.ogp-hermes/` directories
+2. Auto-create `~/.ogp-meta/config.json` with both frameworks enabled
+3. Rename directories:
+   - `~/.ogp/` → `~/.ogp-openclaw/` (if OpenClaw detected)
+   - Keep `~/.ogp-hermes/` as-is
+4. Show migration notice on first run
+
+### Backward Compatibility
+- Still respect `OGP_HOME` environment variable if set (takes precedence over `--for`)
+- Old commands work as-is if only one framework is configured
+- `ogp start` without `--for` starts daemon for current framework context
+
+## Benefits
+
+1. **Native feel**: No more `OGP_HOME=~/.ogp-hermes ogp ...` commands
+2. **Discoverability**: `?` help makes it easy for new users
+3. **Power user friendly**: Tab completion, aliases, defaults
+4. **Clean separation**: Each framework has isolated state/config
+5. **Multi-framework operations**: `--for all` runs commands across all frameworks
+
+## Implementation Notes
+
+### Resolved Design Questions
+
+1. **Custom framework definitions:** Not yet supported in v0.4.0. Future enhancement for users with multiple instances of the same framework.
+
+2. **Daemon lifecycle:** Implemented as Option B - `ogp start` starts daemon for current/default context, `ogp --for all start` starts all configured framework daemons.
+
+3. **Framework config location:** Framework-specific configs remain in their own directories (`~/.ogp-openclaw/`, `~/.ogp-hermes/`), with meta-config centralized at `~/.ogp-meta/config.json`.
+
+### See Also
+
+- [Getting Started Guide](./GETTING-STARTED.md) - Complete setup and usage guide
+- [CLI Reference](./CLI-REFERENCE.md) - Full command documentation
+- [Migration Guide](./MIGRATION.md) - Upgrading from single to multi-framework
+- [Implementation Details](./MULTI-FRAMEWORK-IMPL.md) - Technical implementation notes

package/docs/MULTI-FRAMEWORK-IMPL.md

@@ -0,0 +1,197 @@
+# Multi-Framework Implementation Plan
+
+**Status:** ✅ Implemented in OGP v0.4.0+
+
+> Historical note, April 9, 2026: this file is primarily an implementation log.
+> Some unchecked items below were not maintained after features landed.
+> In particular, completion and `?` help are present in the codebase even though later checklist sections still show them as pending.
+> Do not use this file as the canonical active backlog.
+
+This document tracks the implementation status of multi-framework support.
+
+## Phase 1: Core Infrastructure ✅ COMPLETED
+
+### 1.1 Meta Configuration ✅
+- [x] Create `~/.ogp-meta/` directory structure
+- [x] Implement `loadMetaConfig()` and `saveMetaConfig()` functions
+- [x] Define `Framework` interface and schema
+- [x] Add framework detection logic (check for `~/.openclaw/`, `~/.hermes/`, command existence)
+
+**Files created:**
+- `src/shared/meta-config.ts` - Meta config management
+- `src/shared/framework-detection.ts` - Auto-detect installed frameworks
+
+### 1.2 Migration for Existing Users ✅
+- [x] Detect existing `~/.ogp/` and `~/.ogp-hermes/` installations
+- [x] Auto-create meta config from existing installations
+- [x] Show migration notice with new command patterns
+
+**Files modified:**
+- `src/cli.ts` - Add migration check on startup
+- `src/shared/migration.ts` - Migration logic
+
+### 1.3 `--for` Flag ✅
+- [x] Add global `--for <framework>` option to CLI
+- [x] Implement framework selection logic (auto-select, prompt, or explicit)
+- [x] Set `OGP_HOME` based on selected framework
+- [x] Handle `all` value for multi-framework operations
+
+**Files modified:**
+- `src/cli.ts` - Add `preAction` hook for framework selection
+
+## Phase 2: Setup Wizard ✅ COMPLETED
+
+### 2.1 Interactive Setup ✅
+- [x] Rewrite `ogp setup` to be framework-aware
+- [x] Show detected frameworks with checkboxes
+- [x] Prompt for gateway URL per framework
+- [x] Prompt for display name per framework
+- [x] Save to meta config
+
+**Files modified:**
+- `src/cli/setup.ts` - Interactive framework setup
+
+### 2.2 Config Management Commands ✅
+- [x] `ogp config list` - Show all configured frameworks
+- [x] `ogp config set-default <framework>` - Set default framework
+- [x] `ogp config enable <framework>` - Enable a framework
+- [x] `ogp config disable <framework>` - Disable a framework
+- [x] `ogp config show` - Show current configuration
+
+**Files created:**
+- `src/cli/config.ts` - Config management commands
+
+## Phase 3: Tab Completion ⏳ IN PROGRESS
+
+### 3.1 Completion Script Generation
+- [ ] Create bash completion script template
+- [ ] Create zsh completion script template
+- [ ] Implement `ogp completion install` command
+- [ ] Add completion for top-level commands
+- [ ] Add completion for `--for` flag (framework names + aliases)
+- [ ] Add completion for peer names/aliases
+
+**Files to create:**
+- `scripts/completion.bash` - Bash completion template
+- `scripts/completion.zsh` - Zsh completion template
+- `src/cli/completion.ts` - Completion installer
+
+**Status:** Documented but not yet implemented in code.
+
+### 3.2 Dynamic Completions
+- [ ] `ogp config list --quiet` - Output framework IDs for completion
+- [ ] `ogp federation list --quiet` - Output peer names/aliases for completion
+
+## Phase 4: `?` Style Help ⏳ IN PROGRESS
+
+### 4.1 Help Interceptor
+- [ ] Add `preAction` hook to detect `?` in arguments
+- [ ] Implement context-sensitive help based on command chain
+- [ ] Show available subcommands
+- [ ] Show usage examples
+- [ ] Show available peers (for federation commands)
+
+**Files to modify:**
+- `src/cli.ts` - Add `?` interceptor
+- `src/shared/help.ts` - Context-sensitive help formatter
+
+**Status:** Documented but not yet implemented in code.
+
+### 4.2 Enhanced Help for Key Commands
+- [ ] `ogp ?` - Top-level commands
+- [ ] `ogp federation ?` - Federation subcommands
+- [ ] `ogp federation send ?` - Send command usage + peer list
+- [ ] `ogp federation agent ?` - Agent-comms usage + peer list
+- [ ] `ogp agent-comms ?` - Agent-comms subcommands
+
+## Phase 5: Multi-Framework Operations ✅ COMPLETED
+
+### 5.1 `--for all` Support ✅
+- [x] Run command on all enabled frameworks sequentially
+- [x] Aggregate results with framework labels
+- [x] Handle errors gracefully (continue on failure)
+
+**Implementation:** Commands support `--for all` with framework-labeled output.
+
+### 5.2 Daemon Lifecycle ✅
+- [x] `ogp start` - Start daemon for current framework
+- [x] `ogp --for all start` - Start daemons for all enabled frameworks
+- [x] `ogp stop` - Stop daemon for current framework
+- [x] `ogp --for all stop` - Stop all framework daemons
+- [x] `ogp status` - Show status for current framework
+- [x] `ogp --for all status` - Show status for all frameworks
+
+**Files modified:**
+- `src/cli.ts` - Updated start/stop/status commands
+
+## Testing Plan
+
+### Unit Tests ✅
+- [x] Framework detection logic
+- [x] Meta config load/save
+- [x] Framework selection (auto, prompt, explicit)
+- [x] Migration logic
+
+### Integration Tests ✅
+- [x] Setup wizard with multiple frameworks
+- [x] Command execution with `--for` flag
+- [x] Default framework behavior
+- [x] `--for all` aggregation
+
+### Manual Testing ✅
+- [x] Fresh install on clean machine
+- [x] Migration from existing single-framework setup
+- [x] Migration from existing multi-framework setup
+- [ ] Tab completion (bash and zsh) - Pending implementation
+- [ ] `?` help in various contexts - Pending implementation
+
+## Documentation ✅ COMPLETED
+
+### User-Facing Docs ✅
+- [x] Update README with multi-framework examples
+- [x] Create GETTING-STARTED guide with framework setup
+- [x] Update all examples to show `--for` flag usage
+- [x] Add tab completion installation instructions
+- [x] Create CLI-REFERENCE with complete command documentation
+
+**Files created/updated:**
+- `README.md` - Updated with multi-framework examples
+- `docs/GETTING-STARTED.md` - Comprehensive setup and usage guide
+- `docs/CLI-REFERENCE.md` - Complete command reference
+- `docs/MIGRATION.md` - Migration guide for existing users
+
+### Developer Docs ✅
+- [x] Document meta config schema
+- [x] Document framework detection logic
+- [x] Document migration path for existing users
+
+## Success Metrics
+
+1. ✅ New users can set up OGP for multiple frameworks in < 2 minutes
+2. ✅ Existing users can migrate without manual config editing
+3. ⏳ Tab completion works for all major commands (documented, pending implementation)
+4. ⏳ `?` help provides useful context at every level (documented, pending implementation)
+5. ✅ Zero breaking changes for single-framework users
+
+## Breaking Changes (None!)
+
+- ✅ Old `OGP_HOME` environment variable still works (takes precedence)
+- ✅ Single-framework setups work exactly as before (auto-selected)
+- ✅ All existing commands maintain backward compatibility
+
+## Future Enhancements (Post-v1.0)
+
+- [ ] Framework aliases (`ogp alias add oc openclaw`)
+- [ ] Custom framework definitions (for multiple OpenClaw instances)
+- [ ] Framework-specific config overrides
+- [ ] Cross-framework federation status view
+- [ ] Framework health monitoring dashboard
+- [ ] Tab completion implementation (currently documented)
+- [ ] `?` style help implementation (currently documented)
+
+## See Also
+
+- [Getting Started Guide](./GETTING-STARTED.md) - Complete setup and workflows
+- [CLI Reference](./CLI-REFERENCE.md) - Full command documentation
+- [Migration Guide](./MIGRATION.md) - Upgrading to multi-framework
+- [Design Document](./MULTI-FRAMEWORK-DESIGN.md) - Design principles