@sonenta/cli 0.18.0 → 0.19.0

package/README.md

@@ -102,7 +102,11 @@ you to fix by reloading the session.
 
 `agents add` drops a ready-made Claude agent into the project's
 `.claude/agents/` directory — usable interactively in Claude Code or headless in
-CI. The bundled agents are **local-first** and CRUD-based: they do the work
+CI. Each agent **preflights its prerequisites at startup** — it verifies the
+`@sonenta/mcp` server is connected with an `mcp:*` key before doing any work, and
+if not, fails fast with the exact fix (`sonenta agents add` to wire it, reload
+the session, `sonenta doctor` to diagnose) instead of probing 404s. The bundled
+agents are **local-first** and CRUD-based: they do the work
 themselves and write it back via plain CRUD tools (**0 Sonenta AI credits**;
 changes land as drafts or soft/restorable for review); any server-side AI is an
 explicit, estimated, opt-in fallback.

package/dist/index.js

@@ -6,7 +6,7 @@ import { Command as Command17 } from "commander";
 // package.json
 var package_default = {
   name: "@sonenta/cli",
-  version: "0.18.0",
+  version: "0.19.0",
   description: "Command-line interface for Sonenta translation management.",
   license: "MIT",
   homepage: "https://sonenta.com",
@@ -73,6 +73,27 @@ import { Command as Command2 } from "commander";
 import { promises as fs } from "fs";
 import { resolve } from "path";
 var AGENTS_DIR = ".claude/agents";
+var PREFLIGHT = `## Preflight \u2014 verify your tools FIRST (fail fast, don't guess)
+Before ANY work, confirm the Sonenta MCP tools are actually available to you in
+this session \u2014 make a SINGLE cheap read (e.g. \`get_project_info\` or the first
+read your task needs). Treat the result as a gate:
+- **Tools missing** (you don't see the Sonenta MCP tools in your toolset, or the
+  call errors with "tool not found" / a connection failure) \u2192 the \`@sonenta/mcp\`
+  server isn't connected. **STOP and say so**, e.g.: "I can't run \u2014 I need the
+  \`@sonenta/mcp\` server connected with an \`mcp:*\` API key. Fix it: run
+  \`sonenta agents add <name>\` (it wires \`.mcp.json\` and preflights), then
+  RELOAD this Claude session so the server connects. Run \`sonenta doctor\` to see
+  the exact missing piece \u2014 it checks the wiring, host, key scope, and tools and
+  prints the precise next step."
+- **Auth / scope error** (401 invalid key, or 403 \`MISSING_SCOPE\`) \u2192 the key is
+  missing or lacks \`mcp:*\`. STOP and relay the fix verbatim: a 403 carries
+  \`detail.how_to_get\` / \`detail.message\` (a ready-to-run command) \u2014 show it; or
+  point to \`sonenta doctor\`. Do NOT retry blindly.
+- **Tools respond** \u2192 proceed with the workflow below.
+NEVER probe arbitrary endpoints, guess tool names or URL paths, or hammer a
+failing call \u2014 one clear, actionable message beats a pile of 404s.
+
+`;
 var SONENTA_A11Y = `---
 name: sonenta-a11y
 description: Accessibility (a11y) auditor and fixer for Sonenta-managed i18n projects. Runs a complete code-aware WCAG 2.2 audit, then works like sonenta-source-health \u2014 it builds a remediation PLAN, presents it and reassures you, touches NOTHING until you accept, and only then executes the fixes (a11y variants in bulk, reversible drafts). Generates the alt/aria/screen-reader/plain-language text itself and computes real readability locally, at zero AI-credit cost; server-side AI is an explicit opt-in fallback. Also applies the remediation plans prepared + approved in the Sonenta dashboard, and produces formal WCAG conformance + EAA / EN 301 549 statements. Use interactively in Claude Code or headless in CI.
@@ -108,7 +129,7 @@ default: those bill Sonenta AI credits and exist only as an explicit fallback fo
 very large volumes or when the developer specifically asks for server-side
 generation.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the a11y tools are missing, tell the user to add the server
@@ -346,7 +367,7 @@ results with \`propose_translations_bulk\` as **drafts/proposed** \u2014 plain C
 translation by default; where such a path exists it BILLS Sonenta AI credits and
 is an explicit, estimate-first, opt-in fallback for very large volumes.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Everything goes through its tools \u2014 never call the HTTP API directly.
   If the tools are missing, tell the user to add the server
@@ -464,7 +485,7 @@ narrate what you are about to do, and wait for a clear yes. Reassure: nothing yo
 propose is destructive until accepted, deletes are soft (trash, restorable), and
 every change is a reviewable draft.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the tools are missing, tell the user to add the server
@@ -671,7 +692,7 @@ Knowledge is human-owned. You **propose, then confirm before you overwrite**.
 - Everything you write is a reviewable change \u2014 present proposals as proposals,
   not as done deals.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the tools are missing, tell the user to add the server
@@ -832,7 +853,7 @@ There is no server-side AI in this agent.
   \`update_surface\` response \`affected_variants\` reports how many variants a
   toggle impacts \u2014 always state that blast radius before toggling.
 
-## Requirements
+${PREFLIGHT}## Requirements
 - The Sonenta MCP server (\`@sonenta/mcp\`) must be configured with an \`mcp:*\`
   API key. Every operation goes through its tools \u2014 never call the HTTP API
   directly. If the tools are missing, tell the user to add the server