feat: add cli inspection commands

.changeset/clean-spoons-tell.md

@@ -0,0 +1,7 @@
+---
+"caplets": minor
+---
+
+# CLI inspection and Caplet installation
+
+Add CLI inspection commands for version, configured Caplets, resolved config paths, and installing Caplets from a repo.

README.md

@@ -129,6 +129,15 @@ CAPLETS_CONFIG=/path/to/config.json caplets init
 CAPLETS_CONFIG=/path/to/config.json caplets serve
 ```
 
+Inspect the installed CLI version and resolved config locations:
+
+```sh
+caplets --version
+caplets config path
+caplets config paths
+caplets config paths --json
+```
+
 Caplets validates this file at startup. Config changes take effect after restarting the
 Caplets MCP server.
 
@@ -201,6 +210,30 @@ Top-level files derive their Caplet ID from the filename. Directory-style Caplet
 `linear/CAPLET.md`, which is exposed as `linear`; sibling files can be referenced with
 normal Markdown links from `CAPLET.md`.
 
+This repository includes polished working examples under [`caplets/`](caplets/):
+
+- `github`: GitHub's official MCP server container, using `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- `linear`: Linear's hosted OAuth MCP endpoint.
+- `context7`: Context7 documentation lookup through `@upstash/context7-mcp`.
+
+Install every example from a repo's `caplets/` directory:
+
+```sh
+caplets install spiritledsoftware/caplets
+```
+
+Install one or more individual Caplets by ID:
+
+```sh
+caplets install spiritledsoftware/caplets github
+caplets install spiritledsoftware/caplets github linear
+```
+
+`caplets install` accepts a GitHub `owner/repo` shorthand, a Git URL, or a local repository path.
+It installs into your user Caplets root, which is `~/.caplets` by default or the parent directory
+of `CAPLETS_CONFIG` when that environment variable is set. Existing Caplets are not overwritten
+unless `--force` is passed.
+
 Caplets always loads user Caplet files from `~/.caplets`. Project `./.caplets/config.json`
 is still loaded as project config, but project Markdown Caplet files are executable
 configuration and are ignored unless explicitly trusted:
@@ -390,6 +423,14 @@ caplets auth list
 caplets auth logout <server>
 ```
 
+To list configured Caplets without starting downstream backends:
+
+```sh
+caplets list
+caplets list --all
+caplets list --json
+```
+
 ### Optional Server Settings
 
 Every server can set:

caplets/context7.md

@@ -0,0 +1,33 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Context7 Documentation
+description: Fetch current library and framework documentation through Context7 before using version-sensitive APIs.
+tags:
+  - docs
+  - libraries
+  - frameworks
+  - api-reference
+mcpServer:
+  command: npx
+  args:
+    - -y
+    - "@upstash/context7-mcp"
+---
+
+# Context7 Documentation
+
+Use this Caplet when the agent needs up-to-date library, SDK, framework, CLI, or cloud-service
+documentation before writing code or giving technical instructions.
+
+## Good Fits
+
+- Check current API signatures for fast-moving JavaScript, TypeScript, Python, or cloud libraries.
+- Look up migration notes before changing framework configuration.
+- Retrieve official examples for a specific package version.
+- Resolve uncertainty about CLI flags, config files, or SDK initialization.
+
+## Use Carefully
+
+- Prefer primary documentation over snippets when implementation risk is high.
+- Record the library or package name clearly before searching.
+- Do not use this as a substitute for project-local types and tests.

caplets/github/CAPLET.md

@@ -0,0 +1,54 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: GitHub
+description: Inspect and manage GitHub repositories, issues, pull requests, branches, commits, and code review workflows.
+tags:
+  - code
+  - github
+  - pull-requests
+  - issues
+  - reviews
+mcpServer:
+  command: docker
+  args:
+    - run
+    - -i
+    - --rm
+    - -e
+    - GITHUB_PERSONAL_ACCESS_TOKEN
+    - ghcr.io/github/github-mcp-server
+  env:
+    GITHUB_PERSONAL_ACCESS_TOKEN: $env:GITHUB_PERSONAL_ACCESS_TOKEN
+---
+
+# GitHub
+
+Use this Caplet when the agent needs live GitHub repository context or needs to act on
+issues, pull requests, branches, commits, or review feedback.
+
+## Good Fits
+
+- Summarize recent pull request activity before a code review.
+- Inspect open issues and identify implementation work.
+- Create or update issues from an implementation plan.
+- Compare branches, inspect commits, or review pull request files.
+- Leave review comments after the agent has inspected the relevant diff.
+
+## Use Carefully
+
+- Mutating operations can affect real repositories. Prefer read operations first.
+- Use a least-privilege `GITHUB_PERSONAL_ACCESS_TOKEN`.
+- Do not ask the agent to expose token values, repository secrets, or private issue contents outside
+  the intended conversation.
+
+## Setup
+
+Create a GitHub personal access token with the minimum repository scopes needed for your workflow,
+then export it before starting Caplets:
+
+```sh
+export GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_...
+caplets serve
+```
+
+This Caplet uses GitHub's official MCP server container, so Docker must be available on the host.

caplets/github/README.md

@@ -0,0 +1,13 @@
+# GitHub Caplet
+
+This Caplet wraps GitHub's official MCP server container:
+
+```sh
+docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
+```
+
+Install it from this repo:
+
+```sh
+caplets install spiritledsoftware/caplets github
+```

caplets/linear/CAPLET.md

@@ -0,0 +1,50 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Linear
+description: Plan and track product work in Linear by reading teams, projects, cycles, issues, comments, and workflow state.
+tags:
+  - planning
+  - linear
+  - issues
+  - projects
+  - triage
+mcpServer:
+  transport: http
+  url: https://mcp.linear.app/mcp
+  auth:
+    type: oauth2
+---
+
+# Linear
+
+Use this Caplet when the agent needs live product planning context from Linear or needs to keep
+implementation work synchronized with issues, projects, and team workflows.
+
+## Good Fits
+
+- Find the current issue or project that matches a requested feature.
+- Summarize open work by team, project, cycle, label, or assignee.
+- Draft issue breakdowns from a technical plan.
+- Add implementation notes or status comments after code changes.
+- Check whether a bug or feature already has active work before creating a new issue.
+
+## Reference Files
+
+- [Workflows](./workflows.md): recommended lookup, planning, status update, and triage flows.
+
+## Use Carefully
+
+- Linear issue updates are visible to teammates. Read first, then write deliberately.
+- Keep issue titles and comments concise; use links to detailed implementation artifacts when useful.
+- Avoid broad, noisy searches when a team key, issue ID, project, or label is available.
+
+## Setup
+
+Authenticate once through Caplets:
+
+```sh
+caplets auth login linear
+```
+
+The Linear MCP endpoint supports OAuth. Caplets stores the resulting token bundle in your local
+Caplets auth store.

caplets/linear/workflows.md

@@ -0,0 +1,9 @@
+# Linear Workflows
+
+Useful agent flows:
+
+- **Issue lookup**: search by issue key first, then by title or project if no key is provided.
+- **Planning**: read project context, summarize constraints, then create child issues only when the
+  requested breakdown is clear.
+- **Status updates**: comment with what changed, verification run, and remaining risk.
+- **Triage**: group candidate issues by urgency, owner, and whether they are blocked.

docs/plans/2026-05-12-cli-inspection-polish.md

@@ -0,0 +1,88 @@
+# Caplets CLI Inspection Polish
+
+## Summary
+
+Add a small read-only inspection suite to the existing Commander-based CLI:
+
+- `caplets --version` prints the package version from `package.json`.
+- `caplets list` lists enabled configured Caplets by default.
+- `caplets list --all` includes disabled entries.
+- `caplets list --json` emits stable machine-readable JSON.
+- `caplets config path` prints the effective user config path, honoring `CAPLETS_CONFIG`.
+- `caplets config paths` prints user config, project config, Caplets roots, auth directory, and trust/env state.
+
+No runtime MCP server behavior changes.
+
+## Key Changes
+
+- Update `src/cli.ts` to import `package.json` version and register Commander version support.
+- Add a `list` command that loads config through existing `loadConfig(envConfigPath())`, builds a `ServerRegistry`, and prints:
+  - text columns: `server`, `backend`, `status`, `name`
+  - JSON array objects: `{ server, backend, name, description, disabled, status }`
+- Add `config` subcommands:
+  - `config path`: prints only `resolveConfigPath(envConfigPath())`
+  - `config paths`: prints resolved user config path, project config path, user root, project root, auth dir, whether `CAPLETS_CONFIG` is set, and whether `CAPLETS_TRUST_PROJECT_CAPLETS` is enabled
+  - `--json` on `config paths` for scriptable output
+- Keep existing `init` and `auth` behavior unchanged.
+- Keep disabled Caplets excluded from `caplets list` unless `--all` is passed.
+
+## Interfaces
+
+Public CLI additions:
+
+```sh
+caplets --version
+caplets list
+caplets list --all
+caplets list --json
+caplets config path
+caplets config paths
+caplets config paths --json
+```
+
+Recommended text output shapes:
+
+```txt
+server  backend  status       name
+docs    mcp      not_started  Hosted Docs
+users   openapi  not_started  Users API
+```
+
+```txt
+userConfig: /home/you/.caplets/config.json
+projectConfig: /repo/.caplets/config.json
+userRoot: /home/you/.caplets
+projectRoot: /repo/.caplets
+authDir: /home/you/.caplets/auth
+envConfig: unset
+projectCapletsTrusted: false
+```
+
+## Test Plan
+
+Add focused tests in `test/cli.test.ts`:
+
+- `runCli(["--version"])` prints `package.json` version and does not throw.
+- `runCli(["list"])` prints only enabled MCP/OpenAPI/GraphQL Caplets.
+- `runCli(["list", "--all"])` includes disabled Caplets with `disabled` status.
+- `runCli(["list", "--json"])` emits parseable JSON and redacts/no-ops on auth secrets.
+- `runCli(["config", "path"])` honors `CAPLETS_CONFIG`.
+- `runCli(["config", "paths", "--json"])` returns stable resolved paths and env/trust flags.
+- Unsupported options still raise `REQUEST_INVALID`.
+
+Run:
+
+```sh
+pnpm format:check
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## Assumptions
+
+- "Servers" means all configured Caplet backends: MCP servers, OpenAPI endpoints, and GraphQL endpoints.
+- Human-readable text is the default; `--json` is the stable automation contract.
+- The inspection commands must be read-only and must not start downstream servers, load remote specs, or validate live OAuth.
+- `caplets serve` remains handled by `src/index.ts` as the MCP server entrypoint.

package.json

@@ -24,6 +24,7 @@
   },
   "files": [
     "dist",
+    "caplets",
     "schemas",
     "README.md",
     "LICENSE"