📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,95 @@
+---
+name: cli-development-guidelines
+description: This skill should be used when designing, implementing, or reviewing CLI tools, or when flags, subcommands, help text, exit codes, or `--cli-dev` are mentioned.
+license: CC-BY-SA-4.0 (docs, adapted from clig.dev); MIT (scripts)
+compatibility: Scripts use Python 3.10+ (scripts/cli_audit.py).
+metadata:
+  version: "0.1.0"
+  upstream: "clig.dev + POSIX/GNU/Heroku/12-factor + Agent Skills spec"
+---
+# CLI Development Guidelines
+
+## When to activate this skill
+
+- You are *designing*, *implementing*, or *reviewing* a command-line tool.
+- The user mentions (explicitly or implicitly): `--help`, flags, subcommands, exit codes, stdout/stderr, piping, JSON output, color, prompts, config files, env vars, “works in CI”, install/uninstall, telemetry.
+
+## What this skill produces
+
+- A *CLI contract* (what users can rely on): commands, flags, IO behavior, exit codes, config/env, examples, and safety behavior.
+- Draft *help output* and docs structure (example-first).
+- A *compliance audit* (when runnable) using `scripts/cli_audit.py`.
+
+## Non-negotiable CLI citizenship
+
+- Exit codes:
+  - `0` on success.
+  - Non-zero on failure (and ideally meaningful, documented codes).
+- Streams:
+  - `stdout` is for primary output and machine-readable output.
+  - `stderr` is for errors, warnings, progress, and “what I’m doing” messaging.
+- Discoverability:
+  - `--help` (and usually `-h`) shows help and exits.
+  - `--version` prints version and exits.
+- Interactivity:
+  - Prompts only when `stdin` is a TTY.
+  - Provide `--no-input` to force non-interactive behavior.
+- Scripting friendliness:
+  - No ANSI color / spinners when output isn’t a TTY.
+  - Support `NO_COLOR` and `--no-color`.
+  - Consider `--json` and `--plain` for stable output.
+
+## Workflow
+
+### Sketch the CLI contract first
+
+- Start from the user’s jobs-to-be-done (what they’re trying to accomplish).
+- Decide:
+  - Command shape: single command vs subcommands (`noun verb` is common).
+  - Inputs: args vs flags vs stdin vs prompts vs config/env.
+  - Outputs: human default, plus machine modes (`--json`, `--plain`, `--quiet`).
+  - Safety: confirmations, `--dry-run`, `--force`, secret handling.
+
+Use:
+- [CLI reference](references/REFERENCE.md)
+- [CLI spec template](templates/cli-command-spec-template.json)
+
+### Implement with safe defaults
+
+- Use a CLI parsing library (don’t hand-roll).
+- Make “boundary-crossing” actions explicit:
+  - Network calls
+  - Writing files not explicitly provided
+  - Mutating remote state
+- Avoid footguns:
+  - Don’t accept secrets via flags or environment variables.
+  - Don’t print stack traces by default.
+  - Don’t assume TTY (detect it).
+
+### Validate and iterate
+
+- Run an automated sanity check (when possible):
+  - `python scripts/cli_audit.py -- <your-cli> [subcommand]`
+- Fix in this order:
+  - Broken stdout/stderr separation
+  - Incorrect exit codes
+  - Help that’s missing or undiscoverable
+  - Unsafe defaults (destructive ops, secrets, hidden network writes)
+  - Unscriptable output (no stable modes)
+
+Use:
+- [Checklist](references/CHECKLIST.md)
+- `scripts/cli_audit.py`
+
+## Reference library
+
+- Core reference: [references/REFERENCE.md](references/REFERENCE.md)
+- Quick audit checklist: [references/CHECKLIST.md](references/CHECKLIST.md)
+- Evaluation prompts: [references/EVAL_PROMPTS.md](references/EVAL_PROMPTS.md)
+
+## Templates and scripts
+
+- CLI spec template: `templates/cli-command-spec-template.json`
+- Help text template: `templates/help-text-template.md`
+- Error message template: `templates/error-message-template.md`
+- Audit a CLI: `scripts/cli_audit.py`