feat(cli): Bun-first CLI migration with 7 commands and comprehensive test suite (#259 )

* feat(cli): migrate packages/cli to Bun-first with full test suite

- Replace fs-extra with Bun.file/Bun.write/node:fs/promises across all 9 source files
- Fix --help fast-path so all 8 subcommands are visible
- Replace tsup/tsx/vitest with bun build/bun run/bun:test
- Replace __dirname with import.meta.dir; use JSON import assertion for version
- Fix hardcoded OAC_VERSION in add.ts; add hashesMatch import to status.ts
- Replace computeFileHash with Bun.file().bytes() in sha256.ts
- Rename checkNodeVersion → checkBunVersion; parallelise doctor checks
- Fix TypeScript void-inference errors in update.ts, list.ts, status.ts
  by replacing .catch() with let/try-catch where result is used downstream
- Add ManifestError named error class; remove unsafe type casts
- Add 43 bun:test unit tests (sha256, manifest, installer, version) — 0 failures

* fix(cli): resolve critical bugs and standards violations found in review

Critical bug fixes:
- ide-detect.ts: replace Bun.file(dir).exists() with stat().isDirectory()
  for all directory checks — Bun.file().exists() always returns false for
  directories, breaking Cursor/Windsurf/OpenCode/Claude detection entirely
- bundled.ts: add registry.json exclusion anchor to findPackageRoot() to
  prevent monorepo root from matching before the CLI package root

Standards cleanup (§4.1, §5.1, §6.1, §15.3, §21.1):
- status.ts: parallelise findModifiedFiles + detectIdes with Promise.all
- apply.ts: fix duplicate warn/limit messages; remove else after return in
  reportWarnings; remove redundant mkdir before Bun.write
- version.ts: remove unnecessary (pkgJson as {version?:string}) cast
- manifest.ts: remove redundant mkdir before Bun.write; remove as unknown cast
- installer.ts: remove redundant mkdir calls before Bun.write throughout
- add.ts: add comment explaining why node:fs/promises rm is used

Tests (43 → 142, +99 new tests across 4 new files):
- ide-detect.test.ts: 26 tests covering all 4 IDEs, both claude indicators,
  detectIdes parallel, isIdePresent — directly validates the directory fix
- bundled.test.ts: 27 tests for classifyBundledFile, findPackageRoot,
  listBundledFiles, getBundledFilePath, bundledFileExists
- config.test.ts: 25 tests for readConfig/writeConfig round-trips,
  createDefaultConfig, mergeConfig, isYoloMode, isAutoBackup
- installer-update.test.ts: 14 tests covering all 5 updateFiles decision
  branches (install/update/skip/yolo/dry-run) plus isProjectRoot
- sha256.test.ts: +4 tests for empty file, large file, binary content

* fix(cli): fix P0 bugs — global flags, .git detection, package root resolution

- Remove duplicate --dry-run/--yolo/--verbose from parent program; Commander.js
  global option stealing caused all safety flags to be silently dropped in every
  subcommand action callback
- Fix isProjectRoot() to use stat() for .git detection; Bun.file().exists()
  returns false for directories, breaking oac init in standard git repos
- Add OAC_PACKAGE_ROOT env var override to getPackageRoot() for dev/monorepo mode;
  registry.json heuristic excluded the repo root causing oac init/add/update to
  throw when run from source
- Fix build script: remove --banner flag that caused double shebang in dist/index.js
- Rewrite bin/oac.js to invoke bun instead of node (dist is bun-only target)
- Refactor installer.ts let accumulators to const using Promise.all + reduce
- Add MVP planning docs (00-MVP-PLAN.md, master synthesis, project breakdown)

* fix(install.sh): handle both singular and plural component type formats

The get_registry_key() function was always adding 's' to the type,
causing 'contexts' to become 'contextss' which doesn't exist in registry.json.

Now handles:
- Singular forms: context → contexts, agent → agents, skill → skills
- Plural forms: contexts → contexts (unchanged), agents → agents
- Config stays singular
- Fallback for any type ending in 's'

Fixes #257

2026-03-24 21:54:03 +00:00

9.6 KiB

Raw Blame History

OAC Package Refactor - Planning Index

Date: 2026-02-14
Status: Comprehensive Planning Phase
Branch: feature/oac-package-refactor
Issue: #206

🎯 MVP Plan (START HERE)

mvp/00-MVP-PLAN.md — The 20% that delivers 80% of the value. 5 commands, 6 weeks, focused on what users actually care about. This is what we build first. Everything else is v1.1+.

📁 Full Planning Documents (Reference)

Core Planning

01-main-plan.md (62KB)
- Complete feature specification
- 7-phase implementation plan
- All critical features documented
- CLI commands reference
- Configuration schemas
- Examples and best practices
02-quickstart-guide.md (12KB)
- Quick reference for Phase 1
- Task breakdown
- Validation steps
- Testing strategy
- Development workflow
03-critical-feedback.md (14KB)
- Parallel agent review findings
- Critical additions required
- Approaches to rethink
- Repository structure recommendations
- Community contribution workflow

User Scenario Analysis (Coming)

04-solo-developer-scenarios.md
- Individual developer workflows
- Pain points and solutions
- Key experiences
- Edge cases
05-team-lead-scenarios.md
- Team management workflows
- Standardization needs
- Collaboration features
- Governance requirements
06-enterprise-scenarios.md
- Large organization needs
- Security and compliance
- Policy enforcement
- Audit trails
07-content-creator-scenarios.md
- Non-technical user workflows
- Simplified interfaces
- Template-based workflows
- Onboarding needs
08-open-source-maintainer-scenarios.md
- Community management
- Contribution workflows
- Quality control
- Documentation needs

Architecture & System Design

09-SYNTHESIS.md (14KB)
- Consolidated findings from all scenarios
- Common patterns identified
- Feature prioritization
10-FINAL-REVIEW.md (5KB)
- Final review and sign-off
- Implementation readiness
11-json-config-system.md (NEW - 85KB)
- JSON-based agent configuration system
- Single source of truth architecture
- Multi-IDE conversion system
- Type-safe configuration with TypeScript
- Schema validation and versioning
- Migration path from markdown to JSON
- 6-week implementation plan

🎯 Planning Objectives

Phase 1: Core Planning (Complete)

✅ Define vision and goals
✅ Design architecture
✅ Identify critical features
✅ Get expert feedback
✅ Add customization system

Phase 2: User Scenario Analysis (In Progress)

⬜ Analyze solo developer workflows
⬜ Analyze team workflows
⬜ Analyze enterprise workflows
⬜ Analyze content creator workflows
⬜ Analyze open source maintainer workflows

Phase 3: Synthesis & Refinement (Next)

⬜ Consolidate findings
⬜ Identify common patterns
⬜ Resolve conflicts
⬜ Finalize feature set
⬜ Update implementation plan

📊 Key Features Summary

Critical Features (Must Have v1.0)

User Approval System
- Interactive approval for all file operations
- YOLO mode for power users
- Conflict resolution strategies
- Backup and rollback support
Context Resolution
- 6-layer priority system
- Smart resolution based on agent location
- Project override support
- Fallback strategies
Multi-IDE Support
- OpenCode (full support)
- Claude Code (full support)
- Cursor (limited, optimized)
- Windsurf (partial support)
- Feature parity matrix
- Adaptive installation
Agent Customization
- Personal presets
- Safe editing workflow
- Update management with merge
- Preset sharing
- In-place editing (advanced)
Discovery & Browse
- Interactive TUI browser
- Search functionality
- Component info
- Preview mode
Security & Verification
- Component signing
- Checksum verification
- Malware scanning
- Secret detection
- Permission system
Lockfile & Reproducibility
- Version locking
- Frozen installs
- Dependency resolution
- Conflict detection
Interactive Onboarding
- First-time setup wizard
- Smart defaults
- Use case detection
- IDE detection
Component Creation
- Interactive wizard
- Template system
- Auto-scaffolding
- Multi-IDE support
Community Registry
- shadcn-like model
- Component marketplace
- Ratings and reviews
- Verified publishers

🏗️ Architecture Summary

Repository Structure (Monorepo)

@nextsystems/oac/
├── packages/
│   ├── core/          # Core CLI
│   ├── adapters/      # IDE adapters
│   ├── registry/      # Registry management
│   ├── security/      # Security scanning
│   └── cli/           # CLI entry point
├── .opencode/         # Official components
├── registry.json
└── pnpm-workspace.yaml

Configuration Layers

1. Project Override    (./.oac/context/)      [Highest]
2. Project Context     (./.opencode/context/)
3. IDE Context         (./.cursor/context/)
4. Project Docs        (./docs/context/)
5. User Global         (~/.config/oac/context/)
6. OAC Official        (~/.config/oac/official/) [Lowest]

Preset System

~/.config/oac/
├── presets/
│   ├── agents/
│   │   ├── my-openagent.md
│   │   └── my-opencoder.md
│   └── .presets.json

📋 Implementation Phases

Phase 1: Core CLI Infrastructure (Week 1)

TypeScript project setup
Configuration system (global + local)
Approval system (interactive + YOLO)
Context resolver (6-layer)
Discovery (browse, search)
Security (verify, checksum)
Onboarding (interactive init)
Progress UI (spinners, bars)

Phase 2: Registry & Components (Week 2)

Registry loader/resolver
Component installer
Profile installer
Lockfile generation
Version conflict detection
Semver support

Phase 3: IDE Adapters (Week 3)

Integrate compatibility layer
IDE-specific installers
Feature parity system
Apply command
Preset system

Phase 4: Update System (Week 4)

Version checker
Update fetcher/applier
Update command
Preset merge strategies

Phase 5: Context System (Week 5)

Context locator service
Multi-location resolution
Validation
Composition (not merging)

Phase 6: Community Registry (Week 6)

Component package format
Add/publish commands
Component creation wizard
Search/browse functionality
Security scanning pipeline

Phase 7: Polish & Docs (Week 7)

Error handling
UX improvements
Documentation
Migration guide
npm publish

🚨 Critical Issues Identified

Security (BLOCKER)

No component signing
No malware scanning
No secret detection
Action: Add security layer in Phase 1

Discovery (CRITICAL GAP)

Users can't find components
Action: Add browse/search in Phase 1

Lockfile (CRITICAL GAP)

No reproducible installs
Action: Add lockfile in Phase 2

Version Conflicts (CRITICAL GAP)

No conflict resolution
Action: Add semver + conflict detection in Phase 2

Onboarding (HIGH PRIORITY)

First-time users need guidance
Action: Add interactive wizard in Phase 1

🎯 User Personas

1. Solo Developer (Primary)

Uses OpenCode/Cursor for personal projects
Wants quick setup, minimal config
Explores new agents frequently
Values speed and simplicity

2. Team Lead (Secondary)

Manages 5-10 developers
Needs standardized setup
Wants to enforce best practices
Values reproducibility

3. Content Creator (Emerging)

Uses agents for writing, not coding
Less technical, needs clear CLI
Wants pre-built workflows
Values templates and examples

4. Enterprise Admin (Future)

Manages 50+ developers
Needs security, compliance, governance
Wants central management
Values audit trails, policies

5. Open Source Maintainer (Future)

Manages community contributions
Needs quality control
Wants automated workflows
Values documentation

📚 Documentation Requirements

Before Launch

Quick Start (5-minute guide)
CLI Reference (auto-generated)
Recipes (common workflows)
Component Creation Guide
Migration Guide
Troubleshooting Guide

Post-Launch

Video Tutorials
Interactive Playground
API Documentation
Plugin Development Guide

📊 Success Metrics (6 Months)

Metric	Target
GitHub stars	1,000+
npm downloads/month	10,000+
Community components	50+
Active contributors	20+
Docs page views	5,000+/month
Support tickets	<5/week

🔄 Next Steps

Immediate

✅ Consolidate planning documents
⬜ Analyze user scenarios (5 parallel agents)
⬜ Synthesize findings
⬜ Finalize feature set
⬜ Update implementation plan

Before Phase 1

⬜ Set up monorepo structure
⬜ Create security scanning workflow
⬜ Design TUI for browse command
⬜ Write Quick Start docs

Phase 1 Start

⬜ TypeScript project setup
⬜ Install dependencies
⬜ Implement core systems
⬜ Write tests

📝 Notes

All planning documents are in .tmp/PLANNING-REFACTOR/
User scenario analysis in progress (5 parallel agents)
Synthesis and refinement will follow
Implementation starts after planning complete

Last Updated: 2026-02-15
Status: Planning Phase - Architecture Design Complete
Confidence: High (98% - JSON config system designed)

9.6 KiB Raw Blame History