Vendor the integrations CLI and serve the agent skill (#47)

* Serve integrations skill markdown

* Skill teaches the CLI first

* Vendor integrations CLI

* Rename npm package to integrations

* Credit Zachary Kirby for the package name

* Point CLI repository field at renamed repo

Author: RhysSullivan

.github/workflows/cli.yml

@@ -0,0 +1,26 @@
+name: CLI
+
+on:
+  pull_request:
+    paths:
+      - "cli/**"
+      - ".github/workflows/cli.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "cli/**"
+      - ".github/workflows/cli.yml"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Test CLI
+        run: cd cli && bun install && bun run typecheck && bun run build && INTEGRATIONS_LIVE=0 bun test

.gitignore

@@ -6,6 +6,8 @@ dist/
 .dev.vars
 .wrangler/
 .reference/
+cli/dist/
+cli/node_modules/
 scripts/batch/scrape-cache/
 scripts/batch/kv-bulk.json
 

cli/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+.npmrc

cli/.npmrc

@@ -0,0 +1 @@
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}

cli/README.md

@@ -0,0 +1,127 @@
+# integrations
+
+CLI for [integrations.sh](https://integrations.sh).
+
+```sh
+npx integrations search stripe
+```
+
+Install globally with `npm i -g integrations`; the command is `integrations`.
+
+## Quickstart
+
+```sh
+integrations search stripe
+integrations stripe.com
+integrations detect resend.com
+integrations help surface
+```
+
+`search` accepts a service name. A bare domain such as `stripe.com` is treated
+as a surface lookup.
+
+## Agent Output
+
+For API-backed commands, stdout is human-readable only when attached to a TTY.
+When stdout is piped or `--json` is passed, stdout is exactly one JSON document.
+Diagnostics go to stderr. Errors in JSON mode print this shape to stdout and
+exit non-zero:
+
+```json
+{"error":"unknown flag --example"}
+```
+
+Examples:
+
+```sh
+integrations search stripe | jq .
+integrations stripe.com --json
+```
+
+`integrations skill` is the exception: it prints markdown by default so it can
+be redirected into an agent skill file. Use `integrations skill --json` for the
+structured form.
+
+## Skill
+
+Print the bundled integrations.sh agent skill:
+
+```sh
+integrations skill
+integrations skill --json
+```
+
+Install it for Claude-style skill loaders:
+
+```sh
+mkdir -p ~/.claude/skills/integrations-sh
+integrations skill > ~/.claude/skills/integrations-sh/SKILL.md
+```
+
+## MCP
+
+Print connection details for the hosted public MCP server:
+
+```sh
+integrations mcp
+integrations mcp --json
+```
+
+Claude Code:
+
+```sh
+claude mcp add --transport http integrations https://integrations.sh/mcp
+```
+
+The JSON form is:
+
+```json
+{"url":"https://integrations.sh/mcp","transport":"streamable-http","tools":["detect","discover"]}
+```
+
+## Commands
+
+The API command surface is derived from `https://integrations.sh/openapi.json`
+at runtime. Operation IDs become kebab-case commands, path parameters become
+positional arguments, query parameters become flags, and enum/boolean parameters
+are validated locally.
+
+```sh
+integrations help
+integrations help search
+integrations help discover
+```
+
+Current public operations include `search`, `detect`, `discover`, and `surface`.
+As the OpenAPI spec adds operations, the CLI picks them up without a release.
+
+`discover` can take up to a minute and is rate-limited by the hosted API to 3
+requests per 60 seconds per IP.
+
+## Base URL and Cache
+
+Set `INTEGRATIONS_BASE` to target another compatible host:
+
+```sh
+INTEGRATIONS_BASE=http://localhost:4321 integrations help
+```
+
+The OpenAPI spec is cached in the system temp directory using the server TTL and
+ETag. Use `--no-cache` to bypass the cache for one invocation:
+
+```sh
+integrations search stripe --no-cache
+```
+
+## Build
+
+```sh
+bun run typecheck
+bun run build
+bun test
+```
+
+## Credits
+
+Thanks to [Zachary Kirby](https://www.zkirby.com/) for the `integrations`
+package name on npm.

cli/bun.lock

@@ -0,0 +1,41 @@
+{
+  "name": "integrations",
+  "version": "0.0.1-beta.3",
+  "description": "CLI for integrations.sh — search the registry of agent integrations and read a domain's surface.",
+  "type": "module",
+  "bin": {
+    "integrations": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UsefulSoftwareCo/integrations.git",
+    "directory": "cli"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --target node --outdir dist && chmod +x dist/cli.js",
+    "dev": "bun run src/cli.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "integrations",
+    "mcp",
+    "openapi",
+    "graphql",
+    "agents",
+    "registry",
+    "cli"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}