adom-cli-design

@@ -0,0 +1,328 @@+---+name: adom-cli-design+description: Guidelines for building CLI tools in the Adom ecosystem. Use when creating a new CLI, adding commands to an existing one, or deciding between CLI vs MCP vs HTTP API. Covers Rust CLI conventions, AI-oriented output, skill files, and why we prefer CLIs over MCP servers. Trigger words: build a cli, new cli tool, cli design, cli guidelines, mcp vs cli, should I use mcp, make a tool for the ai.+---++# Building CLI Tools for Adom++## Why CLI over MCP++We use Rust CLIs as the primary interface between Claude Code and Adom tools. **Do not build MCP servers** for new tools.++| | MCP Server | Rust CLI |+|---|---|---|+| Context cost | High — tool schemas injected into every conversation | Zero — skill file loaded only when triggered |+| Discoverability | Always visible, clutters tool list | Skill-triggered, on-demand |+| Reliability | Stdio transport can hang, crash, or desync | Process runs and exits cleanly |+| Debugging | Opaque — hard to see what happened | Just run the command in terminal |+| Distribution | Requires .mcp.json wiring per container | Single binary, `cp` to `/usr/local/bin/` |+| AI usability | AI must guess tool params from schema | AI reads skill examples, runs bash |++**The pattern:** Rust CLI binary + Claude Code skill file. The AI reads the skill to learn the commands, then runs them via Bash.++## CLI Conventions++### Language: Rust++- Use `clap` with derive macros for argument parsing+- Use `serde_json` for JSON input/output+- Minimize dependencies — prefer raw TCP over `reqwest` for simple HTTP calls+- Build with `--release`, `opt-level = "z"`, `lto = true`, `strip = true` for small binaries+- Install to `/usr/local/bin/` so it's on PATH everywhere++### Output: AI-Oriented++The CLI output is consumed by Claude Code, not humans. Design accordingly:++**Every response starts with `OK:` or `ERROR:`** — the AI can instantly determine success/failure.++**Success output is descriptive and confirms what happened:**+```text+OK: Opened /home/adom/project/README.md in VS Code editor tab.+OK: Injected shot-2026-03-28T14-30-22.png (1920x1080, 245 KB) into channel "dart2".+OK: Server listening on port 8820, recovered 3 channels from disk.+```++**Error output includes a `Hint:` line with the next action:**+```text+ERROR: Cannot connect to shotlog server on port 8820.+Hint: Start the server with `shotlog serve &`++ERROR: File not found: /home/adom/project/missing.png+Hint: Check the path exists. Use `ls /home/adom/project/` to list files.++ERROR: Adom Bridge extension not responding on port 8821.+Hint: The extension may need a window reload. Run: adom-bridge health+```++**Never output ambiguous or empty responses.** If a command succeeds silently, still print `OK:`.++### Colored output++Use ANSI escape codes for colored terminal output. No crate needed — raw escape codes work everywhere. But colors are for **humans at interactive terminals only**: when the CLI's output is piped (`cmd | grep`, `cmd > log`, `nohup cmd > log.txt 2>&1`, bash command substitution, etc.), ANSI escape codes leak into log files and into the AI's stdout capture as ugly garbage like `[36mstarting server[0m`. Every CLI MUST strip ANSI when stdout/stderr is not a TTY.++**Required pattern** — `is_terminal()` check gated on each output helper, with a matching `strip_ansi` fallback. Both `println!` / `eprintln!` calls that embed color constants AND internal progress messages need this — not just the `ok` / `err` / `hint` / `warn` helpers:++```rust+use std::io::IsTerminal;+use std::sync::OnceLock;++const GREEN: &str = "\x1b[32m";+const RED: &str = "\x1b[31m";+const YELLOW: &str = "\x1b[33m";+const CYAN: &str = "\x1b[36m";+const BOLD: &str = "\x1b[1m";+const DIM: &str = "\x1b[2m";+const RESET: &str = "\x1b[0m";++static STDOUT_IS_TTY: OnceLock<bool> = OnceLock::new();+static STDERR_IS_TTY: OnceLock<bool> = OnceLock::new();+pub fn stdout_is_tty() -> bool { *STDOUT_IS_TTY.get_or_init(|| std::io::stdout().is_terminal()) }+pub fn stderr_is_tty() -> bool { *STDERR_IS_TTY.get_or_init(|| std::io::stderr().is_terminal()) }++pub fn strip_ansi(s: &str) -> String {+    // Strip CSI sequences like \x1b[36m, \x1b[0m, \x1b[1;32m etc.+    let mut out = String::with_capacity(s.len());+    let mut chars = s.chars().peekable();+    while let Some(c) = chars.next() {+        if c == '\x1b' && chars.peek() == Some(&'[') {+            chars.next();+            for c2 in chars.by_ref() { if c2.is_ascii_alphabetic() { break; } }+            continue;+        }+        out.push(c);+    }+    out+}++fn ok(msg: impl std::fmt::Display) {+    if stdout_is_tty() {+        println!("{GREEN}{BOLD}OK:{RESET} {msg}");+    } else {+        println!("OK: {}", strip_ansi(&msg.to_string()));+    }+}+fn err(msg: impl std::fmt::Display) {+    if stderr_is_tty() {+        eprintln!("{RED}{BOLD}ERROR:{RESET} {msg}");+    } else {+        eprintln!("ERROR: {}", strip_ansi(&msg.to_string()));+    }+}+fn hint(msg: impl std::fmt::Display) {+    if stderr_is_tty() {+        eprintln!("{DIM}Hint:{RESET} {msg}");+    } else {+        eprintln!("Hint: {}", strip_ansi(&msg.to_string()));+    }+}++// And — critically — `note!` for every internal progress message+// ("starting server on port X", "running ffmpeg...", "filter graph:+// N chars", etc.). These are the ones that tend to get written as+// bare `println!("{CYAN}...{RESET}")` and leak raw escape codes into+// logs when the CLI is run under nohup or backgrounded to a file.+// Route them all through a `note!` macro so the isatty gate is+// unmissable:+macro_rules! note {+    ($($arg:tt)*) => {{+        let __s = format!($($arg)*);+        if $crate::stdout_is_tty() {+            println!("{}", __s);+        } else {+            println!("{}", $crate::strip_ansi(&__s));+        }+    }};+}+```++- `OK:` in green bold, paths/values in cyan, search terms in yellow.+- `ERROR:` in red bold, hints in dim.+- The AI reads `OK:` / `ERROR:` prefixes; colors are for human readability **only**.+- **Never leak raw ANSI escape codes to pipes.** If you see `[36m` or `[0m` in a log file, a CLI is broken. The `video-post` crate (adom-inc/video-post on GitHub) implements the full pattern above in `src/main.rs` — `note!` + `enote!` macros + `ok/err/hint/warn` helpers all gated on isatty. Copy from there for any new CLI.++### Bash tab completions++Use `clap_complete` to generate bash completions. The `install` command should write them to `~/.local/share/bash-completion/completions/<tool>` and append an `eval` line to `.bashrc`:++```rust+// In Cargo.toml:+clap_complete = "4"++// Generate completions:+let mut cmd = Cli::command();+let mut buf = Vec::new();+clap_complete::generate(clap_complete::Shell::Bash, &mut cmd, "my-tool", &mut buf);+fs::write(format!("{completions_dir}/my-tool"), &buf).ok();+```++Users get tab completion immediately in new terminals -- `my-tool <TAB>` shows all subcommands.++### Subcommand Structure++Use subcommands for logical grouping:+```text+toolname <verb> [options] [args]++shotlog serve --port 8820+shotlog inject --channel dart2 --desc "..." file.png+shotlog open --channel dart2++adom-bridge open /path/to/file.png+adom-bridge reveal /path/to/folder/+adom-bridge claude new+adom-bridge extensions search "python"+```++### Port Registration++**Before picking a port**, check `/home/adom/gallia/PORT-REGISTRY.md`. Add your service to the registry before writing code. Port ranges are pre-allocated by category (8820–8829 for Adom tools, 8850–8899 for user/ephemeral, etc.).++### Health Check++Every CLI that talks to a server should have a `health` subcommand:+```text+toolname health+```+Returns `OK: ...` if the server is reachable, `ERROR: ...` with a hint if not. This lets the AI self-diagnose connection issues.++## Skill File++Every CLI **must** have a `SKILL.md` so Claude Code knows how to use it.++### Where it lives++- Source: in the tool's own repo (e.g., `/home/adom/project/my-tool/SKILL.md`)+- Embedded in the binary via `include_str!`+- Deployed to `~/.claude/skills/<tool-name>/SKILL.md` by `my-tool install`++### What it contains++```markdown+---+name: tool-name+description: "One-line description with trigger words..."+---++# Tool Name++Brief description of what it does.++## Commands++### `toolname verb`+What it does.++| Flag | Required | Default | Description |+|------|----------|---------|-------------|+| `--flag` | yes | — | What it controls |++**Example:**+\`\`\`bash+toolname verb --flag value /path/to/thing+\`\`\`+```++Include **concrete examples** for every command. The AI copies from examples — if the example is wrong or missing, the AI will guess and get it wrong.++### Register in the capabilities table++Add a row to `~/.claude/skills/adom/SKILL.md`:+```text+| Tool Name | "trigger words" | Standalone skill: `~/.claude/skills/<tool>/SKILL.md` |+```++## Distribution++### Own GitHub repo (recommended)++Every shared CLI should live in its own `adom-inc/<tool-name>` repo. This keeps the tool self-contained, gives it its own release cycle, and avoids bloating gallia with build artifacts. Examples: `adom-inc/adom-cli`, `adom-inc/adom-vscode`.++### The `install` command pattern++**The binary owns its own install.** One command — `my-tool install` — sets up everything: the skill, shell completions, companion pieces (VSIX, config files, etc.). `gallia/install.mjs` just downloads the binary and runs it.++#### DO NOT embed SKILL.md / BUILD-SKILL.md in the binary (hard rule)++Skills are prose, and we edit them *a lot* more often than we rebuild the Rust code — adding triggers, clarifying tool-use patterns, patching a broken sentence an AI misinterpreted. If a skill is compiled into the binary via `include_str!`, every single prose fix requires a full binary rebuild, a GitHub release, a wiki asset upload, and a re-install on every user container. That's way too much ceremony for a 10-character typo. Worse: until a user reinstalls the binary, they silently run the stale skill.++**The rule:**++- SKILL.md and BUILD-SKILL.md ship as **independent assets on the wiki page**. Upload them alongside the binary:+  ```bash+  adom-wiki asset upload apps/my-tool --asset-type skill       --file SKILL.md+  adom-wiki asset upload apps/my-tool --asset-type build-skill --file BUILD-SKILL.md+  ```+- The binary's `install` subcommand **fetches the latest SKILL.md from the wiki** at install time (and falls back to a bundled copy if the wiki is unreachable). The fallback is a safety net, not the primary path.+- Bumping a skill becomes: edit `SKILL.md` in the repo → `adom-wiki asset upload …` → done. No binary rebuild, no version bump. The next user to run `my-tool install` (or re-run gallia's Tier A refresh) picks up the new prose.++Same rule applies to any other rapidly-changing prose asset (policy docs, prompt templates, wiki `body.md`). Binary-side data that is *strictly coupled* to the binary's own structure (e.g., a `VSIX` whose API matches the current binary's RPC schema, or baked-in default config schemas used by the Rust types) can still be embedded via `include_bytes!` — couple-to-code, not couple-to-prose.++#### Implementation — `install` subcommand++1. **Fetch skill from the wiki, fall back to a bundled copy:**+   ```rust+   // Bundled SKILL.md is the fallback used only when the wiki is unreachable.+   // `// SAFETY NET — do not rely on for release propagation.`+   const FALLBACK_SKILL_MD: &str = include_str!("../../SKILL.md");++   fn fetch_skill_md() -> Cow<'static, str> {+       let url = "https://wiki-ufypy5dpx93o.adom.cloud/static/apps/my-tool/SKILL.md";+       match ureq::get(url).timeout(Duration::from_secs(5)).call() {+           Ok(r) => r.into_string().map(Cow::Owned).unwrap_or(Cow::Borrowed(FALLBACK_SKILL_MD)),+           Err(_) => {+               warn("wiki unreachable — installing bundled SKILL.md (may be stale)");+               Cow::Borrowed(FALLBACK_SKILL_MD)+           }+       }+   }+   ```++2. **Add an `install` subcommand** that handles all setup:+   ```rust+   Commands::Install => {+       // 1. Install companion pieces (VSIX, config, etc.)+       // 2. Install skill — fetched fresh from the wiki+       let skill_dir = format!("{home}/.claude/skills/my-tool");+       fs::create_dir_all(&skill_dir).ok();+       fs::write(format!("{skill_dir}/SKILL.md"), fetch_skill_md().as_ref()).ok();+       // 3. Install bash completions+       let comp_dir = format!("{home}/.local/share/bash-completion/completions");+       fs::create_dir_all(&comp_dir).ok();+       let mut cmd = Cli::command();+       let mut buf = Vec::new();+       clap_complete::generate(Shell::Bash, &mut cmd, "my-tool", &mut buf);+       fs::write(format!("{comp_dir}/my-tool"), &buf).ok();+       // 4. Add to .bashrc if not already there+       let bashrc = fs::read_to_string(format!("{home}/.bashrc")).unwrap_or_default();+       if !bashrc.contains("# my-tool completions") {+           fs::OpenOptions::new().append(true).open(format!("{home}/.bashrc"))+               .map(|mut f| f.write_all(b"\n# my-tool completions\neval \"$(my-tool completions bash 2>/dev/null)\"\n")).ok();+       }+   }+   ```++3. **Attach binary to GitHub Releases** — no Rust toolchain needed on user containers++4. **`gallia/install.mjs` is just two lines:**+   ```javascript+   execSync('gh release download --repo adom-inc/my-tool --pattern "my-tool" --output /usr/local/bin/my-tool --clobber');+   execSync('sudo chmod +x /usr/local/bin/my-tool && my-tool install');+   ```++The binary is the primary artifact for *code*. The wiki is the primary artifact for *prose*. `gallia/install.mjs` never needs to know the internals — it just downloads the binary and runs `install`, which then reaches back to the wiki for the skills.++### build.sh (for local development)++Every tool should have a `build.sh` for building locally before cutting a release:+1. Build the binary (`cargo build --release`)+2. Install to `/usr/local/bin/`+3. Run `my-tool install` (installs everything locally)++## Examples of This Pattern++| Tool | Port | What it does |+|------|------|-------------|+| `shotlog` | 8820 | Screenshot log viewer + injector |+| `adom-vscode` | 8821 | VS Code control API (open files, reveal, extensions, Claude Code) |+| `adom-cli` | — | Adom platform API (containers, repos, users, workspaces) |