@ashlr/stack-core 0.1.1 → 0.3.0

package/src/config.ts

@@ -96,10 +96,7 @@ export function hasConfig(cwd: string = process.cwd()): boolean {
 
 interface ShapeFile {
   stack: { version: string; template?: string };
-  services: Record<
-    string,
-    { provider: string; secrets: string[]; mcp?: string }
-  >;
+  services: Record<string, { provider: string; secrets: string[]; mcp?: string }>;
   environments: EnvironmentEntry[];
 }
 
@@ -154,10 +151,7 @@ export async function readConfig(cwd: string = process.cwd()): Promise<StackConf
 // Write: split and route to the two files, auto-gitignore the local one
 // ---------------------------------------------------------------------------
 
-export async function writeConfig(
-  config: StackConfig,
-  cwd: string = process.cwd(),
-): Promise<void> {
+export async function writeConfig(config: StackConfig, cwd: string = process.cwd()): Promise<void> {
   const { shape, instance } = split(config);
 
   const shapeHeader =
@@ -169,8 +163,7 @@ export async function writeConfig(
     "utf-8",
   );
 
-  const instanceHeader =
-    "# Ashlr Stack — local instance data. Auto-generated; do not commit.\n";
+  const instanceHeader = "# Ashlr Stack — local instance data. Auto-generated; do not commit.\n";
   await writeFile(
     resolveLocalConfigPath(cwd),
     instanceHeader + stringifyToml(instance as unknown as Record<string, unknown>),
@@ -193,6 +186,25 @@ export async function writeConfig(
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * The service named `name`, or undefined. An own-property lookup, so a name
+ * like `constructor` or `toString` that is not configured is not mistaken for
+ * an inherited Object.prototype member.
+ */
+export function getService(config: StackConfig, name: string): ServiceEntry | undefined {
+  return Object.hasOwn(config.services, name) ? config.services[name] : undefined;
+}
+
+function setOwnService<T>(services: Record<string, T>, name: string, entry: T): void {
+  // Service names are data, including __proto__; never invoke prototype setters.
+  Object.defineProperty(services, name, {
+    value: entry,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+}
+
 function split(config: StackConfig): { shape: ShapeFile; instance: InstanceFile } {
   const shape: ShapeFile = {
     stack: {
@@ -207,18 +219,18 @@ function split(config: StackConfig): { shape: ShapeFile; instance: InstanceFile
     services: {},
   };
   for (const [name, entry] of Object.entries(config.services)) {
-    shape.services[name] = {
+    setOwnService(shape.services, name, {
       provider: entry.provider,
       secrets: entry.secrets,
       ...(entry.mcp ? { mcp: entry.mcp } : {}),
-    };
+    });
     const inst: InstanceFile["services"][string] = {};
     if (entry.resource_id) inst.resource_id = entry.resource_id;
     if (entry.region) inst.region = entry.region;
     if (entry.meta) inst.meta = entry.meta;
     if (entry.created_at) inst.created_at = entry.created_at;
     if (entry.created_by) inst.created_by = entry.created_by;
-    if (Object.keys(inst).length > 0) instance.services[name] = inst;
+    if (Object.keys(inst).length > 0) setOwnService(instance.services, name, inst);
   }
   return { shape, instance };
 }
@@ -226,8 +238,9 @@ function split(config: StackConfig): { shape: ShapeFile; instance: InstanceFile
 function merge(shape: ShapeFile, instance: InstanceFile): StackConfig {
   const services: Record<string, ServiceEntry> = {};
   for (const [name, s] of Object.entries(shape.services ?? {})) {
-    const i = instance.services?.[name] ?? {};
-    services[name] = {
+    const i =
+      instance.services && Object.hasOwn(instance.services, name) ? instance.services[name] : {};
+    setOwnService(services, name, {
       provider: s.provider,
       secrets: s.secrets,
       ...(s.mcp ? { mcp: s.mcp } : {}),
@@ -236,7 +249,7 @@ function merge(shape: ShapeFile, instance: InstanceFile): StackConfig {
       ...(i.meta ? { meta: i.meta } : {}),
       created_at: i.created_at ?? "1970-01-01T00:00:00Z",
       ...(i.created_by ? { created_by: i.created_by } : {}),
-    };
+    });
   }
   return {
     stack: {
@@ -265,7 +278,7 @@ function normalizeLegacy(raw: Record<string, unknown>): StackConfig {
     environments,
   };
   for (const [name, entry] of Object.entries(services)) {
-    out.services[name] = {
+    setOwnService(out.services, name, {
       provider: (entry.provider as string) ?? name,
       secrets: (entry.secrets as string[]) ?? [],
       ...(typeof entry.mcp === "string" ? { mcp: entry.mcp } : {}),
@@ -274,7 +287,7 @@ function normalizeLegacy(raw: Record<string, unknown>): StackConfig {
       ...(entry.meta ? { meta: entry.meta as Record<string, unknown> } : {}),
       created_at: (entry.created_at as string) ?? new Date().toISOString(),
       ...(typeof entry.created_by === "string" ? { created_by: entry.created_by } : {}),
-    };
+    });
   }
   return out;
 }

package/src/detect-source.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
+import { SourceDirectoryNotFoundError } from "./errors.ts";
 
 /**
  * Source-level provider detection. Reads package.json / requirements.txt /
@@ -37,7 +38,8 @@ const JS_RULES: DepRule[] = [
   { provider: "neon", matches: (d) => d.startsWith("@neondatabase/"), confidence: "high" },
   {
     provider: "vercel",
-    matches: (d) => d === "@vercel/analytics" || d === "@vercel/speed-insights" || d === "@vercel/kv",
+    matches: (d) =>
+      d === "@vercel/analytics" || d === "@vercel/speed-insights" || d === "@vercel/kv",
     confidence: "medium",
   },
   { provider: "sentry", matches: (d) => d.startsWith("@sentry/"), confidence: "high" },
@@ -48,7 +50,11 @@ const JS_RULES: DepRule[] = [
   },
   { provider: "openai", matches: (d) => d === "openai", confidence: "high" },
   { provider: "anthropic", matches: (d) => d === "@anthropic-ai/sdk", confidence: "high" },
-  { provider: "stripe", matches: (d) => d === "stripe" || d === "@stripe/stripe-js", confidence: "high" },
+  {
+    provider: "stripe",
+    matches: (d) => d === "stripe" || d === "@stripe/stripe-js",
+    confidence: "high",
+  },
   { provider: "clerk", matches: (d) => d.startsWith("@clerk/"), confidence: "high" },
   { provider: "resend", matches: (d) => d === "resend", confidence: "high" },
   {
@@ -102,7 +108,11 @@ const JS_RULES: DepRule[] = [
 ];
 
 const PY_RULES: DepRule[] = [
-  { provider: "supabase", matches: (d) => d === "supabase" || d === "supabase-py", confidence: "high" },
+  {
+    provider: "supabase",
+    matches: (d) => d === "supabase" || d === "supabase-py",
+    confidence: "high",
+  },
   { provider: "openai", matches: (d) => d === "openai", confidence: "high" },
   { provider: "anthropic", matches: (d) => d === "anthropic", confidence: "high" },
   { provider: "sentry", matches: (d) => d === "sentry-sdk", confidence: "high" },
@@ -120,18 +130,34 @@ const GO_RULES: DepRule[] = [
     matches: (d) => d.startsWith("github.com/supabase-community/"),
     confidence: "high",
   },
-  { provider: "openai", matches: (d) => d === "github.com/sashabaranov/go-openai", confidence: "high" },
+  {
+    provider: "openai",
+    matches: (d) => d === "github.com/sashabaranov/go-openai",
+    confidence: "high",
+  },
   {
     provider: "anthropic",
     matches: (d) => d.startsWith("github.com/liushuangls/go-anthropic"),
     confidence: "medium",
   },
-  { provider: "sentry", matches: (d) => d === "github.com/getsentry/sentry-go", confidence: "high" },
-  { provider: "stripe", matches: (d) => d.startsWith("github.com/stripe/stripe-go"), confidence: "high" },
+  {
+    provider: "sentry",
+    matches: (d) => d === "github.com/getsentry/sentry-go",
+    confidence: "high",
+  },
+  {
+    provider: "stripe",
+    matches: (d) => d.startsWith("github.com/stripe/stripe-go"),
+    confidence: "high",
+  },
 ];
 
 const RUST_RULES: DepRule[] = [
-  { provider: "openai", matches: (d) => d === "async-openai" || d === "openai", confidence: "high" },
+  {
+    provider: "openai",
+    matches: (d) => d === "async-openai" || d === "openai",
+    confidence: "high",
+  },
   { provider: "sentry", matches: (d) => d === "sentry", confidence: "high" },
   { provider: "stripe", matches: (d) => d === "async-stripe", confidence: "high" },
 ];
@@ -140,6 +166,18 @@ export async function scanSource(
   cwd: string,
   _opts: SourceScanOptions = {},
 ): Promise<SourceDetection[]> {
+  let root: Awaited<ReturnType<typeof stat>>;
+  try {
+    root = await stat(cwd);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      throw new SourceDirectoryNotFoundError(cwd, { cause: error });
+    }
+    throw error;
+  }
+  if (!root.isDirectory()) throw new SourceDirectoryNotFoundError(cwd);
+
   const hits = new Map<string, SourceDetection>();
 
   const add = (provider: string, signal: string, confidence: DetectionConfidence) => {
@@ -202,7 +240,10 @@ async function scanPython(
   if (existsSync(reqPath)) {
     const text = await readFile(reqPath, "utf-8");
     for (const line of text.split(/\r?\n/)) {
-      const pkg = line.split(/[=<>!~\[]/)[0].trim().toLowerCase();
+      const pkg = line
+        .split(/[=<>!~\[]/)[0]
+        .trim()
+        .toLowerCase();
       if (!pkg || pkg.startsWith("#")) continue;
       for (const rule of PY_RULES) {
         if (rule.matches(pkg)) add(rule.provider, `requirements.txt:${pkg}`, rule.confidence);

package/src/detect.ts

@@ -55,7 +55,11 @@ const RULES: DetectionRule[] = [
     matches: (n) => /^UPSTASH_/.test(n),
     primary: (n) => n === "UPSTASH_MANAGEMENT_TOKEN",
   },
-  { provider: "openai", matches: (n) => /^OPENAI_/.test(n), primary: (n) => n === "OPENAI_API_KEY" },
+  {
+    provider: "openai",
+    matches: (n) => /^OPENAI_/.test(n),
+    primary: (n) => n === "OPENAI_API_KEY",
+  },
   {
     provider: "anthropic",
     matches: (n) => /^ANTHROPIC_/.test(n),
@@ -96,11 +100,14 @@ const RULES: DetectionRule[] = [
     matches: (n) => /^STRIPE_/.test(n),
     primary: (n) => n === "STRIPE_SECRET_KEY",
   },
-  { provider: "resend", matches: (n) => /^RESEND_/.test(n), primary: (n) => n === "RESEND_API_KEY" },
+  {
+    provider: "resend",
+    matches: (n) => /^RESEND_/.test(n),
+    primary: (n) => n === "RESEND_API_KEY",
+  },
   {
     provider: "clerk",
-    matches: (n) =>
-      /^CLERK_/.test(n) || /^NEXT_PUBLIC_CLERK_/.test(n),
+    matches: (n) => /^CLERK_/.test(n) || /^NEXT_PUBLIC_CLERK_/.test(n),
     primary: (n) => n === "CLERK_SECRET_KEY",
   },
   {
@@ -160,7 +167,8 @@ export function groupByProvider(envNames: string[]): Record<string, string[]> {
   for (const name of envNames) {
     const provider = detectProvider(name);
     if (!provider) continue;
-    (out[provider] ??= []).push(name);
+    if (!out[provider]) out[provider] = [];
+    out[provider].push(name);
   }
   return out;
 }

package/src/errors.ts

@@ -27,3 +27,9 @@ export class ConfigNotFoundError extends StackError {
     super("CONFIG_NOT_FOUND", `No .stack.toml at ${path}. Run \`stack init\` first.`);
   }
 }
+
+export class SourceDirectoryNotFoundError extends StackError {
+  constructor(path: string, options?: { cause?: unknown }) {
+    super("SOURCE_DIRECTORY_NOT_FOUND", `Source directory not found: ${path}`, options);
+  }
+}

package/src/http.ts

@@ -48,7 +48,7 @@ export function defaultRetryOn(res: Response): boolean {
  * executed exactly once unless `idempotent: true` is passed.
  */
 export async function fetchWithRetry(
-  input: RequestInfo | URL,
+  input: string | URL | Request,
   init?: RequestInit,
   opts: RetryOptions = {},
 ): Promise<Response> {
@@ -78,7 +78,6 @@ export async function fetchWithRetry(
       const waitMs = computeDelay(res, attempt, baseDelayMs, maxDelayMs);
       await sleep(waitMs, signal);
       attempt++;
-      continue;
     } catch (err) {
       // Network-level failure (DNS, connection reset, fetch threw). Only retry
       // for idempotent requests — a POST that "failed" may have actually been
@@ -89,7 +88,6 @@ export async function fetchWithRetry(
       const waitMs = computeDelay(undefined, attempt, baseDelayMs, maxDelayMs);
       await sleep(waitMs, signal);
       attempt++;
-      continue;
     }
   }
 
@@ -125,7 +123,7 @@ function computeDelay(
     const parsed = parseRetryAfter(header);
     if (parsed !== undefined) return Math.max(0, Math.min(parsed, maxDelayMs * 4));
   }
-  const exp = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
+  const exp = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
   const jitter = Math.random() * baseDelayMs;
   return exp + jitter;
 }
@@ -181,7 +179,10 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  * `AbortSignal.any` where available; falling back to a manual linkage on older
  * runtimes.
  */
-function mergeSignal(init: RequestInit | undefined, external?: AbortSignal): RequestInit | undefined {
+function mergeSignal(
+  init: RequestInit | undefined,
+  external?: AbortSignal,
+): RequestInit | undefined {
   if (!external) return init;
   const existing = init?.signal ?? undefined;
   if (!existing) return { ...init, signal: external };

package/src/index.ts

@@ -1,7 +1,20 @@
 export * from "./config.ts";
+export { STACK_MANIFEST, type StackManifest, type StackComponent } from "./stack-manifest.ts";
+export {
+  isEnabled as isTelemetryEnabled,
+  promptFirstRun as promptTelemetryFirstRun,
+  emit as emitTelemetry,
+  disable as disableTelemetry,
+  enable as enableTelemetry,
+  type TelemetryEvent,
+  type TelemetryConfig,
+} from "./telemetry.ts";
+export { detectPackageManager, installCommand } from "./pm-detect.ts";
+export type { PackageManager } from "./pm-detect.ts";
 export * from "./phantom.ts";
 export * from "./providers/_base.ts";
 export { providers, getProvider, listProviderNames } from "./providers/index.ts";
+export { takeRevealRefusals } from "./providers/_helpers.ts";
 export * from "./errors.ts";
 export * from "./templates.ts";
 export * from "./pipeline.ts";
@@ -47,6 +60,8 @@ export {
   type RecipeDraft,
   type RecipeProvider,
 } from "./ai/inference.ts";
+export { findSwap, suggestSwaps, SWAP_PAIRS } from "./swap.ts";
+export type { SwapPair } from "./swap.ts";
 export {
   CircuitBreaker,
   type CircuitBreakerOptions,
@@ -59,3 +74,4 @@ export {
   type RateCard,
   type UsageRecord,
 } from "./ai/cost-tracker.ts";
+export * from "./agent-onboard.ts";

package/src/mcp-writer.ts

@@ -10,21 +10,79 @@ interface McpFile {
   [key: string]: unknown;
 }
 
-export async function mergeMcpEntry(entry: McpServerEntry, cwd: string = process.cwd()): Promise<void> {
+/**
+ * Other MCP clients that read a project-level `mcpServers` JSON file. Stack
+ * mirrors entries into these only when the client's directory already exists
+ * in the project (the user opted into that client); it never creates them.
+ */
+const MIRROR_TARGETS = [
+  { client: "cursor", dir: ".cursor", file: "mcp.json" },
+  { client: "gemini", dir: ".gemini", file: "settings.json" },
+] as const;
+
+type MirrorClient = (typeof MIRROR_TARGETS)[number]["client"];
+
+export async function mergeMcpEntry(
+  entry: McpServerEntry,
+  cwd: string = process.cwd(),
+): Promise<void> {
   const path = join(cwd, MCP_FILENAME);
   const current = await readMcp(path);
+  const previous = current.mcpServers[entry.name];
   current.mcpServers[entry.name] = toJsonShape(entry);
   await writeFile(path, `${JSON.stringify(current, null, 2)}\n`, "utf-8");
+
+  for (const t of MIRROR_TARGETS) {
+    if (!existsSync(join(cwd, t.dir))) continue;
+    const target = join(cwd, t.dir, t.file);
+    try {
+      const doc = await readMcp(target);
+      const next = toClientShape(entry, t.client);
+      const existing = doc.mcpServers[entry.name];
+      // Client configs are user-owned: replace a same-name entry only when it
+      // is what Stack itself mirrored (now or from the previous .mcp.json
+      // entry). A hand-written entry is left as it is.
+      if (existing !== undefined) {
+        if (sameJson(existing, next)) continue;
+        const mirrored = previous && toClientShape(asEntry(entry.name, previous), t.client);
+        if (!mirrored || !sameJson(existing, mirrored)) continue;
+      }
+      doc.mcpServers[entry.name] = next;
+      await writeFile(target, `${JSON.stringify(doc, null, 2)}\n`, "utf-8");
+    } catch {
+      // A client file Stack cannot parse is left untouched: .mcp.json is the
+      // source of truth and a broken sibling must not fail provisioning.
+    }
+  }
 }
 
 export async function removeMcpEntry(name: string, cwd: string = process.cwd()): Promise<void> {
   const path = join(cwd, MCP_FILENAME);
   if (!existsSync(path)) return;
   const current = await readMcp(path);
-  if (current.mcpServers[name]) {
+  const previous = current.mcpServers[name];
+  if (previous) {
     delete current.mcpServers[name];
     await writeFile(path, `${JSON.stringify(current, null, 2)}\n`, "utf-8");
   }
+  // Without a .mcp.json entry there is nothing to prove a client entry of the
+  // same name was written by Stack, so the client configs are not touched.
+  if (!previous) return;
+
+  for (const t of MIRROR_TARGETS) {
+    const target = join(cwd, t.dir, t.file);
+    if (!existsSync(target)) continue;
+    try {
+      const doc = await readMcp(target);
+      const existing = doc.mcpServers[name];
+      if (existing && sameJson(existing, toClientShape(asEntry(name, previous), t.client))) {
+        delete doc.mcpServers[name];
+        await writeFile(target, `${JSON.stringify(doc, null, 2)}\n`, "utf-8");
+      }
+    } catch {
+      // Unparseable sibling config: leave it alone.
+    }
+  }
 }
 
 async function readMcp(path: string): Promise<McpFile> {
@@ -48,3 +106,40 @@ function toJsonShape(entry: McpServerEntry): Record<string, unknown> {
   if (entry.headers) out.headers = entry.headers;
   return out;
 }
+
+/**
+ * Gemini CLI names remote transports differently: `httpUrl` for streamable
+ * HTTP and `url` for SSE, and it has no `type` field. Cursor accepts the
+ * generic shape.
+ */
+function toClientShape(entry: McpServerEntry, client: MirrorClient): Record<string, unknown> {
+  if (client !== "gemini") return toJsonShape(entry);
+  const out: Record<string, unknown> = {};
+  if (entry.command) out.command = entry.command;
+  if (entry.args) out.args = entry.args;
+  if (entry.url) out[entry.type === "http" ? "httpUrl" : "url"] = entry.url;
+  if (entry.env) out.env = entry.env;
+  if (entry.headers) out.headers = entry.headers;
+  return out;
+}
+
+/** Rebuild an entry from its `.mcp.json` shape (the inverse of toJsonShape). */
+function asEntry(name: string, json: Record<string, unknown>): McpServerEntry {
+  return { ...json, name } as McpServerEntry;
+}
+
+function sameJson(a: unknown, b: unknown): boolean {
+  return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+}
+
+function sortKeys(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(sortKeys);
+  if (v && typeof v === "object") {
+    return Object.fromEntries(
+      Object.entries(v as Record<string, unknown>)
+        .sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0))
+        .map(([k, val]) => [k, sortKeys(val)]),
+    );
+  }
+  return v;
+}

package/src/oauth.ts

@@ -1,10 +1,18 @@
+import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
-import { spawn } from "node:child_process";
-import { platform } from "node:os";
 import type { AddressInfo } from "node:net";
+import { platform } from "node:os";
 import { StackError } from "./errors.ts";
 
+/**
+ * The deterministic loopback port Stack tries first for OAuth callbacks.
+ * Register `http://127.0.0.1:8787/callback` as the redirect URI in your
+ * OAuth app (Supabase, GitHub, etc.) so no wildcard matching is needed.
+ * Stack falls back to a random OS-assigned port only when 8787 is in use.
+ */
+export const STACK_OAUTH_PORT = 8787;
+
 /**
  * Minimal OAuth PKCE helper suitable for CLI/desktop OAuth flows. Spins up a
  * localhost loopback server, opens the browser to the provider auth URL,
@@ -102,60 +110,80 @@ async function captureCallback(args: CaptureArgs): Promise<{ code: string; redir
     }, args.timeoutMs);
     server.on("close", () => clearTimeout(timer));
 
-    server.listen(0, "127.0.0.1", () => {
-      const { port } = server.address() as AddressInfo;
-      const redirectUri = `http://127.0.0.1:${port}/callback`;
-
-      server.on("request", (req, res) => {
-        if (!req.url) {
-          res.writeHead(400).end();
-          return;
-        }
-        const url = new URL(req.url, "http://127.0.0.1");
-        if (url.pathname !== "/callback") {
-          res.writeHead(404).end();
-          return;
-        }
-        const receivedState = url.searchParams.get("state");
-        const code = url.searchParams.get("code");
-        const error = url.searchParams.get("error");
-        if (error) {
+    function startListening(preferredPort: number) {
+      server.listen(preferredPort, "127.0.0.1", () => {
+        const { port } = server.address() as AddressInfo;
+        const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+        server.on("request", (req, res) => {
+          if (!req.url) {
+            res.writeHead(400).end();
+            return;
+          }
+          const url = new URL(req.url, "http://127.0.0.1");
+          if (url.pathname !== "/callback") {
+            res.writeHead(404).end();
+            return;
+          }
+          const receivedState = url.searchParams.get("state");
+          const code = url.searchParams.get("code");
+          const error = url.searchParams.get("error");
+          if (error) {
+            res
+              .writeHead(400, { "content-type": "text/html" })
+              .end(htmlPage("error", args.providerName, error));
+            server.close();
+            reject(new StackError("OAUTH_DENIED", `${args.providerName} auth denied: ${error}`));
+            return;
+          }
+          if (!code || receivedState !== args.state) {
+            res
+              .writeHead(400, { "content-type": "text/html" })
+              .end(htmlPage("error", args.providerName, "state mismatch"));
+            server.close();
+            reject(
+              new StackError("OAUTH_STATE_MISMATCH", "Auth callback state did not match request."),
+            );
+            return;
+          }
           res
-            .writeHead(400, { "content-type": "text/html" })
-            .end(htmlPage("error", args.providerName, error));
+            .writeHead(200, { "content-type": "text/html" })
+            .end(htmlPage("ok", args.providerName));
           server.close();
-          reject(new StackError("OAUTH_DENIED", `${args.providerName} auth denied: ${error}`));
-          return;
-        }
-        if (!code || receivedState !== args.state) {
-          res
-            .writeHead(400, { "content-type": "text/html" })
-            .end(htmlPage("error", args.providerName, "state mismatch"));
-          server.close();
-          reject(new StackError("OAUTH_STATE_MISMATCH", "Auth callback state did not match request."));
-          return;
-        }
-        res.writeHead(200, { "content-type": "text/html" }).end(htmlPage("ok", args.providerName));
-        server.close();
-        resolve({ code, redirectUri });
-      });
-
-      const params = new URLSearchParams({
-        response_type: "code",
-        client_id: args.clientId,
-        redirect_uri: redirectUri,
-        state: args.state,
-        code_challenge: args.challenge,
-        code_challenge_method: "S256",
-        ...(args.scope ? { scope: args.scope } : {}),
-        ...(args.extraAuthParams ?? {}),
+          resolve({ code, redirectUri });
+        });
+
+        const params = new URLSearchParams({
+          response_type: "code",
+          client_id: args.clientId,
+          redirect_uri: redirectUri,
+          state: args.state,
+          code_challenge: args.challenge,
+          code_challenge_method: "S256",
+          ...(args.scope ? { scope: args.scope } : {}),
+          ...(args.extraAuthParams ?? {}),
+        });
+        const authorizeUrl = `${args.authUrl}?${params.toString()}`;
+
+        console.log(`\n  Opening ${args.providerName} in your browser…`);
+        console.log(`  If nothing happens, visit:\n    ${authorizeUrl}\n`);
+        openBrowser(authorizeUrl);
       });
-      const authorizeUrl = `${args.authUrl}?${params.toString()}`;
-
-      console.log(`\n  Opening ${args.providerName} in your browser…`);
-      console.log(`  If nothing happens, visit:\n    ${authorizeUrl}\n`);
-      openBrowser(authorizeUrl);
+    }
+
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "EADDRINUSE") {
+        console.warn(
+          `  [stack] Port ${STACK_OAUTH_PORT} in use, falling back to OS-assigned port.`,
+        );
+        server.removeAllListeners("error");
+        startListening(0);
+      } else {
+        reject(new StackError("OAUTH_SERVER_ERROR", `OAuth server error: ${err.message}`));
+      }
     });
+
+    startListening(STACK_OAUTH_PORT);
   });
 }
 
@@ -169,7 +197,11 @@ function openBrowser(url: string): void {
 }
 
 function base64url(buf: Buffer | Uint8Array): string {
-  return Buffer.from(buf).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  return Buffer.from(buf)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
 }
 
 function htmlPage(kind: "ok" | "error", provider: string, detail?: string): string {