Startsida Utforska Hjälp
Logga in
logic855
/
OpenAgentsControl
spegling av https://github.com/darrenhinde/OpenAgentsControl.git
1
0
Fork 0
Filer Ärenden 0 Wiki
Träd: 40dd267b12
Grenar Taggar
OpenAgentsCo...
/
docs
/
planning
/
02-quickstart-guide.md

02-quickstart-guide.md 12 KB
Historik Rå

OAC Package Refactor - Quick Start

Purpose: Quick reference for working on the OAC package refactor
Issue: #206
Branch: feature/oac-package-refactor
Context: features/oac-package-refactor.md

Current Status

✅ Planning Complete

  • Context file created
  • GitHub issue #206 created
  • Feature branch created and pushed
  • CRITICAL features defined:
    • User approval system with YOLO mode
    • Layered context resolution (project + global)

📝 Next: Phase 1 - Core CLI Infrastructure

Critical Features Overview

1. User Approval System

  • Default: Interactive approval for ALL file operations
  • YOLO Mode (--yolo): Skip confirmations, auto-resolve, report at end
  • Always asks: Local vs global install location
  • Conflict handling: Show diffs, ask user, create backups
  • Safety: Git detection, rollback support, audit log

2. Context Resolution

  • 6-layer priority: Project override → Project → IDE → Docs → User global → OAC official
  • Smart resolution: Based on agent location (global vs local)
  • Configurable: preferLocal option
  • CLI tools: oac context resolve, list, validate, override, sync

Quick Commands

# Switch to feature branch
git checkout feature/oac-package-refactor

# View full context
cat .opencode/context/openagents-repo/features/oac-package-refactor.md

# View GitHub issue
gh issue view 206

# Start Phase 1
# (See Phase 1 section below)

Phase 1: Core CLI Infrastructure

Goal: Set up TypeScript project and configuration system

Tasks

  1. Set up TypeScript project structure

    mkdir -p src/{cli/{commands,config},core/{context,installer,approval},types,utils}
npm install --save-dev typescript @types/node tsx vitest
npx tsc --init

  2. Install CLI dependencies

    npm install commander inquirer zod chalk ora boxen
npm install --save-dev @types/inquirer

  3. Create configuration schema (CRITICAL)

    • File: src/cli/config/schema.ts
    • Use Zod for validation
    • Define OACConfig interface
    • Include: confirmOverwrites, yoloMode, preferLocal, context resolution config

  4. Create configuration manager

    • File: src/cli/config/manager.ts
    • Read/write config files
    • Merge global and local configs (priority: local > global)
    • Validate with schema
    • Support: ~/.config/oac/config.json (global) and .oac/config.json (local)

  5. Create approval system (CRITICAL)

    • File: src/core/approval/manager.ts
    • Interactive prompts for file operations
    • YOLO mode support
    • Conflict resolution strategies
    • Backup management
    • Audit logging

  6. Create context resolver (CRITICAL)

    • File: src/core/context/resolver.ts
    • 6-layer priority resolution
    • Agent location detection (global vs local)
    • preferLocal configuration
    • Fallback support
    • Validation and suggestions

  7. Implement basic CLI commands

    • File: src/cli/index.ts (Commander setup)
    • File: src/cli/commands/configure.ts
    • File: src/cli/commands/list.ts
    • File: src/cli/commands/init.ts
    • Add global flags: --yolo, --dry-run, --local, --global

  8. Update bin/oac.js

    • Point to compiled TypeScript
    • Handle both legacy and new commands
    • Detect current working directory

  9. Write tests

    • Test configuration schema
    • Test config manager (global + local merge)
    • Test approval system (interactive + YOLO)
    • Test context resolver (all 6 layers)
    • Test CLI commands

Deliverables

  • TypeScript project configured
  • Configuration schema defined (with approval + context config)
  • Configuration manager working (global + local merge)
  • Approval system working (interactive + YOLO mode)
  • Context resolver working (6-layer priority)
  • oac configure command works
  • oac list command works
  • oac init command works (asks local vs global)
  • oac context resolve command works
  • Tests passing (including approval + context tests)

Validation

# Test configuration (global + local)
oac configure show
oac configure set agents.permissions.bash auto
oac configure get agents.permissions.bash
oac configure set preferences.yoloMode true

# Test list
oac list
oac list --agents
oac list --local
oac list --global

# Test init (should ask local vs global)
cd /tmp/test-project
oac init developer
# Should prompt: "Install locally or globally?"

# Test approval system
cd /tmp/test-project
oac install opencode
# Should show file list and ask for confirmation

# Test YOLO mode
oac install opencode --yolo
# Should auto-confirm and report at end

# Test context resolution
oac context resolve 'core/standards/code-quality.md'
# Should show resolved path and priority

oac context list
# Should show all context files from all layers

oac context validate
# Should validate all context references

Project Structure (Phase 1)

@nextsystems/oac/
├── bin/
│   └── oac.js                  # Updated entry point
├── src/
│   ├── cli/
│   │   ├── commands/
│   │   │   ├── configure.ts    # NEW - Config management
│   │   │   ├── list.ts         # NEW - List components
│   │   │   ├── init.ts         # NEW - Initialize (asks local/global)
│   │   │   └── context.ts      # NEW - Context commands (resolve, list, validate)
│   │   ├── config/
│   │   │   ├── manager.ts      # NEW - Global + local merge
│   │   │   ├── schema.ts       # NEW - Zod schema (approval + context config)
│   │   │   └── defaults.ts     # NEW - Default config
│   │   └── index.ts            # NEW - Commander setup (global flags)
│   ├── core/
│   │   ├── approval/
│   │   │   ├── manager.ts      # NEW - Approval system (CRITICAL)
│   │   │   ├── strategies.ts   # NEW - Conflict strategies
│   │   │   └── backup.ts       # NEW - Backup management
│   │   ├── context/
│   │   │   ├── resolver.ts     # NEW - 6-layer resolution (CRITICAL)
│   │   │   ├── locator.ts      # NEW - Find context files
│   │   │   └── validator.ts    # NEW - Validate references
│   │   └── installer/
│   │       └── location.ts     # NEW - Detect local vs global
│   ├── types/
│   │   ├── config.ts           # NEW - Config types
│   │   ├── approval.ts         # NEW - Approval types
│   │   └── context.ts          # NEW - Context types
│   └── utils/
│       ├── logger.ts           # NEW - Logging
│       ├── prompts.ts          # NEW - Interactive prompts
│       └── git.ts              # NEW - Git detection
├── config/
│   └── oac.config.json         # NEW - Default config
├── tsconfig.json               # NEW
├── package.json                # UPDATED
└── .opencode/                  # EXISTING

Configuration Schema (Reference)

// src/cli/config/schema.ts
import { z } from 'zod';

export const OACConfigSchema = z.object({
  version: z.string(),
  preferences: z.object({
    defaultIDE: z.enum(['opencode', 'cursor', 'claude', 'windsurf']),
    installLocation: z.enum(['local', 'global']),
    autoUpdate: z.boolean(),
    updateChannel: z.enum(['stable', 'beta', 'alpha'])
  }),
  ides: z.record(z.object({
    enabled: z.boolean(),
    path: z.string(),
    profile: z.string()
  })),
  agents: z.object({
    behavior: z.object({
      approvalGates: z.boolean(),
      contextLoading: z.enum(['lazy', 'eager']),
      delegationThreshold: z.number()
    }),
    permissions: z.object({
      bash: z.enum(['approve', 'auto', 'deny']),
      write: z.enum(['approve', 'auto', 'deny']),
      edit: z.enum(['approve', 'auto', 'deny']),
      task: z.enum(['approve', 'auto', 'deny'])
    })
  }),
  context: z.object({
    locations: z.array(z.string()),
    autoDiscover: z.boolean(),
    cacheEnabled: z.boolean()
  }),
  registry: z.object({
    source: z.string().url(),
    localCache: z.string(),
    updateInterval: z.number()
  })
});

export type OACConfig = z.infer<typeof OACConfigSchema>;

Default Configuration (Reference)

{
  "version": "1.0.0",
  "preferences": {
    "defaultIDE": "opencode",
    "installLocation": "local",
    "autoUpdate": false,
    "updateChannel": "stable"
  },
  "ides": {
    "opencode": {
      "enabled": true,
      "path": ".opencode",
      "profile": "developer"
    },
    "cursor": {
      "enabled": false,
      "path": ".cursor",
      "profile": "developer"
    },
    "claude": {
      "enabled": false,
      "path": ".claude",
      "profile": "developer"
    },
    "windsurf": {
      "enabled": false,
      "path": ".windsurf",
      "profile": "developer"
    }
  },
  "agents": {
    "behavior": {
      "approvalGates": true,
      "contextLoading": "lazy",
      "delegationThreshold": 4
    },
    "permissions": {
      "bash": "approve",
      "write": "approve",
      "edit": "approve",
      "task": "approve"
    }
  },
  "context": {
    "locations": [
      ".opencode/context",
      ".claude/context",
      "docs/context"
    ],
    "autoDiscover": true,
    "cacheEnabled": true
  },
  "registry": {
    "source": "https://raw.githubusercontent.com/darrenhinde/OpenAgentsControl/main/registry.json",
    "localCache": "~/.config/oac/registry.cache.json",
    "updateInterval": 86400
  }
}

Testing Strategy

Unit Tests

// src/cli/config/manager.test.ts
import { describe, it, expect } from 'vitest';
import { ConfigManager } from './manager';

describe('ConfigManager', () => {
  it('should load default config', async () => {
    const manager = new ConfigManager();
    const config = await manager.load();
    expect(config.version).toBe('1.0.0');
  });

  it('should validate config schema', async () => {
    const manager = new ConfigManager();
    const valid = await manager.validate(mockConfig);
    expect(valid).toBe(true);
  });

  it('should merge global and local configs', async () => {
    const manager = new ConfigManager();
    const config = await manager.load();
    expect(config.preferences.defaultIDE).toBeDefined();
  });
});

Integration Tests

# Test CLI commands
npm run build
./bin/oac.js configure show
./bin/oac.js list
./bin/oac.js init developer

Development Workflow

  1. Create feature branch ✅

    git checkout feature/oac-package-refactor

  2. Set up TypeScript project

    mkdir -p src/{cli/{commands,config},core,types,utils}
npm install dependencies
npx tsc --init

  3. Implement Phase 1 tasks

    • Configuration schema
    • Configuration manager
    • CLI commands

  4. Write tests

    npm run test

  5. Build and test locally

    npm run build
npm pack
npm install -g ./nextsystems-oac-*.tgz
oac configure

  6. Commit and push

    git add .
git commit -m "feat(phase1): implement core CLI infrastructure"
git push

Resources

Context Files:

  • features/oac-package-refactor.md - Full feature context
  • core-concepts/registry.md - Registry system
  • guides/npm-publishing.md - Publishing workflow

External Docs:

GitHub:

Next Phase Preview

Phase 2: Registry & Component Management

  • Port registry validation to TypeScript
  • Implement registry loader/resolver
  • Create component installer
  • Profile installer
  • Dependency resolution

Last Updated: 2026-02-14
Status: Ready to start Phase 1