@ashlr/stack-core 0.1.1

package/src/detect.ts

@@ -0,0 +1,207 @@
+/**
+ * Given the name of an env var, guess which curated provider owns it. Used by
+ * `stack import` to auto-wire existing .env files into Stack's service map.
+ *
+ * Heuristics are deliberately conservative — if the match isn't obvious we
+ * return `undefined` and the caller stores the secret without associating it
+ * with any provider. Users can always `stack add <name>` later to reconcile.
+ */
+
+import type { ServiceEntry } from "./config.ts";
+
+export interface DetectedService {
+  provider: string;
+  secrets: string[];
+  mcp?: string;
+}
+
+interface DetectionRule {
+  provider: string;
+  mcp?: string;
+  /** Match a single env var name to this provider. */
+  matches: (name: string) => boolean;
+  /** Optional: pick the "primary" secret name that implies the service is present. */
+  primary?: (name: string) => boolean;
+}
+
+const RULES: DetectionRule[] = [
+  {
+    provider: "supabase",
+    mcp: "supabase",
+    matches: (n) => /^(NEXT_PUBLIC_)?SUPABASE_(URL|ANON_KEY|SERVICE_ROLE_KEY|JWT_SECRET)$/.test(n),
+    primary: (n) => /^(NEXT_PUBLIC_)?SUPABASE_URL$/.test(n),
+  },
+  {
+    // DATABASE_URL is intentionally NOT attributed here — it's a generic
+    // Postgres convention used by Supabase, Railway, Render, PlanetScale,
+    // and plain self-hosted Postgres. Only NEON_* keys identify Neon.
+    provider: "neon",
+    matches: (n) => /^NEON_/.test(n),
+    primary: (n) => n === "NEON_API_KEY",
+  },
+  {
+    provider: "vercel",
+    matches: (n) => /^VERCEL_/.test(n),
+    primary: (n) => n === "VERCEL_TOKEN",
+  },
+  {
+    provider: "railway",
+    matches: (n) => /^RAILWAY_/.test(n),
+    primary: (n) => n === "RAILWAY_TOKEN",
+  },
+  { provider: "fly", matches: (n) => /^FLY_/.test(n), primary: (n) => n === "FLY_API_TOKEN" },
+  {
+    provider: "upstash",
+    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: "anthropic",
+    matches: (n) => /^ANTHROPIC_/.test(n),
+    primary: (n) => n === "ANTHROPIC_API_KEY",
+  },
+  { provider: "xai", matches: (n) => /^XAI_/.test(n), primary: (n) => n === "XAI_API_KEY" },
+  {
+    provider: "deepseek",
+    matches: (n) => /^DEEPSEEK_/.test(n),
+    primary: (n) => n === "DEEPSEEK_API_KEY",
+  },
+  {
+    provider: "posthog",
+    mcp: "posthog",
+    matches: (n) => /^(NEXT_PUBLIC_)?POSTHOG_/.test(n),
+    primary: (n) => n === "POSTHOG_PERSONAL_API_KEY",
+  },
+  {
+    provider: "sentry",
+    mcp: "sentry",
+    matches: (n) => /^SENTRY_/.test(n) || /^(NEXT_PUBLIC_)?SENTRY_DSN$/.test(n),
+    primary: (n) => n === "SENTRY_AUTH_TOKEN",
+  },
+  {
+    provider: "github",
+    mcp: "github",
+    matches: (n) => /^GITHUB_(TOKEN|PERSONAL_ACCESS_TOKEN)$/.test(n),
+    primary: (n) => n === "GITHUB_TOKEN",
+  },
+  {
+    provider: "linear",
+    mcp: "linear",
+    matches: (n) => /^LINEAR_/.test(n),
+    primary: (n) => n === "LINEAR_API_KEY",
+  },
+  {
+    provider: "stripe",
+    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: "clerk",
+    matches: (n) =>
+      /^CLERK_/.test(n) || /^NEXT_PUBLIC_CLERK_/.test(n),
+    primary: (n) => n === "CLERK_SECRET_KEY",
+  },
+  {
+    provider: "aws",
+    matches: (n) => /^AWS_(ACCESS_KEY_ID|SECRET_ACCESS_KEY|REGION|SESSION_TOKEN)$/.test(n),
+    primary: (n) => n === "AWS_ACCESS_KEY_ID",
+  },
+  {
+    provider: "cloudflare",
+    matches: (n) => /^CLOUDFLARE_(API_TOKEN|ACCOUNT_ID|ZONE_ID)$/.test(n) || /^CF_/.test(n),
+    primary: (n) => n === "CLOUDFLARE_API_TOKEN",
+  },
+  {
+    provider: "turso",
+    matches: (n) => /^TURSO_(DATABASE_URL|AUTH_TOKEN|PLATFORM_TOKEN)$/.test(n),
+    primary: (n) => n === "TURSO_DATABASE_URL",
+  },
+  {
+    provider: "convex",
+    matches: (n) => /^(NEXT_PUBLIC_)?CONVEX_(URL|DEPLOY_KEY)$/.test(n),
+    primary: (n) => n === "CONVEX_DEPLOY_KEY",
+  },
+  {
+    provider: "render",
+    matches: (n) => /^RENDER_/.test(n),
+    primary: (n) => n === "RENDER_API_KEY",
+  },
+  {
+    provider: "firebase",
+    matches: (n) => /^FIREBASE_/.test(n),
+    primary: (n) => n === "FIREBASE_SERVICE_ACCOUNT_JSON",
+  },
+  {
+    provider: "replicate",
+    matches: (n) => /^REPLICATE_/.test(n),
+    primary: (n) => n === "REPLICATE_API_TOKEN",
+  },
+  {
+    provider: "braintrust",
+    matches: (n) => /^BRAINTRUST_/.test(n),
+    primary: (n) => n === "BRAINTRUST_API_KEY",
+  },
+  {
+    provider: "modal",
+    matches: (n) => /^MODAL_/.test(n),
+    primary: (n) => n === "MODAL_TOKEN",
+  },
+];
+
+export function detectProvider(envName: string): string | undefined {
+  const rule = RULES.find((r) => r.matches(envName));
+  return rule?.provider;
+}
+
+export function groupByProvider(envNames: string[]): Record<string, string[]> {
+  const out: Record<string, string[]> = {};
+  for (const name of envNames) {
+    const provider = detectProvider(name);
+    if (!provider) continue;
+    (out[provider] ??= []).push(name);
+  }
+  return out;
+}
+
+export function mcpForProvider(provider: string): string | undefined {
+  return RULES.find((r) => r.provider === provider && r.mcp)?.mcp;
+}
+
+/**
+ * Build a minimal ServiceEntry from a detected group of env vars. The caller
+ * is responsible for attaching provider-specific metadata (resource_id,
+ * region) later via `stack doctor --fix` or a manual edit.
+ */
+export function toServiceEntry(provider: string, secrets: string[]): ServiceEntry {
+  return {
+    provider,
+    secrets,
+    mcp: mcpForProvider(provider),
+    created_at: new Date().toISOString(),
+    created_by: "stack import",
+  };
+}
+
+/** Lightweight .env parser (no interpolation, no export support — good enough for import). */
+export function parseEnv(text: string): Array<{ key: string; value: string }> {
+  const out: Array<{ key: string; value: string }> = [];
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (!/^[A-Z_][A-Z0-9_]*$/i.test(key)) continue;
+    out.push({ key, value });
+  }
+  return out;
+}

package/src/env.ts

@@ -0,0 +1,35 @@
+/**
+ * OAuth client IDs for the Ashlr-owned apps registered at each provider.
+ *
+ * These are PUBLIC values — the client secret stays server-side (at the
+ * provider, or in Phantom Cloud for confidential flows). The client ID
+ * alone is not sensitive; it's sent as a URL query parameter in the
+ * browser redirect.
+ *
+ * Values are baked into the published tarball by
+ * `scripts/inject-client-ids.mjs`, which reads the
+ * `OAUTH_*_CLIENT_ID` env vars (provided by GitHub Actions secrets at
+ * release time) and rewrites this file in-place before `npm publish`.
+ * The release workflow restores the file from git after publish, so
+ * these defaults stay empty strings in the repo.
+ *
+ * Provider code resolves the effective client ID with this precedence:
+ *   1. `process.env.<PROVIDER>_STACK_CLIENT_ID`  — runtime override
+ *   2. `OAUTH_DEFAULTS.<provider>`               — shipped default
+ *   3. (none)                                    — fall back to PAT paste
+ */
+
+export const OAUTH_DEFAULTS = {
+  supabase: "",
+  github: "",
+} as const;
+
+export type OAuthProviderName = keyof typeof OAUTH_DEFAULTS;
+
+export function resolveOAuthClientId(
+  provider: OAuthProviderName,
+  envOverride?: string,
+): string | undefined {
+  const value = envOverride ?? OAUTH_DEFAULTS[provider];
+  return value.length > 0 ? value : undefined;
+}

package/src/errors.ts

@@ -0,0 +1,29 @@
+export class StackError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "StackError";
+    this.code = code;
+  }
+}
+
+export class ProviderNotFoundError extends StackError {
+  constructor(name: string) {
+    super("PROVIDER_NOT_FOUND", `No provider registered for "${name}"`);
+  }
+}
+
+export class PhantomNotInstalledError extends StackError {
+  constructor() {
+    super(
+      "PHANTOM_NOT_INSTALLED",
+      "Phantom Secrets is required but not found on PATH. Install with: brew install ashlrai/phantom/phantom",
+    );
+  }
+}
+
+export class ConfigNotFoundError extends StackError {
+  constructor(path: string) {
+    super("CONFIG_NOT_FOUND", `No .stack.toml at ${path}. Run \`stack init\` first.`);
+  }
+}

package/src/http.ts

@@ -0,0 +1,212 @@
+/**
+ * Retry-with-backoff wrapper for `fetch`. Used by provider healthchecks and
+ * read-only API calls; NEVER wire this in on mutating requests (POST / PUT /
+ * PATCH / DELETE) unless the caller explicitly opts in via `idempotent: true`
+ * — we'd rather surface a failure than risk double-charging a provider API or
+ * duplicating an upstream resource.
+ *
+ * Design notes:
+ *   - Pure dependency: `globalThis.fetch` + `setTimeout`. No new runtime deps.
+ *   - Honors `Retry-After` (both integer-seconds and HTTP-date formats).
+ *   - Exponential backoff with jitter so a flock of retries doesn't stampede.
+ *   - Abortable via the passed `AbortSignal` — stops the loop between attempts.
+ */
+
+export interface RetryOptions {
+  /** How many retry attempts (after the initial try). Default: 3. */
+  retries?: number;
+  /** Base delay in ms for the exponential backoff. Default: 400. */
+  baseDelayMs?: number;
+  /** Cap on a single sleep interval (before jitter). Default: 8000. */
+  maxDelayMs?: number;
+  /**
+   * Predicate deciding whether a non-ok Response should be retried. Default
+   * matches the common "transient" set: 429, 500, 502, 503, 504.
+   */
+  retryOn?: (res: Response) => boolean;
+  /**
+   * Whether the caller considers the request safe to retry. If omitted, we
+   * derive from `init.method`: GET and HEAD are idempotent, everything else
+   * is not. Set this explicitly for edge cases (e.g. a PUT to a versioned
+   * URL that the caller knows is safe).
+   */
+  idempotent?: boolean;
+  /** Caller-supplied abort signal. Cancels both the active fetch and any pending sleep. */
+  signal?: AbortSignal;
+}
+
+const DEFAULT_RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+
+export function defaultRetryOn(res: Response): boolean {
+  return DEFAULT_RETRY_STATUSES.has(res.status);
+}
+
+/**
+ * Drop-in replacement for `fetch` that retries idempotent requests on
+ * transient failures. Returns the final `Response` — callers still check
+ * `.ok` themselves. Non-idempotent methods (POST/PUT/PATCH/DELETE) are
+ * executed exactly once unless `idempotent: true` is passed.
+ */
+export async function fetchWithRetry(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  opts: RetryOptions = {},
+): Promise<Response> {
+  const retries = opts.retries ?? 3;
+  const baseDelayMs = opts.baseDelayMs ?? 400;
+  const maxDelayMs = opts.maxDelayMs ?? 8000;
+  const retryOn = opts.retryOn ?? defaultRetryOn;
+  const idempotent = opts.idempotent ?? isIdempotent(init?.method);
+  const signal = opts.signal;
+
+  let attempt = 0;
+  // Track the last non-ok response so a final failure returns something the
+  // caller can inspect (status / body) rather than a synthetic error.
+  let lastResponse: Response | undefined;
+  let lastError: unknown;
+
+  while (true) {
+    if (signal?.aborted) throw abortError(signal);
+
+    try {
+      const res = await fetch(input, mergeSignal(init, signal));
+      if (res.ok || !idempotent || !retryOn(res)) return res;
+
+      lastResponse = res;
+      if (attempt >= retries) return res;
+
+      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
+      // accepted by the remote before the connection dropped.
+      if (isAbortError(err)) throw err;
+      lastError = err;
+      if (!idempotent || attempt >= retries) throw err;
+      const waitMs = computeDelay(undefined, attempt, baseDelayMs, maxDelayMs);
+      await sleep(waitMs, signal);
+      attempt++;
+      continue;
+    }
+  }
+
+  // Unreachable — both branches above either return or throw. The assignment
+  // to lastResponse/lastError keeps TS happy if the loop ever changes shape.
+  void lastResponse;
+  void lastError;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function isIdempotent(method?: string): boolean {
+  if (!method) return true; // fetch defaults to GET
+  const upper = method.toUpperCase();
+  return upper === "GET" || upper === "HEAD";
+}
+
+/**
+ * Exponential backoff with jitter, overridden by a server-supplied
+ * `Retry-After` if present. Jitter prevents thundering-herd when a burst of
+ * callers all see the same 429 and pick the same deterministic delay.
+ */
+function computeDelay(
+  res: Response | undefined,
+  attempt: number,
+  baseDelayMs: number,
+  maxDelayMs: number,
+): number {
+  if (res) {
+    const header = res.headers.get("retry-after");
+    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 jitter = Math.random() * baseDelayMs;
+  return exp + jitter;
+}
+
+/**
+ * Parse a Retry-After header. The spec allows either a non-negative integer
+ * (seconds) or an HTTP-date (RFC 7231). Returns ms, or undefined if we can't
+ * parse it — callers then fall back to exponential backoff.
+ */
+export function parseRetryAfter(header: string | null): number | undefined {
+  if (!header) return undefined;
+  const trimmed = header.trim();
+  if (trimmed === "") return undefined;
+
+  // Integer-seconds form.
+  if (/^\d+$/.test(trimmed)) {
+    const seconds = Number.parseInt(trimmed, 10);
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  }
+
+  // HTTP-date form. Date.parse understands RFC 7231 formats; if it fails it
+  // returns NaN and we fall through.
+  const asDate = Date.parse(trimmed);
+  if (Number.isFinite(asDate)) {
+    const delta = asDate - Date.now();
+    return delta > 0 ? delta : 0;
+  }
+
+  return undefined;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Merge a caller-supplied `AbortSignal` into the `init.signal` passed to
+ * `fetch`. If both are set, either aborting should cancel the request. Using
+ * `AbortSignal.any` where available; falling back to a manual linkage on older
+ * runtimes.
+ */
+function mergeSignal(init: RequestInit | undefined, external?: AbortSignal): RequestInit | undefined {
+  if (!external) return init;
+  const existing = init?.signal ?? undefined;
+  if (!existing) return { ...init, signal: external };
+  const anyFn = (AbortSignal as unknown as { any?: (signals: AbortSignal[]) => AbortSignal }).any;
+  if (typeof anyFn === "function") {
+    return { ...init, signal: anyFn([existing, external]) };
+  }
+  // Manual linkage fallback.
+  const controller = new AbortController();
+  const onAbort = (signal: AbortSignal) => () => controller.abort(signal.reason);
+  existing.addEventListener("abort", onAbort(existing), { once: true });
+  external.addEventListener("abort", onAbort(external), { once: true });
+  if (existing.aborted) controller.abort(existing.reason);
+  if (external.aborted) controller.abort(external.reason);
+  return { ...init, signal: controller.signal };
+}
+
+function abortError(signal?: AbortSignal): Error {
+  const reason = signal?.reason;
+  if (reason instanceof Error) return reason;
+  const err = new Error(typeof reason === "string" ? reason : "The operation was aborted.");
+  err.name = "AbortError";
+  return err;
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+export * from "./config.ts";
+export * from "./phantom.ts";
+export * from "./providers/_base.ts";
+export { providers, getProvider, listProviderNames } from "./providers/index.ts";
+export * from "./errors.ts";
+export * from "./templates.ts";
+export * from "./pipeline.ts";
+export * from "./detect.ts";
+export * from "./detect-source.ts";
+export * from "./registry.ts";
+export {
+  PROVIDER_CATEGORIES,
+  PROVIDERS_REF,
+  findProviderRef,
+  groupByCategory,
+} from "./catalog.ts";
+export type { AuthKind as CatalogAuthKind, ProviderRef } from "./catalog.ts";
+export {
+  retrieve,
+  retrieveByCategory,
+  type RetrievalHit,
+  type RetrieveOptions,
+} from "./ai/catalog-index.ts";
+export {
+  listRecipes,
+  readRecipe,
+  recipeFromRetrieval,
+  slugifyQuery,
+  writeRecipe,
+  type Recipe,
+} from "./ai/recipe.ts";
+export { wirePhantomForRecipe, type WireResult } from "./ai/phantom-wire.ts";
+export {
+  ClaudeMCPBackend,
+  LocalSLMBackend,
+  NoInferenceBackendError,
+  getInferenceBackend,
+  parseRecipeDraft,
+  type InferenceBackend,
+  type InferenceMode,
+  type InferenceRequest,
+  type InferenceResult,
+  type InferenceUsage,
+  type LocalSLMBackendOptions,
+  type LocalSLMEndpoint,
+  type GetInferenceBackendOptions,
+  type RecipeDraft,
+  type RecipeProvider,
+} from "./ai/inference.ts";
+export {
+  CircuitBreaker,
+  type CircuitBreakerOptions,
+  type CircuitState,
+} from "./ai/circuit-breaker.ts";
+export {
+  CostTracker,
+  defaultCostTracker,
+  type CostSummary,
+  type RateCard,
+  type UsageRecord,
+} from "./ai/cost-tracker.ts";

package/src/mcp-writer.ts

@@ -0,0 +1,50 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { McpServerEntry } from "./providers/_base.ts";
+
+const MCP_FILENAME = ".mcp.json";
+
+interface McpFile {
+  mcpServers: Record<string, Record<string, unknown>>;
+  [key: string]: unknown;
+}
+
+export async function mergeMcpEntry(entry: McpServerEntry, cwd: string = process.cwd()): Promise<void> {
+  const path = join(cwd, MCP_FILENAME);
+  const current = await readMcp(path);
+  current.mcpServers[entry.name] = toJsonShape(entry);
+  await writeFile(path, `${JSON.stringify(current, null, 2)}\n`, "utf-8");
+}
+
+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]) {
+    delete current.mcpServers[name];
+    await writeFile(path, `${JSON.stringify(current, null, 2)}\n`, "utf-8");
+  }
+}
+
+async function readMcp(path: string): Promise<McpFile> {
+  if (!existsSync(path)) return { mcpServers: {} };
+  const raw = await readFile(path, "utf-8");
+  try {
+    const parsed = JSON.parse(raw) as Partial<McpFile>;
+    return { ...parsed, mcpServers: parsed.mcpServers ?? {} };
+  } catch (err) {
+    throw new Error(`Failed to parse ${path}: ${(err as Error).message}`);
+  }
+}
+
+function toJsonShape(entry: McpServerEntry): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (entry.type) out.type = entry.type;
+  if (entry.command) out.command = entry.command;
+  if (entry.args) out.args = entry.args;
+  if (entry.url) out.url = entry.url;
+  if (entry.env) out.env = entry.env;
+  if (entry.headers) out.headers = entry.headers;
+  return out;
+}