@sonenta/cli 0.16.0 → 0.17.0

package/README.md

@@ -16,7 +16,7 @@ npx @sonenta/cli --help
 
 ```bash
 # 1. Authenticate (the key must carry the `mcp:*` scope — see Auth below)
-sonenta login --host https://api.sonenta.com --token vrb_live_<prefix>.<secret>
+sonenta login --host https://api.sonenta.dev --token vrb_live_<prefix>.<secret>
 
 # 2. Bind the current directory to a project
 sonenta init --project 069fc15d-…  --version main
@@ -51,9 +51,9 @@ The credentials file shape:
 
 ```json
 {
-  "default": "https://api.sonenta.com",
+  "default": "https://api.sonenta.dev",
   "hosts": {
-    "https://api.sonenta.com":     { "api_key": "vrb_live_…", "user_email": "…" },
+    "https://api.sonenta.dev":     { "api_key": "vrb_live_…", "user_email": "…" },
     "https://api.dev.sonenta.ca": { "api_key": "vrb_live_…" }
   }
 }

package/dist/index.js

@@ -1106,6 +1106,86 @@ async function requireAuth(opts = {}) {
   return ctx;
 }
 
+// src/mcpserver.ts
+import { promises as fs4 } from "fs";
+import { resolve as resolve3 } from "path";
+var MCP_JSON_FILENAME = ".mcp.json";
+var MCP_SERVER_KEY = "sonenta";
+var MCP_PACKAGE = "@sonenta/mcp";
+function buildServerBlock(env, opts = {}) {
+  const e = {};
+  if (opts.embedKey && env.apiKey) e.SONENTA_API_KEY = env.apiKey;
+  if (env.host) e.SONENTA_BASE_URL = env.host.replace(/\/+$/, "");
+  if (env.projectUuid) e.SONENTA_PROJECT = env.projectUuid;
+  return { command: "npx", args: ["-y", MCP_PACKAGE], env: e };
+}
+async function readMcpJson(path) {
+  try {
+    const raw = await fs4.readFile(path, "utf8");
+    const trimmed = raw.trim();
+    if (!trimmed) return { json: {}, existed: true };
+    const parsed = JSON.parse(trimmed);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`${MCP_JSON_FILENAME} is not a JSON object`);
+    }
+    return { json: parsed, existed: true };
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return { json: {}, existed: false };
+    }
+    throw err;
+  }
+}
+async function wireMcpServer(env, opts = {}) {
+  const baseDir = opts.baseDir ?? process.cwd();
+  const path = resolve3(baseDir, MCP_JSON_FILENAME);
+  const { json, existed } = await readMcpJson(path);
+  const embeddedKey = Boolean(opts.embedKey && env.apiKey);
+  const block = buildServerBlock(env, { embedKey: opts.embedKey });
+  const servers = json.mcpServers && typeof json.mcpServers === "object" ? json.mcpServers : {};
+  const prior = servers[MCP_SERVER_KEY];
+  const identical = prior !== void 0 && deepEqual(prior, block);
+  servers[MCP_SERVER_KEY] = block;
+  json.mcpServers = servers;
+  const action = !existed ? "created" : identical ? "unchanged" : "updated";
+  if (action !== "unchanged") {
+    await fs4.writeFile(path, JSON.stringify(json, null, 2) + "\n", "utf8");
+  }
+  let gitignoreUpdated = false;
+  const wantGitignore = opts.gitignore ?? embeddedKey;
+  if (wantGitignore) {
+    gitignoreUpdated = await ensureGitignored(baseDir, MCP_JSON_FILENAME);
+  }
+  return { path, action, serverKey: MCP_SERVER_KEY, gitignoreUpdated, embeddedKey };
+}
+async function ensureGitignored(baseDir, entry) {
+  const path = resolve3(baseDir, ".gitignore");
+  let current = "";
+  try {
+    current = await fs4.readFile(path, "utf8");
+  } catch (err) {
+    if (err?.code !== "ENOENT") throw err;
+  }
+  const already = current.split(/\r?\n/).map((l) => l.trim()).some((l) => l === entry || l === `/${entry}`);
+  if (already) return false;
+  const prefix = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+  const header = current.length === 0 ? "" : "\n# Sonenta MCP server config (contains an API key)\n";
+  await fs4.writeFile(path, `${current}${prefix}${header}${entry}
+`, "utf8");
+  return true;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  return ak.every(
+    (k) => deepEqual(a[k], b[k])
+  );
+}
+
 // src/commands/agents.ts
 var agentsCommand = new Command("agents").description("Install bundled Claude agents (e.g. sonenta-a11y) into .claude/agents/.").addCommand(
   new Command("list").description("List the bundled agents available to install.").option("--dir <path>", "Project directory (default: current directory)").action(async (opts) => {
@@ -1122,20 +1202,55 @@ var agentsCommand = new Command("agents").description("Install bundled Claude ag
 Install with: sonenta agents add <name>`);
   })
 ).addCommand(
-  new Command("add").description("Write a bundled agent definition into <dir>/.claude/agents/<name>.md.").argument("<name>", "Agent name (e.g. sonenta-a11y)").option("--dir <path>", "Project directory (default: current directory)").option("--host <url>", "Override host (otherwise from config/credentials)").option("--force", "Overwrite an existing agent definition", false).action(async (name, opts) => {
-    await requireAuth({ hostOverride: opts.host });
-    const path = await writeAgent(name, { baseDir: opts.dir, force: opts.force });
-    console.log(`Wrote ${path}`);
-    console.log(
-      `
-The ${name} agent drives the Sonenta a11y MCP tools. Make sure the Sonenta MCP server is configured (npx -y @sonenta/mcp) with an mcp:* SONENTA_API_KEY, then use the agent in Claude Code or CI.`
-    );
-    console.log(`Agent dir: ${AGENTS_DIR}/`);
-  })
+  new Command("add").description("Write a bundled agent definition into <dir>/.claude/agents/<name>.md.").argument("<name>", "Agent name (e.g. sonenta-a11y)").option("--dir <path>", "Project directory (default: current directory)").option("--host <url>", "Override host (otherwise from config/credentials)").option("--force", "Overwrite an existing agent definition", false).option("--no-mcp", "Skip auto-wiring the @sonenta/mcp server into .mcp.json").option(
+    "--embed-key",
+    "Bake the API key into .mcp.json (for CI / no-login); otherwise the server reads it from ~/.sonenta",
+    false
+  ).action(
+    async (name, opts) => {
+      const ctx = await requireAuth({ hostOverride: opts.host });
+      const path = await writeAgent(name, { baseDir: opts.dir, force: opts.force });
+      console.log(`Wrote ${path}`);
+      if (opts.mcp) {
+        const wired = await wireMcpServer(
+          { apiKey: ctx.apiKey, host: ctx.host, projectUuid: ctx.projectUuid },
+          { baseDir: opts.dir, embedKey: opts.embedKey }
+        );
+        const verb = wired.action === "created" ? "Created" : wired.action === "updated" ? "Updated" : "Verified";
+        console.log(
+          `${verb} ${MCP_JSON_FILENAME} \u2192 connected the "${wired.serverKey}" server (${"npx -y @sonenta/mcp"}, host ${ctx.host}${ctx.projectUuid ? `, project ${ctx.projectUuid}` : ""}).`
+        );
+        if (wired.embeddedKey) {
+          console.log(
+            `Embedded your API key in ${MCP_JSON_FILENAME}` + (wired.gitignoreUpdated ? " and added it to .gitignore" : "") + " \u2014 keep it out of git."
+          );
+        } else {
+          console.log(
+            `No secret stored in ${MCP_JSON_FILENAME} \u2014 the server reads your API key from ~/.sonenta at startup (run \`sonenta login\` if it can't). Safe to commit.`
+          );
+        }
+        if (!ctx.projectUuid) {
+          console.log(
+            "Note: no project bound \u2014 run `sonenta init --project <uuid>` so the agent's tools default to one project (or pass project_uuid per call)."
+          );
+        }
+        console.log(
+          `
+\u27F3 Reload your Claude Code session (or restart the MCP client) so the "${wired.serverKey}" server connects \u2014 then ${name}'s tools are available.`
+        );
+      } else {
+        console.log(
+          `
+Skipped .mcp.json (--no-mcp). The ${name} agent needs the Sonenta MCP server (npx -y @sonenta/mcp) with an mcp:* SONENTA_API_KEY to have any tools.`
+        );
+      }
+      console.log(`Agent dir: ${AGENTS_DIR}/`);
+    }
+  )
 );
 
 // src/commands/export.ts
-import { promises as fs4 } from "fs";
+import { promises as fs5 } from "fs";
 import { join as join2 } from "path";
 import { Command as Command2 } from "commander";
 
@@ -1275,9 +1390,9 @@ var exportCommand = new Command2("export").description(
       for (const [lang, nss] of Object.entries(collected)) {
         for (const [ns, flat] of Object.entries(nss)) {
           const dir = join2(opts.out, lang);
-          await fs4.mkdir(dir, { recursive: true });
+          await fs5.mkdir(dir, { recursive: true });
           const p = join2(dir, `${ns}.json`);
-          await fs4.writeFile(p, JSON.stringify(shape(flat), null, 2) + "\n", "utf8");
+          await fs5.writeFile(p, JSON.stringify(shape(flat), null, 2) + "\n", "utf8");
           console.log(`  ${p}  ${Object.keys(flat).length} keys`);
           files++;
         }
@@ -1295,7 +1410,7 @@ var exportCommand = new Command2("export").description(
 );
 
 // src/commands/import.ts
-import { promises as fs5 } from "fs";
+import { promises as fs6 } from "fs";
 import { basename, dirname as dirname3 } from "path";
 import { Command as Command3 } from "commander";
 function resolveLangNs(filePath, optLang, optNs) {
@@ -1313,7 +1428,7 @@ function resolveLangNs(filePath, optLang, optNs) {
   return { lang, ns };
 }
 async function readTree(filePath) {
-  const parsed = JSON.parse(await fs5.readFile(filePath, "utf8"));
+  const parsed = JSON.parse(await fs6.readFile(filePath, "utf8"));
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`${filePath} is not a JSON object`);
   }
@@ -1370,13 +1485,13 @@ var importCommand = new Command3("import").description(
 
 // src/commands/init.ts
 import { existsSync } from "fs";
-import { resolve as resolve4 } from "path";
+import { resolve as resolve5 } from "path";
 import { Command as Command4 } from "commander";
 
 // src/repodoc.ts
-import { promises as fs6 } from "fs";
-import { resolve as resolve3 } from "path";
-var DOC_API_HOST = "https://api.sonenta.com";
+import { promises as fs7 } from "fs";
+import { resolve as resolve4 } from "path";
+var DOC_API_HOST = "https://api.sonenta.dev";
 var DOC_CDN_HOST = "https://cdn.sonenta.com";
 var REPO_DOC_FILES = ["CLAUDE.md", "AGENTS.md"];
 var BLOCK_BEGIN = "<!-- SONENTA:BEGIN \u2014 managed by `sonenta init`; edits between these markers are overwritten -->";
@@ -1464,13 +1579,13 @@ function renderManagedBlock(d) {
 async function upsertManagedBlock(filePath, block) {
   let existing = null;
   try {
-    existing = await fs6.readFile(filePath, "utf8");
+    existing = await fs7.readFile(filePath, "utf8");
   } catch {
     existing = null;
   }
   const normalizedBlock = block.endsWith("\n") ? block : block + "\n";
   if (existing === null) {
-    await fs6.writeFile(filePath, normalizedBlock, "utf8");
+    await fs7.writeFile(filePath, normalizedBlock, "utf8");
     return "created";
   }
   const begin = existing.indexOf(BLOCK_BEGIN);
@@ -1479,18 +1594,18 @@ async function upsertManagedBlock(filePath, block) {
     const before = existing.slice(0, begin);
     const after = existing.slice(end + BLOCK_END.length);
     const blockCore = block.slice(0, block.indexOf(BLOCK_END) + BLOCK_END.length);
-    await fs6.writeFile(filePath, before + blockCore + after, "utf8");
+    await fs7.writeFile(filePath, before + blockCore + after, "utf8");
     return "updated";
   }
   const sep = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-  await fs6.writeFile(filePath, existing + sep + normalizedBlock, "utf8");
+  await fs7.writeFile(filePath, existing + sep + normalizedBlock, "utf8");
   return "inserted";
 }
 async function writeRepoDocs(dir, data) {
   const block = renderManagedBlock(data);
   const results = [];
   for (const file of REPO_DOC_FILES) {
-    const path = resolve3(dir, file);
+    const path = resolve4(dir, file);
     const action = await upsertManagedBlock(path, block);
     results.push({ file, path, action });
   }
@@ -1498,7 +1613,7 @@ async function writeRepoDocs(dir, data) {
 }
 
 // src/commands/init.ts
-var DEFAULT_HOST = "https://api.sonenta.com";
+var DEFAULT_HOST = "https://api.sonenta.dev";
 var ACTION_LABEL = {
   created: "Created",
   updated: "Updated",
@@ -1539,9 +1654,13 @@ async function gatherRepoDocData(opts) {
 }
 var initCommand = new Command4("init").description(
   "Scaffold sonenta.config.json AND write a managed Sonenta block into CLAUDE.md / AGENTS.md so coding agents know how this repo uses Sonenta."
-).option("--host <url>", "API base URL", DEFAULT_HOST).option("--project <uuid>", "Project UUID").option("--version <slug>", "Version slug (default: main)", "main").option("--force", "Overwrite an existing sonenta.config.json", false).option("--no-repo-doc", "Skip writing the managed block into CLAUDE.md / AGENTS.md").action(
+).option("--host <url>", "API base URL", DEFAULT_HOST).option("--project <uuid>", "Project UUID").option("--version <slug>", "Version slug (default: main)", "main").option("--force", "Overwrite an existing sonenta.config.json", false).option("--no-repo-doc", "Skip writing the managed block into CLAUDE.md / AGENTS.md").option("--no-mcp", "Skip auto-wiring the @sonenta/mcp server into .mcp.json").option(
+  "--embed-key",
+  "Bake the API key into .mcp.json (for CI / no-login); otherwise the server reads it from ~/.sonenta",
+  false
+).action(
   async (opts) => {
-    const path = resolve4(process.cwd(), CONFIG_FILENAME);
+    const path = resolve5(process.cwd(), CONFIG_FILENAME);
     if (existsSync(path) && !opts.force) {
       console.error(
         `${CONFIG_FILENAME} already exists at ${path}. Pass --force to overwrite.`
@@ -1568,6 +1687,50 @@ var initCommand = new Command4("init").description(
     } else {
       console.log("Skipped CLAUDE.md / AGENTS.md (--no-repo-doc).");
     }
+    if (opts.mcp) {
+      let liveHost = opts.host !== DEFAULT_HOST ? opts.host : void 0;
+      if (!liveHost) {
+        const creds = await readCredentials().catch(() => null);
+        liveHost = creds?.default ?? void 0;
+      }
+      let resolved = null;
+      try {
+        const ctx = await resolveContext({ hostOverride: liveHost });
+        resolved = { apiKey: ctx.apiKey, host: ctx.host, projectUuid: ctx.projectUuid };
+      } catch {
+        resolved = opts.embedKey ? null : { host: liveHost ?? opts.host, projectUuid: opts.project };
+      }
+      if (resolved) {
+        const wired = await wireMcpServer(
+          {
+            apiKey: resolved.apiKey,
+            host: resolved.host,
+            projectUuid: resolved.projectUuid ?? opts.project
+          },
+          { embedKey: opts.embedKey }
+        );
+        const verb = wired.action === "created" ? "Created" : wired.action === "updated" ? "Updated" : "Verified";
+        console.log(
+          `${verb} ${MCP_JSON_FILENAME} \u2192 connected the "${wired.serverKey}" server (npx -y @sonenta/mcp${resolved.host ? `, host ${resolved.host}` : ""}).`
+        );
+        if (wired.embeddedKey) {
+          console.log(
+            `Embedded your API key in ${MCP_JSON_FILENAME}` + (wired.gitignoreUpdated ? " and added it to .gitignore" : "") + " \u2014 keep it out of git."
+          );
+        } else {
+          console.log(
+            `No secret stored in ${MCP_JSON_FILENAME} \u2014 the server reads your API key from ~/.sonenta at startup (run \`sonenta login\` if it can't). Safe to commit.`
+          );
+        }
+        console.log(
+          `\u27F3 Reload your Claude Code session so the "${wired.serverKey}" server connects.`
+        );
+      } else {
+        console.log(
+          `Note: skipped ${MCP_JSON_FILENAME} wiring (--embed-key needs a login). Run \`sonenta login\` then \`sonenta agents add <name>\`.`
+        );
+      }
+    }
     if (!opts.project) {
       console.log(
         "Tip: pass --project <uuid> to bind this directory to a specific project (or edit project_uuid in the file later), then re-run `sonenta init --force`."
@@ -1596,8 +1759,8 @@ async function promptLine(message) {
   if (!process.stdin.isTTY) return "";
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {
-    return await new Promise((resolve6) => {
-      rl.question(message, (answer) => resolve6(answer.trim()));
+    return await new Promise((resolve7) => {
+      rl.question(message, (answer) => resolve7(answer.trim()));
     });
   } finally {
     rl.close();
@@ -1613,7 +1776,7 @@ async function promptSecret(message) {
   process.stdout.write(message);
   process.stdin.setRawMode(true);
   process.stdin.resume();
-  return await new Promise((resolve6) => {
+  return await new Promise((resolve7) => {
     let buffer = "";
     const onData = (chunk) => {
       for (const byte of chunk) {
@@ -1622,7 +1785,7 @@ async function promptSecret(message) {
           process.stdin.removeListener("data", onData);
           process.stdin.setRawMode(false);
           process.stdin.pause();
-          resolve6(buffer);
+          resolve7(buffer);
           return;
         }
         if (byte === CTRL_C) {
@@ -1651,10 +1814,10 @@ async function promptSecret(message) {
 var TOKEN_REGEX = /^vrb_[a-z]+_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
 var loginCommand = new Command6("login").description(
   "Store an API key for a host. Token resolution order: --token, SONENTA_TOKEN env, then interactive prompt (TTY only)."
-).option("--host <url>", "API base URL", "https://api.sonenta.com").option("--token <vrb_live_\u2026>", "API key token (prefix.secret form)").option("--email <email>", "User email associated with the token (optional)").option("--default", "Set this host as the default for future commands", false).action(async (opts) => {
+).option("--host <url>", "API base URL", "https://api.sonenta.dev").option("--token <vrb_live_\u2026>", "API key token (prefix.secret form)").option("--email <email>", "User email associated with the token (optional)").option("--default", "Set this host as the default for future commands", false).action(async (opts) => {
   let host = opts.host;
   if (!host && process.stdin.isTTY) {
-    host = await promptLine("Host (default https://api.sonenta.com): ") || "https://api.sonenta.com";
+    host = await promptLine("Host (default https://api.sonenta.dev): ") || "https://api.sonenta.dev";
   }
   let token = opts.token ?? (process.env.SONENTA_TOKEN ?? process.env.VERBUMIA_TOKEN) ?? "";
   if (!token && process.stdin.isTTY) {
@@ -1773,14 +1936,14 @@ var projectsCommand = new Command9("projects").description("Inspect Verbumia pro
 import { Command as Command10 } from "commander";
 
 // src/locales.ts
-import { promises as fs7 } from "fs";
-import { join as join3, resolve as resolve5 } from "path";
+import { promises as fs8 } from "fs";
+import { join as join3, resolve as resolve6 } from "path";
 var DEFAULT_LOCALES_DIR = "locales";
 async function listLocaleFiles(rootDir) {
-  const root = resolve5(rootDir);
+  const root = resolve6(rootDir);
   let langDirs;
   try {
-    langDirs = await fs7.readdir(root);
+    langDirs = await fs8.readdir(root);
   } catch {
     return [];
   }
@@ -1789,12 +1952,12 @@ async function listLocaleFiles(rootDir) {
     const langPath = join3(root, lang);
     let stat;
     try {
-      stat = await fs7.stat(langPath);
+      stat = await fs8.stat(langPath);
     } catch {
       continue;
     }
     if (!stat.isDirectory()) continue;
-    const files = await fs7.readdir(langPath);
+    const files = await fs8.readdir(langPath);
     for (const f of files) {
       if (!f.endsWith(".json")) continue;
       out.push({ lang, namespace: f.replace(/\.json$/, ""), path: join3(langPath, f) });
@@ -1803,7 +1966,7 @@ async function listLocaleFiles(rootDir) {
   return out;
 }
 async function readLocaleFile(path) {
-  const raw = await fs7.readFile(path, "utf8");
+  const raw = await fs8.readFile(path, "utf8");
   const parsed = JSON.parse(raw);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(`${path} is not a flat object`);
@@ -1819,12 +1982,12 @@ async function readLocaleFile(path) {
 }
 async function writeLocaleFile(rootDir, lang, namespace, values) {
   const dir = join3(rootDir, lang);
-  await fs7.mkdir(dir, { recursive: true });
+  await fs8.mkdir(dir, { recursive: true });
   const path = join3(dir, `${namespace}.json`);
   const sorted = Object.fromEntries(
     Object.entries(values).sort(([a], [b]) => a.localeCompare(b))
   );
-  await fs7.writeFile(path, JSON.stringify(sorted, null, 2) + "\n", "utf8");
+  await fs8.writeFile(path, JSON.stringify(sorted, null, 2) + "\n", "utf8");
   return path;
 }
 function diffFlat(local, remote) {
@@ -1963,7 +2126,7 @@ var releasesCommand = new Command12("releases").description("Manage CDN releases
 );
 
 // src/commands/snapshot.ts
-import { promises as fs8 } from "fs";
+import { promises as fs9 } from "fs";
 import { Command as Command13 } from "commander";
 function bundleUrl(cdnBase, project, version, lang, ns) {
   return `${cdnBase.replace(/\/+$/, "")}/p/${project}/${version}/latest/${lang}/${ns}.json`;
@@ -2030,7 +2193,7 @@ var snapshotCommand = new Command13("snapshot").description(
       opts.format === "json" ? "json" : "ts"
     );
     if (opts.out) {
-      await fs8.writeFile(opts.out, output, "utf8");
+      await fs9.writeFile(opts.out, output, "utf8");
       console.log(
         `wrote ${opts.out}: ${fetched} bundle(s)` + (missing ? `, ${missing} not published (404)` : "")
       );