Skip to content

Commit e6edb41

Browse files
Shashwat Jainclaude
Shashwat Jain
and
claude
committed
Realign clify around copy-exemplar + validation-gate model (v0.2)
Inspired by google/agents-cli. Replaces "skeleton + LLM adapts" codegen with "copy hand-crafted exemplar + mechanically substitute + run validation gate." Architecture: - bin/clify.mjs — verb-based binary: validate, scaffold-init, sync-check, scaffold (info) - lib/{validate,scaffold-init,sync-check}.mjs — pure-JS deterministic phases - skills/{clify-scaffold,clify-validate,clify-sync}/SKILL.md — LLM-driven phases - examples/jsonplaceholder-cli/ — A+ exemplar (47 tests, full CRUD, mock server) - references/{conventions,validation-gate}.md — single-source contracts Validation gate (8 categories, deterministic): manifest, coverage, structural, nuances, secrets, ci, tests, schema Hard-fail nuances limited to pagination, idempotency, multipart, deprecated to avoid prose-detection brittleness; soft-warn for the rest. Verification: - 15/15 clify unit + deliberate-break tests pass - 47/47 exemplar smoke + integration tests pass on Node 22 - Round-trip: scaffold-init demo --target /tmp produces a repo where npm test passes and clify validate passes - Live: jsonplaceholder-cli posts get --id 1 hits real API - CI matrix: Node 20 + 22 Throws out: skills/clify/ skeletons (cli-skeleton.mjs, skill-skeleton.md, smoke-test-skeleton.mjs). Salvages: error taxonomy, .env loader, three-level help, knowledge schema, .clify.json shape, manifest cross-check rules. Plan in plan.md; codex pre-mortem incorporated into v0.2 narrowing decisions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent ff936e3 commit e6edb41

41 files changed

Lines changed: 3307 additions & 1643 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude-plugin/marketplace.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
{
2-
"name": "derrickko-clify",
2+
"name": "codeyogi911-clify",
33
"owner": {
4-
"name": "derrickko",
5-
"url": "https://github.com/derrickko"
4+
"name": "codeyogi911",
5+
"url": "https://github.com/codeyogi911"
66
},
77
"plugins": [
88
{
99
"name": "clify",
10-
"description": "Generate self-updating CLI repos from API documentation URLs.",
11-
"version": "0.1.0",
10+
"description": "Generate A+ Node.js CLIs from API documentation. Copy a hand-crafted exemplar, mechanically substitute API-specific content, then verify with a deterministic validation gate.",
11+
"version": "0.2.0",
1212
"source": "./"
1313
}
1414
]

‎.claude-plugin/plugin.json‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
11
{
22
"name": "clify",
3-
"version": "0.1.0",
4-
"description": "Generate self-updating CLI repos from API documentation URLs. Produces Node.js CLIs with agent framework wrappers, smoke tests, and a self-learning knowledge system.",
3+
"version": "0.2.0",
4+
"description": "Generate A+ Node.js CLIs from API documentation. Copy a hand-crafted exemplar, mechanically substitute API-specific content, then verify with a deterministic validation gate.",
55
"author": {
6-
"name": "Derrick",
7-
"url": "https://github.com/derrickko"
6+
"name": "codeyogi911",
7+
"url": "https://github.com/codeyogi911"
88
},
9-
"homepage": "https://github.com/derrickko/clify",
10-
"repository": "https://github.com/derrickko/clify",
9+
"homepage": "https://github.com/codeyogi911/clify",
10+
"repository": "https://github.com/codeyogi911/clify",
1111
"license": "MIT",
12-
"keywords": ["cli-generator", "api", "openapi", "codegen", "agent"]
12+
"keywords": ["cli-generator", "api", "openapi", "codegen", "agent"],
13+
"skills": [
14+
{ "name": "clify-scaffold", "source": "skills/clify-scaffold/SKILL.md" },
15+
{ "name": "clify-validate", "source": "skills/clify-validate/SKILL.md" },
16+
{ "name": "clify-sync", "source": "skills/clify-sync/SKILL.md" }
17+
],
18+
"capabilities": ["network", "codegen", "file-write"]
1319
}

‎.github/workflows/test.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: test
2+
on:
3+
push:
4+
pull_request:
5+
jobs:
6+
clify:
7+
runs-on: ubuntu-latest
8+
strategy:
9+
matrix:
10+
node: ["20", "22"]
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: ${{ matrix.node }}
16+
- name: clify unit tests
17+
run: npm test
18+
- name: validate exemplar
19+
run: node bin/clify.mjs validate examples/jsonplaceholder-cli
20+
- name: exemplar tests
21+
working-directory: examples/jsonplaceholder-cli
22+
run: npm test

‎README.md‎

Lines changed: 67 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -1,258 +1,125 @@
11
<h1 align="center">clify</h1>
22

33
<p align="center">
4-
<strong>Paste a URL. Get a CLI.</strong>
4+
<strong>Paste a URL. Get a tested, A+ grade CLI.</strong>
55
</p>
66

77
<p align="center">
8-
A Claude Code plugin that turns any API documentation into a self-updating CLI repo.
8+
A Claude Code plugin that generates Node.js CLIs from API documentation by copying a hand-crafted exemplar, mechanically substituting API-specific content, and verifying with a deterministic validation gate. Inspired by <a href="https://github.com/google/agents-cli">google/agents-cli</a>.
99
</p>
1010

1111
<p align="center">
12-
<a href="https://github.com/derrickko/clify/blob/main/LICENSE"><img src="https://img.shields.io/github/license/derrickko/clify?style=flat" alt="License"></a>
12+
<a href="https://github.com/codeyogi911/clify/blob/main/LICENSE"><img src="https://img.shields.io/github/license/codeyogi911/clify?style=flat" alt="License"></a>
1313
<a href="#install"><img src="https://img.shields.io/badge/Claude_Code-plugin-blueviolet?style=flat" alt="Claude Code plugin"></a>
1414
<img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat" alt="Node 20+">
1515
</p>
1616

1717
---
1818

19-
```
20-
You: /clify https://developer.calendly.com/api-docs
21-
22-
Claude: Fetching docs... detected REST API.
23-
Crawling 8 doc pages...
24-
25-
Detected API: Calendly
26-
Base URL: https://api.calendly.com
27-
Auth: Bearer token via CALENDLY_API_KEY
19+
## Why
2820

29-
Resources (15 endpoints):
30-
events: list, get, cancel
31-
scheduling-links: list, create
32-
users: get, list
33-
invitees: list, get, no-show
34-
webhooks: list, get, create, delete
35-
organizations: get, invite
21+
MCPs are heavy; CLIs are the natural fit for agents. clify produces CLIs that are:
3622

37-
CLI name: calendly-cli
23+
- **Tested by default.** Every generated repo ships with smoke + integration tests and CI on Node 20 & 22.
24+
- **Verifiable.** A deterministic validation gate (`clify validate`) checks 8 categories — manifest consistency, coverage bookkeeping, structural reachability, declared nuances, secrets, CI, and tests.
25+
- **Reproducible.** The deterministic phases (copy + rename + validate) are pure JS — same pass/fail for any agent.
26+
- **Honest.** Endpoints that get dropped require an explicit reason in `coverage.json`. No silent omissions.
3827

39-
Recommendations:
40-
1. Include all 6 resources — small enough to ship as one CLI.
41-
2. Map DELETE /scheduled_events/{uuid} → events cancel (not
42-
events delete) — Calendly treats this as a cancellation.
28+
## Architecture
4329

44-
Before generating, one question:
45-
Docs show both OAuth and Personal Access Token auth.
46-
Recommendation: Personal Access Token only — simpler for
47-
CLI/agent use. OK?
30+
clify is **a binary + skills**, on the same model as `google/agents-cli`:
4831

49-
You: yes, ship it
32+
| Layer | What it does | What runs it |
33+
|---|---|---|
34+
| **Skills** | Fetch docs, parse free-form HTML/Markdown, consult the user on tradeoffs, rewrite per-API content. | LLM (Claude/Codex) |
35+
| **`bin/clify.mjs`** | `clify validate <dir>` — full validation gate. `clify scaffold-init <api-name>` — copy exemplar + rename. `clify sync-check <dir>` — re-fetch docs, hash diff. | Pure JS, no LLM |
5036

51-
Claude: Generated ./calendly-cli/ with:
52-
- 6 resources, 15 actions
53-
- CLI: bin/calendly-cli.mjs
54-
- Skills: skills/calendly/SKILL.md, skills/sync/SKILL.md
55-
- Tests: 15 passing
56-
57-
Install as Claude Code plugin:
58-
claude plugin add ./calendly-cli
59-
```
37+
Anything verifiable by code goes in the binary. Anything requiring judgment stays in skills. The binary is what makes verification reproducible across agent vendors.
6038

6139
## Install
6240

41+
In a Claude Code session:
42+
6343
```
64-
/plugin marketplace add derrickko/clify
65-
/plugin install clify@derrickko-clify
44+
/plugin install codeyogi911/clify
6645
```
6746

68-
Or from a local clone:
47+
Or clone and link:
6948

70-
```bash
71-
git clone https://github.com/derrickko/clify.git
72-
```
7349
```
74-
/plugin add ./clify
50+
git clone https://github.com/codeyogi911/clify
51+
cd clify
52+
npm install
53+
npm link # makes `clify` available as a CLI
7554
```
7655

77-
## What You Get
56+
## Use
7857

79-
One command produces a complete, installable repo:
58+
Inside Claude Code:
8059

8160
```
82-
calendly-cli/
83-
├── bin/calendly-cli.mjs ← zero-dep CLI (Node.js built-ins only)
84-
├── skills/calendly/SKILL.md ← Claude Code skill with guided setup
85-
├── skills/sync/SKILL.md ← detects doc changes, regenerates
86-
├── knowledge/ ← patterns learned from usage
87-
├── test/smoke.test.mjs ← structural tests (pass without API key)
88-
├── .claude-plugin/ ← plugin registration
89-
├── AGENTS.md ← Codex / OpenAI agent instructions
90-
├── .clify.json ← metadata + content hash for sync
91-
├── .env.example ← annotated credential template
92-
├── package.json
93-
└── LICENSE (MIT)
61+
/clify-scaffold https://docs.example.com/api
9462
```
9563

96-
The generated CLI works three ways:
97-
98-
| Mode | How | Example |
99-
|------|-----|---------|
100-
| **Standalone** | Run directly from terminal | `calendly-cli events list --status active` |
101-
| **Claude Code plugin** | Install and use conversationally | `"cancel all my Calendly events for next Friday"` |
102-
| **Codex / agent** | Reads AGENTS.md for autonomous use | Agent runs CLI commands with structured JSON output |
103-
104-
## Features
105-
106-
| | Feature | Details |
107-
|-|---------|---------|
108-
| **Zero deps** | Generated CLIs use only Node.js built-ins | No `node_modules`, no supply chain risk |
109-
| **Any format** | OpenAPI specs parsed directly; HTML/Markdown crawled and extracted | Structured specs preferred for accuracy |
110-
| **Self-update** | `/sync` re-crawls docs, diffs content hashes, regenerates on change | Knowledge files preserved across syncs |
111-
| **Guided setup** | Generated skill walks through auth + defaults on first use | Auto-detects pervasive parameters (e.g., `workspace_id`) |
112-
| **Knowledge system** | Learns gotchas, patterns, and shortcuts as you use the CLI | Agents consult knowledge before every command |
113-
| **Smoke tests** | Every generated repo ships with structural tests | Tests pass with no API key — validates CLI shape, not API responses |
114-
| **Agent-native** | Structured JSON output, error taxonomy, three-level `--help` | Agents discover flags at runtime via `--help` |
115-
| **Consulted generation** | Shows parsed endpoints and recommendations before writing code | You approve, override, or refine before anything is generated |
64+
The skill walks the 13-step pipeline (fetch → parse → consult → init → substitute → validate → simplify → report) and produces `<api-name>-cli/` next to the current directory.
11665

117-
## Usage
66+
You can also call the binary verbs directly:
11867

11968
```
120-
/clify <api-docs-url>
69+
clify validate ./my-api-cli # check a generated repo
70+
clify scaffold-init demo-api --target . # copy exemplar + rename only
71+
clify sync-check ./my-api-cli # detect upstream doc drift
72+
clify --help
12173
```
12274

123-
That's it. clify fetches, parses, asks you to confirm, generates, and tests.
75+
## What "A+" means
12476

125-
### Examples
77+
Every check in [`references/validation-gate.md`](references/validation-gate.md) passes:
12678

127-
```bash
128-
# From OpenAPI specs (highest accuracy)
129-
/clify https://api.example.com/openapi.json
79+
- `package.json` ↔ `plugin.json` ↔ `marketplace.json` are consistent
80+
- Every endpoint has `included: true` or `dropped: true` + a reason
81+
- Every resource × action is reachable via `--help`
82+
- Hard-fail nuances (pagination, idempotency, multipart, deprecated) have artifacts
83+
- No real-shaped secrets in source
84+
- CI runs `npm test` on Node 20 + 22
85+
- `npm test` exits 0
13086

131-
# From HTML documentation
132-
/clify https://developer.calendly.com/api-docs
87+
The exemplar at [`examples/jsonplaceholder-cli/`](examples/jsonplaceholder-cli/) is the canonical A+ implementation. Run the gate against it:
13388

134-
# From Markdown docs
135-
/clify https://raw.githubusercontent.com/org/repo/main/docs/api.md
13689
```
137-
138-
### Generated CLI in Action
139-
140-
Every generated CLI follows the same resource-action pattern:
141-
142-
```bash
143-
# CRUD operations map naturally
144-
calendly-cli events list --status active --json
145-
calendly-cli webhooks create --url https://hook.example.com --events invitee.created
146-
calendly-cli scheduling-links create --owner-uri <user-uri> --max-event-count 1
147-
148-
# Global flags work on every command
149-
calendly-cli invitees list --event <uri> --all # auto-paginate
150-
calendly-cli events get --uuid <uuid> --verbose # show request/response details
151-
152-
# Three-level help for runtime discovery
153-
calendly-cli --help # list all resources
154-
calendly-cli events --help # list actions for events
155-
calendly-cli events cancel --help # show flags with descriptions
156-
157-
# Structured errors for agents
158-
calendly-cli events cancel --uuid bad
159-
# → { "type": "error", "code": "not_found", "message": "...", "retryable": false }
90+
node bin/clify.mjs validate examples/jsonplaceholder-cli
16091
```
16192

162-
### Self-Update
163-
164-
When the API changes, the generated `/sync` skill keeps your CLI current:
93+
## Testing
16594

16695
```
167-
/sync
168-
→ "3 new endpoints, 1 removed, 2 modified"
169-
→ Regenerates CLI + skills
170-
→ Runs smoke tests
171-
→ Reviews knowledge/ for stale entries
96+
npm test # clify unit tests + deliberate-break tests
97+
npm run validate-exemplar # run the gate against the bundled exemplar
17298
```
17399

174-
Content hashes in `.clify.json` track exactly what changed. Knowledge files survive regeneration, so your learned patterns carry forward.
175-
176-
### Knowledge System
100+
The clify CI workflow (`.github/workflows/test.yml`) runs both, plus the exemplar's own test suite, on Node 20 and 22.
177101

178-
As agents use the generated CLI, they write down what they learn:
102+
## Repo layout
179103

180-
```yaml
181-
# knowledge/upload-content-type.md
182-
---
183-
type: gotcha
184-
command: "files upload"
185-
learned: 2026-04-06
186-
confidence: high
187-
---
188-
Upload endpoint returns 422 if Content-Type header is missing.
189-
Always include --content-type application/octet-stream for binary uploads.
190104
```
191-
192-
Four knowledge types: **gotcha** (error → recovery), **pattern** (common flag combos), **shortcut** (multi-step workflows), **quirk** (API contradicts docs). The generated skill reads all knowledge files before every command, so accumulated patterns carry forward without touching code.
193-
194-
## How It Works
195-
196-
clify is a pure Claude Code skill with no runtime dependencies. The generation pipeline:
197-
198-
1. **Fetch** — pulls the docs URL
199-
2. **Detect** — checks for OpenAPI/Swagger (parsed directly) vs HTML/Markdown (crawled up to depth 2)
200-
3. **Parse** — extracts endpoints, auth scheme, resource structure, pervasive parameters
201-
4. **Consult** — presents findings with opinionated recommendations; you confirm before generating
202-
5. **Generate** — writes all files following rigid conventions ([`conventions.md`](skills/clify/references/conventions.md))
203-
6. **Validate** — runs smoke tests, scans for leaked secrets, self-reviews generated skills
204-
7. **Report** — summary + install command
205-
206-
OpenAPI specs skip crawling entirely — structured data means higher accuracy and fewer questions.
207-
208-
<details>
209-
<summary>Error taxonomy in generated CLIs</summary>
210-
211-
Every generated CLI maps HTTP errors to a standard taxonomy that agents can act on programmatically:
212-
213-
| Code | Retryable | When |
214-
|------|-----------|------|
215-
| `auth_missing` | No | No API key in `.env` |
216-
| `auth_invalid` | No | Key rejected (401) |
217-
| `validation_error` | No | Bad request (400, 422) |
218-
| `not_found` | No | Resource doesn't exist (404) |
219-
| `forbidden` | No | Insufficient permissions (403) |
220-
| `conflict` | No | State conflict (409) |
221-
| `rate_limited` | Yes | Too many requests (429) |
222-
| `server_error` | Yes | API server error (5xx) |
223-
| `network_error` | Yes | Connection failed |
224-
| `timeout` | Yes | Request exceeded timeout |
225-
226-
Retry logic lives in the skill wrapper, not the CLI — the agent decides when and how to retry.
227-
228-
</details>
229-
230-
<details>
231-
<summary>Generated CLI conventions</summary>
232-
233-
All generated CLIs follow the same contracts:
234-
235-
- **Resource-action pattern:** `<cli> <resource> <action> [flags]`
236-
- **Standard CRUD mapping:** `list`, `get`, `create`, `update`, `delete`
237-
- **Non-CRUD verbs:** use the API's own terminology (`send`, `verify`, `cancel`)
238-
- **Nesting cap:** 2 levels max; deeper paths flatten to flags
239-
- **Global flags:** `--json`, `--dry-run`, `--help`, `--version`, `--verbose`, `--all`
240-
- **Per-action flags:** declared via `_flags` metadata — single source of truth for both parsing and help text
241-
- **`.env` loading:** reads from repo root only, never overrides shell env vars
242-
- **Pagination:** one page by default, `--all` auto-paginates
243-
- **`--body <json>`:** escape hatch on every mutating endpoint
244-
245-
See [`conventions.md`](skills/clify/references/conventions.md) for the full specification.
246-
247-
</details>
248-
249-
## Contributing
250-
251-
Contributions welcome.
252-
253-
- [Report a bug](https://github.com/derrickko/clify/issues/new?labels=bug)
254-
- [Request a feature](https://github.com/derrickko/clify/issues/new?labels=enhancement)
105+
clify/
106+
├── bin/clify.mjs top-level binary (verbs)
107+
├── lib/
108+
│ ├── validate.mjs validation gate impl
109+
│ ├── scaffold-init.mjs file-copy + rename
110+
│ └── sync-check.mjs hash-diff
111+
├── skills/
112+
│ ├── clify-scaffold/SKILL.md the 13-step generation pipeline
113+
│ ├── clify-validate/SKILL.md wraps `clify validate`
114+
│ └── clify-sync/SKILL.md wraps `clify sync-check` + regeneration
115+
├── examples/jsonplaceholder-cli/ canonical A+ exemplar
116+
├── references/
117+
│ ├── conventions.md contracts every generated CLI honors
118+
│ └── validation-gate.md every check the gate enforces
119+
├── test/clify.test.mjs unit + deliberate-break tests
120+
└── .github/workflows/test.yml CI (Node 20, 22)
121+
```
255122

256123
## License
257124

258-
[MIT](LICENSE)
125+
MIT — see [LICENSE](LICENSE).

0 commit comments

Comments
 (0)