syndai 0.1.1 → 0.4.0

package/src/errors.js

@@ -0,0 +1,148 @@
+// Exit codes and the one place a server problem becomes a sentence plus the next command.
+//
+// The exit codes are a contract with scripts and agents (docs: syndai.ai/docs/cli, "Exit codes"):
+// never renumber one.
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  FAILED: 1, // the change failed, was reverted or cancelled; or the request was refused
+  USAGE: 2, // bad arguments, or no project could be resolved
+  NEEDS_YOU: 3, // a question, a hold, or an approval only a browser session can give
+  UNVERIFIED: 4, // live, but the live check did not confirm it
+  AUTH: 5, // 401/402/403: key, scope, role or plan
+  TIMEOUT: 6, // --timeout reached; the change keeps going
+  UNAVAILABLE: 7, // the service did not answer after retries
+  INTERRUPTED: 130, // Ctrl-C; the change keeps going
+});
+
+/** A user-facing failure: `message` is one sentence, `next` the command (or URL) to run next. */
+export class CliError extends Error {
+  constructor(exitCode, message, { next = null, result = null } = {}) {
+    super(message);
+    this.exitCode = exitCode;
+    this.next = next;
+    // `result` is printed to stdout (JSON for scripts) before the error line.
+    this.result = result;
+  }
+}
+
+/** A non-2xx answer from the API. `problem` is the parsed body (problem+json or plain JSON). */
+export class ApiError extends Error {
+  constructor(status, problem, headers) {
+    super(problem?.detail || problem?.title || `HTTP ${status}`);
+    this.status = status;
+    this.problem = problem ?? {};
+    this.code = this.problem.code ?? null;
+    this.headers = headers;
+  }
+}
+
+/** The service did not answer (network error, 5xx or 429) after the retry budget. */
+export class UnavailableError extends Error {}
+
+const BILLING_URL = "https://app.syndai.ai/billing";
+export const PORTAL_URL = "https://app.syndai.ai";
+
+/**
+ * A scope `syndai login --scope` may add with one browser approval. Members, keys and
+ * unpublish stay portal-only: the approval page promises a CLI key never manages members or
+ * keys, and those powers stay out of a device-code grant.
+ */
+export function steppable(scope) {
+  return !/:members:|keys|:unpublish$/.test(scope);
+}
+
+// code -> [exit, sentence, next]. Either may be a function of the problem body.
+const KNOWN = {
+  INVALID_TOKEN: [EXIT.AUTH, "Your Syndai key is missing, expired or revoked.", "syndai login"],
+  INVALID_SCOPE: [
+    EXIT.AUTH,
+    ({ required_scope: scope }) =>
+      !scope
+        ? "This key is not allowed to do that."
+        : steppable(scope)
+          ? `This key does not have the ${scope} scope.`
+          : `Only the portal can do this (it needs ${scope}).`,
+    ({ required_scope: scope }) =>
+      !scope ? "syndai login" : steppable(scope) ? `syndai login --scope ${scope}` : PORTAL_URL,
+  ],
+  ROLE_REQUIRED: [EXIT.AUTH, "Only workspace owners and admins can do that.", null],
+  PLAN_UPGRADE_REQUIRED: [EXIT.AUTH, "Your plan does not include that.", BILLING_URL],
+  BUDGET_EXHAUSTED: [EXIT.AUTH, "This workspace is out of credits.", BILLING_URL],
+  QUOTA_EXCEEDED: [EXIT.AUTH, "This workspace is out of credits for now.", BILLING_URL],
+  CUSTOMER_DISABLED: [EXIT.AUTH, "This workspace is disabled. Contact Syndai support.", null],
+  HUMAN_APPROVAL_REQUIRED: [
+    EXIT.NEEDS_YOU,
+    "Only you can approve this, in your browser.",
+    (p) => p.review_url ?? p.extensions?.review_url ?? null,
+  ],
+  PROTECTED_PATHS_MANAGED_ONLY: [
+    EXIT.FAILED,
+    "Protected files work on Syndai-hosted projects only; use the code host's branch rules.",
+    null,
+  ],
+  CLI_UPGRADE_REQUIRED: [EXIT.FAILED, "This version of syndai is too old.", "npx -y syndai@latest"],
+  RUN_CONCURRENCY_LIMIT: [EXIT.FAILED, "Too many changes are running at once.", "syndai status"],
+  REPO_NOT_BOUND: [EXIT.USAGE, "That project is not available to this workspace.", "syndai link"],
+  INSTALLATION_INCOMPLETE: [
+    EXIT.FAILED,
+    "A code-host connection needs finishing in the portal.",
+    "https://app.syndai.ai",
+  ],
+  HITL_REQUEST_SETTLED: [EXIT.FAILED, "That question is already answered or closed.", null],
+  RUN_TERMINATED_BEFORE_RESPONSE: [EXIT.FAILED, "The change ended before your answer arrived.", null],
+  TEXT_EDIT_REFUSED: [
+    EXIT.FAILED,
+    (p) => oneSentence(p.detail || "The text edit was refused."),
+    // Text built from code: the server hands back a ready change instruction.
+    (p) => (p.refusal === "NOT_LITERAL" && p.prompt ? `syndai change ${shellQuote(p.prompt)}` : null),
+  ],
+  RUN_IN_FLIGHT: [
+    EXIT.FAILED,
+    "A change is in flight on this site; edit text once it lands.",
+    (p) => (p.run_id ? `syndai watch ${p.run_id}` : "syndai status"),
+  ],
+  NOT_FOUND: [EXIT.FAILED, "Not found.", "syndai status"],
+  RATE_LIMITED: [EXIT.UNAVAILABLE, "Syndai is rate-limiting this workspace.", null],
+};
+
+/** Map any thrown error to {exitCode, message, next}. */
+export function explain(err) {
+  if (err instanceof CliError) {
+    return { exitCode: err.exitCode, message: err.message, next: err.next };
+  }
+  if (err instanceof UnavailableError) {
+    return {
+      exitCode: EXIT.UNAVAILABLE,
+      message: `Syndai is not answering right now (${err.message}).`,
+      next: "try again in a minute",
+    };
+  }
+  if (err instanceof ApiError) {
+    const known = err.code ? KNOWN[err.code] : null;
+    if (known) {
+      const [exitCode, sentence, next] = known;
+      return {
+        exitCode,
+        message: typeof sentence === "function" ? sentence(err.problem) : sentence,
+        next: typeof next === "function" ? next(err.problem) : next,
+      };
+    }
+    const auth = err.status === 401 || err.status === 402 || err.status === 403;
+    return {
+      exitCode: auth ? EXIT.AUTH : EXIT.FAILED,
+      message: oneSentence(err.problem.detail || err.problem.title || `HTTP ${err.status}`),
+      next: err.status === 401 ? "syndai login" : null,
+    };
+  }
+  return { exitCode: EXIT.FAILED, message: oneSentence(String(err?.message ?? err)), next: null };
+}
+
+function shellQuote(text) {
+  return `'${String(text).replace(/'/g, "'\\''")}'`;
+}
+
+function oneSentence(text) {
+  const line = String(text).split("\n")[0].trim();
+  return /[.!?]$/.test(line) ? line : `${line}.`;
+}

package/src/http.js

@@ -0,0 +1,166 @@
+// The one HTTP client. Raw `fetch`, no SDK: `test/contract.test.js` checks every route
+// against the published OpenAPI instead.
+//
+// Retry rule (docs: syndai.ai/docs/cli, "Retries"): only GETs and POSTs that carry their own
+// idempotency key are retried — callers opt in with `retry: true`. A 429 waits out
+// `Retry-After`; a 5xx, 408, network error or `MISSION_BUSY_RETRY` backs off from 0.5 s
+// towards 8 s with jitter. Five tries, then `UnavailableError` (exit 7).
+
+import { readFileSync } from "node:fs";
+import { ApiError, CliError, EXIT, UnavailableError } from "./errors.js";
+import { route } from "./routes.js";
+
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const USER_AGENT = `syndai-cli/${VERSION}`;
+export const DEFAULT_API_URL = "https://api.syndai.ai";
+
+const TRIES = 5;
+const MAX_WAIT_MS = 8_000;
+const MAX_RETRY_AFTER_MS = 60_000;
+
+export function backoffMs(attempt, random = Math.random) {
+  const base = 500 * 2 ** (attempt - 1);
+  return Math.min(MAX_WAIT_MS, Math.round(base * (1 + random() / 2)));
+}
+
+/** `Retry-After` as milliseconds (delta-seconds or an HTTP date), or null. */
+export function retryAfterMs(value, now = Date.now()) {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const at = Date.parse(value);
+  return Number.isNaN(at) ? null : Math.max(0, at - now);
+}
+
+export function interrupted() {
+  return new CliError(EXIT.INTERRUPTED, "Interrupted.");
+}
+
+/**
+ * `onMissingScope(scope)` is asked once per request when a 403 names the scope it needs
+ * (`required_scope`); when it answers true (a new key was approved), the request is sent
+ * again with the new key.
+ *
+ * @param {{baseUrl: string, getKey: () => Promise<string>, io: object, onMissingScope?: (scope: string) => Promise<boolean>}} options
+ */
+export function createClient({ baseUrl, getKey, io, onMissingScope }) {
+  /** Call a named route from `routes.js`. */
+  function call(name, { params, ...opts } = {}) {
+    const [method, path] = route(name, params);
+    return send(method, path, opts);
+  }
+
+  async function send(
+    method,
+    path,
+    { query, body, retry = method === "GET", auth = true, timeoutMs = 30_000, raw = false, signal } = {},
+  ) {
+    const url = new URL(baseUrl + path);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (Array.isArray(value)) for (const item of value) url.searchParams.append(key, String(item));
+      else if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const headers = { "user-agent": USER_AGENT, accept: "application/json" };
+    if (body !== undefined) headers["content-type"] = "application/json";
+    if (auth) headers.authorization = `Bearer ${await getKey()}`;
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+
+    let steppedUp = false;
+    for (let attempt = 1; ; attempt++) {
+      let res;
+      let parsed;
+      try {
+        res = await fetch(url, {
+          method,
+          headers,
+          body: payload,
+          signal: AbortSignal.any([io.signal, AbortSignal.timeout(timeoutMs), signal].filter(Boolean)),
+        });
+        parsed = await readBody(res);
+      } catch (err) {
+        if (io.signal.aborted) throw interrupted();
+        if (signal?.aborted) throw signal.reason;
+        if (!retry || attempt >= TRIES) throw new UnavailableError(networkReason(err));
+        await pause(backoffMs(attempt), signal);
+        continue;
+      }
+
+      const problem = res.ok ? null : new ApiError(res.status, parsed, res.headers);
+      const scope = problem?.code === "INVALID_SCOPE" ? problem.problem.required_scope : null;
+      if (scope && auth && onMissingScope && !steppedUp) {
+        steppedUp = true;
+        if (await onMissingScope(scope)) {
+          headers.authorization = `Bearer ${await getKey()}`;
+          attempt = 0;
+          continue;
+        }
+      }
+      const transient =
+        problem !== null &&
+        (res.status >= 500 ||
+          res.status === 408 ||
+          (res.status === 429 && (!problem.code || problem.code === "RATE_LIMITED")) ||
+          problem.code === "MISSION_BUSY_RETRY");
+      if (!transient) {
+        if (raw) return { status: res.status, body: parsed, headers: res.headers };
+        if (problem) throw problem;
+        return parsed;
+      }
+      if (!retry || attempt >= TRIES) {
+        throw new UnavailableError(`HTTP ${res.status}${problem.code ? ` ${problem.code}` : ""}`);
+      }
+      const hinted = res.status === 429 ? retryAfterMs(res.headers.get("retry-after")) : null;
+      const wait = hinted ?? backoffMs(attempt);
+      if (wait > MAX_RETRY_AFTER_MS) {
+        throw new UnavailableError(`rate-limited for ${Math.ceil(wait / 1000)} s`);
+      }
+      await pause(wait, signal);
+    }
+  }
+
+  /** Open a streaming GET (SSE). Returns the Response; non-2xx throws ApiError. */
+  async function stream(name, { params, query, headers = {}, signal } = {}) {
+    const [, path] = route(name, params);
+    const url = new URL(baseUrl + path);
+    for (const [key, value] of Object.entries(query ?? {})) url.searchParams.set(key, value);
+    const res = await fetch(url, {
+      headers: {
+        "user-agent": USER_AGENT,
+        accept: "text/event-stream",
+        authorization: `Bearer ${await getKey()}`,
+        ...headers,
+      },
+      signal: AbortSignal.any([io.signal, signal].filter(Boolean)),
+    });
+    if (!res.ok) throw new ApiError(res.status, await readBody(res), res.headers);
+    return res;
+  }
+
+  async function pause(ms, signal) {
+    try {
+      await io.sleep(ms, AbortSignal.any([io.signal, signal].filter(Boolean)));
+    } catch (err) {
+      if (io.signal.aborted) throw interrupted();
+      if (signal?.aborted) throw signal.reason;
+      throw err;
+    }
+  }
+
+  return { call, send, stream, baseUrl };
+}
+
+async function readBody(res) {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { detail: text.slice(0, 500) };
+  }
+}
+
+function networkReason(err) {
+  if (err?.name === "TimeoutError") return "timed out";
+  const code = err?.cause?.code ?? err?.code;
+  return code ? String(code) : String(err?.cause?.message ?? err?.message ?? "network error");
+}

package/src/main.js

@@ -0,0 +1,249 @@
+// Command table, argument parsing and the one error report. `main(argv, io)` takes all
+// process I/O as `io`, so tests drive it in-process with a fake server and fake clocks.
+
+import { setTimeout as sleep } from "node:timers/promises";
+import { parseArgs } from "node:util";
+import { createContext, login, logout, whoami } from "./auth.js";
+import { answer, cancel, change, editText, goLive, newProject, review, revert, status, watch } from "./changes.js";
+import { CliError, EXIT, explain } from "./errors.js";
+import { VERSION } from "./http.js";
+import { mcp } from "./mcp.js";
+import { link } from "./projects.js";
+import { api } from "./api.js";
+import { repeat, schedule } from "./schedules.js";
+import { settings } from "./settings.js";
+import { closeInput, openBrowser, page } from "./ui.js";
+
+const str = { type: "string" };
+const bool = { type: "boolean" };
+const COMMON = { json: bool, "no-input": bool, help: { type: "boolean", short: "h" } };
+
+const COMMANDS = {
+  change: {
+    usage: 'change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]',
+    summary: "Make a change; it goes live when its checks pass (--review: open a PR instead).",
+    options: {
+      app: str,
+      review: bool,
+      image: { type: "string", multiple: true },
+      "no-wait": bool,
+      timeout: str,
+    },
+    run: (ctx, args) => change(ctx, args),
+    stepUp: false,
+  },
+  new: {
+    usage: 'new "<what>" [--no-learn] [--no-wait] [--timeout D]',
+    summary: "Start a new project; a product URL in the text builds your own version of it.",
+    options: { "no-learn": bool, "no-wait": bool, timeout: str },
+    run: (ctx, args) => newProject(ctx, args),
+    stepUp: false,
+  },
+  watch: {
+    usage: "watch <run> [--timeout D] [--logs]",
+    summary: "Follow a change to its outcome (Ctrl-C detaches; the change keeps going).",
+    options: { timeout: str, logs: bool },
+    run: (ctx, [run]) => watch(ctx, run),
+    stepUp: false,
+  },
+  answer: {
+    usage: "answer <run> [--input FILE|-]",
+    summary: 'Answer a change\'s open question (--input: {"entries":[...]} from a file or stdin).',
+    options: { input: str },
+    run: (ctx, [run]) => answer(ctx, run),
+  },
+  review: {
+    usage: "review <run> [--retry | --close]",
+    summary: "See why a change is held, then approve it in your browser.",
+    options: { retry: bool, close: bool },
+    run: (ctx, [run]) => review(ctx, run),
+  },
+  "go-live": {
+    usage: "go-live <run> [--timeout D]",
+    summary: "Put a ready change live.",
+    options: { timeout: str },
+    run: (ctx, [run]) => goLive(ctx, run),
+    stepUp: false,
+  },
+  revert: {
+    usage: "revert <run> [--force] [--timeout D]",
+    summary: "Undo a change that went live.",
+    options: { force: bool, timeout: str },
+    run: (ctx, [run]) => revert(ctx, run),
+    stepUp: false,
+  },
+  cancel: {
+    usage: "cancel <run>",
+    summary: "Stop a change.",
+    options: {},
+    run: (ctx, [run]) => cancel(ctx, run),
+  },
+  status: {
+    usage: "status [--app A]",
+    summary: "What is running, and everything that needs you.",
+    options: { app: str },
+    run: (ctx) => status(ctx),
+  },
+  "edit-text": {
+    usage: 'edit-text [--app A] [--page /] --from "Old" --to "New" [--all] | --undo <sha>',
+    summary: "Swap exact text on a live site in seconds, free and undoable (--all: every match in its file).",
+    options: { app: str, page: str, from: str, to: str, all: bool, undo: str },
+    run: (ctx) => editText(ctx),
+  },
+  login: {
+    usage: "login [--with-token] [--scope S]...",
+    summary:
+      "Log in by approving this computer in your browser (--scope adds access to the key's; --with-token reads a key from stdin).",
+    options: { "with-token": bool, scope: { type: "string", multiple: true } },
+    run: (ctx) => login(ctx),
+  },
+  logout: {
+    usage: "logout",
+    summary: "Revoke and forget the stored key.",
+    options: {},
+    run: (ctx) => logout(ctx),
+  },
+  whoami: {
+    usage: "whoami",
+    summary: "Show the workspace and key in use.",
+    options: {},
+    run: (ctx) => whoami(ctx),
+  },
+  link: {
+    usage: "link [project]",
+    summary: "Remember which project this directory changes (stored outside the repo).",
+    options: { app: str },
+    run: (ctx, [ref]) => link(ctx, ref),
+  },
+  settings: {
+    usage: "settings [--app A] [get | set key=value...]",
+    summary: "autonomy, feature_requests, bug_scan, protected_paths (a key can only tighten them).",
+    options: { app: str },
+    run: (ctx, args) => settings(ctx, args),
+  },
+  mcp: {
+    usage: "mcp install claude|cursor|codex",
+    summary: "Add Syndai to an AI coding tool, with its own key.",
+    options: {},
+    run: (ctx, args) => mcp(ctx, args),
+  },
+  schedule: {
+    usage:
+      'schedule list [--app A | --all] | show <id> | add "<what>" --every E [--at T] [--tz Z] [--budget USD] [--app A]\n' +
+      "               | edit <id> [--prompt P] [--every E] [--at T] [--tz Z] [--budget USD|none]\n" +
+      "               | pause | resume | run-now | delete <id> [--yes]",
+    summary:
+      'A project\'s recurring runs. E: hourly (--at :MM), daily or weekdays (--at HH:MM), weekly (--at "mon HH:MM"), or a 5-field cron.',
+    options: { app: str, all: bool, every: str, at: str, tz: str, budget: str, prompt: str, yes: bool },
+    run: (ctx, args) => schedule(ctx, args),
+  },
+  repeat: {
+    usage: "repeat <run> --every E [--at T] [--tz Z] [--budget USD]",
+    summary: "Run a change you liked again on a schedule (its first run is the next scheduled time).",
+    options: { every: str, at: str, tz: str, budget: str },
+    run: (ctx, args) => repeat(ctx, args),
+  },
+  api: {
+    usage: "api [<operationId> | <METHOD> <path>] [-f k=v]... [-F k=v]... [--input FILE|-] [--paginate] [--app A]",
+    summary: "Call any Syndai API operation with your key (no arguments: list them; <operationId> --help: its fields).",
+    options: {
+      "raw-field": { type: "string", short: "f", multiple: true },
+      field: { type: "string", short: "F", multiple: true },
+      input: str,
+      paginate: bool,
+      app: str,
+    },
+    ownHelp: true,
+    run: (ctx, args) => api(ctx, args),
+  },
+};
+
+export function helpText() {
+  const rows = Object.values(COMMANDS).map((c) => `  syndai ${c.usage}\n      ${c.summary}`);
+  return [
+    `syndai ${VERSION}: tell Syndai what to change; it builds it, checks it and puts it live.`,
+    "",
+    ...rows,
+    "",
+    "Every command: --json (machine output; also when stdout is not a terminal),",
+    "--no-input (never prompt), -h/--help.",
+    "Environment: SYNDAI_API_KEY (wins over `syndai login`), SYNDAI_APP, SYNDAI_API_URL, NO_COLOR.",
+    "Exit codes: 0 done, 1 failed, 2 usage or no project, 3 needs you, 4 live but unverified,",
+    "5 auth/scope/plan, 6 --timeout reached, 7 service unavailable, 130 interrupted.",
+    "",
+  ].join("\n");
+}
+
+/** The real process as `io` (the bin passes the SIGINT AbortSignal). */
+export function processIo(signal) {
+  return {
+    env: process.env,
+    cwd: process.cwd(),
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    signal,
+    now: () => Date.now(),
+    sleep: (ms, abortSignal) => sleep(ms, undefined, { signal: abortSignal }),
+    openUrl: openBrowser,
+    page: (text) => page(process, text),
+  };
+}
+
+export async function main(argv, io) {
+  const [command, ...rest] = argv;
+  if (!command || ["help", "--help", "-h"].includes(command)) {
+    io.stdout.write(helpText());
+    return EXIT.OK;
+  }
+  if (["--version", "-v", "version"].includes(command)) {
+    io.stdout.write(`${VERSION}\n`);
+    return EXIT.OK;
+  }
+  const spec = COMMANDS[command];
+  if (!spec) {
+    io.stderr.write(`error: unknown command "${command}"\n\n${helpText()}`);
+    return EXIT.USAGE;
+  }
+  let parsed;
+  try {
+    parsed = parseArgs({ args: rest, options: { ...COMMON, ...spec.options }, allowPositionals: true });
+  } catch (err) {
+    io.stderr.write(`error: ${err.message}\n  usage: syndai ${spec.usage}\n`);
+    return EXIT.USAGE;
+  }
+  if (parsed.values.help && !spec.ownHelp) {
+    io.stdout.write(`usage: syndai ${spec.usage}\n${spec.summary}\n`);
+    return EXIT.OK;
+  }
+  const ctx = createContext(io, parsed.values, { stepUp: spec.stepUp !== false });
+  try {
+    return await spec.run(ctx, parsed.positionals);
+  } catch (err) {
+    return report(ctx, err);
+  } finally {
+    closeInput(io);
+  }
+}
+
+/** One error line (plus the next command) on stderr; a JSON error on stdout for machines. */
+function report(ctx, err) {
+  const { ui, io } = ctx;
+  const { exitCode, message, next } = explain(err);
+  if (io.env.SYNDAI_DEBUG && err?.stack) io.stderr.write(`${err.stack}\n`);
+  const extra = err instanceof CliError ? err.result : null;
+  if (exitCode === EXIT.INTERRUPTED) {
+    ui.progress(message);
+  } else {
+    ui.progress(`${ui.red("error:")} ${message}`);
+    if (extra?.human) ui.progress(extra.human);
+    if (ui.json) {
+      const code = err?.code ?? null;
+      io.stdout.write(
+        `${JSON.stringify({ error: { exit_code: exitCode, code, message, next }, ...(extra?.data ?? {}) })}\n`,
+      );
+    }
+  }
+  if (next) ui.progress(`  next: ${next}`);
+  return exitCode;
+}

package/src/mcp.js

@@ -0,0 +1,93 @@
+// `syndai mcp install claude|cursor|codex`: the same browser approval as `syndai login`,
+// but it mints a SEPARATE key per client (audit rows say which door acted; one door can be
+// revoked alone) and writes it into that client's USER-scope config only. Never a project
+// file such as `.mcp.json`: a repo is shared, and `.syndai/**`-style paths are protected.
+//
+// Config locations (checked against each client's docs, 2026-10):
+//   Claude Code  $CLAUDE_CONFIG_DIR/.claude.json or ~/.claude.json, top-level "mcpServers"
+//   Cursor       ~/.cursor/mcp.json, "mcpServers"
+//   Codex        $CODEX_HOME/config.toml or ~/.codex/config.toml, [mcp_servers.<name>]
+
+import fs from "node:fs";
+import path from "node:path";
+import { deviceApproval } from "./auth.js";
+import { CliError, EXIT } from "./errors.js";
+import { MCP_PATH } from "./routes.js";
+import { readJson, writeFileAtomic, writeJson } from "./store.js";
+
+const SERVER_NAME = "syndai";
+
+export const CLIENTS = {
+  claude: {
+    label: "Claude Code",
+    file: (env, home) => path.join(env.CLAUDE_CONFIG_DIR || home, ".claude.json"),
+    write: (file, url, key) =>
+      upsertJsonServer(file, { type: "http", url, headers: { Authorization: `Bearer ${key}` } }),
+  },
+  cursor: {
+    label: "Cursor",
+    file: (_env, home) => path.join(home, ".cursor", "mcp.json"),
+    write: (file, url, key) => upsertJsonServer(file, { url, headers: { Authorization: `Bearer ${key}` } }),
+  },
+  codex: {
+    label: "Codex",
+    file: (env, home) => path.join(env.CODEX_HOME || path.join(home, ".codex"), "config.toml"),
+    write: (file, url, key) => upsertTomlServer(file, url, key),
+  },
+};
+
+export async function mcp(ctx, [action, clientName]) {
+  const target = CLIENTS[clientName];
+  if (action !== "install" || !target) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai mcp install claude|cursor|codex");
+  }
+  const token = await deviceApproval(ctx, `MCP · ${target.label}`);
+  const file = target.file(ctx.io.env, ctx.paths.home);
+  target.write(file, ctx.baseUrl + MCP_PATH, token.api_key);
+  ctx.ui.result(
+    {
+      client: clientName,
+      config_file: file,
+      customer_id: token.customer_id,
+      key_id: token.key_id,
+      expires_at: token.expires_at,
+    },
+    `Syndai is set up in ${target.label} (${file}). Restart ${target.label} to load it.`,
+  );
+  return EXIT.OK;
+}
+
+/** Set `mcpServers.syndai` in a JSON config, keeping everything else. 0600: it holds a key. */
+export function upsertJsonServer(file, entry) {
+  const data = readJson(file, {});
+  data.mcpServers = { ...(data.mcpServers ?? {}), [SERVER_NAME]: entry };
+  writeJson(file, data, 0o600);
+}
+
+/** Replace (or append) the `[mcp_servers.syndai]` table in a TOML config. */
+export function upsertTomlServer(file, url, key) {
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const kept = [];
+  let inOurs = false;
+  for (const line of text.split("\n")) {
+    const header = /^\s*\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(line);
+    if (header) {
+      const name = header[1].replace(/"/g, "");
+      inOurs = name === `mcp_servers.${SERVER_NAME}` || name.startsWith(`mcp_servers.${SERVER_NAME}.`);
+    }
+    if (!inOurs) kept.push(line);
+  }
+  const rest = kept.join("\n").replace(/\s+$/, "");
+  // JSON string escaping is valid TOML basic-string escaping for these ASCII values.
+  const table = [
+    `[mcp_servers.${SERVER_NAME}]`,
+    `url = ${JSON.stringify(url)}`,
+    `http_headers = { Authorization = ${JSON.stringify(`Bearer ${key}`)} }`,
+  ].join("\n");
+  writeFileAtomic(file, `${rest ? `${rest}\n\n` : ""}${table}\n`, 0o600);
+}