specbox 6.14.0

package/README.md

@@ -0,0 +1,38 @@
+# specbox
+
+Connect this computer to [SpecBox](https://specbox.embed.build) without copying tokens.
+
+```bash
+npx specbox login
+```
+
+1. It shows a one-time code and opens `https://cloud.specbox.build/device`.
+2. You sign in with GitHub and confirm the code.
+3. Done: the token goes straight into your system's secure store, and Claude Code is configured to send it on every connection. You never see it or paste it.
+
+The token expires after 90 days and **renews itself** from 14 days before. If a connection ever ends ("the connection from this device has ended"), run `specbox login` again.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `specbox login` | Connects this computer (one device = this computer + Claude Code). Signing in again replaces the previous token of this device. |
+| `specbox status` | Account, device, expiry date, whether the token is still valid and whether Claude Code uses it. |
+| `specbox logout` | Disconnects this device in the panel and deletes the local credential. |
+
+Options: `--no-browser` (just print the link), `--server <url>` and `--cloud <url>` for self-hosted servers (or `SPECBOX_MCP_URL` / `SPECBOX_CLOUD_API`).
+
+## What it changes on your computer
+
+- **Secure store:** the macOS Keychain, Secret Service on Linux (`secret-tool`) or Windows DPAPI. Without any of them (headless Linux), a `~/.specbox/credentials.json` file with `0600` permissions; `specbox login` says so.
+- **`~/.specbox/bin/mcp-headers.mjs`:** a small helper. Claude Code runs it when it connects (and after a `401`) to get the `Authorization` header; it reads the store and renews the token when due. It never prints anything but that header.
+- **Claude Code:** the `SpecBox-MCP` server (user scope) becomes `{"type": "http", "url": …, "headersHelper": "<node> ~/.specbox/bin/mcp-headers.mjs"}` through the official `claude mcp` command, and other entries pointing to the same server get the same helper.
+- **`~/.specbox/device-id`:** only if the machine id cannot be read. The server only ever sees a SHA-256 of it.
+
+Your devices are listed in the panel under **Profile → Connected devices**, where you can rename or disconnect them. For clients that cannot sign in (Cursor, Claude Desktop…), **Advanced** creates a manual token with the exact configuration for each client.
+
+More: [How SpecBox connects](https://cloud.specbox.build/how-to-connect) · [Cómo se conecta SpecBox](https://cloud.specbox.build/como-se-conecta)
+
+---
+
+**En español.** `npx specbox login` conecta este ordenador: te muestra un código, lo confirmas en el navegador con tu cuenta de GitHub y el token queda en el almacén seguro del sistema; Claude Code lo envía solo y se renueva solo. `specbox status` dice con qué cuenta estás conectado y cuándo caduca; `specbox logout` desconecta el ordenador. Los mensajes salen en español si tu sistema está en español.

package/bin/specbox.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * `specbox` — conectar un ordenador a SpecBox sin copiar tokens (UC-3904).
+ *
+ *   specbox login    código de un solo uso → token al almacén seguro →
+ *                    ayudante en ~/.specbox/bin → Claude Code lo usa solo
+ *   specbox status   con qué cuenta y dispositivo, caducidad, si sigue valiendo
+ *   specbox logout   desconecta el dispositivo y borra la credencial local
+ *
+ * Todo se puede inyectar (`run`) para las pruebas.
+ */
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { claudeUsesHelper, configureClaudeCode, helperCommand, stableNodePath } from "../lib/claude.mjs";
+import { CLIENT, HOW_TO_CONNECT_URL, accountFor, resolveConfig, specboxHome } from "../lib/config.mjs";
+import { deviceId, hostLabel } from "../lib/device.mjs";
+import { installHelper, packageVersion } from "../lib/install.mjs";
+import { readStdinJson, runInternal } from "../lib/internal.mjs";
+import { LoginError, deviceLogin } from "../lib/login.mjs";
+import { messages, pickLang } from "../lib/messages.mjs";
+import { createStore } from "../lib/store.mjs";
+
+export function parseArgs(argv) {
+  const opts = { command: null, server: null, cloud: null, browser: true };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--server") opts.server = argv[(i += 1)];
+    else if (arg === "--cloud") opts.cloud = argv[(i += 1)];
+    else if (arg === "--no-browser") opts.browser = false;
+    else if (arg === "--version" || arg === "-v") opts.command = "version";
+    else if (arg === "--help" || arg === "-h") opts.command = "help";
+    else if (!opts.command) opts.command = arg;
+  }
+  return opts;
+}
+
+function openInBrowser(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true }).on("error", () => {}).unref();
+  } catch {
+    // sin navegador: la persona tiene el enlace en pantalla
+  }
+}
+
+export async function run(argv, deps = {}) {
+  const env = deps.env ?? process.env;
+  const print = deps.print ?? ((line) => process.stdout.write(`${line}\n`));
+  const printErr = deps.printErr ?? ((line) => process.stderr.write(`${line}\n`));
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const t = messages(pickLang(env));
+  const opts = parseArgs(argv);
+  const config = resolveConfig({ server: opts.server, cloud: opts.cloud }, env);
+  const home = specboxHome(env);
+  const store = deps.store ?? createStore({ home });
+  const account = accountFor(config.mcpUrl);
+
+  // Órdenes internas de la extensión de VSCode (JSON por stdin/stdout).
+  if (typeof opts.command === "string" && opts.command.startsWith("_")) {
+    return runInternal(opts.command, {
+      config,
+      store,
+      account,
+      home,
+      fetchImpl,
+      readInput: deps.readInput ?? readStdinJson,
+      out: (value) => print(JSON.stringify(value)),
+      deps,
+    });
+  }
+
+  switch (opts.command) {
+    case "version":
+      print(packageVersion() ?? "unknown");
+      return 0;
+    case "login": {
+      print(t.loginTitle);
+      const device = {
+        device_id: deps.deviceId ?? deviceId(CLIENT, { home }),
+        host: deps.host ?? hostLabel(),
+        client: CLIENT,
+      };
+      let credential;
+      try {
+        credential = await deviceLogin({
+          cloudApi: config.cloudApi,
+          account,
+          store,
+          device,
+          fetchImpl,
+          sleep: deps.sleep,
+          onCode: (code) => {
+            print(t.openUrl(code.verification_uri_complete));
+            print(t.confirmCode(code.user_code));
+            print(t.waiting(Math.round((code.expires_in ?? 600) / 60)));
+            if (opts.browser) (deps.openUrl ?? openInBrowser)(code.verification_uri_complete);
+          },
+        });
+      } catch (err) {
+        printErr(err instanceof LoginError ? t.loginError(err.code) : t.loginError(err?.message ?? "error"));
+        return 1;
+      }
+      print(t.connected(credential, store.kind));
+      if (store.kind === "file") print(t.fileStoreWarning);
+
+      const helperPath = (deps.installHelper ?? installHelper)(home);
+      const result = configureClaudeCode({
+        mcpUrl: config.mcpUrl,
+        helperCmd: helperCommand(helperPath, deps.nodePath ?? stableNodePath()),
+        run: deps.runCommand,
+        claudeJsonPath: deps.claudeJsonPath,
+      });
+      if (result.ok) {
+        print(t.claudeConfigured(result.updated));
+        if (result.failed.length) print(t.claudeFailed(result.failed));
+      } else {
+        print(t.claudeManual(result.manual));
+      }
+      print(t.howItWorks(HOW_TO_CONNECT_URL));
+      return 0;
+    }
+    case "status": {
+      const credential = store.read(account);
+      if (!credential?.token) {
+        print(t.notConnected);
+        return 1;
+      }
+      let valid = null;
+      try {
+        const res = await fetchImpl(`${credential.cloud_api ?? config.cloudApi}/whoami`, {
+          headers: { authorization: `Bearer ${credential.token}`, accept: "application/json" },
+        });
+        valid = res.status === 200 ? true : res.status === 401 ? false : null;
+      } catch {
+        valid = null;
+      }
+      print(t.statusTitle);
+      print(
+        t.statusLines(
+          credential,
+          store.kind,
+          config.mcpUrl,
+          valid,
+          claudeUsesHelper(deps.claudeJsonPath ? { claudeJsonPath: deps.claudeJsonPath } : {}),
+        ),
+      );
+      return valid === false ? 1 : 0;
+    }
+    case "logout": {
+      const credential = store.read(account);
+      if (!credential?.token) {
+        print(t.notConnected);
+        return 0;
+      }
+      let remote = false;
+      try {
+        const res = await fetchImpl(`${credential.cloud_api ?? config.cloudApi}/devices/logout`, {
+          method: "POST",
+          headers: { authorization: `Bearer ${credential.token}` },
+        });
+        remote = res.status === 200 || res.status === 401; // 401: ya no valía
+      } catch {
+        remote = false;
+      }
+      store.remove(account);
+      print(t.loggedOut(credential.device_name ?? "?", remote));
+      return 0;
+    }
+    case "help":
+    case null:
+      print(t.usage);
+      return opts.command === "help" ? 0 : 1;
+    default:
+      printErr(t.usage);
+      return 1;
+  }
+}
+
+// Por `npx`/npm el script se ejecuta a través de un enlace simbólico: se
+// compara con la ruta real.
+const invokedDirectly = (() => {
+  try {
+    return Boolean(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+})();
+if (invokedDirectly) {
+  run(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(`${err?.stack ?? err}\n`);
+      process.exit(1);
+    },
+  );
+}

package/lib/claude.mjs

@@ -0,0 +1,167 @@
+/**
+ * Configurar Claude Code para que envíe el token en cada conexión (UC-3901
+ * AC-03): la entrada `SpecBox-MCP` (ámbito de usuario) pasa a ser
+ * `{type: "http", url, headersHelper}`, y las demás entradas que apuntan al
+ * mismo servidor (ámbito local de cada proyecto) reciben el mismo ayudante,
+ * de modo que los proyectos ya configurados siguen funcionando sin pasos
+ * manuales.
+ *
+ * Se usa la orden oficial `claude mcp` (remove + add-json), nunca se edita
+ * `~/.claude.json` a mano: Claude Code lo reescribe mientras está abierto. Si
+ * `claude` no está en el PATH, se devuelve la orden para ejecutarla a mano.
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, posix, win32 } from "node:path";
+import { SERVER_NAME } from "./config.mjs";
+import { runCommand } from "./store.mjs";
+
+export function quoteArg(value) {
+  return `"${String(value).replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * La ruta de Node que se graba en el ayudante. `process.execPath` es la ruta
+ * real del binario, que en Homebrew lleva la versión
+ * (`/opt/homebrew/Cellar/node/26.7.0/bin/node`) y desaparece con
+ * `brew upgrade`; se prefiere la primera entrada del PATH que apunta a ese
+ * mismo binario (`/opt/homebrew/bin/node`), que el gestor de paquetes mantiene
+ * al actualizar. Si ninguna apunta a él, se usa `process.execPath`.
+ */
+export function stableNodePath({
+  execPath = process.execPath,
+  pathEnv = process.env.PATH ?? "",
+  platform = process.platform,
+  realpath = realpathSync,
+  exists = existsSync,
+} = {}) {
+  const path = platform === "win32" ? win32 : posix;
+  const binary = platform === "win32" ? "node.exe" : "node";
+  let target;
+  try {
+    target = realpath(execPath);
+  } catch {
+    return execPath;
+  }
+  for (const dir of pathEnv.split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, binary);
+    try {
+      if (exists(candidate) && realpath(candidate) === target) return candidate;
+    } catch {
+      // entrada del PATH rota o sin permisos: se ignora
+    }
+  }
+  return execPath;
+}
+
+/** La orden que Claude Code ejecuta: node absoluto + ayudante absoluto. */
+export function helperCommand(helperPath, nodePath = stableNodePath()) {
+  return `${quoteArg(nodePath)} ${quoteArg(helperPath)}`;
+}
+
+/** Las dos rutas de una orden de `helperCommand`, o null si no tiene esa forma. */
+export function helperPaths(cmd) {
+  const m = /^"([^"]+)" "([^"]+)"$/.exec(String(cmd ?? ""));
+  return m ? { node: m[1], helper: m[2] } : null;
+}
+
+function origin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Entradas de `~/.claude.json` (usuario y locales) que apuntan al servidor de SpecBox. */
+export function findSpecboxEntries(claudeJson, mcpUrl) {
+  const target = origin(mcpUrl);
+  const matches = (entry) => entry && typeof entry.url === "string" && origin(entry.url) === target;
+  const found = [];
+  for (const [name, entry] of Object.entries(claudeJson?.mcpServers ?? {})) {
+    if (matches(entry)) found.push({ scope: "user", name, entry, cwd: null });
+  }
+  for (const [project, config] of Object.entries(claudeJson?.projects ?? {})) {
+    for (const [name, entry] of Object.entries(config?.mcpServers ?? {})) {
+      if (matches(entry)) found.push({ scope: "local", name, entry, cwd: project });
+    }
+  }
+  return found;
+}
+
+/** La entrada con el ayudante, sin ninguna cabecera Authorization fija que lo contradiga. */
+export function withHelper(entry, helperCmd) {
+  const { headers, headersHelper: _old, ...rest } = entry ?? {};
+  void _old;
+  const kept = Object.fromEntries(Object.entries(headers ?? {}).filter(([k]) => k.toLowerCase() !== "authorization"));
+  return {
+    ...rest,
+    type: rest.type ?? "http",
+    ...(Object.keys(kept).length ? { headers: kept } : {}),
+    headersHelper: helperCmd,
+  };
+}
+
+export function configureClaudeCode({
+  mcpUrl,
+  helperCmd,
+  run = runCommand,
+  claudeJsonPath = join(homedir(), ".claude.json"),
+  readFile = readFileSync,
+  projectExists = existsSync,
+}) {
+  const userEntry = JSON.stringify({ type: "http", url: mcpUrl, headersHelper: helperCmd });
+  const manual = `claude mcp add-json ${SERVER_NAME} '${userEntry}' --scope user`;
+  const probe = run("claude", ["--version"]);
+  if (probe.error || probe.status === null) return { ok: false, reason: "claude_missing", manual };
+
+  run("claude", ["mcp", "remove", SERVER_NAME, "--scope", "user"]); // puede no existir
+  const added = run("claude", ["mcp", "add-json", SERVER_NAME, userEntry, "--scope", "user"]);
+  if (added.status !== 0) {
+    return { ok: false, reason: "add_failed", detail: `${added.stderr}${added.stdout}`.trim(), manual };
+  }
+
+  const updated = [{ scope: "user", name: SERVER_NAME, cwd: null }];
+  const failed = [];
+  let claudeJson = {};
+  try {
+    claudeJson = JSON.parse(readFile(claudeJsonPath, "utf8"));
+  } catch {
+    // sin ~/.claude.json no hay más entradas que migrar
+  }
+  for (const found of findSpecboxEntries(claudeJson, mcpUrl)) {
+    if (found.scope === "user" && found.name === SERVER_NAME) continue;
+    if (found.entry.headersHelper === helperCmd) continue;
+    if (found.cwd && !projectExists(found.cwd)) continue; // proyecto que ya no existe
+    const opts = found.cwd ? { cwd: found.cwd } : {};
+    run("claude", ["mcp", "remove", found.name, "--scope", found.scope], opts);
+    const res = run(
+      "claude",
+      ["mcp", "add-json", found.name, JSON.stringify(withHelper(found.entry, helperCmd)), "--scope", found.scope],
+      opts,
+    );
+    (res.status === 0 ? updated : failed).push({ scope: found.scope, name: found.name, cwd: found.cwd });
+  }
+  return { ok: true, updated, failed };
+}
+
+/**
+ * ¿La entrada de usuario usa nuestro ayudante y este puede ejecutarse? (para
+ * `specbox status` y la extensión). Si el Node grabado ya no existe (p. ej.
+ * una versión que borró el gestor de paquetes), es `false`: la extensión
+ * vuelve a configurar Claude Code en el siguiente arranque.
+ */
+export function claudeUsesHelper({
+  claudeJsonPath = join(homedir(), ".claude.json"),
+  readFile = readFileSync,
+  exists = existsSync,
+} = {}) {
+  try {
+    const entry = JSON.parse(readFile(claudeJsonPath, "utf8"))?.mcpServers?.[SERVER_NAME];
+    const paths = helperPaths(entry?.headersHelper);
+    return Boolean(paths && paths.helper.endsWith("mcp-headers.mjs") && exists(paths.node) && exists(paths.helper));
+  } catch {
+    return false;
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,44 @@
+/**
+ * Valores por defecto y rutas de `specbox` (UC-3904).
+ *
+ * Todo se puede cambiar por entorno para operadores con su propio servidor:
+ *   SPECBOX_MCP_URL    servidor MCP remoto
+ *   SPECBOX_CLOUD_API  API del panel (código de un solo uso, renovación)
+ *   SPECBOX_HOME       carpeta local de specbox (por defecto ~/.specbox)
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_MCP_URL = "https://mcp-specbox-engine.jpsdeveloper.com/mcp";
+export const DEFAULT_CLOUD_API = "https://api-cloud.specbox.build/api";
+export const HOW_TO_CONNECT_URL = "https://cloud.specbox.build/como-se-conecta";
+
+/** Nombre del servidor en Claude Code: las skills del engine usan `mcp__SpecBox-MCP__*`. */
+export const SERVER_NAME = "SpecBox-MCP";
+
+/** El cliente que usa el token guardado en el almacén: Claude Code. */
+export const CLIENT = "claude-code";
+
+/** Los clientes renuevan a partir de estos días antes de caducar (UC-3904 AC-03). */
+export const RENEW_WINDOW_DAYS = 14;
+
+export function specboxHome(env = process.env) {
+  return env.SPECBOX_HOME || join(homedir(), ".specbox");
+}
+
+export function resolveConfig({ server, cloud } = {}, env = process.env) {
+  return {
+    mcpUrl: stripSlash(server || env.SPECBOX_MCP_URL || DEFAULT_MCP_URL),
+    cloudApi: stripSlash(cloud || env.SPECBOX_CLOUD_API || DEFAULT_CLOUD_API),
+  };
+}
+
+/** Clave de la credencial en el almacén: la URL del servidor sin barra final. */
+export function accountFor(mcpUrl) {
+  const url = new URL(mcpUrl);
+  return stripSlash(`${url.origin}${url.pathname}`);
+}
+
+function stripSlash(value) {
+  return String(value).replace(/\/+$/, "");
+}

package/lib/device.mjs

@@ -0,0 +1,68 @@
+/**
+ * Identidad del dispositivo (UC-3904 AC-01): un dispositivo es un ordenador y
+ * un cliente MCP. El `device_id` es el SHA-256 del id de la máquina y el
+ * cliente: estable entre reinstalaciones y sin revelar el id real al servidor.
+ * Si no se puede leer el id de la máquina, se usa uno aleatorio guardado en
+ * `~/.specbox/device-id`.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+
+export function machineId({ platform = process.platform, run = execFileSync, readFile = readFileSync } = {}) {
+  try {
+    if (platform === "darwin") {
+      const out = run("ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], { encoding: "utf8" });
+      const match = /"IOPlatformUUID" = "([^"]+)"/.exec(out);
+      if (match) return match[1];
+    } else if (platform === "win32") {
+      const out = run("reg", ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid"], {
+        encoding: "utf8",
+      });
+      const match = /MachineGuid\s+REG_SZ\s+(\S+)/.exec(out);
+      if (match) return match[1];
+    } else {
+      for (const file of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+        try {
+          const value = String(readFile(file, "utf8")).trim();
+          if (value) return value;
+        } catch {
+          // siguiente fuente
+        }
+      }
+    }
+  } catch {
+    // sin id de máquina: se usa el aleatorio persistido
+  }
+  return null;
+}
+
+function persistedRandomId(home) {
+  const file = join(home, "device-id");
+  try {
+    const value = readFileSync(file, "utf8").trim();
+    if (value) return value;
+  } catch {
+    // se crea abajo
+  }
+  const id = randomUUID();
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  writeFileSync(file, id, { mode: 0o600 });
+  return id;
+}
+
+export function deviceId(client, { home, machine = machineId } = {}) {
+  const seed = (typeof machine === "function" ? machine() : machine) || persistedRandomId(home);
+  return createHash("sha256").update(`${seed}:${client}`).digest("hex");
+}
+
+/** Nombre legible del ordenador para el nombre del dispositivo (≤ 80 caracteres). */
+export function hostLabel(name = hostname()) {
+  const clean = String(name)
+    .replace(/\.local$/i, "")
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .trim();
+  return (clean || "ordenador").slice(0, 80);
+}

package/lib/install.mjs

@@ -0,0 +1,32 @@
+/**
+ * Instala el ayudante de cabeceras en `~/.specbox/bin` (ruta fija que no
+ * cambia al actualizar el paquete ni la extensión): el script y los módulos
+ * que importa, más un package.json que marca la carpeta como ESM. Se
+ * sobrescribe en cada `specbox login` para llevar siempre la última versión.
+ */
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const RUNTIME_FILES = ["config.mjs", "store.mjs", "renew.mjs", "mcp-headers.mjs"];
+
+const LIB_DIR = dirname(fileURLToPath(import.meta.url));
+
+export function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(join(LIB_DIR, "..", "package.json"), "utf8")).version;
+  } catch {
+    return null;
+  }
+}
+
+export function installHelper(home, { sourceDir = LIB_DIR, version = packageVersion() } = {}) {
+  const bin = join(home, "bin");
+  mkdirSync(bin, { recursive: true, mode: 0o700 });
+  for (const file of RUNTIME_FILES) copyFileSync(join(sourceDir, file), join(bin, file));
+  writeFileSync(
+    join(bin, "package.json"),
+    `${JSON.stringify({ private: true, type: "module", specbox_helper_version: version }, null, 2)}\n`,
+  );
+  return join(bin, "mcp-headers.mjs");
+}