opencastle 0.31.6 → 0.32.0

package/src/cli/convoy/types.ts

@@ -75,9 +75,11 @@ export interface TaskRecord {
   dispute_id: string | null
   drift_score: number | null
   drift_retried: number
+  compaction_count: number
   outputs?: string | null          // JSON array of TaskOutput
   inputs?: string | null           // JSON array of TaskInput
   discovered_issues?: string | null // JSON array
+  contract_result?: string | null  // JSON ContractResult
 }
 
 export interface WorkerRecord {
@@ -117,6 +119,15 @@ export interface PipelineRecord {
   total_cost_usd: number | null
 }
 
+export interface TDDGateConfig {
+  enabled: boolean
+  source_patterns: string[]
+  test_patterns: string[]
+  exclude_patterns: string[]
+  mode: 'warn' | 'block'
+  exempt_agents: string[]
+}
+
 export interface BuiltInGatesConfig {
   secret_scan?: boolean
   blast_radius?: boolean
@@ -124,6 +135,7 @@ export interface BuiltInGatesConfig {
   regression_test?: 'auto' | boolean
   browser_test?: 'auto' | boolean
   gate_timeout?: number
+  tdd_check?: boolean | TDDGateConfig
 }
 
 
@@ -163,6 +175,12 @@ export interface CircuitBreakerConfig {
   fallback_agent?: string // reassign pending tasks when circuit opens
 }
 
+export interface CompactionConfig {
+  enabled: boolean
+  token_threshold_pct: number  // e.g., 70 = compact at 70% of model context window
+  summary_max_tokens: number   // max tokens for the compaction summary
+}
+
 export interface TaskOutput {
   name: string
   type: 'file' | 'summary' | 'json'
@@ -260,6 +278,23 @@ export interface MCPServerConfig {
   config?: Record<string, unknown>
 }
 
+// ── Two-stage review ─────────────────────────────────────────────────────────
+
+export type ReviewStage = 'spec-compliance' | 'code-quality'
+
+export interface StageVerdict {
+  stage: ReviewStage
+  verdict: 'pass' | 'block'
+  issues: string[]
+  tokens_used: number
+}
+
+export interface TwoStageReviewResult {
+  stages: StageVerdict[]
+  overall_verdict: 'pass' | 'block'
+  total_tokens: number
+}
+
 // ---------------------------------------------------------------------------
 // Discriminated union covering every canonical convoy event type.
 // Each variant constrains the `data` shape that callers may pass to emit().
@@ -321,6 +356,14 @@ export type ConvoyEventType =
   | { type: 'watch_stopped'; data?: { reason?: string } }
   | { type: 'worker_killed'; data?: { reason?: string; worker_id?: string; task_id?: string } }
   | { type: 'discovered_issue'; data?: { task_id?: string; title?: string; file?: string; description?: string; severity?: string } }
+  | { type: 'contract_violation'; data?: { task_id?: string; agent?: string; missing?: string[]; warnings?: string[] } }
+  | { type: 'review_stage_completed'; data?: { stage: string; verdict: string; tokens: number; task_id?: string; model?: string } }
+  | { type: 'partition_violation'; data?: { task_id?: string; allowed?: string[]; actual?: string[]; violations?: string[] } }
+  | { type: 'context_compacted'; data?: { task_id?: string; compaction_count?: number; summary_path?: string; model?: string; tokens_used?: number } }
+  | { type: 'skill_refinement_proposed'; data?: { skill_name?: string; proposal_path?: string; failure_count?: number; confidence?: string } }
+  | { type: 'tdd_check_passed'; data?: { task_id?: string; new_source_files?: number; existing_test_files?: number } }
+  | { type: 'tdd_check_failed'; data?: { task_id?: string; missing_test_files?: string[]; new_source_files?: number } }
+  | { type: 'tdd_check_skipped'; data?: { task_id?: string; reason?: string; agent?: string } }
 
 /** All canonical convoy event type strings. Used for runtime validation. */
 export const KNOWN_EVENT_TYPES: Set<string> = new Set<ConvoyEventType['type']>([
@@ -363,4 +406,12 @@ export const KNOWN_EVENT_TYPES: Set<string> = new Set<ConvoyEventType['type']>([
   'watch_stopped',
   'worker_killed',
   'discovered_issue',
+  'contract_violation',
+  'review_stage_completed',
+  'partition_violation',
+  'context_compacted',
+  'skill_refinement_proposed',
+  'tdd_check_passed',
+  'tdd_check_failed',
+  'tdd_check_skipped',
 ])

package/src/cli/dashboard.ts

@@ -185,6 +185,61 @@ export async function startDashboardServer(
           pathname = '/index.html'
         }
 
+        // Handle refresh requests — re-run ETL on demand
+        if (pathname === '/data/refresh' && runtimeDataDir) {
+          try {
+            const { runEtl } = await import('../dashboard/scripts/etl.js')
+            const dbPath = resolve(projectRoot, '.opencastle', 'convoy.db')
+            const result = await runEtl({ dbPath, outputDir: runtimeDataDir })
+            res.writeHead(200, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify({ ok: true, convoyCount: result.convoyCount }))
+          } catch (err) {
+            res.writeHead(200, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify({ ok: true, convoyCount: 0 }))
+          }
+          return
+        }
+
+        // Handle active convoy resolution — queries DB directly (no ETL needed)
+        if (pathname === '/data/active-convoy.json' && !seed) {
+          try {
+            const { createConvoyStore } = await import('./convoy/store.js')
+            const dbPath = resolve(projectRoot, '.opencastle', 'convoy.db')
+            const { existsSync } = await import('node:fs')
+            if (!existsSync(dbPath)) {
+              res.writeHead(200, { 'Content-Type': 'application/json' })
+              res.end(JSON.stringify({ convoy: null, pipeline: null }))
+              return
+            }
+            const store = createConvoyStore(dbPath)
+            try {
+              // Find the running convoy, or fall back to the latest
+              const allConvoys = store.getConvoyList(10, 0)
+              const running = allConvoys.find(c => c.status === 'running')
+              const pending = allConvoys.find(c => c.status === 'pending')
+              const target = running ?? pending ?? (allConvoys.length > 0 ? allConvoys[0] : null)
+
+              let pipelineConvoys: Array<{ id: string; name: string; status: string }> | null = null
+              if (target?.pipeline_id) {
+                const pipeConvoys = store.getConvoysByPipeline(target.pipeline_id)
+                pipelineConvoys = pipeConvoys.map(c => ({ id: c.id, name: c.name, status: c.status }))
+              }
+
+              res.writeHead(200, { 'Content-Type': 'application/json' })
+              res.end(JSON.stringify({
+                convoy: target ? { id: target.id, name: target.name, status: target.status, pipeline_id: target.pipeline_id ?? null } : null,
+                pipeline: pipelineConvoys,
+              }))
+            } finally {
+              store.close()
+            }
+          } catch {
+            res.writeHead(200, { 'Content-Type': 'application/json' })
+            res.end(JSON.stringify({ convoy: null, pipeline: null }))
+          }
+          return
+        }
+
         // Handle data file requests — proxy to project logs or dist
         const dataMatch = pathname.match(/^\/data\/(.+\.ndjson)$/)
         if (dataMatch && DATA_FILES.includes(dataMatch[1])) {

package/src/cli/insights.ts

@@ -0,0 +1,99 @@
+import { stat } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import type { CliContext } from './types.js'
+import { createConvoyStore } from './convoy/store.js'
+import { analyzeDAG, formatInsightsMarkdown, formatInsightsJSON } from './convoy/dag-analysis.js'
+
+const HELP = `
+  opencastle insights [options]
+
+  Analyze convoy execution history and generate recommendations.
+
+  Options:
+    --json           Output machine-readable JSON instead of markdown
+    --since <days>   Limit analysis window (default: 90 days)
+    --db <path>      Path to convoy.db (default: auto-detect)
+    --help, -h       Show this help
+`
+
+/** Walk up the directory tree to find .opencastle/convoy.db. */
+async function findConvoyDb(override?: string | null): Promise<string | null> {
+  if (override) return override
+
+  let dir = process.cwd()
+  for (;;) {
+    const candidate = join(dir, '.opencastle', 'convoy.db')
+    try {
+      const s = await stat(candidate)
+      if (s.isFile()) return candidate
+    } catch {
+      // not found here — walk up
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+export default async function insights({ args }: CliContext): Promise<void> {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(HELP)
+    return
+  }
+
+  let jsonMode = false
+  let sinceDays = 90
+  let dbOverride: string | null = null
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--json') {
+      jsonMode = true
+    } else if (arg === '--since') {
+      const raw = args[++i]
+      const parsed = parseInt(raw, 10)
+      if (isNaN(parsed) || parsed <= 0) {
+        console.error('  \u2717 --since requires a positive integer (number of days)')
+        process.exit(1)
+      }
+      sinceDays = parsed
+    } else if (arg === '--db') {
+      dbOverride = args[++i] ?? null
+    }
+  }
+
+  const dbPath = await findConvoyDb(dbOverride)
+  if (!dbPath) {
+    if (jsonMode) {
+      console.log(
+        JSON.stringify(
+          {
+            patterns: [],
+            agent_stats: [],
+            insights: ['No execution history available yet. Run some convoys first.'],
+            generated_at: new Date().toISOString(),
+          },
+          null,
+          2,
+        ),
+      )
+    } else {
+      console.log('  No convoy.db found. Run some convoys first.\n')
+      console.log('  Tip: convoy.db is created automatically when you run `opencastle run`.')
+    }
+    return
+  }
+
+  const store = createConvoyStore(dbPath)
+  try {
+    const rec = analyzeDAG(store, sinceDays)
+    if (jsonMode) {
+      console.log(formatInsightsJSON(rec))
+    } else {
+      console.log(formatInsightsMarkdown(rec))
+    }
+  } finally {
+    store.close()
+  }
+}

package/src/cli/lesson.ts

@@ -38,6 +38,7 @@ const HELP = `
     --correct <text>         The correct approach that works
     --why <text>             Root cause explanation
     --customizations-dir <p> Override the customizations directory path
+    --dry-run                Preview what would be appended without writing
     --help, -h               Show this help
 
   Examples:
@@ -230,6 +231,7 @@ export default async function lesson({ args }: CliContext): Promise<void> {
     return
   }
 
+  const dryRun = args.includes('--dry-run') || args.includes('--dryRun')
   let title: string | null = null
   let category: string | null = null
   let severity: string | null = null
@@ -299,6 +301,12 @@ export default async function lesson({ args }: CliContext): Promise<void> {
     process.exit(1)
   }
 
+  if (dryRun) {
+    console.log(`  [dry-run] Would append lesson to LESSONS-LEARNED.md:`)
+    console.log(`  Title: ${title}`)
+    return
+  }
+
   try {
     const id = await appendLesson(
       { title: title!, category: category!, severity: severity!, problem: problem!, wrong, correct, why },

package/src/cli/log.ts

@@ -11,6 +11,7 @@ const HELP = `
     --type <type>          Event type (required): session|delegation|review|panel|dispute
     --<field> <value>      Any field from the event schema (see documentation)
     --logs-dir <path>      Override the logs directory path
+    --dry-run              Preview what would be logged without writing
     --help, -h             Show this help
 
   Array fields (comma-separated): file_partition, lessons_added, discoveries, reviewing_agents
@@ -77,6 +78,7 @@ export default async function log({ args }: CliContext): Promise<void> {
     return
   }
 
+  const dryRun = args.includes('--dry-run') || args.includes('--dryRun')
   let type: string | null = null
   let logsDir: string | null = null
   const fields: Record<string, unknown> = {}
@@ -122,6 +124,12 @@ export default async function log({ args }: CliContext): Promise<void> {
   delete fields['timestamp']
   const record = { type, timestamp, ...fields }
 
+  if (dryRun) {
+    console.log(`  [dry-run] Would append to events.ndjson:`)
+    console.log(JSON.stringify(record))
+    return
+  }
+
   try {
     await appendEvent(record, logsDir)
     console.log(JSON.stringify(record))

package/src/cli/package-config.ts

@@ -0,0 +1,48 @@
+// Platform skill compatibility -- not all skills are relevant on all platforms
+
+export interface PlatformSkillConfig {
+  platform: 'claude-code' | 'cursor' | 'opencode' | 'gemini'
+  excludedSkills: string[]
+  displayName: string
+  manifestFile: string
+  entryPoint: string
+  outputDir: string
+  includedDirs: ('skills' | 'agents' | 'instructions' | 'prompts' | 'agent-workflows')[]
+}
+
+const SESSION_ONLY = ['session-checkpoints']
+const CONCURRENT_ONLY = ['panel-majority-vote']
+const TEAM_LEAD_ONLY = [
+  'orchestration-protocols', 'team-lead-reference', 'decomposition',
+  'agent-memory', 'context-map', 'fast-review', 'memory-merger',
+]
+const SIMPLE_PLATFORM_EXCLUSIONS = [...SESSION_ONLY, ...CONCURRENT_ONLY, ...TEAM_LEAD_ONLY]
+
+export const PLATFORM_CONFIGS: Record<string, PlatformSkillConfig> = {
+  'claude-code': {
+    platform: 'claude-code', excludedSkills: [], displayName: 'Claude Code',
+    manifestFile: 'manifest.json', entryPoint: 'CLAUDE.md', outputDir: 'claude-code',
+    includedDirs: ['skills', 'agents', 'instructions', 'prompts', 'agent-workflows'],
+  },
+  cursor: {
+    platform: 'cursor', excludedSkills: [...SESSION_ONLY], displayName: 'Cursor',
+    manifestFile: 'manifest.json', entryPoint: '.cursorrules', outputDir: 'cursor',
+    includedDirs: ['skills', 'agents', 'instructions'],
+  },
+  opencode: {
+    platform: 'opencode', excludedSkills: [...SIMPLE_PLATFORM_EXCLUSIONS], displayName: 'OpenCode',
+    manifestFile: 'manifest.json', entryPoint: 'OPENCODE.md', outputDir: 'opencode',
+    includedDirs: ['skills', 'agents', 'instructions'],
+  },
+  gemini: {
+    platform: 'gemini', excludedSkills: [...SIMPLE_PLATFORM_EXCLUSIONS], displayName: 'Gemini CLI',
+    manifestFile: 'gemini-extension.json', entryPoint: 'GEMINI.md', outputDir: 'gemini',
+    includedDirs: ['skills', 'agents', 'instructions'],
+  },
+}
+
+export function getSkillsForPlatform(platform: string, allSkills: string[]): string[] {
+  const config = PLATFORM_CONFIGS[platform]
+  if (!config) return allSkills
+  return allSkills.filter(skill => !config.excludedSkills.includes(skill))
+}

package/src/cli/package.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import {
+  readVersion,
+  listSkillDirs,
+  generateManifest,
+  generateEntryPoint,
+  generateReadme,
+  buildPluginPackage,
+  parseArgs,
+} from './package.js'
+import { PLATFORM_CONFIGS, getSkillsForPlatform } from './package-config.js'
+
+const pkgRoot = resolve(process.cwd())
+
+describe('readVersion', () => {
+  it('reads the correct version from package.json', () => {
+    const version = readVersion(pkgRoot)
+    expect(version).toMatch(/^\d+\.\d+\.\d+$/)
+  })
+})
+
+describe('listSkillDirs', () => {
+  it('returns skill directory names', () => {
+    const skills = listSkillDirs(pkgRoot)
+    expect(skills.length).toBeGreaterThan(0)
+    expect(skills).toContain('react-development')
+    expect(skills).toContain('testing-workflow')
+  })
+  it('returns only directory names (not paths)', () => {
+    const skills = listSkillDirs(pkgRoot)
+    expect(skills.every(s => !s.includes('/'))).toBe(true)
+  })
+})
+
+describe('getSkillsForPlatform', () => {
+  const allSkills = [
+    'react-development', 'session-checkpoints', 'panel-majority-vote',
+    'orchestration-protocols', 'team-lead-reference', 'testing-workflow',
+    'decomposition', 'agent-memory', 'context-map', 'fast-review', 'memory-merger',
+  ]
+
+  it('returns all skills for claude-code (fewest exclusions)', () => {
+    const skills = getSkillsForPlatform('claude-code', allSkills)
+    expect(skills).toEqual(allSkills)
+  })
+
+  it('excludes session-checkpoints for cursor', () => {
+    const skills = getSkillsForPlatform('cursor', allSkills)
+    expect(skills).not.toContain('session-checkpoints')
+    expect(skills).toContain('react-development')
+  })
+
+  it('excludes team-lead skills from opencode', () => {
+    const skills = getSkillsForPlatform('opencode', allSkills)
+    expect(skills).not.toContain('session-checkpoints')
+    expect(skills).not.toContain('panel-majority-vote')
+    expect(skills).not.toContain('orchestration-protocols')
+    expect(skills).not.toContain('team-lead-reference')
+    expect(skills).not.toContain('decomposition')
+    expect(skills).not.toContain('agent-memory')
+    expect(skills).not.toContain('context-map')
+    expect(skills).not.toContain('fast-review')
+    expect(skills).not.toContain('memory-merger')
+    expect(skills).toContain('react-development')
+    expect(skills).toContain('testing-workflow')
+  })
+
+  it('excludes team-lead skills from gemini', () => {
+    const skills = getSkillsForPlatform('gemini', allSkills)
+    expect(skills).not.toContain('session-checkpoints')
+    expect(skills).not.toContain('orchestration-protocols')
+  })
+
+  it('returns all skills for unknown platform', () => {
+    const skills = getSkillsForPlatform('unknown-platform', allSkills)
+    expect(skills).toEqual(allSkills)
+  })
+})
+
+describe('generateManifest', () => {
+  const skills = ['react-development', 'testing-workflow']
+  const agents = ['developer', 'reviewer']
+  const version = '0.31.6'
+
+  it('generates correct structure for claude-code', () => {
+    const m = generateManifest('claude-code', version, skills, agents) as Record<string, unknown>
+    expect(m.name).toBe('opencastle')
+    expect(m.version).toBe(version)
+    expect(m.skills).toEqual(skills)
+    expect(m.agents).toEqual(agents)
+    expect(m.hooks).toEqual(['SessionStart'])
+  })
+
+  it('generates correct structure for cursor', () => {
+    const m = generateManifest('cursor', version, skills, agents) as Record<string, unknown>
+    expect(m.name).toBe('opencastle')
+    expect(m.version).toBe(version)
+    expect(m.hooks).toBeUndefined()
+    expect(m.type).toBeUndefined()
+  })
+
+  it('generates correct structure for opencode', () => {
+    const m = generateManifest('opencode', version, skills, agents) as Record<string, unknown>
+    expect(m.name).toBe('opencastle')
+    expect(m.version).toBe(version)
+    expect(m.type).toBeUndefined()
+  })
+
+  it('generates correct structure for gemini (includes type: extension)', () => {
+    const m = generateManifest('gemini', version, skills, agents) as Record<string, unknown>
+    expect(m.name).toBe('opencastle')
+    expect(m.version).toBe(version)
+    expect(m.type).toBe('extension')
+  })
+
+  it('includes version from package.json', () => {
+    const ver = readVersion(pkgRoot)
+    const m = generateManifest('cursor', ver, skills, agents) as Record<string, unknown>
+    expect(m.version).toBe(ver)
+  })
+})
+
+describe('generateEntryPoint', () => {
+  const skills = ['react-development', 'testing-workflow']
+  const version = '1.0.0'
+
+  it('generates CLAUDE.md content for claude-code', () => {
+    const ep = generateEntryPoint('claude-code', version, skills)
+    expect(ep).toContain('OpenCastle v' + version)
+    expect(ep).toContain('react-development')
+    expect(ep).toContain('Claude Code')
+  })
+
+  it('generates .cursorrules content for cursor', () => {
+    const ep = generateEntryPoint('cursor', version, skills)
+    expect(ep).toContain('OpenCastle v' + version)
+    expect(ep).toContain('Cursor')
+    expect(ep).toContain('react-development')
+  })
+
+  it('generates OPENCODE.md content for opencode', () => {
+    const ep = generateEntryPoint('opencode', version, skills)
+    expect(ep).toContain('OpenCastle v' + version)
+    expect(ep).toContain('react-development')
+  })
+
+  it('generates GEMINI.md content for gemini', () => {
+    const ep = generateEntryPoint('gemini', version, skills)
+    expect(ep).toContain('OpenCastle v' + version)
+    expect(ep).toContain('react-development')
+  })
+})
+
+describe('generateReadme', () => {
+  it('contains installation instructions', () => {
+    const readme = generateReadme('claude-code', '1.0.0')
+    expect(readme).toContain('Installation')
+    expect(readme).toContain('Claude Code')
+    expect(readme).toContain('1.0.0')
+  })
+
+  it('references the correct entry point', () => {
+    const readme = generateReadme('cursor', '1.0.0')
+    expect(readme).toContain('.cursorrules')
+  })
+})
+
+describe('PLATFORM_CONFIGS', () => {
+  it('has configs for all 4 platforms', () => {
+    expect(PLATFORM_CONFIGS).toHaveProperty('claude-code')
+    expect(PLATFORM_CONFIGS).toHaveProperty('cursor')
+    expect(PLATFORM_CONFIGS).toHaveProperty('opencode')
+    expect(PLATFORM_CONFIGS).toHaveProperty('gemini')
+  })
+
+  it('each platform config has required fields', () => {
+    for (const [, config] of Object.entries(PLATFORM_CONFIGS)) {
+      expect(config.outputDir).toBeTruthy()
+      expect(config.manifestFile).toBeTruthy()
+      expect(config.entryPoint).toBeTruthy()
+      expect(Array.isArray(config.includedDirs)).toBe(true)
+      expect(config.includedDirs.length).toBeGreaterThan(0)
+    }
+  })
+
+  it('gemini uses gemini-extension.json manifest', () => {
+    expect(PLATFORM_CONFIGS.gemini.manifestFile).toBe('gemini-extension.json')
+  })
+
+  it('cursor uses .cursorrules entry point', () => {
+    expect(PLATFORM_CONFIGS.cursor.entryPoint).toBe('.cursorrules')
+  })
+})
+
+describe('buildPluginPackage', () => {
+  it('creates correct directory structure for claude-code', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'oc-test-'))
+    try {
+      const result = buildPluginPackage(pkgRoot, 'claude-code', tmpDir)
+      expect(result.platform).toBe('claude-code')
+      expect(result.skillCount).toBeGreaterThan(0)
+      expect(result.agentCount).toBeGreaterThan(0)
+      expect(existsSync(join(result.outputDir, 'manifest.json'))).toBe(true)
+      expect(existsSync(join(result.outputDir, 'CLAUDE.md'))).toBe(true)
+      expect(existsSync(join(result.outputDir, 'README.md'))).toBe(true)
+      expect(existsSync(join(result.outputDir, 'skills'))).toBe(true)
+      expect(existsSync(join(result.outputDir, 'agents'))).toBe(true)
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it('respects platform skill filtering for gemini', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'oc-test-'))
+    try {
+      const result = buildPluginPackage(pkgRoot, 'gemini', tmpDir)
+      expect(existsSync(join(result.outputDir, 'skills', 'session-checkpoints'))).toBe(false)
+      expect(existsSync(join(result.outputDir, 'skills', 'react-development'))).toBe(true)
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it('throws for unknown platform', () => {
+    const tmpDir = mkdtempSync(join(tmpdir(), 'oc-test-'))
+    try {
+      expect(() => buildPluginPackage(pkgRoot, 'unknown-platform', tmpDir)).toThrow()
+    } finally {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('parseArgs', () => {
+  it('parses --platform flag', () => {
+    const opts = parseArgs(['--platform', 'cursor'])
+    expect(opts.platform).toBe('cursor')
+    expect(opts.all).toBe(false)
+  })
+
+  it('parses -p shorthand', () => {
+    const opts = parseArgs(['-p', 'gemini'])
+    expect(opts.platform).toBe('gemini')
+  })
+
+  it('parses --all flag', () => {
+    const opts = parseArgs(['--all'])
+    expect(opts.all).toBe(true)
+  })
+
+  it('parses --output flag', () => {
+    const opts = parseArgs(['--output', '/tmp/out'])
+    expect(opts.output).toBe('/tmp/out')
+  })
+
+  it('parses -o shorthand', () => {
+    const opts = parseArgs(['-o', '/tmp/out'])
+    expect(opts.output).toBe('/tmp/out')
+  })
+
+  it('parses --help flag', () => {
+    const opts = parseArgs(['--help'])
+    expect(opts.help).toBe(true)
+  })
+
+  it('returns defaults for empty args', () => {
+    const opts = parseArgs([])
+    expect(opts.platform).toBeNull()
+    expect(opts.all).toBe(false)
+    expect(opts.output).toBe('dist/plugins')
+    expect(opts.help).toBe(false)
+  })
+})