CLI Redesign: Resource-Oriented Architecture (v0.4.0)

[acossta]

Overview

Redesign the CLI to use a consistent resource-oriented architecture pattern, similar to Docker and Kubernetes. This will introduce breaking changes for v0.4.0.

Problem Statement

The current CLI has inconsistent command patterns:

• Mix of verb-noun (captan issue) and noun-verb (captan enlist stakeholder)
• Unclear conventions for listing resources (captan safes vs captan list stakeholders)
• Confusing top-level list command that doesn't follow RESTful patterns
• Inconsistent parameter notation (missing brackets for optional parameters)

Solution: Resource-Oriented Design

Core Principles

1. Resource-first: Commands start with the resource type (stakeholder, safe, security, etc.)
2. RESTful verbs: Use standard verbs (add, list, show, update, delete)
3. Consistent notation: Use [param] for optional parameters everywhere
4. Dual identifiers: Support both ID and email for stakeholder lookups

New Command Structure

Stakeholder Commands

captan stakeholder add --name "Alice" --email "alice@example.com" [--entity PERSON]
captan stakeholder list [--format json]
captan stakeholder show [id-or-email]
captan stakeholder update [id-or-email] [--name "New Name"] [--email "new@example.com"]
captan stakeholder delete [id-or-email]

Security Class Commands

captan security add --kind COMMON --label "Common Stock" [--authorized 10000000]
captan security list [--format json]
captan security show [id]
captan security update [id] [--authorized 20000000]
captan security delete [id]

Issuance Commands

captan issuance add --stakeholder [id-or-email] --security [id] --qty 1000000
captan issuance list [--stakeholder id-or-email] [--format json]
captan issuance show [id]
captan issuance update [id] [--qty 2000000]
captan issuance delete [id]

Option Grant Commands

captan grant add --stakeholder [id-or-email] --qty 100000 --exercise 0.10
captan grant list [--stakeholder id-or-email] [--format json]
captan grant show [id]
captan grant update [id] [--vesting-start 2024-06-01]
captan grant delete [id]

SAFE Commands

captan safe add --stakeholder [id-or-email] --amount 100000 [--cap 5000000]
captan safe list [--stakeholder id-or-email] [--format json]
captan safe show [id]
captan safe update [id] [--discount 20]
captan safe delete [id]
captan safe convert --pre-money 10000000 --pps 2.00 [--dry-run]

Report Commands

captan report summary [--format json]
captan report ownership [--date 2024-01-01]
captan report stakeholder [id-or-email]
captan report security [id]

Export Commands

captan export csv [--output captable.csv]
captan export json [--output captable.json]
captan export pdf [--output captable.pdf]

System Commands

captan init [--wizard] [--name "Company"] [--authorized 10000000]
captan validate [--extended] [--file captable.json]
captan schema [--output captable.schema.json]
captan log [--action ISSUE] [--limit 10]
captan version
captan help [command]

Implementation Plan

Phase 1: Architecture Refactoring

• Create new command structure using Commander.js subcommands
• Implement resource-based command routing
• Add parameter validation layer
• Create identifier resolution system (ID or email)

Phase 2: Command Migration

• Migrate stakeholder commands
• Migrate security commands
• Migrate issuance commands
• Migrate grant commands
• Migrate SAFE commands
• Migrate report commands
• Migrate export commands
• Migrate system commands

Phase 3: Testing

• Unit tests for all command handlers (200+ tests)
• Integration tests for command flows (150+ tests)
• E2E tests for complete workflows (50+ tests)
• Identifier resolution tests (30+ tests)
• Error handling tests (50+ tests)
• Parameter validation tests (40+ tests)
• Migration guide tests (10+ tests)

Phase 4: Documentation

• Update README with new command structure
• Create migration guide from v0.3.x to v0.4.0
• Update all code examples
• Add command reference documentation
• Create video tutorials for new structure

Testing Strategy

Coverage Goals

• Overall: >85%
• Command handlers: >90%
• Business logic: >95%
• Utilities: >80%

Test Categories

1. Unit Tests (400+ tests)

   • Command parsing
   • Parameter validation
   • Identifier resolution
   • Business logic

2. Integration Tests (150+ tests)

   • Command execution
   • File I/O
   • Service integration
   • Error propagation

3. E2E Tests (50+ tests)

   • Complete workflows
   • Real file operations
   • CLI interaction
   • Output formatting

Breaking Changes

Commands That Will Break

• captan enlist stakeholder → captan stakeholder add
• captan security:add → captan security add
• captan issue → captan issuance add
• captan grant → captan grant add
• captan safe → captan safe add
• captan safes → captan safe list
• captan list stakeholders → captan stakeholder list
• captan list securities → captan security list
• captan chart → captan report ownership
• captan convert → captan safe convert

No Migration Path

Since v0.4.0 is still early in the project lifecycle, we won't provide backward compatibility or aliases. Users will need to update their scripts.

Success Criteria

• All commands follow resource-oriented pattern
• Consistent parameter notation throughout
• ID/email resolution works for all stakeholder operations
• Test coverage >85%
• Zero regression in functionality
• Clear migration documentation
• Performance remains unchanged or improves

Timeline

• Week 1-2: Architecture refactoring and command structure
• Week 3-4: Command migration and core functionality
• Week 5: Comprehensive testing
• Week 6: Documentation and release preparation

Notes

• This is a breaking change for v0.4.0
• No backward compatibility will be maintained
• Focus on consistency and developer experience
• Consider this the "1.0 architecture" that we'll maintain long-term

References

• Docker CLI design: https://docs.docker.com/engine/reference/commandline/cli/
• Kubernetes kubectl: https://kubernetes.io/docs/reference/kubectl/
• RESTful API design: https://restfulapi.net/resource-naming/

[acossta]

✅ Completed in PR #24

The CLI redesign to resource-oriented architecture has been successfully implemented and released in v0.4.0.

What was delivered:

• ✨ Complete CLI redesign with resource-verb pattern (e.g., captan stakeholder add)
• 🔍 Email-based stakeholder resolution with fuzzy matching
• ✅ 886 comprehensive tests
• 📚 Full migration from old command structure
• ⚡ Performance testing for 50,000+ stakeholder cap tables

Released in:

• PR: feat: Complete CLI redesign with comprehensive testing #24
• Release: v0.4.0
• npm: https://www.npmjs.com/package/captan/v/0.4.0
• GitHub Release: https://github.com/acossta/captan/releases/tag/v0.4.0

All success criteria from this issue have been met.