WORK-165
ID:WORK-165Status:draft

Lint cli-plugin shape in refrakt package validate

Add a lint pass to refrakt package validate that checks a package's cli-plugin export for structural issues — missing namespace, missing descriptions, malformed inputSchema, namespace conflicts with already-installed plugins. Catches problems at package-publish time rather than at runtime when the MCP server tries to advertise the broken tool.

Priority:lowComplexity:simpleMilestone:v0.11.0Source:SPEC-043
main View source

Criteria completion

Criteria completion: 0 of 7 (0%) checked; tracking started on May 1, no incremental history yet0%25%50%75%100%May 1May 11

Tracking started May 1 — check back for trends.

Relationships

Implements 1
Related 2
Branches 3
main current draft
claude/v0.11.0-config-foundation doneclaude/mcp-cli-wrapper-design-LsEXZ draftmain draft

Acceptance Criteria

  • refrakt package validate <pkg> runs the existing checks plus a new "cli-plugin" pass when the package exposes a cli-plugin export
  • Errors: missing namespace, missing commands array, command without name, command without description, command without handler
  • Errors: inputSchema present but not a valid JSON Schema (per a lightweight check using ajv or similar)
  • Warnings: command has no inputSchema (recommended for MCP exposure), command has no mcpHandler (recommended for clean structured I/O)
  • Warnings: namespace clashes with another installed plugin in the current project
  • Lint output integrated into the existing package validate text and JSON formats
  • Tests cover: valid plugin (no findings), each error case, each warning case

Approach

  1. Extend packages/cli/src/commands/package-validate.ts with a validateCliPlugin(pkgPath, allDiscovered) step.

  2. Use a small JSON Schema validator (ajv is already used elsewhere in the workspace if needed) for inputSchema/outputSchema syntactic validation.

  3. The allDiscovered argument lets the namespace-clash check work without re-scanning.

Dependencies

  • WORK-160 — to pass discovered plugins for clash detection
  • WORK-161 — to lint the new schema fields

References

  • SPEC-043 — Refrakt MCP Server
  • packages/cli/src/commands/package-validate.ts — current validator to extend