npm - @myspec/mcp-server - Versions diffs - 0.1.0-next.1 - Mend

@myspec/mcp-server 0.1.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/dist/index.js ADDED Viewed

@@ -0,0 +1,3604 @@
+#!/usr/bin/env node
+// src/index.ts
+import { readFileSync, realpathSync } from "fs";
+import { pathToFileURL } from "url";
+// src/auth/oauth-loopback.ts
+import http from "http";
+import { randomBytes } from "crypto";
+import readline from "readline";
+// src/errors.ts
+var NeedsLoginError = class extends Error {
+  constructor(message = "Not authenticated. Run `npx @myspec/mcp-server login` to sign in.") {
+    super(message);
+    this.name = "NeedsLoginError";
+  }
+};
+var HttpStatusError = class extends Error {
+  status;
+  body;
+  constructor(status, body, message) {
+    const safeBody = redactSensitive(body);
+    super(message ?? `HTTP ${String(status)}: ${safeBody.slice(0, 200)}`);
+    this.name = "HttpStatusError";
+    this.status = status;
+    this.body = safeBody;
+  }
+};
+var BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._\-+/=]+/g;
+var REFRESH_TOKEN_PATTERN = /"refreshToken"\s*:\s*"[^"]+"/g;
+var ACCESS_TOKEN_PATTERN = /"accessToken"\s*:\s*"[^"]+"/g;
+var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token)"\s*:\s*"[^"]+"/g;
+var JWT_PATTERN = /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
+function redactSensitive(value) {
+  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
+}
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+// src/auth/oauth-loopback.ts
+var DEFAULT_TIMEOUT_MS = 5 * 6e4;
+var SUCCESS_HTML = "<!doctype html><html><body><h1>Sign-in complete</h1><p>You may close this tab and return to your terminal.</p></body></html>";
+var ERROR_HTML = "<!doctype html><html><body><h1>Sign-in failed</h1><p>Return to your terminal for details.</p></body></html>";
+async function loopbackLogin(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? Date.now;
+  const callbackPath = opts.callbackPath ?? "/cb";
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const logger = opts.logger ?? ((m) => {
+    process.stderr.write(m + "\n");
+  });
+  const state = randomBytes(32).toString("base64url");
+  const { code } = await waitForOAuthCallback({
+    callbackPath,
+    timeoutMs,
+    expectedState: state,
+    pasteInput: opts.disablePasteFallback ? void 0 : opts.pasteInput ?? process.stdin,
+    logger,
+    onListen: (boundPort) => {
+      const callbackBase = `http://127.0.0.1:${String(boundPort)}${callbackPath}`;
+      const loopbackTarget = `${callbackBase}?mode=cli&state=${state}`;
+      const webappLogin = new URL(`${opts.webappUrl.replace(/\/$/, "")}/auth/cli`);
+      webappLogin.searchParams.set("target", loopbackTarget);
+      const signInUrl = webappLogin.toString();
+      logger(`Open this URL in your browser to sign in:
+  ${signInUrl}`);
+      if (!opts.disablePasteFallback) {
+        logger(
+          "If the browser cannot reach this CLI directly, paste the code shown on the\n/auth/cli page here and press Enter."
+        );
+      }
+      if (opts.openBrowser) {
+        opts.openBrowser(signInUrl).catch((err) => {
+          const message = err instanceof Error ? err.message : String(err);
+          logger(`Failed to open browser automatically: ${message}`);
+        });
+      }
+    }
+  });
+  logger("Captured authorization code. Exchanging for tokens...");
+  const exchanged = await exchangeCode(opts.userAuthUrl, code, fetchImpl);
+  return {
+    accessToken: exchanged.accessToken,
+    refreshToken: exchanged.refreshToken,
+    expiresAt: now() + exchanged.expiresIn * 1e3,
+    userAuthUrl: opts.userAuthUrl,
+    platformUrl: opts.platformUrl,
+    user: exchanged.user
+  };
+}
+function applyCorsHeaders(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+}
+async function waitForOAuthCallback(opts) {
+  return new Promise((resolve2, reject) => {
+    const settledFlag = { value: false };
+    const timeoutRef = { handle: void 0 };
+    const rlRef = { handle: void 0 };
+    const settle = (fn) => {
+      if (settledFlag.value) {
+        return;
+      }
+      settledFlag.value = true;
+      if (timeoutRef.handle) {
+        clearTimeout(timeoutRef.handle);
+      }
+      if (rlRef.handle) {
+        rlRef.handle.close();
+      }
+      server.close();
+      fn();
+    };
+    const server = http.createServer((req, res) => {
+      applyCorsHeaders(res);
+      if (req.method === "OPTIONS") {
+        res.statusCode = 204;
+        res.end();
+        return;
+      }
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== opts.callbackPath) {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return;
+      }
+      const error = url.searchParams.get("error");
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!state || !timingSafeEqualStrings(state, opts.expectedState)) {
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "text/html");
+        res.end(ERROR_HTML);
+        settle(() => {
+          reject(new Error("OAuth callback state mismatch (possible CSRF or stale request)"));
+        });
+        return;
+      }
+      if (error || !code) {
+        res.statusCode = 400;
+        res.setHeader("Content-Type", "text/html");
+        res.end(ERROR_HTML);
+        settle(() => {
+          reject(
+            new Error(error ? `OAuth callback returned error=${error}` : "OAuth callback missing code")
+          );
+        });
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/html");
+      res.end(SUCCESS_HTML);
+      settle(() => {
+        resolve2({ code });
+      });
+    });
+    server.on("error", (err) => {
+      settle(() => {
+        reject(err);
+      });
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const port = server.address().port;
+      Promise.resolve(opts.onListen(port)).catch((err) => {
+        settle(() => {
+          reject(err instanceof Error ? err : new Error(String(err)));
+        });
+      });
+    });
+    timeoutRef.handle = setTimeout(() => {
+      settle(() => {
+        reject(new Error(`Timed out waiting for OAuth callback after ${String(opts.timeoutMs)}ms`));
+      });
+    }, opts.timeoutMs);
+    timeoutRef.handle.unref();
+    if (opts.pasteInput) {
+      const rl = readline.createInterface({ input: opts.pasteInput });
+      rlRef.handle = rl;
+      rl.on("line", (raw) => {
+        const trimmed = raw.trim();
+        if (!trimmed) {
+          return;
+        }
+        const dot = trimmed.lastIndexOf(".");
+        if (dot < 1 || dot === trimmed.length - 1) {
+          opts.logger(
+            "Pasted token is missing a state suffix; expected `<code>.<state>`. Re-copy the value shown on the /auth/cli page."
+          );
+          return;
+        }
+        const code = trimmed.slice(0, dot);
+        const state = trimmed.slice(dot + 1);
+        if (!timingSafeEqualStrings(state, opts.expectedState)) {
+          opts.logger(
+            "Pasted token state does not match this CLI session. Refusing to exchange the code."
+          );
+          return;
+        }
+        settle(() => {
+          opts.logger("Captured pasted token; finishing sign-in...");
+          resolve2({ code });
+        });
+      });
+    }
+  });
+}
+function timingSafeEqualStrings(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+async function exchangeCode(userAuthUrl, code, fetchImpl) {
+  const response = await fetchImpl(`${userAuthUrl}/api/auth/oauth/exchange`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code })
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new HttpStatusError(response.status, body, `OAuth code exchange failed: HTTP ${String(response.status)}`);
+  }
+  return await response.json();
+}
+// src/auth/oauth-paste.ts
+import readline2 from "readline/promises";
+async function pasteLogin(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const now = opts.now ?? Date.now;
+  const logger = opts.logger ?? ((m) => {
+    process.stderr.write(m + "\n");
+  });
+  const signInUrl = `${opts.webappUrl.replace(/\/$/, "")}/auth/cli`;
+  logger("Open this URL in your browser, sign in, and copy the one-time code shown:");
+  logger(`  ${signInUrl}`);
+  const ask = opts.prompt ?? defaultPrompt;
+  const raw = await ask("Paste the one-time code: ");
+  const code = raw.trim();
+  if (!code) {
+    throw new Error("No code provided.");
+  }
+  const response = await fetchImpl(`${opts.userAuthUrl}/api/auth/oauth/exchange`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code })
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new HttpStatusError(response.status, body, `OAuth code exchange failed: HTTP ${String(response.status)}`);
+  }
+  const exchanged = await response.json();
+  return {
+    accessToken: exchanged.accessToken,
+    refreshToken: exchanged.refreshToken,
+    expiresAt: now() + exchanged.expiresIn * 1e3,
+    userAuthUrl: opts.userAuthUrl,
+    platformUrl: opts.platformUrl,
+    user: exchanged.user
+  };
+}
+async function defaultPrompt(question) {
+  const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+// src/auth/credentials-store.ts
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+function defaultCredentialsPath(env = process.env) {
+  if (process.platform === "win32") {
+    const appData = env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(appData, "myspec", "mcp-server.json");
+  }
+  const xdg = env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+  return path.join(xdg, "myspec", "mcp-server.json");
+}
+function createFileCredentialsStore(filePath) {
+  const target = filePath ?? defaultCredentialsPath();
+  return {
+    path: () => target,
+    async load() {
+      try {
+        if (process.platform !== "win32") {
+          const stat = await fs.stat(target);
+          if ((stat.mode & 63) !== 0) {
+            throw new Error(
+              `Refusing to load credentials from ${target}: file mode is too permissive (${(stat.mode & 511).toString(8)}). Run \`chmod 600 ${target}\` and retry.`
+            );
+          }
+        }
+        const raw = await fs.readFile(target, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parseCredentials(parsed);
+      } catch (err) {
+        if (isFsNotFound(err)) {
+          return null;
+        }
+        throw err;
+      }
+    },
+    async save(creds) {
+      const dir = path.dirname(target);
+      await fs.mkdir(dir, { recursive: true, mode: 448 });
+      await fs.writeFile(target, JSON.stringify(creds, null, 2), { mode: 384 });
+      if (process.platform !== "win32") {
+        await fs.chmod(target, 384);
+      }
+    },
+    async clear() {
+      try {
+        await fs.unlink(target);
+      } catch (err) {
+        if (!isFsNotFound(err)) {
+          throw err;
+        }
+      }
+    }
+  };
+}
+var DEFAULT_USER_AUTH_URL = "https://auth.myspec.dev";
+function readEnvRefreshConfig(env = process.env) {
+  if (env.MYSPEC_ACCESS_TOKEN || env.MYSPEC_ACCESS_TOKEN_EXPIRES_AT) {
+    throw new ConfigError(
+      "MYSPEC_ACCESS_TOKEN / MYSPEC_ACCESS_TOKEN_EXPIRES_AT are not supported. The MCP server mints a fresh access token via MYSPEC_REFRESH_TOKEN; unset MYSPEC_ACCESS_TOKEN (and MYSPEC_ACCESS_TOKEN_EXPIRES_AT if set) and provide only MYSPEC_REFRESH_TOKEN."
+    );
+  }
+  if (!env.MYSPEC_REFRESH_TOKEN) {
+    return null;
+  }
+  return {
+    refreshToken: env.MYSPEC_REFRESH_TOKEN,
+    userAuthUrl: env.MYSPEC_USER_AUTH_URL ?? DEFAULT_USER_AUTH_URL
+  };
+}
+function createCompositeCredentialsStore(opts) {
+  const { fileStore, envConfig } = opts;
+  const envRefreshToken = envConfig?.refreshToken;
+  const envUserAuthUrl = envConfig?.userAuthUrl ?? DEFAULT_USER_AUTH_URL;
+  return {
+    path: () => fileStore.path(),
+    async load() {
+      const fromFile = await fileStore.load();
+      if (fromFile) {
+        return fromFile;
+      }
+      if (!envRefreshToken) {
+        return null;
+      }
+      return {
+        accessToken: "",
+        refreshToken: envRefreshToken,
+        expiresAt: 0,
+        userAuthUrl: envUserAuthUrl,
+        user: { id: "env", email: "env@mcp" }
+      };
+    },
+    save(creds) {
+      return fileStore.save(creds);
+    },
+    clear() {
+      return fileStore.clear();
+    },
+    envRefreshToken: () => envRefreshToken,
+    envUserAuthUrl: () => envUserAuthUrl
+  };
+}
+function parseCredentials(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error("Credentials file is malformed (not an object)");
+  }
+  const v = value;
+  const accessToken = requireString(v, "accessToken");
+  const refreshToken = requireString(v, "refreshToken");
+  const expiresAt = requireNumber(v, "expiresAt");
+  const userAuthUrl = requireString(v, "userAuthUrl");
+  const platformUrl = typeof v.platformUrl === "string" ? v.platformUrl : void 0;
+  const userRaw = v.user;
+  if (typeof userRaw !== "object" || userRaw === null) {
+    throw new Error("Credentials file is malformed (missing user)");
+  }
+  const userObj = userRaw;
+  const user = {
+    id: requireString(userObj, "id"),
+    email: requireString(userObj, "email"),
+    name: typeof userObj.name === "string" ? userObj.name : void 0
+  };
+  return { accessToken, refreshToken, expiresAt, userAuthUrl, platformUrl, user };
+}
+function requireString(obj, key) {
+  const value = obj[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Credentials file is malformed (missing ${key})`);
+  }
+  return value;
+}
+function requireNumber(obj, key) {
+  const value = obj[key];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`Credentials file is malformed (invalid ${key})`);
+  }
+  return value;
+}
+function isFsNotFound(err) {
+  return typeof err === "object" && err !== null && err.code === "ENOENT";
+}
+// src/config.ts
+function resolveConfig(sources = {}) {
+  const env = sources.env ?? process.env;
+  const userAuthUrl = sources.cliUserAuthUrl ?? env.MYSPEC_USER_AUTH_URL ?? sources.storedUserAuthUrl ?? "https://auth.myspec.dev";
+  const platformUrl = sources.cliPlatformUrl ?? env.MYSPEC_PLATFORM_URL ?? sources.storedPlatformUrl ?? "https://api.myspec.dev";
+  const webappUrl = sources.cliWebappUrl ?? env.MYSPEC_WEBAPP_URL ?? deriveWebappFromAuth(userAuthUrl);
+  validateUrl(userAuthUrl, "user-auth URL");
+  validateUrl(platformUrl, "platform URL");
+  validateUrl(webappUrl, "webapp URL");
+  return {
+    userAuthUrl: stripTrailingSlash(userAuthUrl),
+    platformUrl: stripTrailingSlash(platformUrl),
+    webappUrl: stripTrailingSlash(webappUrl)
+  };
+}
+function deriveWebappFromAuth(userAuthUrl) {
+  try {
+    const parsed = new URL(userAuthUrl);
+    if (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") {
+      return `${parsed.protocol}//${parsed.hostname}:5173`;
+    }
+    parsed.hostname = parsed.hostname.replace(/^auth\./, "app.").replace(/^dev-auth\./, "dev-app.").replace(/^staging-auth\./, "staging-app.");
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return "https://app.myspec.dev";
+  }
+}
+function validateUrl(value, label) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new ConfigError(`${label} is not a valid URL: ${value}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new ConfigError(`${label} must use http or https: ${value}`);
+  }
+  if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
+    throw new ConfigError(
+      `${label} must use https:// for non-loopback hosts (got http://${parsed.hostname})`
+    );
+  }
+}
+function isLoopbackHost(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "[::1]";
+}
+function stripTrailingSlash(value) {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+// src/cli/login.ts
+async function runLogin(options) {
+  const config = resolveConfig({
+    cliUserAuthUrl: options.userAuthUrl,
+    cliPlatformUrl: options.platformUrl,
+    cliWebappUrl: options.webappUrl
+  });
+  const store = createFileCredentialsStore();
+  const credentials = options.paste ? await pasteLogin({
+    userAuthUrl: config.userAuthUrl,
+    platformUrl: config.platformUrl,
+    webappUrl: config.webappUrl
+  }) : await loopbackLogin({
+    userAuthUrl: config.userAuthUrl,
+    platformUrl: config.platformUrl,
+    webappUrl: config.webappUrl,
+    openBrowser: async (url) => {
+      const mod = await import("open");
+      await mod.default(url);
+    }
+  });
+  await store.save(credentials);
+  process.stderr.write(`Signed in as ${credentials.user.email}.
+`);
+  process.stderr.write(`Credentials saved to ${store.path()}
+`);
+}
+// src/cli/logout.ts
+async function runLogout() {
+  const store = createFileCredentialsStore();
+  const existing = await store.load();
+  if (!existing) {
+    process.stderr.write("No credentials to clear.\n");
+    return;
+  }
+  const config = resolveConfig({ storedUserAuthUrl: existing.userAuthUrl });
+  try {
+    await fetch(`${config.userAuthUrl}/api/auth/logout`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${existing.accessToken}`
+      },
+      body: JSON.stringify({ refreshToken: existing.refreshToken }),
+      signal: AbortSignal.timeout(5e3)
+    });
+  } catch {
+  }
+  await store.clear();
+  process.stderr.write("Signed out and cleared local credentials.\n");
+}
+// src/auth/token-manager.ts
+var EXPIRY_SKEW_MS = 3e4;
+var TokenManager = class {
+  store;
+  fetchImpl;
+  now;
+  envFallback;
+  cached = null;
+  refreshInFlight = null;
+  constructor(deps) {
+    this.store = deps.store;
+    this.fetchImpl = deps.fetchImpl ?? fetch;
+    this.now = deps.now ?? Date.now;
+    this.envFallback = deps.envFallback ?? null;
+  }
+  async getValidAccessToken() {
+    const creds = await this.ensureLoaded();
+    if (creds.expiresAt > this.now() + EXPIRY_SKEW_MS) {
+      return creds.accessToken;
+    }
+    const refreshed = await this.refresh(creds);
+    return refreshed.accessToken;
+  }
+  async getCredentials() {
+    return this.ensureLoaded();
+  }
+  async forceRefresh() {
+    const creds = await this.ensureLoaded();
+    const refreshed = await this.refresh(creds);
+    return refreshed.accessToken;
+  }
+  async clear() {
+    this.cached = null;
+    await this.store.clear();
+  }
+  async ensureLoaded() {
+    if (this.cached) {
+      return this.cached;
+    }
+    const loaded = await this.store.load();
+    if (!loaded) {
+      throw new NeedsLoginError();
+    }
+    this.cached = loaded;
+    return loaded;
+  }
+  async refresh(creds) {
+    if (this.refreshInFlight) {
+      return this.refreshInFlight;
+    }
+    this.refreshInFlight = this.doRefresh(creds).finally(() => {
+      this.refreshInFlight = null;
+    });
+    return this.refreshInFlight;
+  }
+  async doRefresh(creds) {
+    try {
+      return await this.performRefresh(creds);
+    } catch (err) {
+      if (err instanceof RefreshRejectedError && this.envFallback && this.envFallback.refreshToken !== creds.refreshToken) {
+        const bootstrap = {
+          accessToken: "",
+          refreshToken: this.envFallback.refreshToken,
+          expiresAt: 0,
+          userAuthUrl: this.envFallback.userAuthUrl,
+          platformUrl: creds.platformUrl,
+          user: creds.user
+        };
+        try {
+          return await this.performRefresh(bootstrap);
+        } catch (retryErr) {
+          await this.invalidateOnAuthFailure(retryErr);
+          throw retryErr;
+        }
+      }
+      await this.invalidateOnAuthFailure(err);
+      throw err;
+    }
+  }
+  async invalidateOnAuthFailure(err) {
+    if (err instanceof NeedsLoginError) {
+      this.cached = null;
+      await this.store.clear();
+    }
+  }
+  async performRefresh(creds) {
+    const url = `${creds.userAuthUrl}/api/auth/token/refresh`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: creds.refreshToken })
+    });
+    if (response.status === 400 || response.status === 401 || response.status === 403 || response.status === 422) {
+      throw new RefreshRejectedError(
+        "Refresh token rejected. Run `npx @myspec/mcp-server login` to sign in again."
+      );
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new HttpStatusError(response.status, body, `Token refresh failed: HTTP ${String(response.status)}`);
+    }
+    const payload = await response.json().catch(() => null);
+    if (!payload || typeof payload.accessToken !== "string" || typeof payload.refreshToken !== "string" || typeof payload.expiresIn !== "number") {
+      throw new NeedsLoginError(
+        "Token refresh response was malformed. Run `npx @myspec/mcp-server login` to sign in again."
+      );
+    }
+    const next = {
+      ...creds,
+      accessToken: payload.accessToken,
+      refreshToken: payload.refreshToken,
+      expiresAt: this.now() + payload.expiresIn * 1e3
+    };
+    this.cached = next;
+    await this.store.save(next);
+    return next;
+  }
+};
+var RefreshRejectedError = class extends NeedsLoginError {
+};
+// ../../packages/platform-client/shared/types.ts
+var RETRYABLE_STATUS_CODES = [408, 429, 502, 503, 504];
+// ../../packages/platform-client/shared/retry.ts
+var DEFAULT_RETRY_CONFIG = {
+  initialDelayMs: 100,
+  multiplier: 2,
+  maxDelayMs: 1e4,
+  maxAttempts: 3,
+  jitterFactor: 0.1
+};
+var defaultShouldRetry = () => true;
+function calculateDelay(attempt, config) {
+  const baseDelay = config.initialDelayMs * Math.pow(config.multiplier, attempt);
+  const cappedDelay = Math.min(baseDelay, config.maxDelayMs);
+  const jitterMultiplier = 1 + (Math.random() * 2 - 1) * config.jitterFactor;
+  return Math.round(cappedDelay * jitterMultiplier);
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function withRetry(fn, config = DEFAULT_RETRY_CONFIG, shouldRetry = defaultShouldRetry) {
+  const startTime = Date.now();
+  let lastError;
+  let attempt = 0;
+  while (attempt < config.maxAttempts) {
+    try {
+      const value = await fn();
+      return {
+        success: true,
+        value,
+        attempts: attempt + 1,
+        totalTimeMs: Date.now() - startTime
+      };
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      attempt++;
+      if (attempt >= config.maxAttempts || !shouldRetry(lastError, attempt - 1)) {
+        break;
+      }
+      const delay = calculateDelay(attempt - 1, config);
+      await sleep(delay);
+    }
+  }
+  return {
+    success: false,
+    error: lastError,
+    attempts: attempt,
+    totalTimeMs: Date.now() - startTime
+  };
+}
+// ../../packages/shared/logger.ts
+var LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var ConsoleLogger = class {
+  minLevel;
+  constructor(minLevel = "info") {
+    this.minLevel = minLevel;
+  }
+  debug(message, meta) {
+    this.log("debug", message, meta);
+  }
+  info(message, meta) {
+    this.log("info", message, meta);
+  }
+  warn(message, meta) {
+    this.log("warn", message, meta);
+  }
+  error(message, error, meta) {
+    const errorDetails = error ? {
+      error: {
+        message: error.message,
+        stack: error.stack
+      }
+    } : void 0;
+    this.log("error", message, { ...errorDetails, ...meta });
+  }
+  log(level, message, meta) {
+    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.minLevel]) {
+      return;
+    }
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      message,
+      ...meta
+    };
+    const output = JSON.stringify(entry);
+    if (level === "error") {
+      console.error(output);
+    } else if (level === "warn") {
+      console.warn(output);
+    } else {
+      console.log(output);
+    }
+  }
+};
+// ../../packages/platform-client/shared/http-base.ts
+var DEFAULT_HTTP_CONFIG = {
+  timeout: 3e4,
+  retryConfig: DEFAULT_RETRY_CONFIG
+};
+var STANDARD_HEADERS = {
+  "Content-Type": "application/json",
+  Accept: "application/json"
+};
+var BaseHttpClient = class {
+  config;
+  logger;
+  constructor(config) {
+    this.logger = config.logger ?? new ConsoleLogger();
+    this.config = {
+      ...DEFAULT_HTTP_CONFIG,
+      ...config,
+      retryConfig: config.retryConfig ?? DEFAULT_HTTP_CONFIG.retryConfig
+    };
+  }
+  /**
+   * Makes a GET request.
+   */
+  async get(path4, jwt, options) {
+    return this.request("GET", path4, void 0, jwt, options);
+  }
+  /**
+   * Makes a POST request.
+   */
+  async post(path4, body, jwt, options) {
+    return this.request("POST", path4, JSON.stringify(body), jwt, options);
+  }
+  /**
+   * Makes a PUT request.
+   */
+  async put(path4, body, jwt, options) {
+    return this.request("PUT", path4, JSON.stringify(body), jwt, options);
+  }
+  /**
+   * Makes a PATCH request.
+   */
+  async patch(path4, body, jwt, options) {
+    return this.request("PATCH", path4, JSON.stringify(body), jwt, options);
+  }
+  /**
+   * Makes a DELETE request.
+   */
+  async delete(path4, jwt, options) {
+    return this.request("DELETE", path4, void 0, jwt, options);
+  }
+  /**
+   * Checks if the client is configured and ready.
+   */
+  isReady() {
+    return !!this.config.baseUrl;
+  }
+  /**
+   * Gets the base URL.
+   */
+  getBaseUrl() {
+    return this.config.baseUrl;
+  }
+  /**
+   * Makes an HTTP request with retry logic.
+   */
+  async request(method, path4, body, jwt, options) {
+    const result = await withRetry(
+      () => this.executeRequest(method, path4, body, jwt, options),
+      this.config.retryConfig,
+      this.shouldRetry.bind(this)
+    );
+    if (!result.success) {
+      const error = result.error ?? new Error("Unknown error");
+      this.logger.error(`${method} ${path4} failed after ${result.attempts} attempts`, error, {
+        method,
+        path: path4,
+        attempts: result.attempts
+      });
+      const wrapped = new Error(
+        `${method} ${path4} failed after ${result.attempts} attempts: ${error.message}`
+      );
+      const originalStatus = error.status;
+      if (originalStatus !== void 0) {
+        wrapped.status = originalStatus;
+      }
+      throw wrapped;
+    }
+    return result.value;
+  }
+  /**
+   * Executes a single HTTP request.
+   */
+  async executeRequest(method, path4, body, jwt, options) {
+    const url = this.buildUrl(path4);
+    const headers = this.buildHeaders(jwt, options);
+    const timeout = options.timeout ?? this.config.timeout;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        let errorMessage2;
+        const rawBody = await response.text().catch(() => "");
+        if (rawBody) {
+          try {
+            const errorBody = JSON.parse(rawBody);
+            const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+            errorMessage2 = (errorBody.message ?? JSON.stringify(errorBody)) + details;
+          } catch {
+            const MAX_ERROR_LENGTH = 500;
+            errorMessage2 = rawBody.length > MAX_ERROR_LENGTH ? rawBody.slice(0, MAX_ERROR_LENGTH) + "... [truncated]" : rawBody;
+          }
+        } else {
+          errorMessage2 = "Unknown error";
+        }
+        const error = new Error(`HTTP ${response.status}: ${errorMessage2}`);
+        error.status = response.status;
+        throw error;
+      }
+      const contentLength = response.headers.get("Content-Length");
+      if (contentLength === "0" || response.status === 204) {
+        return {};
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Builds the full URL for a request.
+   */
+  buildUrl(path4) {
+    const baseUrl = this.config.baseUrl.replace(/\/$/, "");
+    const normalizedPath = path4.startsWith("/") ? path4 : `/${path4}`;
+    return `${baseUrl}${normalizedPath}`;
+  }
+  /**
+   * Builds headers for a request including JWT auth.
+   */
+  buildHeaders(jwt, options) {
+    const headers = new Headers({
+      ...STANDARD_HEADERS,
+      Authorization: `Bearer ${jwt}`
+    });
+    if (options.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        headers.set(key, value);
+      }
+    }
+    return headers;
+  }
+  /**
+   * Determines if a failed request should be retried.
+   */
+  shouldRetry(error) {
+    if (error.name === "AbortError") {
+      this.logger.debug("Retrying after abort/timeout", { error: error.message });
+      return true;
+    }
+    const httpError = error;
+    if (httpError.status !== void 0) {
+      const shouldRetry = RETRYABLE_STATUS_CODES.includes(httpError.status);
+      if (shouldRetry) {
+        this.logger.debug("Retrying after HTTP error", { status: httpError.status });
+      }
+      return shouldRetry;
+    }
+    if (error.message.includes("fetch") || error.message.includes("network")) {
+      this.logger.debug("Retrying after network error", { error: error.message });
+      return true;
+    }
+    return false;
+  }
+};
+// ../../packages/platform-client/project/types/attachment.types.ts
+var MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+function transformAttachmentResponse(raw) {
+  return {
+    id: raw.id,
+    projectId: raw.project_id,
+    org: raw.org,
+    uploadedBy: raw.uploaded_by,
+    name: raw.name,
+    mimeType: raw.mime_type,
+    fileSizeBytes: raw.file_size_bytes,
+    checksum: raw.checksum,
+    createdAt: new Date(raw.created_at),
+    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
+  };
+}
+// ../../packages/platform-client/project/types/file.types.ts
+function normalizeFileType(raw) {
+  return raw === "design" ? "solution" : raw;
+}
+function transformSpecFileResponse(raw) {
+  return {
+    id: raw.id,
+    projectId: raw.project_id,
+    sessionId: raw.session_id,
+    org: raw.org,
+    fileType: normalizeFileType(raw.file_type),
+    filePath: raw.file_path,
+    fileUri: raw.file_uri,
+    fileSizeBytes: raw.file_size_bytes,
+    checksum: raw.checksum,
+    revisionCount: raw.revision_count,
+    createdAt: new Date(raw.created_at),
+    updatedAt: new Date(raw.updated_at),
+    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
+  };
+}
+function transformFileRevisionResponse(raw) {
+  return {
+    id: raw.id,
+    specFileId: raw.spec_file_id,
+    org: raw.org,
+    revisionNumber: raw.revision_number,
+    fileUri: raw.file_uri,
+    fileSizeBytes: raw.file_size_bytes,
+    checksum: raw.checksum,
+    changedBy: raw.changed_by,
+    createdAt: new Date(raw.created_at)
+  };
+}
+function transformFileListResult(raw) {
+  return {
+    files: raw.files.map(transformSpecFileResponse),
+    total: raw.total,
+    limit: raw.limit,
+    offset: raw.offset
+  };
+}
+// ../../packages/platform-client/project/types/project.types.ts
+function transformProjectResponse(raw) {
+  return {
+    id: raw.id,
+    org: raw.org,
+    ownerId: raw.owner_id,
+    name: raw.name,
+    description: raw.description,
+    status: raw.status,
+    metadata: raw.metadata,
+    createdAt: new Date(raw.created_at),
+    updatedAt: new Date(raw.updated_at),
+    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
+  };
+}
+// ../../packages/platform-client/project/types/session.types.ts
+function transformSpecSessionResponse(raw) {
+  return {
+    id: raw.id,
+    projectId: raw.project_id,
+    projectName: raw.project_name,
+    org: raw.org,
+    userId: raw.user_id,
+    status: raw.status,
+    messageCount: raw.message_count,
+    tokenCount: raw.token_count,
+    context: raw.context,
+    startedAt: new Date(raw.started_at),
+    completedAt: raw.completed_at ? new Date(raw.completed_at) : void 0,
+    archivedAt: raw.archived_at ? new Date(raw.archived_at) : void 0,
+    createdAt: new Date(raw.created_at),
+    updatedAt: new Date(raw.updated_at),
+    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
+  };
+}
+// ../../packages/platform-client/project/http/attachment.http-client.ts
+var UPLOAD_TIMEOUT_MS = 3e4;
+var HttpAttachmentClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async listByProject(projectId, jwtToken) {
+    const path4 = `/project/v1/attachments?project_id=${encodeURIComponent(projectId)}`;
+    const response = await this.httpClient.get(
+      path4,
+      jwtToken,
+      {}
+    );
+    return response.attachments.map(transformAttachmentResponse);
+  }
+  async getById(attachmentId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `/project/v1/attachments/${attachmentId}`,
+      jwtToken,
+      {}
+    );
+    return transformAttachmentResponse(raw);
+  }
+  async getDownloadUrl(attachmentId, jwtToken) {
+    const response = await this.httpClient.get(
+      `/project/v1/attachments/${attachmentId}/content`,
+      jwtToken,
+      { headers: { Accept: "application/json" } }
+    );
+    return {
+      signedUrl: response.signed_url,
+      expiresAt: new Date(response.expires_at)
+    };
+  }
+  async initiateUpload(request, jwtToken) {
+    const body = {
+      project_id: request.projectId,
+      file_name: request.fileName,
+      mime_type: request.mimeType,
+      file_size_bytes: request.fileSizeBytes,
+      checksum: request.checksum
+    };
+    const response = await this.httpClient.post(
+      "/project/v1/attachments/initiate",
+      body,
+      jwtToken,
+      {}
+    );
+    return { attachmentId: response.attachment_id };
+  }
+  async uploadContent(attachmentId, content, jwtToken) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const url = `${baseUrl}/project/v1/attachments/${attachmentId}/content`;
+    const attempt = async () => {
+      const blob = new Blob([content], { type: "application/octet-stream" });
+      const response = await fetch(url, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/octet-stream",
+          Authorization: `Bearer ${jwtToken}`
+        },
+        body: blob,
+        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
+        const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+        const err = new Error(
+          `HTTP ${String(response.status)}: ${errorBody.message ?? "Upload failed"}${details}`
+        );
+        err.status = response.status;
+        throw err;
+      }
+      const result = await response.json();
+      return {
+        attachmentId: result.attachment_id,
+        fileUri: result.file_uri
+      };
+    };
+    const retryResult = await withRetry(attempt, DEFAULT_RETRY_CONFIG, (error) => {
+      const status = error.status;
+      if (status !== void 0) {
+        return RETRYABLE_STATUS_CODES.includes(status);
+      }
+      return true;
+    });
+    if (!retryResult.success) {
+      throw retryResult.error ?? new Error("Upload failed");
+    }
+    return retryResult.value;
+  }
+  async deleteById(attachmentId, jwtToken) {
+    await this.httpClient.delete(
+      `/project/v1/attachments/${attachmentId}`,
+      jwtToken,
+      {}
+    );
+  }
+  async downloadContent(attachmentId, jwtToken) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const url = `${baseUrl}/project/v1/attachments/${attachmentId}/content`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/octet-stream",
+        Authorization: `Bearer ${jwtToken}`
+      }
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
+      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+      const err = new Error(
+        `HTTP ${String(response.status)}: ${errorBody.message ?? "Download failed"}${details}`
+      );
+      err.status = response.status;
+      throw err;
+    }
+    const buffer = await response.arrayBuffer();
+    return new Uint8Array(buffer);
+  }
+};
+// ../../packages/platform-client/project/http/file.http-client.ts
+var HttpFileClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async initiateUpload(request, jwtToken) {
+    const body = {
+      project_id: request.projectId,
+      session_id: request.sessionId,
+      file_type: request.fileType,
+      file_path: request.filePath,
+      file_size_bytes: request.fileSizeBytes,
+      checksum: request.checksum
+    };
+    const response = await this.httpClient.post(
+      "/project/v1/files/initiate",
+      body,
+      jwtToken,
+      {}
+    );
+    return { fileId: response.file_id };
+  }
+  async uploadContent(fileId, content, jwtToken) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const url = `${baseUrl}/project/v1/files/${fileId}/content`;
+    const blob = new Blob([content], { type: "application/octet-stream" });
+    const response = await fetch(url, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/octet-stream",
+        Authorization: `Bearer ${jwtToken}`
+      },
+      body: blob
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
+      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+      throw new Error(
+        `HTTP ${response.status}: ${errorBody.message ?? "Upload failed"}${details}`
+      );
+    }
+    const result = await response.json();
+    return {
+      fileId: result.file_id,
+      fileRevisionId: result.file_revision_id,
+      fileUri: result.file_uri,
+      revisionNumber: result.revision_number
+    };
+  }
+  async saveManualRevision(fileId, content, jwtToken) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const url = `${baseUrl}/project/v1/files/${fileId}/revisions`;
+    const blob = new Blob([content], { type: "application/octet-stream" });
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/octet-stream",
+        Authorization: `Bearer ${jwtToken}`
+      },
+      body: blob
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
+      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+      throw new Error(
+        `HTTP ${response.status}: ${errorBody.message ?? "Save failed"}${details}`
+      );
+    }
+    const result = await response.json();
+    return {
+      fileId: result.file_id,
+      fileRevisionId: result.file_revision_id,
+      // The manual-revision endpoint does not return a current file URI (the FE only
+      // needs the revision id + number); keep the response shape stable with ''.
+      fileUri: "",
+      revisionNumber: result.revision_number
+    };
+  }
+  async getFile(fileId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `/project/v1/files/${fileId}/metadata`,
+      jwtToken,
+      {}
+    );
+    return transformSpecFileResponse(raw);
+  }
+  async getDownloadUrl(fileId, jwtToken) {
+    const response = await this.httpClient.get(
+      `/project/v1/files/${fileId}`,
+      jwtToken,
+      { headers: { Accept: "application/json" } }
+    );
+    return {
+      signedUrl: response.signed_url,
+      expiresAt: new Date(response.expires_at)
+    };
+  }
+  async downloadContent(fileId, jwtToken) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const url = `${baseUrl}/project/v1/files/${fileId}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/octet-stream",
+        Authorization: `Bearer ${jwtToken}`
+      }
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
+      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+      throw new Error(
+        `HTTP ${response.status}: ${errorBody.message ?? "Download failed"}${details}`
+      );
+    }
+    const buffer = await response.arrayBuffer();
+    return new Uint8Array(buffer);
+  }
+  async listFiles(projectId, jwtToken, opts) {
+    const queryParams = new URLSearchParams();
+    queryParams.set("project_id", projectId);
+    if (opts?.fileType) queryParams.set("file_type", opts.fileType);
+    if (opts?.query) queryParams.set("q", opts.query);
+    if (opts?.limit !== void 0) queryParams.set("limit", String(opts.limit));
+    if (opts?.offset !== void 0) queryParams.set("offset", String(opts.offset));
+    const query = queryParams.toString();
+    const path4 = `/project/v1/files?${query}`;
+    const raw = await this.httpClient.get(path4, jwtToken, {});
+    return transformFileListResult(raw);
+  }
+  async deleteFile(fileId, jwtToken) {
+    await this.httpClient.delete(
+      `/project/v1/files/${fileId}`,
+      jwtToken,
+      {}
+    );
+  }
+  async listRevisions(fileId, jwtToken) {
+    const response = await this.httpClient.get(
+      `/project/v1/files/${fileId}/revisions`,
+      jwtToken,
+      {}
+    );
+    return response.revisions.map(transformFileRevisionResponse);
+  }
+  async getRevision(fileId, revisionNumber, jwtToken) {
+    const revisions = await this.listRevisions(fileId, jwtToken);
+    const revision = revisions.find((r) => r.revisionNumber === revisionNumber);
+    if (!revision) {
+      throw new Error(`Revision ${revisionNumber} not found for file ${fileId}`);
+    }
+    return revision;
+  }
+  async downloadRevision(fileId, revisionNumber, jwtToken) {
+    const baseUrl = this.httpClient.getBaseUrl().replace(/\/$/, "");
+    const url = `${baseUrl}/project/v1/files/${fileId}/revisions/${revisionNumber}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/octet-stream",
+        Authorization: `Bearer ${jwtToken}`
+      }
+    });
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({ message: "Unknown error" }));
+      const details = errorBody.details ? ` [details: ${JSON.stringify(errorBody.details)}]` : "";
+      throw new Error(
+        `HTTP ${response.status}: ${errorBody.message ?? "Download failed"}${details}`
+      );
+    }
+    const buffer = await response.arrayBuffer();
+    return new Uint8Array(buffer);
+  }
+};
+// ../../packages/platform-client/project/http/project.http-client.ts
+var HttpProjectClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async createProject(request, jwtToken) {
+    const raw = await this.httpClient.post(
+      "/project/v1/projects",
+      request,
+      jwtToken,
+      {}
+    );
+    return transformProjectResponse(raw);
+  }
+  async getProject(projectId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `/project/v1/projects/${projectId}`,
+      jwtToken,
+      {}
+    );
+    return transformProjectResponse(raw);
+  }
+  async listProjects(jwtToken, opts) {
+    const queryParams = new URLSearchParams();
+    if (opts?.status) queryParams.set("status", opts.status);
+    if (opts?.limit) queryParams.set("limit", String(opts.limit));
+    if (opts?.offset !== void 0) queryParams.set("offset", String(opts.offset));
+    if (opts?.query) queryParams.set("q", opts.query);
+    const query = queryParams.toString();
+    const path4 = query ? `/project/v1/projects?${query}` : "/project/v1/projects";
+    const response = await this.httpClient.get(path4, jwtToken, {});
+    return {
+      projects: response.projects.map(transformProjectResponse),
+      total: response.total,
+      limit: response.limit,
+      offset: response.offset
+    };
+  }
+  async updateProject(projectId, updates, jwtToken) {
+    const raw = await this.httpClient.put(
+      `/project/v1/projects/${projectId}`,
+      updates,
+      jwtToken,
+      {}
+    );
+    return transformProjectResponse(raw);
+  }
+  async deleteProject(projectId, jwtToken) {
+    await this.httpClient.delete(
+      `/project/v1/projects/${projectId}`,
+      jwtToken,
+      {}
+    );
+  }
+  async getDashboardSummary(jwtToken) {
+    const raw = await this.httpClient.get("/project/v1/summary", jwtToken, {});
+    return {
+      totalProjects: raw.total_projects,
+      totalSessions: raw.total_sessions,
+      activeSessions: raw.active_sessions,
+      totalSpecFiles: raw.total_spec_files,
+      projectSessionCounts: raw.project_session_counts ?? {},
+      projectFileCounts: raw.project_file_counts ?? {}
+    };
+  }
+};
+// ../../packages/platform-client/project/http/session.http-client.ts
+var HttpSpecSessionClient = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  async createSpecSession(request, jwtToken) {
+    const body = {
+      project_id: request.projectId,
+      context: request.context ?? void 0
+    };
+    const raw = await this.httpClient.post(
+      `/project/v1/projects/${request.projectId}/sessions`,
+      body,
+      jwtToken,
+      {}
+    );
+    return transformSpecSessionResponse(raw);
+  }
+  async getSpecSession(sessionId, jwtToken) {
+    const raw = await this.httpClient.get(
+      `/project/v1/sessions/${sessionId}`,
+      jwtToken,
+      {}
+    );
+    return transformSpecSessionResponse(raw);
+  }
+  async listSpecSessions(projectId, jwtToken, opts) {
+    const params = new URLSearchParams();
+    params.set("filter", opts?.archiveFilter ?? "active");
+    if (opts?.status) params.set("status", opts.status);
+    if (opts?.query) params.set("q", opts.query);
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+    const response = await this.httpClient.get(
+      `/project/v1/projects/${projectId}/sessions?${params.toString()}`,
+      jwtToken,
+      {}
+    );
+    return {
+      sessions: response.sessions.map(transformSpecSessionResponse),
+      total: response.total,
+      limit: response.limit,
+      offset: response.offset
+    };
+  }
+  async updateSpecSession(sessionId, updates, jwtToken) {
+    const body = {};
+    if (updates.status !== void 0) body.status = updates.status;
+    if (updates.messageCount !== void 0) body.message_count = updates.messageCount;
+    if (updates.tokenCount !== void 0) body.token_count = updates.tokenCount;
+    if (updates.context !== void 0) body.context = updates.context;
+    const raw = await this.httpClient.put(
+      `/project/v1/sessions/${sessionId}`,
+      body,
+      jwtToken,
+      {}
+    );
+    return transformSpecSessionResponse(raw);
+  }
+  async archiveSpecSession(sessionId, jwtToken) {
+    const raw = await this.httpClient.post(
+      `/project/v1/sessions/${sessionId}/archive`,
+      {},
+      jwtToken,
+      {}
+    );
+    return transformSpecSessionResponse(raw);
+  }
+  async unarchiveSpecSession(sessionId, jwtToken) {
+    const raw = await this.httpClient.post(
+      `/project/v1/sessions/${sessionId}/unarchive`,
+      {},
+      jwtToken,
+      {}
+    );
+    return transformSpecSessionResponse(raw);
+  }
+  async deleteSpecSession(sessionId, jwtToken) {
+    await this.httpClient.delete(`/project/v1/sessions/${sessionId}`, jwtToken, {});
+  }
+  async listUserSessions(opts, jwtToken) {
+    const limit = opts.limit ?? 20;
+    const response = await this.httpClient.get(`/project/v1/sessions?limit=${String(limit)}`, jwtToken, {});
+    return {
+      sessions: response.sessions.map(transformSpecSessionResponse),
+      fileCounts: response.file_counts ?? {}
+    };
+  }
+  async getSessionSpecLinks(sessionId, jwtToken) {
+    return this.httpClient.get(
+      `/project/v1/sessions/${sessionId}/spec-links`,
+      jwtToken,
+      {}
+    );
+  }
+};
+// src/platform/client.ts
+var silentLogger = {
+  debug: () => void 0,
+  info: () => void 0,
+  warn: () => void 0,
+  error: () => void 0
+};
+var PlatformClient = class {
+  tokenManager;
+  project;
+  session;
+  file;
+  attachment;
+  baseUrl;
+  constructor(deps) {
+    this.tokenManager = deps.tokenManager;
+    this.baseUrl = deps.baseUrl.replace(/\/$/, "");
+    const httpClient = new BaseHttpClient({ baseUrl: this.baseUrl, logger: silentLogger });
+    this.project = new HttpProjectClient(httpClient);
+    this.session = new HttpSpecSessionClient(httpClient);
+    this.file = new HttpFileClient(httpClient);
+    this.attachment = new HttpAttachmentClient(httpClient);
+  }
+  async listProjects(opts = {}) {
+    return this.withTokenRetry((jwt) => this.project.listProjects(jwt, opts));
+  }
+  async getProject(projectId) {
+    return this.withTokenRetry((jwt) => this.project.getProject(projectId, jwt));
+  }
+  async listProjectSessions(projectId, opts = {}) {
+    const merged = {
+      archiveFilter: opts.archiveFilter ?? "active",
+      ...opts
+    };
+    return this.withTokenRetry((jwt) => this.session.listSpecSessions(projectId, jwt, merged));
+  }
+  async listFiles(projectId, opts = {}) {
+    return this.withTokenRetry((jwt) => this.file.listFiles(projectId, jwt, opts));
+  }
+  async getFileMetadata(fileId) {
+    return this.withTokenRetry((jwt) => this.file.getFile(fileId, jwt));
+  }
+  async getAccessTokenWithExpiry() {
+    const accessToken = await this.tokenManager.getValidAccessToken();
+    const creds = await this.tokenManager.getCredentials();
+    return { accessToken, expiresAt: creds.expiresAt };
+  }
+  async getFileDownloadUrl(fileId) {
+    return this.withTokenRetry((jwt) => this.file.getDownloadUrl(fileId, jwt));
+  }
+  async getAttachmentDownloadUrl(attachmentId) {
+    return this.withTokenRetry((jwt) => this.attachment.getDownloadUrl(attachmentId, jwt));
+  }
+  async downloadFile(fileId, revision) {
+    if (revision !== void 0) {
+      const bytes2 = await this.withTokenRetry(
+        (jwt) => this.file.downloadRevision(fileId, revision, jwt)
+      );
+      return { bytes: bytes2, revisionNumber: revision };
+    }
+    const bytes = await this.withTokenRetry((jwt) => this.file.downloadContent(fileId, jwt));
+    const meta = await this.getFileMetadata(fileId);
+    return { bytes, revisionNumber: meta.revisionCount };
+  }
+  async listAttachments(projectId) {
+    return this.withTokenRetry((jwt) => this.attachment.listByProject(projectId, jwt));
+  }
+  /**
+   * Fetch a single attachment's metadata by id. Returns null on a 404 so callers
+   * can report a clean "not found" instead of surfacing a raw HTTP error. Any
+   * other status — including a 405 (Method Not Allowed) or 501 (Not Implemented)
+   * from a verb mismatch — is thrown so an endpoint regression surfaces instead
+   * of masquerading as a missing attachment.
+   */
+  async getAttachmentMetadata(attachmentId) {
+    try {
+      return await this.withTokenRetry((jwt) => this.attachment.getById(attachmentId, jwt));
+    } catch (err) {
+      if (statusOf(err) === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  async downloadAttachment(attachmentId) {
+    return this.withTokenRetry((jwt) => this.attachment.downloadContent(attachmentId, jwt));
+  }
+  /**
+   * Soft-deletes an attachment by id. The server hides it from subsequent
+   * list/get responses and frees its filename so a new upload can take it
+   * without dedup-renaming. Used by `upload_attachment` when `override=true`
+   * is set and an attachment with the same filename already exists.
+   */
+  async deleteAttachment(attachmentId) {
+    await this.withTokenRetry((jwt) => this.attachment.deleteById(attachmentId, jwt));
+  }
+  /**
+   * Two-phase attachment upload. Reserves an attachment id (Phase 1), then
+   * PUTs the binary content (Phase 2). Each HTTP call is independently
+   * wrapped in withTokenRetry so a 401 on either phase triggers refresh.
+   * Returns the final attachment id (echoed by the server) and storage URI.
+   */
+  async uploadAttachment(args) {
+    const initiated = await this.withTokenRetry(
+      (jwt) => this.attachment.initiateUpload(
+        {
+          projectId: args.projectId,
+          fileName: args.fileName,
+          mimeType: args.mimeType,
+          fileSizeBytes: args.fileSizeBytes,
+          checksum: args.checksum
+        },
+        jwt
+      )
+    );
+    const uploaded = await this.withTokenRetry(
+      (jwt) => this.attachment.uploadContent(initiated.attachmentId, args.content, jwt)
+    );
+    return {
+      attachmentId: uploaded.attachmentId,
+      fileUri: uploaded.fileUri
+    };
+  }
+  async withTokenRetry(call) {
+    const jwt = await this.tokenManager.getValidAccessToken();
+    try {
+      return await call(jwt);
+    } catch (err) {
+      if (statusOf(err) === 401) {
+        const refreshed = await this.tokenManager.forceRefresh();
+        return await call(refreshed);
+      }
+      throw err;
+    }
+  }
+};
+function statusOf(err) {
+  if (typeof err !== "object" || err === null) {
+    return void 0;
+  }
+  const candidate = err.status;
+  if (typeof candidate === "number") {
+    return candidate;
+  }
+  const message = err instanceof Error ? err.message : "";
+  const match = /HTTP (\d{3}):/.exec(message);
+  return match ? Number(match[1]) : void 0;
+}
+// src/server/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import "zod";
+// src/server/tool-types.ts
+function jsonResult(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+// src/server/tools/get_attachment.ts
+import { z } from "zod";
+var inputSchema = {
+  attachment_id: z.string().min(1).describe("UUID of the attachment"),
+  include_download_url: z.number().int().nonnegative().optional().describe("Set to any positive value to include a signed download URL. Omit or 0 to skip.")
+};
+var getAttachmentTool = {
+  name: "get_attachment",
+  description: "Get attachment metadata. With `include_download_url>0`, also returns a signed `download_url`.",
+  inputSchema,
+  handler: async (args, ctx) => {
+    const attachment = await ctx.client.getAttachmentMetadata(args.attachment_id);
+    if (!attachment) {
+      return errorResult(`Attachment ${args.attachment_id} not found.`);
+    }
+    const base = {
+      id: attachment.id,
+      project_id: attachment.projectId,
+      name: attachment.name,
+      mime_type: attachment.mimeType,
+      file_size_bytes: attachment.fileSizeBytes,
+      checksum: attachment.checksum,
+      created_at: attachment.createdAt
+    };
+    const requested = args.include_download_url ?? 0;
+    if (requested <= 0) {
+      return jsonResult(base);
+    }
+    const signed = await ctx.client.getAttachmentDownloadUrl(attachment.id);
+    return jsonResult({
+      ...base,
+      download_url: signed.signedUrl,
+      expires_at: signed.expiresAt.toISOString()
+    });
+  }
+};
+// src/server/tools/get_file.ts
+import { z as z2 } from "zod";
+var inputSchema2 = {
+  file_id: z2.string().min(1).describe("UUID of the file"),
+  include_download_url: z2.number().int().nonnegative().optional().describe(
+    "Revision number to include a download URL for. Pass `revision_count` for the latest (signed URL); pass an older revision to get a URL plus `download_headers` carrying a short-lived bearer token. Omit or 0 to skip."
+  )
+};
+var getFileTool = {
+  name: "get_file",
+  description: "Get file metadata. With `include_download_url=N`, also returns a download URL for revision N: latest returns a signed URL; older revisions return a URL plus `download_headers` containing a short-lived bearer token (treat as sensitive).",
+  inputSchema: inputSchema2,
+  handler: async (args, ctx) => {
+    const meta = await ctx.client.getFileMetadata(args.file_id);
+    const base = {
+      id: meta.id,
+      project_id: meta.projectId,
+      session_id: meta.sessionId,
+      file_type: meta.fileType,
+      file_path: meta.filePath,
+      file_size_bytes: meta.fileSizeBytes,
+      checksum: meta.checksum,
+      revision_count: meta.revisionCount,
+      created_at: meta.createdAt,
+      updated_at: meta.updatedAt
+    };
+    const requested = args.include_download_url ?? 0;
+    if (requested <= 0) {
+      return jsonResult(base);
+    }
+    if (requested > meta.revisionCount) {
+      return errorResult(
+        `include_download_url=${String(requested)} is greater than revision_count=${String(meta.revisionCount)} for file ${meta.id}.`
+      );
+    }
+    const isLatest = requested === meta.revisionCount;
+    let downloadBlock;
+    if (isLatest) {
+      const signed = await ctx.client.getFileDownloadUrl(meta.id);
+      downloadBlock = {
+        download_url: signed.signedUrl,
+        download_revision: meta.revisionCount,
+        expires_at: signed.expiresAt.toISOString()
+      };
+    } else {
+      const url = `${ctx.client.baseUrl}/project/v1/files/${encodeURIComponent(meta.id)}/revisions/${String(requested)}`;
+      const token = await ctx.client.getAccessTokenWithExpiry();
+      downloadBlock = {
+        download_url: url,
+        download_revision: requested,
+        expires_at: new Date(token.expiresAt).toISOString(),
+        download_headers: [`Authorization: Bearer ${token.accessToken}`]
+      };
+    }
+    return jsonResult({ ...base, ...downloadBlock });
+  }
+};
+// src/server/tools/get_project.ts
+import { z as z3 } from "zod";
+var inputSchema3 = {
+  project_id: z3.string().min(1).describe("UUID of the project to fetch")
+};
+var getProjectTool = {
+  name: "get_project",
+  description: "Get details for a project including all active spec sessions, files (id + metadata), and attachments (id + metadata).",
+  inputSchema: inputSchema3,
+  handler: async (args, ctx) => {
+    const [project, sessions, files, attachments] = await Promise.all([
+      ctx.client.getProject(args.project_id),
+      ctx.client.listProjectSessions(args.project_id, { archiveFilter: "active", limit: 100 }).catch(() => ({ sessions: [], total: 0, limit: 0, offset: 0 })),
+      ctx.client.listFiles(args.project_id, { limit: 200 }).catch(() => ({ files: [], total: 0, limit: 0, offset: 0 })),
+      ctx.client.listAttachments(args.project_id).catch(() => [])
+    ]);
+    return jsonResult({
+      project: {
+        id: project.id,
+        name: project.name,
+        description: project.description,
+        status: project.status,
+        created_at: project.createdAt,
+        updated_at: project.updatedAt
+      },
+      active_sessions: sessions.sessions.map((s) => ({
+        id: s.id,
+        status: s.status,
+        message_count: s.messageCount,
+        token_count: s.tokenCount,
+        started_at: s.startedAt,
+        updated_at: s.updatedAt
+      })),
+      files: files.files.map((f) => ({
+        id: f.id,
+        file_path: f.filePath,
+        file_type: f.fileType,
+        file_size_bytes: f.fileSizeBytes,
+        revision_count: f.revisionCount,
+        session_id: f.sessionId,
+        updated_at: f.updatedAt
+      })),
+      attachments: attachments.map((a) => ({
+        id: a.id,
+        name: a.name,
+        mime_type: a.mimeType,
+        file_size_bytes: a.fileSizeBytes,
+        created_at: a.createdAt
+      }))
+    });
+  }
+};
+// src/server/tools/list_projects.ts
+import { z as z4 } from "zod";
+var inputSchema4 = {
+  query: z4.string().optional().describe(
+    "Search term to filter projects by name. Omit to list all projects."
+  ),
+  limit: z4.number().int().positive().max(100).optional().describe("Max projects to return (default 20)"),
+  offset: z4.number().int().nonnegative().optional().describe("Pagination offset (default 0)")
+};
+var listProjectsTool = {
+  name: "list_projects",
+  description: "List or search MySpec projects accessible to the authenticated user.",
+  inputSchema: inputSchema4,
+  handler: async (args, ctx) => {
+    const result = await ctx.client.listProjects({
+      query: args.query,
+      limit: args.limit ?? 20,
+      offset: args.offset ?? 0
+    });
+    return jsonResult({
+      projects: result.projects.map((p) => ({
+        id: p.id,
+        name: p.name,
+        description: p.description,
+        status: p.status,
+        updated_at: p.updatedAt
+      })),
+      total: result.total,
+      limit: result.limit,
+      offset: result.offset
+    });
+  }
+};
+// src/server/tools/read_file.ts
+import { promises as fs3 } from "fs";
+import os3 from "os";
+import path3 from "path";
+import { z as z5 } from "zod";
+// src/server/download-path.ts
+import { promises as fs2 } from "fs";
+import os2 from "os";
+import path2 from "path";
+function resolveDownloadRoot(env = process.env) {
+  const configured = env.MYSPEC_DOWNLOAD_ROOT;
+  if (configured) {
+    if (!path2.isAbsolute(configured)) {
+      throw new Error(`MYSPEC_DOWNLOAD_ROOT must be an absolute path (got: ${configured})`);
+    }
+    return path2.resolve(configured);
+  }
+  return path2.join(os2.homedir(), ".myspec");
+}
+function assertWithinRoot(target, root) {
+  const resolvedTarget = path2.resolve(target);
+  const resolvedRoot = path2.resolve(root);
+  const rel = path2.relative(resolvedRoot, resolvedTarget);
+  if (rel.startsWith("..") || path2.isAbsolute(rel)) {
+    return `path resolves outside the configured root (${resolvedRoot}): ${resolvedTarget}`;
+  }
+  return null;
+}
+function computeFileCachePath(args) {
+  const basename4 = path2.basename(args.filePath) || "content";
+  return path2.join(
+    args.cacheRoot,
+    "project",
+    args.projectId,
+    "file",
+    args.fileId,
+    "rev",
+    String(args.revision),
+    basename4
+  );
+}
+async function pathExists(p) {
+  try {
+    await fs2.stat(p);
+    return true;
+  } catch (err) {
+    if (isFsNotFound2(err)) {
+      return false;
+    }
+    throw err;
+  }
+}
+function isFsNotFound2(err) {
+  return typeof err === "object" && err !== null && err.code === "ENOENT";
+}
+async function writeBytesAtomically(target, bytes) {
+  const dir = path2.dirname(target);
+  await fs2.mkdir(dir, { recursive: true });
+  const tmp = path2.join(dir, `.${path2.basename(target)}.${process.pid.toString()}.tmp`);
+  const handle = await fs2.open(tmp, "wx", 384);
+  try {
+    await handle.write(bytes);
+  } finally {
+    await handle.close();
+  }
+  await fs2.rename(tmp, target);
+}
+// src/server/tools/read_file.ts
+var MAX_READ_BYTES = 1 * 1024 * 1024;
+var inputSchema5 = {
+  file_id: z5.string().min(1).describe("UUID of the file"),
+  revision: z5.number().int().positive().optional().describe("Specific revision number to read (defaults to the latest revision).")
+};
+var readFileTool = {
+  name: "read_file",
+  description: "Return a file's UTF-8 content. Bytes are cached on disk under the configured cache root (default ~/.myspec) at `project/<projectId>/file/<fileId>/rev/<rev>/<basename>` and reused on subsequent reads of the same revision. Fails for binary files or files larger than 1 MiB \u2014 use get_file with `include_download_url` to obtain a download URL for those.",
+  inputSchema: inputSchema5,
+  handler: async (args, ctx) => {
+    const meta = await ctx.client.getFileMetadata(args.file_id);
+    const targetRevision = args.revision ?? meta.revisionCount;
+    if (targetRevision === meta.revisionCount && meta.fileSizeBytes > MAX_READ_BYTES) {
+      return errorResult(buildOversizeMessage(args.file_id, meta.fileSizeBytes));
+    }
+    const cacheRoot = resolveDownloadRoot();
+    const cachePath = computeFileCachePath({
+      cacheRoot,
+      projectId: meta.projectId,
+      fileId: meta.id,
+      revision: targetRevision,
+      filePath: meta.filePath
+    });
+    const escape = assertWithinRoot(cachePath, cacheRoot);
+    if (escape) {
+      return errorResult(
+        `read_file refused to write cache: ${escape}. This indicates an unexpected platform response shape (projectId/fileId/filePath).`
+      );
+    }
+    let bytes;
+    let cacheHit = false;
+    if (await pathExists(cachePath)) {
+      bytes = await fs3.readFile(cachePath);
+      cacheHit = true;
+    } else {
+      const downloaded = await ctx.client.downloadFile(args.file_id, args.revision);
+      bytes = downloaded.bytes;
+      if (bytes.byteLength > MAX_READ_BYTES) {
+        return errorResult(buildOversizeMessage(args.file_id, bytes.byteLength));
+      }
+      await writeBytesAtomically(cachePath, bytes);
+    }
+    if (bytes.byteLength > MAX_READ_BYTES) {
+      return errorResult(buildOversizeMessage(args.file_id, bytes.byteLength));
+    }
+    if (isBinary(bytes)) {
+      return errorResult(
+        `File ${args.file_id} appears to be binary (file_type=${meta.fileType}, size=${String(bytes.byteLength)} bytes). Use get_file with \`include_download_url\` to obtain a download URL.`
+      );
+    }
+    let text;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch {
+      return errorResult(
+        `File ${args.file_id} is not valid UTF-8 text. Use get_file with \`include_download_url\` to obtain a download URL.`
+      );
+    }
+    return jsonResult({
+      file_id: meta.id,
+      revision_number: targetRevision,
+      file_path: meta.filePath,
+      file_type: meta.fileType,
+      cache_path: maskHomedir(cachePath),
+      cache_hit: cacheHit,
+      content: text
+    });
+  }
+};
+function buildOversizeMessage(fileId, byteLength) {
+  return `File ${fileId} is ${String(byteLength)} bytes which exceeds the read cap of ${String(MAX_READ_BYTES)} bytes. Use get_file with \`include_download_url\` to obtain a download URL and fetch it directly.`;
+}
+function maskHomedir(p, home = os3.homedir()) {
+  if (!home) {
+    return p;
+  }
+  if (p === home) {
+    return "~";
+  }
+  if (p.startsWith(home + path3.sep)) {
+    return "~" + p.slice(home.length);
+  }
+  return p;
+}
+function isBinary(bytes) {
+  for (const byte of bytes) {
+    if (byte === 0) {
+      return true;
+    }
+  }
+  return false;
+}
+// src/server/tools/upload_attachment.ts
+import { createHash } from "crypto";
+import { lstat, readFile } from "fs/promises";
+import { basename, extname, isAbsolute } from "path";
+import { z as z6 } from "zod";
+var DEFAULT_MIME = "application/octet-stream";
+var MAX_ATTACHMENT_MB = MAX_ATTACHMENT_BYTES / (1024 * 1024);
+var STRUCTURED_EXTENSION_MIME = {
+  ".pdf": "application/pdf",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+};
+var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  // Plain prose / docs
+  ".txt",
+  ".md",
+  ".markdown",
+  ".rst",
+  ".log",
+  ".tex",
+  // Markup
+  ".xml",
+  ".html",
+  ".htm",
+  ".svg",
+  ".xhtml",
+  // Data / config
+  ".json",
+  ".jsonl",
+  ".ndjson",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".env",
+  ".csv",
+  ".tsv",
+  ".properties",
+  // Scripts / source code
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".py",
+  ".go",
+  ".rb",
+  ".rs",
+  ".java",
+  ".scala",
+  ".c",
+  ".cc",
+  ".cpp",
+  ".cxx",
+  ".h",
+  ".hpp",
+  ".hxx",
+  ".cs",
+  ".swift",
+  ".kt",
+  ".kts",
+  ".php",
+  ".lua",
+  ".r",
+  ".dart",
+  ".clj",
+  ".cljs",
+  ".ex",
+  ".exs",
+  ".erl",
+  ".hs",
+  ".ml",
+  ".fs",
+  // Shell / build
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".fish",
+  ".ps1",
+  ".bat",
+  ".cmd",
+  ".sql"
+]);
+function effectiveFileNameFromUri(fileUri, requested) {
+  const lastSlash = fileUri.lastIndexOf("/");
+  if (lastSlash === -1 || lastSlash === fileUri.length - 1) {
+    return requested;
+  }
+  return fileUri.slice(lastSlash + 1);
+}
+function inferMimeFromName(name) {
+  const ext = extname(name).toLowerCase();
+  const structured = STRUCTURED_EXTENSION_MIME[ext];
+  if (structured !== void 0) {
+    return structured;
+  }
+  if (TEXT_EXTENSIONS.has(ext)) {
+    return "text/plain";
+  }
+  return DEFAULT_MIME;
+}
+var inputSchema6 = {
+  project_id: z6.string().min(1).describe("UUID of the project to attach the file to."),
+  file_path: z6.string().min(1).describe(
+    "Absolute path to the local file to upload. The MCP server reads this path from its own host."
+  ),
+  file_name: z6.string().min(1).optional().describe("Override the filename recorded on the attachment. Defaults to the path basename."),
+  mime_type: z6.string().min(1).optional().describe(
+    "Override the MIME type sent to the platform. The platform re-detects from content, so this is only a hint. If omitted, inferred from the file extension \u2014 structured (.pdf, .docx, .xlsx) keep their canonical MIME; common UTF-8 text formats (.xml, .json, .yaml, .html, .csv, .md, source code, ...) are sent as text/plain."
+  ),
+  override: z6.boolean().optional().describe(
+    "When true, any existing (non-deleted) attachment on the project whose recorded filename exactly matches `file_name` (or the path basename) is soft-deleted before the new upload, so the new attachment keeps the original name instead of getting an auto-dedup `(1)` suffix. The platform has no in-place content-replace API, so the new upload always gets a new `attachment_id`; any replaced ids are returned as `overridden_attachment_ids` (array, possibly empty) so callers can refresh stored references. Defaults to false (let the platform auto-dedup)."
+  )
+};
+var uploadAttachmentTool = {
+  name: "upload_attachment",
+  description: `Upload a local file as a new attachment on a project. Reads \`file_path\` from the host running the MCP server, computes its SHA256, then performs the two-phase platform upload. Max ${String(MAX_ATTACHMENT_MB)} MB. Supported content: PDF, DOCX, XLSX, and any UTF-8 text file (XML, JSON, YAML, HTML, Markdown, CSV, source code, ...). Binary files outside the structured types will be rejected by the platform.`,
+  inputSchema: inputSchema6,
+  handler: async (args, ctx) => {
+    if (!isAbsolute(args.file_path)) {
+      return errorResult(`file_path must be an absolute path; got "${args.file_path}".`);
+    }
+    let stats;
+    try {
+      stats = await lstat(args.file_path);
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") {
+        return errorResult(`File not found: ${args.file_path}`);
+      }
+      if (code === "EACCES" || code === "EPERM") {
+        return errorResult(`Permission denied reading ${args.file_path}`);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResult(`Failed to stat ${args.file_path}: ${message}`);
+    }
+    if (stats.isSymbolicLink()) {
+      return errorResult(`Refusing to follow symlink: ${args.file_path}`);
+    }
+    if (stats.isDirectory()) {
+      return errorResult(`Path is a directory, not a file: ${args.file_path}`);
+    }
+    if (!stats.isFile()) {
+      return errorResult(`Path is not a regular file: ${args.file_path}`);
+    }
+    if (stats.size === 0) {
+      return errorResult(`File is empty: ${args.file_path}`);
+    }
+    if (stats.size > MAX_ATTACHMENT_BYTES) {
+      return errorResult(
+        `File size ${String(stats.size)} bytes exceeds the ${String(MAX_ATTACHMENT_MB)} MB attachment limit.`
+      );
+    }
+    let buf;
+    try {
+      buf = await readFile(args.file_path);
+    } catch (err) {
+      const code = err.code;
+      if (code === "EACCES" || code === "EPERM") {
+        return errorResult(`Permission denied reading ${args.file_path}`);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResult(`Failed to read ${args.file_path}: ${message}`);
+    }
+    if (buf.byteLength === 0) {
+      return errorResult(`File is empty: ${args.file_path}`);
+    }
+    if (buf.byteLength > MAX_ATTACHMENT_BYTES) {
+      return errorResult(
+        `File size ${String(buf.byteLength)} bytes exceeds the ${String(MAX_ATTACHMENT_MB)} MB attachment limit.`
+      );
+    }
+    const fileName = args.file_name ?? basename(args.file_path);
+    const mimeType = args.mime_type ?? inferMimeFromName(fileName);
+    const checksum = `sha256:${createHash("sha256").update(buf).digest("hex")}`;
+    const bytes = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    const existing = await ctx.client.listAttachments(args.project_id);
+    const nameMatches = existing.filter((a) => a.name === fileName);
+    const checksumMatch = nameMatches.find((a) => a.checksum === checksum);
+    if (checksumMatch) {
+      return jsonResult({
+        attachment_id: checksumMatch.id,
+        project_id: args.project_id,
+        file_name: checksumMatch.name,
+        // No new attachment created → no name was dedup'd this call.
+        has_file_name_conflict: false,
+        mime_type: checksumMatch.mimeType,
+        file_size_bytes: checksumMatch.fileSizeBytes,
+        checksum: checksumMatch.checksum,
+        // True when the response describes a pre-existing attachment we
+        // returned in lieu of uploading. `file_uri` is omitted here because
+        // the platform's list endpoint does not surface it; use
+        // `get_attachment` with `include_download_url=1` to fetch a signed URL.
+        reused_existing_attachment: true
+      });
+    }
+    const overriddenIds = [];
+    if (args.override === true) {
+      for (const match of nameMatches) {
+        await ctx.client.deleteAttachment(match.id);
+        overriddenIds.push(match.id);
+      }
+    }
+    const uploaded = await ctx.client.uploadAttachment({
+      projectId: args.project_id,
+      fileName,
+      mimeType,
+      fileSizeBytes: buf.byteLength,
+      checksum,
+      content: bytes
+    });
+    const effectiveFileName = effectiveFileNameFromUri(uploaded.fileUri, fileName);
+    const hasFileNameConflict = effectiveFileName !== fileName;
+    return jsonResult({
+      attachment_id: uploaded.attachmentId,
+      project_id: args.project_id,
+      // Reflects the name the platform actually stored, which can differ from
+      // the requested name when auto-dedup adds a `(N)` suffix. Callers
+      // looking the attachment back up by name should use this value.
+      file_name: effectiveFileName,
+      // True when the platform stored a different name than requested (e.g.
+      // dedup'd `notes.txt` → `notes (1).txt`). Always present so callers can
+      // branch without conditional-presence checks.
+      has_file_name_conflict: hasFileNameConflict,
+      mime_type: mimeType,
+      file_size_bytes: buf.byteLength,
+      checksum,
+      file_uri: uploaded.fileUri,
+      // False when we actually uploaded (always the case in this branch).
+      // Kept on every response so callers don't have to special-case its
+      // absence vs. its `true` value.
+      reused_existing_attachment: false,
+      // Only present when override=true AND a name-matching attachment was
+      // soft-deleted. Empty array (`[]`) means override was requested but
+      // there was nothing to replace; field is omitted entirely otherwise.
+      ...args.override === true ? { overridden_attachment_ids: overriddenIds } : {}
+    });
+  }
+};
+// src/server/server.ts
+function buildServer(deps) {
+  const server = new McpServer({
+    name: "myspec-mcp-server",
+    version: deps.version ?? "0.1.0"
+  });
+  registerTool(server, listProjectsTool, deps.client);
+  registerTool(server, getProjectTool, deps.client);
+  registerTool(server, getFileTool, deps.client);
+  registerTool(server, readFileTool, deps.client);
+  registerTool(server, getAttachmentTool, deps.client);
+  registerTool(server, uploadAttachmentTool, deps.client);
+  return server;
+}
+async function startStdioServer(deps) {
+  const server = buildServer(deps);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+function wrapToolHandler(tool, client) {
+  return async (args) => {
+    try {
+      return await tool.handler(args, { client });
+    } catch (err) {
+      if (err instanceof NeedsLoginError) {
+        return errorResult(err.message);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      return errorResult(`${tool.name} failed: ${message}`);
+    }
+  };
+}
+function registerTool(server, tool, client) {
+  server.registerTool(
+    tool.name,
+    {
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    },
+    wrapToolHandler(tool, client)
+  );
+}
+// src/reverse/run.ts
+import WebSocket from "ws";
+import { basename as basename3 } from "path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+// src/reverse/ws-transport.ts
+var WebSocketClientTransport = class {
+  ws;
+  pending = [];
+  started = false;
+  onclose;
+  onerror;
+  onmessage;
+  constructor(ws) {
+    this.ws = ws;
+    this.ws.on("message", (raw) => {
+      const text = typeof raw === "string" ? raw : raw.toString("utf-8");
+      this.handleFrame(text);
+    });
+    this.ws.on("error", (err) => {
+      this.onerror?.(err);
+    });
+    this.ws.on("close", () => {
+      this.onclose?.();
+    });
+  }
+  start() {
+    this.started = true;
+    const buffered = this.pending;
+    this.pending = [];
+    for (const msg of buffered) {
+      this.onmessage?.(msg);
+    }
+    return Promise.resolve();
+  }
+  send(message) {
+    return new Promise((resolve2, reject) => {
+      this.ws.send(JSON.stringify(message), (err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve2();
+      });
+    });
+  }
+  close() {
+    try {
+      this.ws.close();
+    } catch {
+    }
+    return Promise.resolve();
+  }
+  handleFrame(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      this.onerror?.(err instanceof Error ? err : new Error(String(err)));
+      return;
+    }
+    const msg = parsed;
+    if (!this.started) {
+      this.pending.push(msg);
+      return;
+    }
+    try {
+      this.onmessage?.(msg);
+    } catch (err) {
+      this.onerror?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+};
+// src/reverse/safe-path.ts
+import { realpath } from "fs/promises";
+import { isAbsolute as isAbsolute2, resolve, sep } from "path";
+var PathOutsideRootError = class extends Error {
+  constructor(userPath) {
+    super(`path_outside_root: ${userPath}`);
+    this.userPath = userPath;
+    this.name = "PathOutsideRootError";
+  }
+  userPath;
+};
+var AbsolutePathError = class extends Error {
+  constructor(userPath) {
+    super(`absolute_path_rejected: ${userPath}`);
+    this.userPath = userPath;
+    this.name = "AbsolutePathError";
+  }
+  userPath;
+};
+async function resolveSafePath(realRoot, userPath, opts = {}) {
+  if (isAbsolute2(userPath)) {
+    throw new AbsolutePathError(userPath);
+  }
+  const joined = resolve(realRoot, userPath);
+  let resolved;
+  try {
+    resolved = await realpath(joined);
+  } catch (err) {
+    if (opts.allowMissing && err.code === "ENOENT") {
+      resolved = joined;
+    } else {
+      throw err;
+    }
+  }
+  if (resolved !== realRoot && !resolved.startsWith(realRoot + sep)) {
+    throw new PathOutsideRootError(userPath);
+  }
+  return resolved;
+}
+async function canonicaliseRoot(root) {
+  const real = await realpath(root);
+  return real;
+}
+// src/reverse/local-fs-tools.ts
+import { promises as fs4 } from "fs";
+import { join as join2, relative } from "path";
+import { spawn } from "child_process";
+import { z as z7 } from "zod";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+// src/reverse/ignore.ts
+import { basename as basename2 } from "path";
+var SEGMENT_IGNORES = [
+  ".git",
+  ".hg",
+  ".svn",
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".aws",
+  ".ssh",
+  ".gnupg",
+  ".kube",
+  ".docker",
+  ".gem",
+  ".cargo"
+];
+var PREFIX_IGNORES = [
+  ".env",
+  ".netrc",
+  ".npmrc",
+  ".pypirc",
+  "kubeconfig",
+  "credentials",
+  "id_rsa",
+  "id_ed25519",
+  "id_ecdsa"
+];
+var SUFFIX_IGNORES = [
+  ".pem",
+  ".key",
+  ".p12",
+  ".pfx",
+  ".jks",
+  ".crt",
+  ".cer"
+];
+var SEGMENT_SET = new Set(SEGMENT_IGNORES);
+function isIgnored(pathRelativeToRoot) {
+  const segments = pathRelativeToRoot.split(/[\\/]+/).filter((s) => s.length > 0);
+  for (const seg of segments) {
+    if (SEGMENT_SET.has(seg)) {
+      return { ignored: true, rule: `segment:${seg}` };
+    }
+  }
+  const name = basename2(pathRelativeToRoot);
+  for (const prefix of PREFIX_IGNORES) {
+    if (name === prefix || name.startsWith(prefix)) {
+      return { ignored: true, rule: `prefix:${prefix}` };
+    }
+  }
+  for (const suffix of SUFFIX_IGNORES) {
+    if (name.endsWith(suffix)) {
+      return { ignored: true, rule: `suffix:${suffix}` };
+    }
+  }
+  return { ignored: false };
+}
+function ripgrepIgnoreGlobs() {
+  const argv = [];
+  for (const seg of SEGMENT_IGNORES) {
+    argv.push("--glob", `!${seg}`);
+    argv.push("--glob", `!**/${seg}/**`);
+  }
+  for (const prefix of PREFIX_IGNORES) {
+    argv.push("--glob", `!${prefix}*`);
+    argv.push("--glob", `!**/${prefix}*`);
+  }
+  for (const suffix of SUFFIX_IGNORES) {
+    argv.push("--glob", `!*${suffix}`);
+  }
+  return argv;
+}
+// src/reverse/pack-codebase.ts
+import { createHash as createHash2 } from "crypto";
+import { mkdtemp, readFile as readFile2, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { runCli } from "repomix";
+var PAGE_SIZE_LINES = 5e3;
+var REPOMIX_TIMEOUT_MS = 12e4;
+var CACHE_TTL_MS = 30 * 60 * 1e3;
+var CACHE_MAX_ENTRIES = 5;
+var PackCache = class {
+  entries = /* @__PURE__ */ new Map();
+  set(outputId, content) {
+    this.evictExpired();
+    while (this.entries.size >= CACHE_MAX_ENTRIES) {
+      const oldestKey = this.entries.keys().next().value;
+      if (oldestKey === void 0) break;
+      this.entries.delete(oldestKey);
+    }
+    const lines = splitIntoLines(content);
+    const totalPages = Math.max(1, Math.ceil(lines.length / PAGE_SIZE_LINES));
+    const entry = { outputId, lines, createdAt: Date.now(), totalPages };
+    this.entries.set(outputId, entry);
+    return entry;
+  }
+  get(outputId) {
+    this.evictExpired();
+    return this.entries.get(outputId);
+  }
+  size() {
+    return this.entries.size;
+  }
+  evictExpired() {
+    const now = Date.now();
+    for (const [key, entry] of this.entries.entries()) {
+      if (now - entry.createdAt > CACHE_TTL_MS) {
+        this.entries.delete(key);
+      }
+    }
+  }
+};
+function splitIntoLines(text) {
+  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const parts = normalized.split("\n");
+  if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
+  return parts;
+}
+async function runPack(opts) {
+  const subpath = opts.args.subpath ?? ".";
+  const targetDir = await resolveSafePath(opts.realRoot, subpath);
+  const outputId = computeOutputId({
+    realRoot: opts.realRoot,
+    subpath,
+    includePatterns: opts.args.includePatterns,
+    ignorePatterns: opts.args.ignorePatterns
+  });
+  const cached = opts.cache.get(outputId);
+  if (cached) {
+    return buildPage(cached, 1);
+  }
+  const exec = opts._runCli ?? runCli;
+  const content = await invokeRepomix(exec, targetDir, opts.args, REPOMIX_TIMEOUT_MS);
+  const entry = opts.cache.set(outputId, content);
+  return buildPage(entry, 1);
+}
+function computeOutputId(inputs) {
+  const payload = JSON.stringify({
+    r: inputs.realRoot,
+    s: inputs.subpath,
+    i: inputs.includePatterns ?? "",
+    x: inputs.ignorePatterns ?? ""
+  });
+  const digest = createHash2("sha256").update(payload).digest("hex").slice(0, 12);
+  return `pack-${digest}`;
+}
+function readPage(cache, outputId, page) {
+  const entry = cache.get(outputId);
+  if (!entry) {
+    throw new PackCacheMissError(outputId);
+  }
+  if (!Number.isInteger(page) || page < 1 || page > entry.totalPages) {
+    throw new InvalidPageError(page, entry.totalPages);
+  }
+  return buildPage(entry, page);
+}
+var PackCacheMissError = class extends Error {
+  constructor(outputId) {
+    super(`pack_output_not_found: ${outputId}`);
+    this.outputId = outputId;
+    this.name = "PackCacheMissError";
+  }
+  outputId;
+};
+var InvalidPageError = class extends Error {
+  constructor(page, totalPages) {
+    super(`invalid_page: ${String(page)} (must be 1..${String(totalPages)})`);
+    this.page = page;
+    this.totalPages = totalPages;
+    this.name = "InvalidPageError";
+  }
+  page;
+  totalPages;
+};
+function buildPage(entry, page) {
+  const start = (page - 1) * PAGE_SIZE_LINES;
+  const end = Math.min(start + PAGE_SIZE_LINES, entry.lines.length);
+  const sliceLines = entry.lines.slice(start, end);
+  const hasMore = page < entry.totalPages;
+  return {
+    outputId: entry.outputId,
+    page,
+    totalPages: entry.totalPages,
+    totalLines: entry.lines.length,
+    pageLines: sliceLines.length,
+    hasMore,
+    content: sliceLines.join("\n"),
+    ...hasMore && {
+      nextPage: {
+        tool: "local_pack_codebase_read_page",
+        args: { outputId: entry.outputId, page: page + 1 }
+      }
+    }
+  };
+}
+async function invokeRepomix(exec, targetDir, args, timeoutMs) {
+  const workDir = await mkdtemp(join(tmpdir(), "myspec-pack-"));
+  const outputFile = join(workDir, "pack.txt");
+  const options = {
+    compress: true,
+    style: "plain",
+    quiet: true,
+    output: outputFile,
+    securityCheck: true,
+    include: args.includePatterns,
+    ignore: args.ignorePatterns
+  };
+  const execPromise = exec(["."], targetDir, options);
+  try {
+    await withTimeout(execPromise, timeoutMs);
+    const content = await readFile2(outputFile, "utf-8");
+    await rm(workDir, { recursive: true, force: true });
+    return content;
+  } catch (err) {
+    void execPromise.catch(() => void 0).finally(() => {
+      return rm(workDir, { recursive: true, force: true }).catch(() => void 0);
+    });
+    throw err;
+  }
+}
+async function withTimeout(promise, timeoutMs) {
+  let timer;
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`repomix timed out after ${String(timeoutMs)}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+}
+// src/reverse/local-fs-tools.ts
+var READ_FILE_MAX_BYTES = 5 * 1024 * 1024;
+var READ_FILE_BINARY_PROBE_BYTES = 8192;
+var READ_FILE_MAX_LINES = 2e3;
+var LIST_DIR_HARD_CAP = 5e3;
+var LIST_DIR_DEFAULT_CAP = 1e3;
+var GREP_MAX_MATCHES_DEFAULT = 200;
+var listDirInput = z7.object({
+  path: z7.string(),
+  recursive: z7.boolean().optional(),
+  maxEntries: z7.number().int().positive().optional(),
+  includeIgnored: z7.boolean().optional()
+});
+var readFileInput = z7.object({
+  path: z7.string(),
+  offset: z7.number().int().nonnegative().optional(),
+  limit: z7.number().int().positive().optional(),
+  includeIgnored: z7.boolean().optional()
+});
+var grepInput = z7.object({
+  pattern: z7.string(),
+  path: z7.string().optional(),
+  isRegex: z7.boolean().optional(),
+  caseSensitive: z7.boolean().optional(),
+  maxMatches: z7.number().int().positive().optional(),
+  contextLines: z7.number().int().nonnegative().optional(),
+  includeIgnored: z7.boolean().optional()
+});
+var packCodebaseInput = z7.object({
+  subpath: z7.string().optional(),
+  includePatterns: z7.string().optional(),
+  ignorePatterns: z7.string().optional()
+});
+var packCodebaseReadPageInput = z7.object({
+  outputId: z7.string(),
+  page: z7.number().int().positive()
+});
+function structuredError(error, message, extra) {
+  const payload = { error, message, ...extra ?? {} };
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(payload) }]
+  };
+}
+function structuredOk(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }]
+  };
+}
+async function handleList(args, opts) {
+  let realPath;
+  try {
+    realPath = await resolveSafePath(opts.realRoot, args.path);
+  } catch (err) {
+    return mapPathError(err);
+  }
+  if (!args.includeIgnored) {
+    const check = isIgnored(args.path);
+    if (check.ignored) {
+      return structuredError("path_ignored", `Path matches ignore rule ${check.rule ?? ""}`);
+    }
+  }
+  const cap = Math.min(args.maxEntries ?? LIST_DIR_DEFAULT_CAP, LIST_DIR_HARD_CAP);
+  const entries = [];
+  let truncated = false;
+  async function walk(dir, prefix) {
+    if (entries.length >= cap) {
+      truncated = true;
+      return;
+    }
+    const items = await fs4.readdir(dir, { withFileTypes: true });
+    for (const item of items) {
+      if (entries.length >= cap) {
+        truncated = true;
+        return;
+      }
+      const rel = prefix ? `${prefix}/${item.name}` : item.name;
+      if (!args.includeIgnored) {
+        const c = isIgnored(rel);
+        if (c.ignored) continue;
+      }
+      const full = join2(dir, item.name);
+      let type = "file";
+      if (item.isDirectory()) {
+        type = "dir";
+      } else if (item.isSymbolicLink()) {
+        type = "symlink";
+      }
+      let size;
+      let mtimeMs;
+      try {
+        const st = await fs4.stat(full);
+        size = st.size;
+        mtimeMs = st.mtimeMs;
+      } catch {
+      }
+      entries.push({ name: rel, type, size, mtimeMs });
+      if (args.recursive && type === "dir") {
+        await walk(full, rel);
+      }
+    }
+  }
+  try {
+    await walk(realPath, "");
+  } catch (err) {
+    return structuredError("list_dir_failed", errorMessage(err));
+  }
+  return structuredOk({ entries, truncated });
+}
+async function handleRead(args, opts) {
+  let realPath;
+  try {
+    realPath = await resolveSafePath(opts.realRoot, args.path);
+  } catch (err) {
+    return mapPathError(err);
+  }
+  if (!args.includeIgnored) {
+    const check = isIgnored(args.path);
+    if (check.ignored) {
+      return structuredError("path_ignored", `Path matches ignore rule ${check.rule ?? ""}`);
+    }
+  }
+  let stat;
+  try {
+    stat = await fs4.stat(realPath);
+  } catch (err) {
+    return structuredError("stat_failed", errorMessage(err));
+  }
+  if (!stat.isFile()) {
+    return structuredError("not_a_file", `Not a regular file: ${args.path}`);
+  }
+  if (stat.size > READ_FILE_MAX_BYTES) {
+    return structuredError(
+      "file_too_large",
+      `File is ${String(stat.size)} bytes; the read cap is ${String(READ_FILE_MAX_BYTES)} bytes. Use local_fs_grep to find the lines you need, or local_pack_codebase to pull the whole tree.`,
+      { sizeBytes: stat.size, maxBytes: READ_FILE_MAX_BYTES }
+    );
+  }
+  let raw;
+  try {
+    raw = await fs4.readFile(realPath);
+  } catch (err) {
+    return structuredError("read_failed", errorMessage(err));
+  }
+  const probe = raw.subarray(0, Math.min(READ_FILE_BINARY_PROBE_BYTES, raw.length));
+  if (probe.includes(0)) {
+    return structuredError(
+      "binary_file_not_supported",
+      `Binary content detected in ${args.path}; line-based pagination doesn't apply. Skip this file or use local_fs_grep on neighbouring text files.`
+    );
+  }
+  const text = normalizeNewlines(raw.toString("utf-8"));
+  const lines = splitIntoLines2(text);
+  const page = paginateLines(lines, args.offset, args.limit);
+  if ("error" in page) {
+    return structuredError("invalid_offset", page.error);
+  }
+  return structuredOk(page);
+}
+function normalizeNewlines(s) {
+  const noBom = s.charCodeAt(0) === 65279 ? s.slice(1) : s;
+  return noBom.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function splitIntoLines2(text) {
+  const parts = text.split("\n");
+  if (parts.length > 0 && parts[parts.length - 1] === "") parts.pop();
+  return parts;
+}
+function paginateLines(lines, offsetArg, limitArg) {
+  const totalLines = lines.length;
+  const rawOffset = offsetArg ?? 1;
+  const offset = rawOffset === 0 ? 1 : rawOffset;
+  if (offset < 1) {
+    return { error: `Invalid offset ${String(rawOffset)}; offset is 1-based and must be >= 1.` };
+  }
+  if (totalLines === 0) {
+    return {
+      content: "",
+      startLine: 1,
+      endLine: 0,
+      readLines: 0,
+      totalLines: 0,
+      truncated: false
+    };
+  }
+  if (offset > totalLines) {
+    return {
+      error: `Offset ${String(rawOffset)} is past the end of the file (total ${String(totalLines)} lines).`
+    };
+  }
+  const effectiveLimit = Math.min(Math.max(1, limitArg ?? READ_FILE_MAX_LINES), READ_FILE_MAX_LINES);
+  const startIdx = offset - 1;
+  const endIdx = Math.min(startIdx + effectiveLimit, totalLines);
+  const slice = lines.slice(startIdx, endIdx);
+  const truncated = endIdx < totalLines;
+  return {
+    content: slice.join("\n"),
+    startLine: offset,
+    endLine: endIdx,
+    readLines: slice.length,
+    totalLines,
+    truncated,
+    ...truncated ? { nextOffset: endIdx + 1 } : {}
+  };
+}
+async function handleGrep(args, opts) {
+  const subpath = args.path ?? ".";
+  let realPath;
+  try {
+    realPath = await resolveSafePath(opts.realRoot, subpath);
+  } catch (err) {
+    return mapPathError(err);
+  }
+  const maxMatches = args.maxMatches ?? GREP_MAX_MATCHES_DEFAULT;
+  const contextLines = args.contextLines ?? 0;
+  const isRegex = args.isRegex ?? false;
+  const caseSensitive = args.caseSensitive ?? false;
+  const ripgrep = await tryRipgrep(realPath, opts.realRoot, args.pattern, {
+    isRegex,
+    caseSensitive,
+    maxMatches,
+    contextLines,
+    includeIgnored: args.includeIgnored ?? false
+  });
+  if (ripgrep.ok) {
+    return structuredOk(ripgrep.value);
+  }
+  if (ripgrep.fatal) {
+    return structuredError("grep_failed", ripgrep.error);
+  }
+  return structuredOk(
+    await nodeGrep(realPath, opts.realRoot, args.pattern, {
+      isRegex,
+      caseSensitive,
+      maxMatches,
+      includeIgnored: args.includeIgnored ?? false
+    })
+  );
+}
+async function tryRipgrep(searchRoot, realRoot, pattern, opts) {
+  return new Promise((resolveP) => {
+    const argv = ["--json"];
+    if (!opts.isRegex) argv.push("--fixed-strings");
+    if (!opts.caseSensitive) argv.push("--ignore-case");
+    if (opts.contextLines > 0) argv.push(`--context=${String(opts.contextLines)}`);
+    if (!opts.includeIgnored) {
+      for (const a of ripgrepIgnoreGlobs()) argv.push(a);
+    }
+    argv.push("--", pattern, searchRoot);
+    const child = spawn("rg", argv);
+    let killed = false;
+    let stdoutBuf = "";
+    let stderr = "";
+    const matches = [];
+    const tryEmitFromBuffer = () => {
+      let nl;
+      while ((nl = stdoutBuf.indexOf("\n")) !== -1) {
+        const line = stdoutBuf.slice(0, nl);
+        stdoutBuf = stdoutBuf.slice(nl + 1);
+        const m = parseRipgrepLine(line, realRoot);
+        if (!m) continue;
+        if (!opts.includeIgnored && isIgnored(m.file).ignored) continue;
+        matches.push(m);
+        if (matches.length >= opts.maxMatches && !killed) {
+          killed = true;
+          try {
+            child.kill("SIGTERM");
+          } catch {
+          }
+          return;
+        }
+      }
+    };
+    child.stdout.on("data", (b) => {
+      stdoutBuf += b.toString("utf-8");
+      tryEmitFromBuffer();
+    });
+    child.stderr.on("data", (b) => {
+      stderr += b.toString("utf-8");
+    });
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        resolveP({ ok: false, fatal: false });
+        return;
+      }
+      resolveP({ ok: false, fatal: true, error: err.message });
+    });
+    child.on("close", (code) => {
+      if (stdoutBuf.length > 0) tryEmitFromBuffer();
+      if (code === null && !killed) {
+        resolveP({ ok: false, fatal: true, error: "rg killed" });
+        return;
+      }
+      if (code === 2) {
+        resolveP({ ok: false, fatal: true, error: stderr || "rg failed" });
+        return;
+      }
+      resolveP({
+        ok: true,
+        value: { matches, truncated: killed }
+      });
+    });
+  });
+}
+function parseRipgrepLine(rawLine, realRoot) {
+  if (rawLine.length === 0) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(rawLine);
+  } catch {
+    return null;
+  }
+  const obj = parsed;
+  if (obj.type !== "match" || !obj.data) return null;
+  const pathText = obj.data.path?.text;
+  const line = obj.data.line_number;
+  const text = obj.data.lines?.text ?? "";
+  if (!pathText || typeof line !== "number") return null;
+  return {
+    file: relative(realRoot, pathText) || pathText,
+    line,
+    text: text.replace(/\n$/, "")
+  };
+}
+var NODE_GREP_FILE_SIZE_CAP = 10 * 1024 * 1024;
+async function nodeGrep(searchRoot, realRoot, pattern, opts) {
+  const regex = opts.isRegex ? new RegExp(pattern, opts.caseSensitive ? "" : "i") : new RegExp(escapeRegExp(pattern), opts.caseSensitive ? "" : "i");
+  const matches = [];
+  let truncated = false;
+  async function walk(dir, prefix) {
+    if (matches.length >= opts.maxMatches) {
+      truncated = true;
+      return;
+    }
+    let items;
+    try {
+      items = await fs4.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const item of items) {
+      if (matches.length >= opts.maxMatches) {
+        truncated = true;
+        return;
+      }
+      const rel = prefix ? `${prefix}/${item.name}` : item.name;
+      if (!opts.includeIgnored && isIgnored(rel).ignored) continue;
+      const full = join2(dir, item.name);
+      if (item.isDirectory()) {
+        await walk(full, rel);
+        continue;
+      }
+      if (!item.isFile()) continue;
+      try {
+        const st = await fs4.stat(full);
+        if (st.size > NODE_GREP_FILE_SIZE_CAP) continue;
+        const content = await fs4.readFile(full, "utf-8");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i += 1) {
+          if (matches.length >= opts.maxMatches) {
+            truncated = true;
+            return;
+          }
+          const line = lines[i];
+          if (line === void 0) continue;
+          if (regex.test(line)) {
+            matches.push({
+              file: relative(realRoot, full) || full,
+              line: i + 1,
+              text: line
+            });
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  await walk(searchRoot, relative(realRoot, searchRoot));
+  return { matches, truncated };
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function mapPathError(err) {
+  if (err instanceof AbsolutePathError) {
+    return structuredError("absolute_path_rejected", err.message, { path: err.userPath });
+  }
+  if (err instanceof PathOutsideRootError) {
+    return structuredError("path_outside_root", err.message, { path: err.userPath });
+  }
+  if (err.code === "ENOENT") {
+    return structuredError("not_found", "Path does not exist");
+  }
+  return structuredError("resolve_failed", errorMessage(err));
+}
+function mapPackError(err) {
+  if (err instanceof PackCacheMissError) {
+    return structuredError("pack_output_not_found", err.message, { outputId: err.outputId });
+  }
+  if (err instanceof InvalidPageError) {
+    return structuredError("invalid_page", err.message, {
+      page: err.page,
+      totalPages: err.totalPages
+    });
+  }
+  if (err instanceof AbsolutePathError || err instanceof PathOutsideRootError) {
+    return mapPathError(err);
+  }
+  return structuredError("pack_failed", errorMessage(err));
+}
+function registerLocalFsTools(server, opts) {
+  const packCache = new PackCache();
+  const tools = [
+    {
+      name: "local_fs_list_dir",
+      description: "List directory entries under the granted --root.",
+      inputSchema: jsonSchemaFromZod(listDirInput),
+      handler: (args) => handleList(args, opts)
+    },
+    {
+      name: "local_fs_read_file",
+      description: "Read a file under the granted --root. Hard cap 1 MiB per call.",
+      inputSchema: jsonSchemaFromZod(readFileInput),
+      handler: (args) => handleRead(args, opts)
+    },
+    {
+      name: "local_fs_grep",
+      description: "Search for a pattern under the granted --root (ripgrep with Node fallback).",
+      inputSchema: jsonSchemaFromZod(grepInput),
+      handler: (args) => handleGrep(args, opts)
+    },
+    {
+      name: "local_pack_codebase",
+      description: "Pack the entire local codebase (under the granted --root) into a single plain-text bundle using `npx repomix@latest --style plain --compress`. Prefer this over many `local_fs_read_file` calls when you need broad codebase context. Output is paginated at 5000 lines per page; the response includes `outputId`, `page`, `totalPages`, `totalLines`, `pageLines`, `hasMore`, and a `nextPage` hint. Use `local_pack_codebase_read_page` to fetch subsequent pages by `outputId`. Repeat calls with the same `subpath`/`includePatterns`/`ignorePatterns` return the same `outputId` and are served instantly from the 30-minute cache without re-running repomix.",
+      inputSchema: jsonSchemaFromZod(packCodebaseInput),
+      handler: async (args) => {
+        try {
+          const page = await runPack({ realRoot: opts.realRoot, cache: packCache, args });
+          return structuredOk(page);
+        } catch (err) {
+          return mapPackError(err);
+        }
+      }
+    },
+    {
+      name: "local_pack_codebase_read_page",
+      description: "Read a specific page of a previously packed codebase output. Provide the `outputId` returned by `local_pack_codebase` and the 1-indexed `page` to fetch. Pages are 5000 lines of plain text. Cache entries expire after 30 minutes; on cache miss, re-run `local_pack_codebase` (same args return the same outputId \u2014 re-pack is cheap, served from cache).",
+      inputSchema: jsonSchemaFromZod(packCodebaseReadPageInput),
+      handler: (args) => {
+        try {
+          const page = readPage(packCache, args.outputId, args.page);
+          return Promise.resolve(structuredOk(page));
+        } catch (err) {
+          return Promise.resolve(mapPackError(err));
+        }
+      }
+    }
+  ];
+  server.setRequestHandler(ListToolsRequestSchema, () => {
+    return Promise.resolve({
+      tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema
+      }))
+    });
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params.name;
+    const found = tools.find((t) => t.name === name);
+    const started = performance.now();
+    const argsSummary = summarizeArgs(request.params.arguments ?? {});
+    process.stdout.write(`[tool] ${name}  ${argsSummary}
+`);
+    if (!found) {
+      process.stdout.write(`[tool] ${name}  -> unknown_tool
+`);
+      return structuredError("unknown_tool", `Unknown tool: ${name}`);
+    }
+    try {
+      const result = await found.handler(request.params.arguments ?? {});
+      const elapsedMs = Math.round(performance.now() - started);
+      const status = isErrorResult(result) ? "error" : "ok";
+      process.stdout.write(`[tool] ${name}  -> ${status}  ${String(elapsedMs)}ms
+`);
+      return result;
+    } catch (err) {
+      const msg = errorMessage(err);
+      const elapsedMs = Math.round(performance.now() - started);
+      process.stdout.write(`[tool] ${name}  -> threw  ${String(elapsedMs)}ms  ${msg}
+`);
+      opts.log?.(`local-fs: tool ${name} threw: ${msg}
+`);
+      return structuredError("handler_threw", msg);
+    }
+  });
+}
+function summarizeArgs(args) {
+  if (typeof args !== "object" || args === null) return "";
+  const obj = args;
+  const parts = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "string") {
+      parts.push(`${k}=${v.length > 60 ? v.slice(0, 60) + "\u2026" : v}`);
+    } else if (typeof v === "number" || typeof v === "boolean") {
+      parts.push(`${k}=${String(v)}`);
+    } else {
+      parts.push(`${k}=<${typeof v}>`);
+    }
+  }
+  return parts.join(" ");
+}
+function isErrorResult(result) {
+  if (typeof result !== "object" || result === null) return false;
+  return result.isError === true;
+}
+function jsonSchemaFromZod(schema) {
+  return zodToJson(schema);
+}
+function zodToJson(schema) {
+  if (schema instanceof z7.ZodObject) {
+    const shape = schema.shape;
+    const properties = {};
+    const required = [];
+    for (const [key, val] of Object.entries(shape)) {
+      properties[key] = zodToJson(val);
+      if (!val.safeParse(void 0).success) required.push(key);
+    }
+    const out = {
+      type: "object",
+      properties
+    };
+    if (required.length > 0) out.required = required;
+    return out;
+  }
+  if (schema instanceof z7.ZodOptional) {
+    return zodToJson(schema.unwrap());
+  }
+  if (schema instanceof z7.ZodString) {
+    return { type: "string" };
+  }
+  if (schema instanceof z7.ZodNumber) {
+    return { type: "number" };
+  }
+  if (schema instanceof z7.ZodBoolean) {
+    return { type: "boolean" };
+  }
+  if (schema instanceof z7.ZodEnum) {
+    return { type: "string", enum: schema.options };
+  }
+  return { type: "string" };
+}
+// src/reverse/run.ts
+var PING_INTERVAL_MS = 3e4;
+var PONG_TIMEOUT_MS = 1e4;
+var RECONNECT_BACKOFF_INITIAL_MS = 1e3;
+var RECONNECT_BACKOFF_MAX_MS = 3e4;
+var TERMINAL_CLOSE_CODES = /* @__PURE__ */ new Set([
+  4002
+  // superseded — a newer connection from the same user took over
+]);
+async function runReverse(opts) {
+  const realRoot = await canonicaliseRoot(opts.root);
+  const rootLabel = basename3(realRoot);
+  process.stderr.write(
+    `myspec-mcp reverse: granting read access to ${realRoot}
+myspec-mcp reverse: connecting to ${opts.agentUrl} (label=${rootLabel})
+Press Ctrl-C to stop. Auto-reconnect enabled.
+`
+  );
+  let backoffMs = RECONNECT_BACKOFF_INITIAL_MS;
+  let attempt = 0;
+  let authRetried = false;
+  for (; ; ) {
+    attempt += 1;
+    let outcome;
+    let accessToken;
+    try {
+      accessToken = await opts.getAccessToken();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `myspec-mcp reverse: cannot obtain access token: ${message}
+Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again.
+`
+      );
+      return;
+    }
+    try {
+      outcome = await runOneConnection({
+        realRoot,
+        rootLabel,
+        agentUrl: opts.agentUrl,
+        accessToken,
+        version: opts.version
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`myspec-mcp reverse: connect attempt ${String(attempt)} failed: ${message}
+`);
+      outcome = { terminal: false, reason: `connect_error: ${message}`, upMs: 0, code: 0 };
+    }
+    if (outcome.upMs >= HEALTHY_CONNECTION_THRESHOLD_MS) {
+      backoffMs = RECONNECT_BACKOFF_INITIAL_MS;
+      authRetried = false;
+    }
+    if (outcome.code === 4001) {
+      if (opts.onAuthFailed && !authRetried) {
+        process.stderr.write(
+          "myspec-mcp reverse: server rejected token (4001); force-refreshing and retrying once...\n"
+        );
+        try {
+          await opts.onAuthFailed();
+          authRetried = true;
+          continue;
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          process.stderr.write(
+            `myspec-mcp reverse: token refresh failed: ${message}; not reconnecting.
+`
+          );
+          return;
+        }
+      }
+      process.stderr.write(
+        "myspec-mcp reverse: token rejected after refresh attempt; run `npx @myspec/mcp-server login` and retry.\n"
+      );
+      return;
+    }
+    if (outcome.terminal) {
+      process.stderr.write(
+        `myspec-mcp reverse: terminal close (${outcome.reason}); not reconnecting.
+`
+      );
+      return;
+    }
+    process.stderr.write(
+      `myspec-mcp reverse: reconnecting in ${String(Math.round(backoffMs / 1e3))}s...
+`
+    );
+    await sleep2(backoffMs);
+    backoffMs = Math.min(backoffMs * 2, RECONNECT_BACKOFF_MAX_MS);
+  }
+}
+var HEALTHY_CONNECTION_THRESHOLD_MS = 5e3;
+async function runOneConnection(opts) {
+  const ws = new WebSocket(opts.agentUrl, {
+    headers: {
+      Authorization: `Bearer ${opts.accessToken}`,
+      "X-Mcp-Client": `myspec-mcp-server/${opts.version}`,
+      "X-Mcp-Root-Label": opts.rootLabel
+    }
+  });
+  await waitForOpen(ws);
+  const transport = new WebSocketClientTransport(ws);
+  const server = new Server(
+    { name: "myspec-mcp-server-reverse", version: opts.version },
+    { capabilities: { tools: {} } }
+  );
+  registerLocalFsTools(server, {
+    realRoot: opts.realRoot,
+    log: (line) => process.stderr.write(line)
+  });
+  await server.connect(transport);
+  const connectedAt = Date.now();
+  process.stderr.write("myspec-mcp reverse: connected; awaiting tool calls.\n");
+  let awaitingPong = false;
+  let pongTimer = null;
+  const pingTimer = setInterval(() => {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    if (awaitingPong) {
+      return;
+    }
+    awaitingPong = true;
+    pongTimer = setTimeout(() => {
+      process.stderr.write("myspec-mcp reverse: pong timeout; terminating socket.\n");
+      try {
+        ws.terminate();
+      } catch {
+      }
+    }, PONG_TIMEOUT_MS);
+    try {
+      ws.ping();
+    } catch {
+      try {
+        ws.terminate();
+      } catch {
+      }
+    }
+  }, PING_INTERVAL_MS);
+  ws.on("pong", () => {
+    awaitingPong = false;
+    if (pongTimer) {
+      clearTimeout(pongTimer);
+      pongTimer = null;
+    }
+  });
+  return new Promise((resolve2) => {
+    ws.once("close", (code, reasonBuf) => {
+      clearInterval(pingTimer);
+      if (pongTimer) clearTimeout(pongTimer);
+      const reasonStr = typeof reasonBuf === "string" ? reasonBuf : Buffer.from(reasonBuf).toString("utf-8");
+      process.stderr.write(
+        `myspec-mcp reverse: connection closed (code=${String(code)}, reason=${reasonStr || "-"})
+`
+      );
+      const terminal = TERMINAL_CLOSE_CODES.has(code);
+      resolve2({
+        terminal,
+        reason: `code=${String(code)} ${reasonStr}`,
+        upMs: Date.now() - connectedAt,
+        code
+      });
+    });
+  });
+}
+function waitForOpen(ws) {
+  return new Promise((resolve2, reject) => {
+    const onOpen = () => {
+      ws.removeListener("error", onError);
+      resolve2();
+    };
+    const onError = (err) => {
+      ws.removeListener("open", onOpen);
+      reject(err);
+    };
+    ws.once("open", onOpen);
+    ws.once("error", onError);
+  });
+}
+function sleep2(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+// src/index.ts
+function parseArgs(argv) {
+  const [first, ...rest] = argv;
+  let command = "serve";
+  let flagArgs = argv;
+  if (first === "login" || first === "logout" || first === "serve" || first === "reverse" || first === "help" || first === "version") {
+    command = first;
+    flagArgs = rest;
+  } else if (first === "--help" || first === "-h") {
+    command = "help";
+    flagArgs = rest;
+  } else if (first === "--version" || first === "-v") {
+    command = "version";
+    flagArgs = rest;
+  }
+  const flags = /* @__PURE__ */ new Map();
+  const unknownPositional = [];
+  for (let i = 0; i < flagArgs.length; i += 1) {
+    const arg = flagArgs[i];
+    if (arg === void 0) {
+      continue;
+    }
+    if (!arg.startsWith("--")) {
+      unknownPositional.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf("=");
+    if (eq > -1) {
+      flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+      continue;
+    }
+    const next = flagArgs[i + 1];
+    if (next !== void 0 && !next.startsWith("--")) {
+      flags.set(arg.slice(2), next);
+      i += 1;
+    } else {
+      flags.set(arg.slice(2), true);
+    }
+  }
+  if (unknownPositional.length > 0) {
+    throw new Error(
+      `Unknown positional arguments: ${unknownPositional.join(", ")}. Run \`npx @myspec/mcp-server --help\` for usage.`
+    );
+  }
+  return { command, flags };
+}
+function flagString(flags, key) {
+  const value = flags.get(key);
+  return typeof value === "string" ? value : void 0;
+}
+function flagBool(flags, key) {
+  return flags.get(key) === true || flags.get(key) === "true";
+}
+function printHelp() {
+  const lines = [
+    "myspec-mcp \u2014 MCP server for the MySpec platform",
+    "",
+    "Usage: npx @myspec/mcp-server [command] [flags]",
+    "  (or `myspec-mcp [command]` when installed on your PATH)",
+    "",
+    "Commands:",
+    "  (default)               Start MCP server over stdio",
+    "  serve                   Start MCP server over stdio",
+    "  login                   Sign in via browser (chooser page on the webapp)",
+    "  login --paste           Sign in by pasting a one-time code",
+    "  logout                  Revoke refresh token and clear local credentials",
+    "  reverse --root <dir>    Connect to ai-agent and expose local_fs tools (spike).",
+    "                          Uses the saved refresh_token from `npx @myspec/mcp-server login`",
+    "                          to obtain & auto-refresh access tokens. Override with",
+    "                          --access-token <jwt> or MYSPEC_ACCESS_TOKEN for local testing.",
+    "  --version               Print version",
+    "  --help                  Print this help",
+    "",
+    "Login flags:",
+    "  --user-auth-url <url>   user-auth base URL (overrides env / defaults)",
+    "  --platform-url <url>    platform API base URL",
+    "  --webapp-url <url>      webapp base URL hosting the /auth/cli page",
+    "",
+    "Environment:",
+    "  MYSPEC_USER_AUTH_URL    user-auth base URL (default https://auth.myspec.dev)",
+    "  MYSPEC_PLATFORM_URL     platform API base URL (default https://api.myspec.dev)",
+    "  MYSPEC_WEBAPP_URL       webapp base URL (default derived from user-auth host)",
+    "  MYSPEC_REFRESH_TOKEN    Skip file-based credentials; the server mints a",
+    "                          fresh access token on first use via this refresh",
+    "                          token."
+  ];
+  process.stderr.write(lines.join("\n") + "\n");
+}
+function readVersion() {
+  try {
+    const pkgUrl = new URL("../package.json", import.meta.url);
+    const raw = readFileSync(pkgUrl, "utf8");
+    const pkg = JSON.parse(raw);
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+    return "unknown";
+  } catch (err) {
+    process.stderr.write(`myspec-mcp: could not read version: ${String(err)}
+`);
+    return "unknown";
+  }
+}
+async function main(argv = process.argv.slice(2)) {
+  const { command, flags } = parseArgs(argv);
+  switch (command) {
+    case "help":
+      printHelp();
+      return;
+    case "version":
+      process.stderr.write(readVersion() + "\n");
+      return;
+    case "login":
+      await runLogin({
+        paste: flagBool(flags, "paste"),
+        userAuthUrl: flagString(flags, "user-auth-url"),
+        platformUrl: flagString(flags, "platform-url"),
+        webappUrl: flagString(flags, "webapp-url")
+      });
+      return;
+    case "logout":
+      await runLogout();
+      return;
+    case "reverse":
+      await runReverseCommand(flags);
+      return;
+    case "serve":
+    default:
+      await runServe(flags);
+      return;
+  }
+}
+async function runReverseCommand(flags) {
+  const root = flagString(flags, "root") ?? process.cwd();
+  const agentUrl = flagString(flags, "agent-url") ?? process.env.MYSPEC_AI_AGENT_WS_URL ?? "ws://localhost:3001/mcp/reverse";
+  const inlineToken = flagString(flags, "access-token") ?? process.env.MYSPEC_ACCESS_TOKEN;
+  let getAccessToken;
+  let onAuthFailed;
+  if (inlineToken) {
+    const staticToken = inlineToken;
+    getAccessToken = () => Promise.resolve(staticToken);
+    onAuthFailed = void 0;
+  } else {
+    const envConfig = readEnvRefreshConfig();
+    const store = createCompositeCredentialsStore({
+      fileStore: createFileCredentialsStore(),
+      envConfig
+    });
+    const tokenManager = new TokenManager({ store, envFallback: envConfig });
+    getAccessToken = () => tokenManager.getValidAccessToken();
+    onAuthFailed = async () => {
+      await tokenManager.forceRefresh();
+    };
+  }
+  await runReverse({
+    root,
+    agentUrl,
+    getAccessToken,
+    onAuthFailed,
+    version: readVersion()
+  });
+}
+async function runServe(flags) {
+  const envConfig = readEnvRefreshConfig();
+  const store = createCompositeCredentialsStore({
+    fileStore: createFileCredentialsStore(),
+    envConfig
+  });
+  const initial = await store.load();
+  if (!initial) {
+    process.stderr.write(
+      "myspec-mcp: starting unauthenticated. Run `npx @myspec/mcp-server login` (or set MYSPEC_REFRESH_TOKEN) to enable tools.\n"
+    );
+  }
+  const config = resolveConfig({
+    cliUserAuthUrl: flagString(flags, "user-auth-url"),
+    cliPlatformUrl: flagString(flags, "platform-url"),
+    storedUserAuthUrl: initial?.userAuthUrl,
+    storedPlatformUrl: initial?.platformUrl
+  });
+  const tokenManager = new TokenManager({
+    store,
+    envFallback: envConfig
+  });
+  const client = new PlatformClient({ baseUrl: config.platformUrl, tokenManager });
+  await startStdioServer({ client, version: readVersion() });
+}
+function isCliEntry() {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+  try {
+    let resolved = entry;
+    try {
+      resolved = realpathSync(entry);
+    } catch {
+    }
+    return import.meta.url === pathToFileURL(resolved).href;
+  } catch {
+    return false;
+  }
+}
+if (isCliEntry()) {
+  main().catch((err) => {
+    if (err instanceof NeedsLoginError || err instanceof ConfigError) {
+      process.stderr.write(err.message + "\n");
+      process.exit(2);
+    }
+    const message = err instanceof Error ? err.stack ?? err.message : String(err);
+    process.stderr.write(message + "\n");
+    process.exit(1);
+  });
+}
+export {
+  main,
+  runServe
+};