feat: ai-friendly root-cms client CLI commands and agent skill

[stevenle]

Summary

Exposes the RootCMSClient to AI coding agents (and scripts) through the root-cms CLI, plus a downloadable skill that teaches agents how to use it.

New commands

• root-cms client.call <method> [jsonArgs] — invokes any public method on RootCMSClient. Args are a JSON array of positional arguments matching the method's TypeScript signature. Output is a single-line JSON envelope on stdout:

  {"ok": true, "result": <value>}      # exit 0
  {"ok": false, "error": "<message>"}  # exit 1
  

  • Omit jsonArgs for zero-arg methods; pass - to read args from stdin (stdin is only read when explicitly requested, so no hangs).
  • Firestore Timestamp / GeoPoint / DocumentReference round-trip as {_seconds,_nanoseconds} / {_latitude,_longitude} / {_referencePath} in both args and results.

• root-cms client.methods [--json] [--types] — lists all public methods with their TS signatures and JSDoc descriptions for discovery; --types also emits the referenced interface/type definitions.

• root-cms skill.install [dir] — installs the bundled root-cms-cli agent skill into a local skills directory (default .claude/skills). Supports a custom dir and --force.

How it works

The method/type catalog is parsed from the generated dist/core/client.d.ts, so it always matches the real API. Private methods are excluded. The decorative CLI banner is suppressed for client.* commands to keep stdout as clean JSON.

Also refactors the duplicated convertFirestoreTypes helper into cli/utils.ts.

Downloadable skill

skills/root-cms-cli/SKILL.md teaches the discover-then-call workflow, arg encoding, the result envelope, and write-safety guidance. It ships with the npm package (skills/**/* added to files) and installs via root-cms skill.install.

Testing

• pnpm build:core succeeds; .d.ts generation passes.
• 23 tests pass, including 6 new parser tests in cli/client-reflect.test.ts (private exclusion, multi-line signatures, zero-arg methods, type extraction).
• Lint clean.
• Manually verified client.methods (text + --json --types), client.call error/exit-code paths, and all skill.install scenarios (default, custom dir, duplicate error, --force).

Not exercised: a successful client.call requires a real Root.js project (root.config.ts) + Firebase credentials, which the repo root lacks — plumbing was verified up to config load.

🤖 Generated with Claude Code

[jeremydw]

Nice; looks good. Regarding the local skills directory maybe we could try to have it detect the right dir; for example VS Code uses .agents (https://agentskills.io/skill-creation/quickstart#prerequisites, https://docs.github.com/en/copilot/concepts/agents/about-agent-skills#about-agent-skills). So it could try to identify where the project stores the skills and install it there.

[stevenle]

@jeremydw how do you propose the "detect" mechanism would work? i.e. the agent checks to see if certain folders already exists?

[jeremydw]

@jeremydw how do you propose the "detect" mechanism would work? i.e. the agent checks to see if certain folders already exists?

Yup - the latest commit has what I was thinking!