caplets 0.10.0 → 0.12.0

package/README.md

@@ -28,8 +28,8 @@ exposed two ways: direct flat MCP aggregation versus Caplets progressive disclos
 | Initial Agent Surface     |   Direct Flat MCP |      Caplets |     Reduction |
 | ------------------------- | ----------------: | -----------: | ------------: |
 | Visible tools             |               106 |            3 |   97.2% fewer |
-| Serialized MCP payload    |      32,090 bytes |  8,358 bytes | 74.0% smaller |
-| Approx. context surface   |      8,023 tokens | 2,090 tokens |   5,933 fewer |
+| Serialized MCP payload    |      32,090 bytes |  8,400 bytes | 73.8% smaller |
+| Approx. context surface   |      8,023 tokens | 2,100 tokens |   5,923 fewer |
 | Top-level name collisions | 3 duplicate names |            0 |    eliminated |
 
 The important part: Caplets does not remove access to the downstream tools. It hides
@@ -74,8 +74,8 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 
 ## What It Does
 
-- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, and explicit HTTP API action definitions from the user config file.
-- Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, or HTTP API.
+- Reads downstream MCP server definitions, native OpenAPI endpoint definitions, native GraphQL endpoint definitions, explicit HTTP API action definitions, and curated CLI tool definitions from the user config file.
+- Registers one generated MCP tool for each enabled MCP server, OpenAPI endpoint, GraphQL endpoint, HTTP API, or CLI tools backend.
 - Uses the configured server ID as the generated tool name.
 - Uses the configured `name` and `description` as the capability card shown to agents.
 - Starts downstream MCP servers and loads OpenAPI specs lazily when an operation needs them.
@@ -84,6 +84,7 @@ the agent chooses that server and asks to search, list, inspect, or call them.
 - Converts OpenAPI operations into MCP-style tool metadata and executes HTTP calls directly.
 - Converts configured GraphQL operations into MCP-style tool metadata, and can auto-generate GraphQL tools from schema root query and mutation fields.
 - Converts explicitly configured HTTP actions into MCP-style tool metadata and executes HTTP calls directly.
+- Converts explicitly configured CLI actions into MCP-style tool metadata and executes commands directly without a shell.
 - Preserves downstream tool results instead of rewriting them into a custom format.
 - Redacts secrets from structured errors.
 - Supports static remote auth and OAuth token storage for remote servers.
@@ -218,7 +219,7 @@ the committed schema stays in sync with the Zod config validator.
 
 For richer skill-like cards, add Markdown Caplet files beside `config.json`. Every Caplet
 file must include exactly one executable backend: `mcpServer`, `openapiEndpoint`,
-`graphqlEndpoint`, or `httpApi`;
+`graphqlEndpoint`, `httpApi`, or `cliTools`;
 serverless Caplets are intentionally out of scope.
 
 Top-level files derive the Caplet ID from the filename:
@@ -301,6 +302,26 @@ httpApi:
 # Status API
 ```
 
+CLI-backed Caplet files use `cliTools`:
+
+```md
+---
+name: Repository CLI
+description: Run curated repository workflows through local CLI commands.
+cliTools:
+  cwd: /home/you/project
+  actions:
+    git_status:
+      description: Show concise Git working tree status.
+      command: git
+      args: ["status", "--short"]
+      annotations:
+        readOnlyHint: true
+---
+
+# Repository CLI
+```
+
 Top-level files derive their Caplet ID from the filename. Directory-style Caplets use
 `linear/CAPLET.md`, which is exposed as `linear`; sibling files can be referenced with
 normal Markdown links from `CAPLET.md`.
@@ -310,8 +331,11 @@ 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`.
+- `repo-cli`: Read-oriented repository CLI workflows through `git` and package scripts.
+- `github-cli`: Read-oriented GitHub workflows through the `gh` CLI.
 
-Install every example from a repo's `caplets/` directory:
+Install every example from a repo's `caplets/` directory into the current project's
+`./.caplets` directory:
 
 ```sh
 caplets install spiritledsoftware/caplets
@@ -325,22 +349,20 @@ 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 `${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms,
-`%APPDATA%\caplets` on Windows, or the parent directory of `CAPLETS_CONFIG` when that environment variable is set.
-Existing Caplets are not overwritten unless `--force` is passed.
+By default it writes to `./.caplets`, creating that directory when needed. Pass `-g` or
+`--global` to write to your user Caplets root instead, which is
+`${XDG_CONFIG_HOME:-~/.config}/caplets` on Unix-like platforms, `%APPDATA%\caplets` on Windows,
+or the parent directory of `CAPLETS_CONFIG` when that environment variable is set. Existing
+Caplets are not overwritten unless `--force` is passed.
 
 On Unix-like platforms, relative `XDG_CONFIG_HOME` and `XDG_STATE_HOME` values are ignored.
 
-Caplets always loads user Caplet files from the user Caplets root. Project `./.caplets/config.json`
-is still loaded as project config, but project Markdown Caplet files are executable
-configuration and are ignored unless explicitly trusted:
-
-```sh
-CAPLETS_TRUST_PROJECT_CAPLETS=1 caplets serve
-```
-
-Later sources override earlier ones in this order: user `config.json`, user Caplet files,
-project `config.json`, and, only when trusted, project Caplet files.
+Caplets loads user Caplet files from the user Caplets root and project Caplet files from the
+current working directory's `./.caplets` directory. Later sources override earlier ones in this
+order: user `config.json`, user Caplet files, project `config.json`, and project Caplet files.
+That means a project-local Caplet can intentionally replace a user-level Caplet with the same ID.
+Use `caplets list` to see each Caplet's winning source; when a project Caplet shadows a user-level
+Caplet, the list output includes a warning naming the shadowed path.
 
 `caplets init` refuses to overwrite an existing config. To intentionally replace the file:
 
@@ -350,7 +372,7 @@ caplets init --force
 
 ### Caplet IDs
 
-Each key under `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, or `httpApis` is the
+Each key under `mcpServers`, `openapiEndpoints`, `graphqlEndpoints`, `httpApis`, or `cliTools` is the
 stable Caplet ID. It becomes the generated MCP tool name exactly, so keep it short and specific:
 
 ```json
@@ -367,7 +389,7 @@ stable Caplet ID. It becomes the generated MCP tool name exactly, so keep it sho
 ```
 
 Caplet IDs must match `^[a-zA-Z0-9_-]{1,64}$` and must be unique across `mcpServers`,
-`openapiEndpoints`, `graphqlEndpoints`, and `httpApis`. Spaces, dots, slashes, colons, and Unicode IDs are rejected.
+`openapiEndpoints`, `graphqlEndpoints`, `httpApis`, and `cliTools`. Spaces, dots, slashes, colons, and Unicode IDs are rejected.
 
 ### Stdio Servers
 
@@ -537,6 +559,70 @@ parsed `body` when present, and `elapsedMs`; non-2xx responses set `isError`, re
 timeouts are enforced, response bodies are capped by `maxResponseBytes` (default `1000000`), and
 errors redact secrets.
 
+### CLI Tools
+
+Use `cliTools` for curated local command-line workflows. Each action is an explicitly configured
+tool; Caplets does not expose arbitrary shell access and always spawns `command` plus `args`
+without shell interpolation.
+
+```json
+{
+  "name": "Repository CLI",
+  "description": "Run curated repository workflows through local CLI commands.",
+  "cwd": "/home/you/project",
+  "timeoutMs": 60000,
+  "maxOutputBytes": 1000000,
+  "actions": {
+    "git_status": {
+      "description": "Show concise Git working tree status.",
+      "command": "git",
+      "args": ["status", "--short"],
+      "annotations": { "readOnlyHint": true }
+    },
+    "run_tests": {
+      "description": "Run the package test script.",
+      "command": "pnpm",
+      "args": ["run", "test"],
+      "timeoutMs": 120000,
+      "annotations": { "readOnlyHint": true }
+    }
+  }
+}
+```
+
+CLI actions can set `inputSchema`, `outputSchema`, `env`, action-level `cwd`, `timeoutMs`,
+`maxOutputBytes`, `output: {"type":"json"}`, and MCP annotations. `$input.field` references are
+supported inside `args`, `env`, and `cwd` strings. Caplets performs basic required-field and
+primitive-type validation before spawning. Results are returned as structured content with
+`exitCode`, `stdout`, `stderr`, and `elapsedMs`; non-zero exits set `isError`.
+
+Generate and add a CLI Caplet manifest from a repository:
+
+```sh
+caplets add cli repo-tools --repo . --include git,gh,package
+```
+
+`caplets add` writes generated Markdown Caplet files to `./.caplets/<id>.md` by default.
+Pass `-g` or `--global` to write to the user Caplets root, `--print` to review the generated
+manifest without writing, `--output <path>` for an explicit destination, or `--force` to overwrite
+an existing destination file.
+
+Add MCP, OpenAPI, GraphQL, and HTTP API Caplets with the same destination options:
+
+```sh
+caplets add mcp local-tools --command node --arg ./server.mjs
+caplets add mcp remote-tools --url https://mcp.example.com/mcp --transport http --token-env MCP_TOKEN
+caplets add openapi users --spec ./openapi.json --base-url https://api.example.com --token-env USERS_API_TOKEN
+caplets add graphql catalog --endpoint-url https://api.example.com/graphql --schema ./schema.graphql
+caplets add graphql catalog-live --endpoint-url https://api.example.com/graphql --introspection
+caplets add http status-api --base-url https://api.example.com --action get_status:GET:/status/{service}
+```
+
+For `caplets add mcp`, use `--command` with repeated `--arg`, optional `--cwd`, and repeated
+`--env KEY=VALUE` for stdio servers, or `--url` with `--transport http|sse` for remote servers.
+For HTTP authentication, pass `--token-env <ENV>` so generated manifests reference `$env:ENV`
+instead of embedding raw bearer tokens.
+
 ### Authentication
 
 Remote servers can use:
@@ -580,6 +666,13 @@ caplets list --all
 caplets list --json
 ```
 
+Human output includes a `source` column. JSON output includes each Caplet's `source`, `path`, and
+`shadows` metadata. If a project source overrides a user source, human output prints a warning such
+as `Warning: project Caplet GitHub shadows global Caplet at /path/to/github.md`.
+
+For safety, `caplets add` and `caplets install` reject symlinked output paths and symlinked parent
+directories instead of following them.
+
 ### Optional Server Settings
 
 Every server can set:
@@ -608,7 +701,7 @@ If your client starts the configured command directly, `caplets` without argumen
 starts the MCP server. `serve` is explicit and recommended for clarity.
 
 `caplets serve` watches the effective user config, project config, user Caplet files, and
-trusted project Caplet files. Adding, editing, disabling, or removing a Caplet updates the
+project Caplet files. Adding, editing, disabling, or removing a Caplet updates the
 top-level MCP tool list without restarting Caplets. When an MCP-backed Caplet changes or is
 removed, Caplets closes only that affected downstream connection; unrelated Caplets and
 their downstream connections keep running.

package/caplets/github-cli/CAPLET.md

@@ -0,0 +1,41 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: GitHub CLI
+description: Inspect GitHub pull requests and issues through curated gh CLI commands.
+tags:
+  - cli
+  - github
+  - code
+cliTools:
+  actions:
+    gh_pr_status:
+      description: Show pull request status for the current branch as JSON.
+      command: gh
+      args:
+        - pr
+        - status
+        - --json
+        - currentBranch
+      output:
+        type: json
+      annotations:
+        readOnlyHint: true
+        openWorldHint: true
+    gh_issue_list:
+      description: List open GitHub issues as JSON.
+      command: gh
+      args:
+        - issue
+        - list
+        - --json
+        - number,title,state,url
+      output:
+        type: json
+      annotations:
+        readOnlyHint: true
+        openWorldHint: true
+---
+
+# GitHub CLI
+
+Use this Caplet to expose read-oriented GitHub workflows through `gh` without giving the agent an unrestricted shell.

package/caplets/repo-cli/CAPLET.md

@@ -0,0 +1,37 @@
+---
+$schema: https://raw.githubusercontent.com/spiritledsoftware/caplets/main/schemas/caplet.schema.json
+name: Repository CLI
+description: Inspect and run common local repository workflows through curated CLI tools.
+tags:
+  - cli
+  - code
+cliTools:
+  actions:
+    git_status:
+      description: Show concise Git working tree status.
+      command: git
+      args:
+        - status
+        - --short
+      annotations:
+        readOnlyHint: true
+    git_current_branch:
+      description: Print the current Git branch name.
+      command: git
+      args:
+        - branch
+        - --show-current
+      annotations:
+        readOnlyHint: true
+    package_test:
+      description: Run the repository test script with pnpm.
+      command: pnpm
+      args:
+        - run
+        - test
+      timeoutMs: 120000
+---
+
+# Repository CLI
+
+Use this Caplet to expose a small, typed set of local repository commands without giving an agent arbitrary shell access.