@i4ctime/q-ring 0.14.0 → 0.15.0

package/dist/index.js

@@ -44,7 +44,7 @@ import {
   tunnelList,
   tunnelRead,
   verifyAuditChain
-} from "./chunk-C2TFJ2EH.js";
+} from "./chunk-MLBJCPX2.js";
 
 // src/cli/commands.ts
 import { Command, Help } from "commander";
@@ -764,6 +764,79 @@ var ProviderRegistry = class {
     return [...this.providers.values()];
   }
 };
+function livenessProvider(cfg) {
+  return {
+    name: cfg.name,
+    description: cfg.description,
+    prefixes: cfg.prefixes,
+    async validate(value) {
+      const start = Date.now();
+      try {
+        const { statusCode } = await makeRequest(cfg.url, {
+          "User-Agent": "q-ring-validator/1.0",
+          ...cfg.headers(value)
+        });
+        const latencyMs = Date.now() - start;
+        if (statusCode === 200)
+          return { valid: true, status: "valid", message: "API key is valid", latencyMs, provider: cfg.name };
+        if (statusCode === 401 || statusCode === 403)
+          return { valid: false, status: "invalid", message: `Invalid or revoked API key (${statusCode})`, latencyMs, provider: cfg.name };
+        if (statusCode === 429)
+          return { valid: true, status: "error", message: "Rate limited \u2014 key may be valid", latencyMs, provider: cfg.name };
+        return { valid: false, status: "error", message: `Unexpected status ${statusCode}`, latencyMs, provider: cfg.name };
+      } catch (err) {
+        return { valid: false, status: "error", message: `${err instanceof Error ? err.message : "Network error"}`, latencyMs: Date.now() - start, provider: cfg.name };
+      }
+    }
+  };
+}
+var anthropicProvider = livenessProvider({
+  name: "anthropic",
+  description: "Anthropic API key validation",
+  prefixes: ["sk-ant-"],
+  url: "https://api.anthropic.com/v1/models?limit=1",
+  headers: (value) => ({ "x-api-key": value, "anthropic-version": "2023-06-01" })
+});
+var openrouterProvider = livenessProvider({
+  name: "openrouter",
+  description: "OpenRouter API key validation",
+  prefixes: ["sk-or-"],
+  url: "https://openrouter.ai/api/v1/key",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
+var googleAiProvider = livenessProvider({
+  name: "google-ai",
+  description: "Google AI (Gemini) API key validation",
+  prefixes: ["AIza"],
+  url: "https://generativelanguage.googleapis.com/v1beta/models?pageSize=1",
+  headers: (value) => ({ "x-goog-api-key": value })
+});
+var groqProvider = livenessProvider({
+  name: "groq",
+  description: "Groq API key validation",
+  prefixes: ["gsk_"],
+  url: "https://api.groq.com/openai/v1/models",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
+var huggingfaceProvider = livenessProvider({
+  name: "huggingface",
+  description: "Hugging Face token validation",
+  prefixes: ["hf_"],
+  url: "https://huggingface.co/api/whoami-v2",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
+var elevenlabsProvider = livenessProvider({
+  name: "elevenlabs",
+  description: "ElevenLabs API key validation (explicit-only \u2014 set provider on the secret)",
+  url: "https://api.elevenlabs.io/v1/user",
+  headers: (value) => ({ "xi-api-key": value })
+});
+var vercelProvider = livenessProvider({
+  name: "vercel",
+  description: "Vercel token validation (explicit-only \u2014 set provider on the secret)",
+  url: "https://api.vercel.com/v2/user",
+  headers: (value) => ({ Authorization: `Bearer ${value}` })
+});
 var openaiProvider = {
   name: "openai",
   description: "OpenAI API key validation",
@@ -890,7 +963,14 @@ var httpProvider = {
   }
 };
 var registry2 = new ProviderRegistry();
+registry2.register(anthropicProvider);
+registry2.register(openrouterProvider);
 registry2.register(openaiProvider);
+registry2.register(googleAiProvider);
+registry2.register(groqProvider);
+registry2.register(huggingfaceProvider);
+registry2.register(elevenlabsProvider);
+registry2.register(vercelProvider);
 registry2.register(stripeProvider);
 registry2.register(githubProvider);
 registry2.register(awsProvider);
@@ -1984,10 +2064,9 @@ var RedactionTransform = class extends Transform {
     callback();
   }
 };
-async function execCommand(opts) {
-  const profile = getProfile(opts.profile);
-  const fullCommand = [opts.command, ...opts.args].join(" ");
-  const policyDecision = checkExecPolicy(fullCommand, opts.projectPath);
+function enforceExecPolicy(profile, command, args, projectPath) {
+  const fullCommand = [command, ...args].join(" ");
+  const policyDecision = checkExecPolicy(fullCommand, projectPath);
   if (!policyDecision.allowed) {
     throw new Error(`Policy Denied: ${policyDecision.reason}`);
   }
@@ -2003,9 +2082,13 @@ async function execCommand(opts) {
   if (profile.allowCommands) {
     const allowed = profile.allowCommands.some((a) => fullCommand.startsWith(a));
     if (!allowed) {
-      throw new Error(`Exec profile "${profile.name}" does not allow command "${opts.command}"`);
+      throw new Error(`Exec profile "${profile.name}" does not allow command "${command}"`);
     }
   }
+}
+async function execCommand(opts) {
+  const profile = getProfile(opts.profile);
+  enforceExecPolicy(profile, opts.command, opts.args, opts.projectPath);
   const envMap = {};
   for (const [k, v] of Object.entries(process.env)) {
     if (v !== void 0) envMap[k] = v;
@@ -2052,6 +2135,18 @@ async function execCommand(opts) {
       }
     }
   }
+  return spawnRedacted({
+    profile,
+    command: opts.command,
+    args: opts.args,
+    envMap,
+    secretsToRedact: [...secretsToRedact],
+    captureOutput: opts.captureOutput,
+    projectPath: opts.projectPath
+  });
+}
+function spawnRedacted(opts) {
+  const { profile, secretsToRedact, envMap } = opts;
   const maxRuntime = profile.maxRuntimeSeconds ?? getExecMaxRuntime(opts.projectPath);
   return new Promise((resolve, reject) => {
     const networkTools = /* @__PURE__ */ new Set([
@@ -2492,7 +2587,7 @@ function registerToolingCommands(program2) {
     }
   });
   program2.command("status").description("Launch the quantum status dashboard in your browser").option("--port <port>", "Port to serve on", "9876").option("--no-open", "Don't auto-open the browser").action(async (cmd) => {
-    const { startDashboardServer } = await import("./dashboard-PYYAED45.js");
+    const { startDashboardServer } = await import("./dashboard-T2UG23KI.js");
     const { exec } = await import("child_process");
     const { platform } = await import("os");
     const port = Number(cmd.port);
@@ -3407,12 +3502,540 @@ ${SYMBOLS.lock} Approval Tokens
   });
 }
 
-// src/cli/commands/doctor.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync5, rmSync } from "fs";
-import { join as join3, delimiter } from "path";
+// src/core/run.ts
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
+import { join as join3, resolve as resolvePath } from "path";
+
+// src/core/refs.ts
+var REF_PREFIX = "qring://";
+var KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var REF_PATTERN = /^qring:\/\/(global|project|)\/([^/?#]+)(?:\?([^#]*))?$/;
+function isRef(value) {
+  return value.startsWith(REF_PREFIX);
+}
+function parseRef(raw) {
+  if (!isRef(raw)) {
+    throw new Error(`Not a qring:// reference: "${raw}"`);
+  }
+  const match = REF_PATTERN.exec(raw);
+  if (!match) {
+    const hostOnly = /^qring:\/\/([^/?#]+)\/?$/.exec(raw);
+    if (hostOnly && KEY_PATTERN.test(hostOnly[1]) && !["global", "project"].includes(hostOnly[1])) {
+      throw new Error(
+        `Invalid ref "${raw}": the key belongs in the path, not the host (URL hosts are lowercased by parsers). Use "qring:///${hostOnly[1]}" (auto scope) or "qring://project/${hostOnly[1]}".`
+      );
+    }
+    throw new Error(
+      `Invalid ref "${raw}": expected qring://<global|project|>/KEY[?env=<env>]`
+    );
+  }
+  const [, scopeRaw, key, query] = match;
+  if (!KEY_PATTERN.test(key)) {
+    throw new Error(
+      `Invalid ref "${raw}": "${key}" is not a valid secret key (expected [A-Za-z_][A-Za-z0-9_]*)`
+    );
+  }
+  let env;
+  if (query) {
+    for (const part of query.split("&")) {
+      if (!part) continue;
+      const eq = part.indexOf("=");
+      const name = eq === -1 ? part : part.slice(0, eq);
+      const value = eq === -1 ? "" : decodeURIComponent(part.slice(eq + 1));
+      if (name === "env") {
+        env = value;
+      } else {
+        throw new Error(`Invalid ref "${raw}": unknown query parameter "${name}"`);
+      }
+    }
+  }
+  return {
+    scope: scopeRaw === "" ? void 0 : scopeRaw,
+    key,
+    env,
+    raw
+  };
+}
+function resolveRef(ref, opts = {}) {
+  const scopes = ref.scope ? [ref.scope] : ["project", "global"];
+  for (const scope of scopes) {
+    const value = getSecret(ref.key, {
+      ...opts,
+      scope,
+      env: ref.env ?? opts.env
+    });
+    if (value !== null) return value;
+  }
+  return null;
+}
+function resolveRefsInMap(map, opts = {}) {
+  const resolved = {};
+  const secretValues = [];
+  const missing = [];
+  for (const [name, value] of Object.entries(map)) {
+    if (!isRef(value)) {
+      resolved[name] = value;
+      continue;
+    }
+    const ref = parseRef(value);
+    const secret = resolveRef(ref, opts);
+    if (secret === null) {
+      missing.push({ name, ref });
+      continue;
+    }
+    resolved[name] = secret;
+    secretValues.push(secret);
+  }
+  return { resolved, secretValues, missing };
+}
+
+// src/core/run.ts
+function buildRunPlan(opts) {
+  const projectPath = opts.projectPath ?? process.cwd();
+  const keyringOpts = {
+    projectPath,
+    env: opts.env,
+    source: opts.source ?? "cli",
+    silent: opts.silent
+  };
+  const envMap = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== void 0) envMap[k] = v;
+  }
+  const injected = [];
+  const missingRequired = [];
+  const missingOptional = [];
+  const secretsToRedact = /* @__PURE__ */ new Set();
+  if (opts.useManifest !== false) {
+    const config = readProjectConfig(projectPath);
+    for (const [key, entry] of Object.entries(config?.secrets ?? {})) {
+      const value = resolveRef(
+        { key, raw: `manifest:${key}` },
+        keyringOpts
+      );
+      if (value === null) {
+        if (entry.required !== false) missingRequired.push(key);
+        else if (opts.strict) missingRequired.push(key);
+        else missingOptional.push(key);
+        continue;
+      }
+      envMap[key] = value;
+      injected.push({ name: key, source: "manifest" });
+      if (value.length > 5) secretsToRedact.add(value);
+    }
+  }
+  const envFiles = opts.envFiles ?? (existsSync4(join3(projectPath, ".env")) ? [join3(projectPath, ".env")] : []);
+  for (const file of envFiles) {
+    const path = resolvePath(projectPath, file);
+    if (!existsSync4(path)) {
+      throw new Error(`Env file not found: ${path}`);
+    }
+    const parsed = Object.fromEntries(parseDotenv(readFileSync6(path, "utf8")));
+    const { resolved, secretValues, missing } = resolveRefsInMap(parsed, keyringOpts);
+    for (const [name, value] of Object.entries(resolved)) {
+      envMap[name] = value;
+      injected.push({
+        name,
+        source: isRef(parsed[name]) ? "env-file-ref" : "env-file"
+      });
+    }
+    for (const value of secretValues) {
+      if (value.length > 5) secretsToRedact.add(value);
+    }
+    for (const m of missing) missingRequired.push(m.name);
+  }
+  return {
+    envFiles: envFiles.map((f) => resolvePath(projectPath, f)),
+    injected,
+    missingRequired,
+    missingOptional,
+    envMap,
+    secretsToRedact: [...secretsToRedact]
+  };
+}
+async function runCommand(opts) {
+  const profile = getProfile(opts.profile);
+  enforceExecPolicy(profile, opts.command, opts.args, opts.projectPath);
+  const plan = buildRunPlan(opts);
+  if (plan.missingRequired.length > 0) {
+    throw new Error(
+      `Missing required secrets: ${plan.missingRequired.join(", ")}. Store them with \`qring set <KEY>\` or drop them from the manifest/.env refs.`
+    );
+  }
+  if (profile.stripEnvVars) {
+    for (const key of profile.stripEnvVars) {
+      delete plan.envMap[key];
+    }
+  }
+  const result = await spawnRedacted({
+    profile,
+    command: opts.command,
+    args: opts.args,
+    envMap: plan.envMap,
+    secretsToRedact: plan.secretsToRedact,
+    captureOutput: opts.captureOutput,
+    projectPath: opts.projectPath
+  });
+  return { ...result, plan };
+}
+
+// src/core/setup.ts
+import { existsSync as existsSync5, mkdirSync, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
 import { homedir } from "os";
+import { dirname, join as join4 } from "path";
+var EDITORS = ["cursor", "kiro", "claude"];
+var READ_ONLY_TOOLS = [
+  "list_secrets",
+  "has_secret",
+  "inspect_secret",
+  "detect_environment",
+  "get_project_context",
+  "list_providers",
+  "list_hooks",
+  "get_policy_summary",
+  "audit_log",
+  "verify_audit_chain",
+  "health_check",
+  "analyze_secrets"
+];
+var SERVER_NAME = "q-ring";
+function serverEntry(editor) {
+  switch (editor) {
+    case "cursor":
+      return { command: "qring-mcp", args: [], env: {} };
+    case "kiro":
+      return {
+        command: "qring-mcp",
+        args: [],
+        env: {},
+        disabled: false,
+        autoApprove: READ_ONLY_TOOLS
+      };
+    case "claude":
+      return { type: "stdio", command: "qring-mcp", args: [], env: {} };
+  }
+}
+function configPathFor(editor, global, projectPath) {
+  const home = homedir();
+  switch (editor) {
+    case "cursor":
+      return global ? join4(home, ".cursor", "mcp.json") : join4(projectPath, ".cursor", "mcp.json");
+    case "kiro":
+      return global ? join4(home, ".kiro", "settings", "mcp.json") : join4(projectPath, ".kiro", "settings", "mcp.json");
+    case "claude":
+      if (global) {
+        throw new Error(
+          "Claude Code user-scoped MCP servers are registered via the claude CLI, not a config file.\nRun: claude mcp add --scope user q-ring qring-mcp\nOr install the plugin: /plugin marketplace add I4cTime/q-ring && /plugin install qring@q-ring"
+        );
+      }
+      return join4(projectPath, ".mcp.json");
+  }
+}
+function setupEditor(opts) {
+  const projectPath = opts.projectPath ?? process.cwd();
+  const configPath = configPathFor(opts.editor, opts.global ?? false, projectPath);
+  const warnings = [];
+  let config = {};
+  if (existsSync5(configPath)) {
+    const raw = readFileSync7(configPath, "utf8");
+    try {
+      config = JSON.parse(raw);
+    } catch {
+      throw new Error(
+        `${configPath} exists but is not valid JSON \u2014 fix or remove it, then re-run.`
+      );
+    }
+  }
+  const servers = config.mcpServers ?? {};
+  const desired = serverEntry(opts.editor);
+  const existing = servers[SERVER_NAME];
+  let action;
+  if (existing === void 0) {
+    action = existsSync5(configPath) ? "updated" : "created";
+    servers[SERVER_NAME] = desired;
+  } else if (JSON.stringify(existing) === JSON.stringify(desired)) {
+    action = "unchanged";
+  } else if (opts.force) {
+    action = "updated";
+    servers[SERVER_NAME] = desired;
+  } else {
+    action = "unchanged";
+    warnings.push(
+      `A different "${SERVER_NAME}" entry already exists in ${configPath} \u2014 left as-is (use --force to replace it).`
+    );
+  }
+  config.mcpServers = servers;
+  if (action !== "unchanged" && !opts.dryRun) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync5(configPath, JSON.stringify(config, null, 2) + "\n");
+  }
+  return {
+    editor: opts.editor,
+    configPath,
+    serverName: SERVER_NAME,
+    action,
+    dryRun: opts.dryRun ?? false,
+    warnings
+  };
+}
+
+// src/core/push.ts
+import { spawnSync } from "child_process";
+var PUSH_TARGETS = ["github", "vercel", "cloudflare"];
+var TARGETS = {
+  github: {
+    binary: "gh",
+    args: (key, opts) => [
+      ["secret", "set", key, ...opts.repo ? ["--repo", opts.repo] : []]
+    ],
+    installHint: "install the GitHub CLI: https://cli.github.com (then `gh auth login`)"
+  },
+  vercel: {
+    binary: "vercel",
+    // One invocation per environment — `vercel env add` takes a single target.
+    args: (key, opts) => (opts.vercelEnvs ?? ["production"]).map((env) => [
+      "env",
+      "add",
+      key,
+      env,
+      "--force"
+    ]),
+    installHint: "install the Vercel CLI: npm i -g vercel (then `vercel link` in the project)"
+  },
+  cloudflare: {
+    binary: "wrangler",
+    args: (key) => [["secret", "put", key]],
+    installHint: "install Wrangler: npm i -g wrangler (then `wrangler login`)"
+  }
+};
+function binaryAvailable(binary) {
+  const probe = spawnSync(binary, ["--version"], { stdio: "ignore", shell: false });
+  return !probe.error;
+}
+function resolvePushKeys(opts) {
+  if (opts.keys?.length) return opts.keys;
+  const config = readProjectConfig(opts.projectPath);
+  const manifestKeys = Object.keys(config?.secrets ?? {});
+  if (manifestKeys.length === 0) {
+    throw new Error(
+      "Nothing to push: no --keys given and no secrets manifest in .q-ring.json. Declare the project's secrets there or pass --keys KEY1,KEY2."
+    );
+  }
+  return manifestKeys;
+}
+function pushSecrets(opts) {
+  const target = TARGETS[opts.target];
+  const keys = resolvePushKeys(opts);
+  if (!opts.dryRun && !binaryAvailable(target.binary)) {
+    throw new Error(`"${target.binary}" CLI not found \u2014 ${target.installHint}`);
+  }
+  const result = { target: opts.target, pushed: [], failed: [], missing: [] };
+  for (const key of keys) {
+    const value = resolveRef(
+      { key, raw: `push:${key}` },
+      {
+        projectPath: opts.projectPath,
+        env: opts.env,
+        source: opts.source ?? "cli",
+        silent: opts.silent
+      }
+    );
+    if (value === null) {
+      result.missing.push(key);
+      continue;
+    }
+    if (opts.dryRun) {
+      result.pushed.push(key);
+      continue;
+    }
+    let failedInvocation = null;
+    for (const args of target.args(key, opts)) {
+      const child = spawnSync(target.binary, args, {
+        input: value,
+        cwd: opts.projectPath,
+        encoding: "utf8",
+        shell: false
+      });
+      if (child.status !== 0) {
+        failedInvocation = child.stderr?.trim() || child.error?.message || `exit ${child.status}`;
+        break;
+      }
+    }
+    if (failedInvocation) {
+      result.failed.push({ key, error: failedInvocation });
+      continue;
+    }
+    result.pushed.push(key);
+    if (!opts.silent) {
+      logAudit({
+        action: "push",
+        key,
+        env: opts.env,
+        source: opts.source ?? "cli",
+        detail: `pushed to ${opts.target}${opts.repo ? ` (${opts.repo})` : ""}`
+      });
+    }
+  }
+  return result;
+}
+
+// src/cli/commands/bridges.ts
+function registerBridgeCommands(program2) {
+  program2.command("run <command...>").description(
+    "Run a command with only declared secrets injected \u2014 .q-ring.json manifest keys plus qring:// refs from .env (output auto-redacted)"
+  ).option("--project-path <path>", "Explicit project path").option("-e, --env <env>", "Environment context").option("--env-file <files...>", "Env file(s) to load (default: ./.env when present)").option("--no-manifest", "Skip .q-ring.json manifest keys").option("--profile <name>", "Exec profile: unrestricted, restricted, ci").option("--strict", "Missing optional manifest keys are fatal too").option("--dry-run", "Show what would be injected without running").action(async (commandArgs, cmd) => {
+    const opts = {
+      command: commandArgs[0],
+      args: commandArgs.slice(1),
+      projectPath: cmd.projectPath ?? process.cwd(),
+      env: cmd.env,
+      envFiles: cmd.envFile,
+      useManifest: cmd.manifest !== false,
+      profile: cmd.profile,
+      strict: cmd.strict === true,
+      source: "cli"
+    };
+    try {
+      if (cmd.dryRun) {
+        const plan2 = buildRunPlan({ ...opts, silent: true });
+        console.log(`
+${SYMBOLS.zap} ${c.bold("qring run")} ${c.dim("(dry run)")}`);
+        if (plan2.envFiles.length > 0) {
+          console.log(`  Env files: ${plan2.envFiles.map((f) => c.cyan(f)).join(", ")}`);
+        }
+        for (const v of plan2.injected) {
+          console.log(`  ${c.green(SYMBOLS.check)} ${v.name} ${c.dim(`(${v.source})`)}`);
+        }
+        for (const name of plan2.missingOptional) {
+          console.log(`  ${c.yellow("?")} ${name} ${c.dim("(optional, missing)")}`);
+        }
+        for (const name of plan2.missingRequired) {
+          console.log(`  ${c.red(SYMBOLS.cross)} ${name} ${c.dim("(required, MISSING)")}`);
+        }
+        process.exit(plan2.missingRequired.length > 0 ? 1 : 0);
+      }
+      const { code, plan } = await runCommand(opts);
+      if (plan.missingOptional.length > 0) {
+        console.error(
+          c.yellow(
+            `${SYMBOLS.warning} Optional secrets not found: ${plan.missingOptional.join(", ")}`
+          )
+        );
+      }
+      process.exit(code);
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Run failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+  program2.command("push <target>").description(
+    `Push manifest secrets to a deployment platform via its own CLI (${PUSH_TARGETS.join(", ")}) \u2014 values travel over stdin, never argv`
+  ).option("-k, --keys <keys>", "Comma-separated keys (default: .q-ring.json manifest)").option("--project-path <path>", "Explicit project path").option("-e, --env <env>", "Environment context for superposition collapse").option("--repo <owner/name>", "GitHub repository (github target)").option(
+    "--vercel-env <envs>",
+    "Comma-separated Vercel environments (default: production)"
+  ).option("--dry-run", "Show what would be pushed without pushing").option("--json", "Output as JSON").action((targetArg, cmd) => {
+    if (!PUSH_TARGETS.includes(targetArg)) {
+      console.error(
+        c.red(`${SYMBOLS.cross} Unknown target "${targetArg}" \u2014 expected one of: ${PUSH_TARGETS.join(", ")}`)
+      );
+      process.exit(1);
+    }
+    try {
+      const result = pushSecrets({
+        target: targetArg,
+        keys: cmd.keys?.split(",").map((k) => k.trim()),
+        projectPath: cmd.projectPath ?? process.cwd(),
+        env: cmd.env,
+        repo: cmd.repo,
+        vercelEnvs: cmd.vercelEnv?.split(",").map((e) => e.trim()),
+        dryRun: cmd.dryRun === true,
+        source: "cli"
+      });
+      if (wantsJsonOutput(program2, cmd)) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.failed.length > 0 ? 1 : 0);
+      }
+      const prefix = cmd.dryRun ? c.dim("[dry-run] ") : "";
+      console.log(`
+${SYMBOLS.link} ${prefix}${c.bold(`qring push ${targetArg}`)}`);
+      for (const key of result.pushed) {
+        console.log(`  ${c.green(SYMBOLS.check)} ${key}`);
+      }
+      for (const key of result.missing) {
+        console.log(`  ${c.yellow("?")} ${key} ${c.dim("(not in keyring \u2014 skipped)")}`);
+      }
+      for (const { key, error } of result.failed) {
+        console.log(`  ${c.red(SYMBOLS.cross)} ${key} ${c.dim(`\u2014 ${error}`)}`);
+      }
+      console.log(
+        c.dim(
+          `  ${result.pushed.length} pushed${cmd.dryRun ? " (dry run)" : ""}, ${result.missing.length} missing, ${result.failed.length} failed`
+        )
+      );
+      process.exit(result.failed.length > 0 ? 1 : 0);
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Push failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+  program2.command("setup <editor>").description(
+    `Wire the q-ring MCP server into an editor's MCP config (${EDITORS.join(", ")})`
+  ).option("-g, --global", "Write the per-user config instead of the project one").option("--project-path <path>", "Explicit project path").option("--force", "Replace an existing q-ring entry that differs").option("--dry-run", "Show what would change without writing").option("--json", "Output as JSON").action((editor, cmd) => {
+    if (!EDITORS.includes(editor)) {
+      console.error(
+        c.red(`${SYMBOLS.cross} Unknown editor "${editor}" \u2014 expected one of: ${EDITORS.join(", ")}`)
+      );
+      process.exit(1);
+    }
+    try {
+      const result = setupEditor({
+        editor,
+        global: cmd.global === true,
+        projectPath: cmd.projectPath ?? process.cwd(),
+        force: cmd.force === true,
+        dryRun: cmd.dryRun === true
+      });
+      if (wantsJsonOutput(program2, cmd)) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      const verb = result.action === "created" ? "Created" : result.action === "updated" ? "Updated" : "Already configured";
+      const prefix = result.dryRun ? c.dim("[dry-run] ") : "";
+      console.log(
+        `
+${SYMBOLS.check} ${prefix}${c.bold(verb)}: ${c.cyan(result.configPath)} ${c.dim(`(server "${result.serverName}")`)}`
+      );
+      for (const warning of result.warnings) {
+        console.log(`  ${c.yellow("!")} ${warning}`);
+      }
+      if (result.action !== "unchanged") {
+        console.log(c.dim(`  Restart ${editor} to pick up the MCP server. Verify with: qring doctor`));
+      }
+    } catch (err) {
+      console.error(
+        c.red(
+          `${SYMBOLS.cross} Setup failed: ${err instanceof Error ? err.message : String(err)}`
+        )
+      );
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli/commands/doctor.ts
+import { existsSync as existsSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync6, rmSync } from "fs";
+import { join as join5, delimiter } from "path";
+import { homedir as homedir2 } from "os";
 function auditDir() {
-  return process.env.QRING_AUDIT_DIR ?? join3(homedir(), ".config", "q-ring");
+  return process.env.QRING_AUDIT_DIR ?? join5(homedir2(), ".config", "q-ring");
 }
 function checkNode() {
   const major = Number(process.versions.node.split(".")[0]);
@@ -3452,8 +4075,8 @@ async function checkKeyringBackend() {
 function checkAuditLog() {
   const dir = auditDir();
   try {
-    const probeFile = join3(dir, ".doctor-probe");
-    writeFileSync5(probeFile, "ok");
+    const probeFile = join5(dir, ".doctor-probe");
+    writeFileSync6(probeFile, "ok");
     rmSync(probeFile);
   } catch (err) {
     return {
@@ -3480,8 +4103,8 @@ function checkAuditLog() {
   };
 }
 function checkManifest(projectPath) {
-  const manifestPath = join3(projectPath, ".q-ring.json");
-  if (!existsSync4(manifestPath)) {
+  const manifestPath = join5(projectPath, ".q-ring.json");
+  if (!existsSync6(manifestPath)) {
     return {
       name: "project manifest",
       status: "warn",
@@ -3489,7 +4112,7 @@ function checkManifest(projectPath) {
     };
   }
   try {
-    const config = JSON.parse(readFileSync6(manifestPath, "utf8"));
+    const config = JSON.parse(readFileSync8(manifestPath, "utf8"));
     const declared = Object.keys(config.secrets ?? {}).length;
     const hasPolicy = !!config.policy;
     return {
@@ -3538,11 +4161,11 @@ function checkMcpBinary() {
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
     for (const ext of exts) {
-      if (existsSync4(join3(dir, `qring-mcp${ext}`))) {
+      if (existsSync6(join5(dir, `qring-mcp${ext}`))) {
         return {
           name: "qring-mcp binary",
           status: "ok",
-          detail: `found at ${join3(dir, `qring-mcp${ext}`)}`
+          detail: `found at ${join5(dir, `qring-mcp${ext}`)}`
         };
       }
     }
@@ -3749,6 +4372,11 @@ var COMMAND_GROUPS = [
     symbol: SYMBOLS.zap,
     commands: ["exec", "scan", "lint", "status", "doctor", "completion"]
   },
+  {
+    name: "Bridges",
+    symbol: SYMBOLS.link,
+    commands: ["run", "setup", "push"]
+  },
   {
     name: "Audit & Health",
     symbol: SYMBOLS.eye,
@@ -3889,6 +4517,7 @@ function createProgram() {
   registerHookCommands(program2);
   registerAgentCommands(program2);
   registerSecurityCommands(program2);
+  registerBridgeCommands(program2);
   registerDoctorCommand(program2);
   registerCompletionCommand(program2);
   return program2;