WORK-027
ID:WORK-027Status:done

CLI Plugin Discovery Architecture

Priority:highComplexity:moderateSource:SPEC-022
main View source

Criteria completion

Criteria completion: 6 of 6 (100%) checked; history from Mar 22 to Mar 230%25%50%75%100%Mar 22Mar 23

Relationships

Implements 1
Related 6
Branches 3
main current done
claude/file-naming-convention-LJdwR donechangeset-release/main doneclaude/align-sidenav-styling-4MuxV done
History 5
  1. f2b3512
    Content editedby Claude
    Add {ID}-{slug}.md filename convention + migrate filenames subcommand
  2. f262d7b
    Content editedby Claude
  3. 22ac044
    • ☑ CLI discovers installed packages that export a `cli-plugin` entry point
    • ☑ Plugin commands are registered under their declared namespace (`refrakt plan <cmd>`)
    • ☑ When a plugin package is not installed, CLI prints install instructions and exits
    • ☑ `@refrakt-md/plan` exports `cli-plugin.ts` with command registrations for all 8 commands
    • ☑ Existing commands (inspect, contracts, validate, etc.) are unaffected
    • ☑ Tests for plugin discovery, registration, and missing-package fallback
    by Claude
  4. ebe0c64
    Content editedby Claude
    Migrate plan files to {% ref %} xref syntax (WORK-021)
  5. 30b2ae0
    Created (ready)by Claude
    Add 9 work items for SPEC-022 (Plan CLI) implementation

Summary

Enable the refrakt CLI to discover and load commands from installed packages. Currently all commands are hardcoded in packages/cli/src/bin.ts. This adds a plugin system so @refrakt-md/plan (and future packages) can register subcommands under a namespace (refrakt plan <cmd>).

When a plugin package is not installed, the CLI prints install instructions and exits cleanly. The same pattern could be reused by @refrakt-md/docs (refrakt docs) or @refrakt-md/storytelling (refrakt story) in the future.

Acceptance Criteria

  • CLI discovers installed packages that export a cli-plugin entry point
  • Plugin commands are registered under their declared namespace (refrakt plan <cmd>)
  • When a plugin package is not installed, CLI prints install instructions and exits
  • @refrakt-md/plan exports cli-plugin.ts with command registrations for all 8 commands
  • Existing commands (inspect, contracts, validate, etc.) are unaffected
  • Tests for plugin discovery, registration, and missing-package fallback

Approach

Add a plugin discovery step to packages/cli/src/bin.ts that runs after built-in command matching fails. Check for a cli-plugin export from known package prefixes (@refrakt-md/*). Each plugin exports a { namespace, commands } object. Route refrakt <namespace> <subcommand> to the matching handler.

The @refrakt-md/plan package adds a cli-plugin.ts entry point alongside its existing rune exports.

References

  • SPEC-022 (Plan CLI)
  • packages/cli/src/bin.ts (current CLI entry point)