@mu-cabin/coding-cli 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# coding-cli
+
+Agent-first CLI + Claude Code skill for operating a **self-hosted CODING** instance over its
+OpenAPI surface (429 actions, 17 categories). Built as a **generic spec-driven passthrough**: one
+`coding call <Action>` invokes any action, backed by a bundled action index for discovery,
+validation, and safety.
+
+- **Base URL:** your CODING instance's OpenAPI endpoint, e.g. `https://<your-coding-host>/open-api` — set it via `--base-url` / `CODING_API_BASE` / `config init` (the built-in default is a `coding.example.com` placeholder)
+- **Auth:** personal access token (`Authorization: token <…>`)
+
+## Install (dev)
+
+```bash
+npm install
+npm run regen      # tsc + build the action index/docs from the spec
+npm link           # expose the `coding` binary on PATH (optional)
+```
+
+## Quick start
+
+```bash
+coding config init --base-url https://<your-coding-host>/open-api   # writes ~/.coding/config.json
+coding auth login                               # hidden token prompt (or: coding auth login --token -)
+coding auth status --json                       # verify -> current user
+
+coding actions --search issue --json            # discover actions
+coding schema CreateIssue --json                # params / response / errors / risk
+coding call DescribeProjectIssueList \
+  --param ProjectName=demo --select 'Data.List[].Code,Data.List[].Name' --limit 20 --json
+```
+
+`CODING_TOKEN` / `CODING_API_BASE` / `CODING_PROFILE` env vars override config.
+
+## Output contract
+
+Pass `--json` for the envelope:
+
+```jsonc
+{ "ok": true,  "action": "DescribeTeam", "requestId": "…", "data": { /* Response minus RequestId */ } }
+{ "ok": false, "action": "…", "requestId": "…", "error": { "code|type": "…", "message": "…", "hint": "…" } }
+```
+
+Exit codes: `0` ok · `2` usage · `3` auth · `4` not-found · `5` remote/network · `6/7` config ·
+`8` forbidden/scope · `9` rate-limit · `10` confirmation-required · `11` validation.
+
+## Safety
+
+Destructive actions (`Delete*`, `Remove*`, `Disable*`, …) are gated: calling one without `--yes`
+exits `10` with a `confirmation_required` envelope. Preview any request with `--dry-run` (redacts the
+token, never sends, never trips the gate). Validation rejects unknown action / missing-required /
+unknown-param by default; `--force` (`--no-validate`) bypasses it for actions your instance has that
+the public spec lacks.
+
+## The skill
+
+[`skills/coding/SKILL.md`](./skills/coding/SKILL.md) teaches an agent the bootstrap, discovery,
+call recipe, output/exit-code contract, error/scope playbook, and the exit-10 protocol. Curated
+per-domain playbooks (issues, code/MRs, CI, CD, artifacts, project, test, permissions, org, wiki,
+service hooks, programs, files, export, admin) live in
+[`skills/coding/references/`](./skills/coding/references/) and load **on demand** — SKILL.md §9 is the
+router. Keeping them as reference files (rather than separate skills) means only one skill description
+sits in the agent's context, so the playbooks add no always-on token cost.
+
+## Regenerating the spec artifacts
+
+`generate_docs.py` (the original Python doc generator) is superseded by `src/core/specBuild.ts`,
+which emits **both** `generated/index.json` and the `docs/*.md` reference from one parse. Two ways to run it:
+
+```bash
+npm run regen          # dev: tsc + build from spec/coding-openapi.yaml (cache-first), else fetch
+coding update          # refresh from the LIVE spec, persist the cache, report an added/removed diff
+coding update --offline   # rebuild from the cached spec only (no network)
+coding update --dry-run   # report what would change without writing
+```
+
+`coding update` fetches the latest spec, then **atomically** swaps in the rebuilt `docs/` (pruning
+stale files) and `generated/index.json`. Distribution is local/dev for now, so CLI/skill *code*
+upgrades happen via `git pull` + `npm run regen`; `update` keeps the spec artifacts current.