@ashlr/stack-core 0.1.1

package/src/config.ts

@@ -0,0 +1,293 @@
+import { existsSync } from "node:fs";
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { ConfigNotFoundError } from "./errors.ts";
+
+/**
+ * Stack config is split across two files:
+ *
+ * - `.stack.toml`        (committed) — SHAPE. Services that define this stack,
+ *   their canonical secret slot names, and which MCP servers to wire up.
+ *   Safe to share via git.
+ *
+ * - `.stack.local.toml`  (gitignored) — INSTANCE. Per-developer IDs, timestamps,
+ *   provider-side resource refs. Auto-added to .gitignore on first write.
+ *
+ * Callers work with the merged `StackConfig` shape; `readConfig` combines the
+ * two files and `writeConfig` splits writes back out. Legacy single-file
+ * `.stack.toml` (with instance fields) is read transparently and migrated on
+ * the next write.
+ */
+
+export const CONFIG_FILENAME = ".stack.toml";
+export const LOCAL_FILENAME = ".stack.local.toml";
+export const CONFIG_VERSION = "1";
+
+export interface StackRoot {
+  version: string;
+  project_id: string;
+  template?: string;
+}
+
+export interface ServiceEntry {
+  provider: string;
+  /** Provider-side resource id (project_ref, project_id, app name, etc.). INSTANCE. */
+  resource_id?: string;
+  /** Region. Lives in INSTANCE — can differ per developer if they clone + re-provision. */
+  region?: string;
+  /** Names of secrets stored in Phantom that belong to this service. SHAPE. */
+  secrets: string[];
+  /** Name of the MCP server entry in .mcp.json, if any. SHAPE. */
+  mcp?: string;
+  /** Freeform provider-specific fields. INSTANCE. */
+  meta?: Record<string, unknown>;
+  /** INSTANCE. */
+  created_at: string;
+  /** INSTANCE. */
+  created_by?: string;
+}
+
+export interface EnvironmentEntry {
+  name: string;
+  default?: boolean;
+  overrides?: Record<string, string>;
+}
+
+export interface StackConfig {
+  stack: StackRoot;
+  services: Record<string, ServiceEntry>;
+  environments: EnvironmentEntry[];
+}
+
+export function emptyConfig(template?: string): StackConfig {
+  return {
+    stack: {
+      version: CONFIG_VERSION,
+      project_id: randomProjectId(),
+      ...(template ? { template } : {}),
+    },
+    services: {},
+    environments: [{ name: "dev", default: true }],
+  };
+}
+
+export function randomProjectId(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(6));
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `stk_${hex}`;
+}
+
+export function resolveConfigPath(cwd: string = process.cwd()): string {
+  return resolve(join(cwd, CONFIG_FILENAME));
+}
+
+export function resolveLocalConfigPath(cwd: string = process.cwd()): string {
+  return resolve(join(cwd, LOCAL_FILENAME));
+}
+
+export function hasConfig(cwd: string = process.cwd()): boolean {
+  return existsSync(resolveConfigPath(cwd));
+}
+
+// ---------------------------------------------------------------------------
+// Committed shape fragment
+// ---------------------------------------------------------------------------
+
+interface ShapeFile {
+  stack: { version: string; template?: string };
+  services: Record<
+    string,
+    { provider: string; secrets: string[]; mcp?: string }
+  >;
+  environments: EnvironmentEntry[];
+}
+
+// ---------------------------------------------------------------------------
+// Local instance fragment
+// ---------------------------------------------------------------------------
+
+interface InstanceFile {
+  stack: { project_id: string };
+  services: Record<
+    string,
+    {
+      resource_id?: string;
+      region?: string;
+      meta?: Record<string, unknown>;
+      created_at?: string;
+      created_by?: string;
+    }
+  >;
+}
+
+// ---------------------------------------------------------------------------
+// Read: merge the two files (or migrate a legacy single file)
+// ---------------------------------------------------------------------------
+
+export async function readConfig(cwd: string = process.cwd()): Promise<StackConfig> {
+  const shapePath = resolveConfigPath(cwd);
+  const localPath = resolveLocalConfigPath(cwd);
+  if (!existsSync(shapePath)) throw new ConfigNotFoundError(shapePath);
+
+  const rawShape = await readFile(shapePath, "utf-8");
+  const shape = parseToml(rawShape) as Record<string, unknown>;
+
+  // Detect legacy single-file config — if the top file carries instance fields
+  // (project_id at root, or created_at inside services), treat it as merged.
+  const isLegacy =
+    (shape.stack as Record<string, unknown> | undefined)?.project_id !== undefined ||
+    Object.values((shape.services as Record<string, Record<string, unknown>>) ?? {}).some(
+      (s) => s.created_at !== undefined || s.resource_id !== undefined,
+    );
+
+  if (isLegacy) return normalizeLegacy(shape);
+
+  const instance = existsSync(localPath)
+    ? (parseToml(await readFile(localPath, "utf-8")) as Record<string, unknown>)
+    : ({} as Record<string, unknown>);
+
+  return merge(shape as unknown as ShapeFile, instance as unknown as InstanceFile);
+}
+
+// ---------------------------------------------------------------------------
+// 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> {
+  const { shape, instance } = split(config);
+
+  const shapeHeader =
+    "# Ashlr Stack — committed shape. Defines which services this project uses.\n" +
+    "# Safe to share in git; secret *values* live in Phantom, not here.\n";
+  await writeFile(
+    resolveConfigPath(cwd),
+    shapeHeader + stringifyToml(shape as unknown as Record<string, unknown>),
+    "utf-8",
+  );
+
+  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>),
+    "utf-8",
+  );
+
+  await ensureGitignored(cwd);
+
+  // Best-effort: auto-register the project in the global registry. Failures
+  // here (e.g. a read-only home dir) must not break the write itself.
+  try {
+    const { registerProject } = await import("./registry.ts");
+    await registerProject(cwd);
+  } catch {
+    /* swallow */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function split(config: StackConfig): { shape: ShapeFile; instance: InstanceFile } {
+  const shape: ShapeFile = {
+    stack: {
+      version: config.stack.version,
+      ...(config.stack.template ? { template: config.stack.template } : {}),
+    },
+    services: {},
+    environments: config.environments,
+  };
+  const instance: InstanceFile = {
+    stack: { project_id: config.stack.project_id },
+    services: {},
+  };
+  for (const [name, entry] of Object.entries(config.services)) {
+    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;
+  }
+  return { shape, instance };
+}
+
+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] = {
+      provider: s.provider,
+      secrets: s.secrets,
+      ...(s.mcp ? { mcp: s.mcp } : {}),
+      ...(i.resource_id ? { resource_id: i.resource_id } : {}),
+      ...(i.region ? { region: i.region } : {}),
+      ...(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: {
+      version: shape.stack?.version ?? CONFIG_VERSION,
+      project_id: instance.stack?.project_id ?? randomProjectId(),
+      ...(shape.stack?.template ? { template: shape.stack.template } : {}),
+    },
+    services,
+    environments: shape.environments?.length
+      ? shape.environments
+      : [{ name: "dev", default: true }],
+  };
+}
+
+function normalizeLegacy(raw: Record<string, unknown>): StackConfig {
+  const stackField = (raw.stack ?? {}) as Record<string, unknown>;
+  const services = (raw.services ?? {}) as Record<string, Record<string, unknown>>;
+  const environments = (raw.environments ?? [{ name: "dev", default: true }]) as EnvironmentEntry[];
+  const out: StackConfig = {
+    stack: {
+      version: (stackField.version as string) ?? CONFIG_VERSION,
+      project_id: (stackField.project_id as string) ?? randomProjectId(),
+      ...(typeof stackField.template === "string" ? { template: stackField.template } : {}),
+    },
+    services: {},
+    environments,
+  };
+  for (const [name, entry] of Object.entries(services)) {
+    out.services[name] = {
+      provider: (entry.provider as string) ?? name,
+      secrets: (entry.secrets as string[]) ?? [],
+      ...(typeof entry.mcp === "string" ? { mcp: entry.mcp } : {}),
+      ...(typeof entry.resource_id === "string" ? { resource_id: entry.resource_id } : {}),
+      ...(typeof entry.region === "string" ? { region: entry.region } : {}),
+      ...(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;
+}
+
+async function ensureGitignored(cwd: string): Promise<void> {
+  const gitignorePath = join(cwd, ".gitignore");
+  const needle = LOCAL_FILENAME;
+  if (!existsSync(gitignorePath)) {
+    await writeFile(gitignorePath, `# Ashlr Stack\n${needle}\n.mcp.json.local\n`, "utf-8");
+    return;
+  }
+  const current = await readFile(gitignorePath, "utf-8");
+  if (current.split(/\r?\n/).some((line) => line.trim() === needle)) return;
+  const sep = current.endsWith("\n") ? "" : "\n";
+  await appendFile(gitignorePath, `${sep}# Ashlr Stack\n${needle}\n`, "utf-8");
+}

package/src/detect-source.ts

@@ -0,0 +1,344 @@
+import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Source-level provider detection. Reads package.json / requirements.txt /
+ * pyproject.toml / go.mod / Cargo.toml plus framework config files and
+ * reports which curated providers the project *already uses*.
+ *
+ * This is the backbone of `stack scan` and zero-config onboarding. It runs on
+ * any repo — committed .stack.toml or not — and returns provider names plus
+ * evidence strings for auditing.
+ */
+
+export type DetectionConfidence = "high" | "medium" | "low";
+
+export interface SourceDetection {
+  provider: string;
+  confidence: DetectionConfidence;
+  signals: string[];
+}
+
+export interface SourceScanOptions {
+  /** Skip detection of providers that require hitting the network. Default: true. */
+  offlineOnly?: boolean;
+}
+
+interface DepRule {
+  provider: string;
+  /** Exact match or prefix on the dep name. */
+  matches: (dep: string) => boolean;
+  confidence: DetectionConfidence;
+}
+
+const JS_RULES: DepRule[] = [
+  { provider: "supabase", matches: (d) => d.startsWith("@supabase/"), confidence: "high" },
+  { provider: "neon", matches: (d) => d.startsWith("@neondatabase/"), confidence: "high" },
+  {
+    provider: "vercel",
+    matches: (d) => d === "@vercel/analytics" || d === "@vercel/speed-insights" || d === "@vercel/kv",
+    confidence: "medium",
+  },
+  { provider: "sentry", matches: (d) => d.startsWith("@sentry/"), confidence: "high" },
+  {
+    provider: "posthog",
+    matches: (d) => d === "posthog-js" || d === "posthog-node",
+    confidence: "high",
+  },
+  { 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: "clerk", matches: (d) => d.startsWith("@clerk/"), confidence: "high" },
+  { provider: "resend", matches: (d) => d === "resend", confidence: "high" },
+  {
+    provider: "upstash",
+    matches: (d) => d.startsWith("@upstash/"),
+    confidence: "high",
+  },
+  { provider: "linear", matches: (d) => d === "@linear/sdk", confidence: "high" },
+  {
+    provider: "cloudflare",
+    matches: (d) => d === "wrangler" || d.startsWith("@cloudflare/"),
+    confidence: "high",
+  },
+  {
+    provider: "turso",
+    matches: (d) => d === "@libsql/client" || d === "@libsql/kysely-libsql",
+    confidence: "high",
+  },
+  {
+    provider: "convex",
+    matches: (d) => d === "convex" || d.startsWith("@convex-dev/"),
+    confidence: "high",
+  },
+  {
+    provider: "firebase",
+    matches: (d) => d === "firebase" || d === "firebase-admin" || d.startsWith("@firebase/"),
+    confidence: "high",
+  },
+  {
+    provider: "render",
+    // No canonical npm package; rely on config files & env detection.
+    matches: () => false,
+    confidence: "low",
+  },
+  {
+    provider: "replicate",
+    matches: (d) => d === "replicate",
+    confidence: "high",
+  },
+  {
+    provider: "braintrust",
+    matches: (d) => d === "braintrust" || d === "@braintrust/sdk",
+    confidence: "high",
+  },
+  {
+    provider: "modal",
+    // Modal is Python-first; the dep lives in requirements.txt.
+    matches: () => false,
+    confidence: "low",
+  },
+];
+
+const PY_RULES: DepRule[] = [
+  { 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" },
+  { provider: "stripe", matches: (d) => d === "stripe", confidence: "high" },
+  { provider: "posthog", matches: (d) => d === "posthog", confidence: "high" },
+  { provider: "resend", matches: (d) => d === "resend", confidence: "high" },
+  { provider: "modal", matches: (d) => d === "modal", confidence: "high" },
+  { provider: "replicate", matches: (d) => d === "replicate", confidence: "high" },
+  { provider: "braintrust", matches: (d) => d === "braintrust", confidence: "high" },
+];
+
+const GO_RULES: DepRule[] = [
+  {
+    provider: "supabase",
+    matches: (d) => d.startsWith("github.com/supabase-community/"),
+    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" },
+];
+
+const RUST_RULES: DepRule[] = [
+  { 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" },
+];
+
+export async function scanSource(
+  cwd: string,
+  _opts: SourceScanOptions = {},
+): Promise<SourceDetection[]> {
+  const hits = new Map<string, SourceDetection>();
+
+  const add = (provider: string, signal: string, confidence: DetectionConfidence) => {
+    const existing = hits.get(provider);
+    if (!existing) {
+      hits.set(provider, { provider, confidence, signals: [signal] });
+      return;
+    }
+    if (!existing.signals.includes(signal)) existing.signals.push(signal);
+    existing.confidence = rankUp(existing.confidence, confidence);
+  };
+
+  await scanPackageJson(cwd, add);
+  await scanPython(cwd, add);
+  await scanGoMod(cwd, add);
+  await scanCargoToml(cwd, add);
+  await scanConfigFiles(cwd, add);
+  await scanEnvExample(cwd, add);
+
+  return Array.from(hits.values()).sort((a, b) => {
+    const order: Record<DetectionConfidence, number> = { high: 0, medium: 1, low: 2 };
+    return order[a.confidence] - order[b.confidence] || a.provider.localeCompare(b.provider);
+  });
+}
+
+function rankUp(a: DetectionConfidence, b: DetectionConfidence): DetectionConfidence {
+  const order: DetectionConfidence[] = ["low", "medium", "high"];
+  return order[Math.max(order.indexOf(a), order.indexOf(b))];
+}
+
+async function scanPackageJson(
+  cwd: string,
+  add: (p: string, s: string, c: DetectionConfidence) => void,
+): Promise<void> {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync(pkgPath)) return;
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    for (const dep of Object.keys(allDeps)) {
+      for (const rule of JS_RULES) {
+        if (rule.matches(dep)) {
+          add(rule.provider, `package.json:${dep}`, rule.confidence);
+        }
+      }
+    }
+  } catch {
+    /* malformed package.json — skip */
+  }
+}
+
+async function scanPython(
+  cwd: string,
+  add: (p: string, s: string, c: DetectionConfidence) => void,
+): Promise<void> {
+  const reqPath = join(cwd, "requirements.txt");
+  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();
+      if (!pkg || pkg.startsWith("#")) continue;
+      for (const rule of PY_RULES) {
+        if (rule.matches(pkg)) add(rule.provider, `requirements.txt:${pkg}`, rule.confidence);
+      }
+    }
+  }
+  const pyprojPath = join(cwd, "pyproject.toml");
+  if (existsSync(pyprojPath)) {
+    const text = await readFile(pyprojPath, "utf-8");
+    // Cheap string matching — the TOML module is fine but overkill here.
+    for (const rule of PY_RULES) {
+      for (const sample of candidatePyprojectNames(rule)) {
+        if (new RegExp(`["'\\s]${escapeRegExp(sample)}["'\\s=><~]`).test(text)) {
+          add(rule.provider, `pyproject.toml:${sample}`, rule.confidence);
+        }
+      }
+    }
+  }
+}
+
+function candidatePyprojectNames(rule: DepRule): string[] {
+  // The rule matches on lowercased dep names; reverse-derive a few
+  // canonical package names to scan pyproject text for.
+  const samples = [
+    "supabase",
+    "supabase-py",
+    "openai",
+    "anthropic",
+    "sentry-sdk",
+    "stripe",
+    "posthog",
+    "resend",
+  ];
+  return samples.filter((s) => rule.matches(s));
+}
+
+async function scanGoMod(
+  cwd: string,
+  add: (p: string, s: string, c: DetectionConfidence) => void,
+): Promise<void> {
+  const path = join(cwd, "go.mod");
+  if (!existsSync(path)) return;
+  const text = await readFile(path, "utf-8");
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("require") && !trimmed.match(/^github\.com/)) continue;
+    const tokens = trimmed.split(/\s+/);
+    for (const tok of tokens) {
+      for (const rule of GO_RULES) {
+        if (rule.matches(tok)) add(rule.provider, `go.mod:${tok}`, rule.confidence);
+      }
+    }
+  }
+}
+
+async function scanCargoToml(
+  cwd: string,
+  add: (p: string, s: string, c: DetectionConfidence) => void,
+): Promise<void> {
+  const path = join(cwd, "Cargo.toml");
+  if (!existsSync(path)) return;
+  const text = await readFile(path, "utf-8");
+  for (const rule of RUST_RULES) {
+    for (const sample of ["openai", "async-openai", "sentry", "async-stripe"]) {
+      if (!rule.matches(sample)) continue;
+      if (new RegExp(`^${escapeRegExp(sample)}\\s*=`, "m").test(text)) {
+        add(rule.provider, `Cargo.toml:${sample}`, rule.confidence);
+      }
+    }
+  }
+}
+
+async function scanConfigFiles(
+  cwd: string,
+  add: (p: string, s: string, c: DetectionConfidence) => void,
+): Promise<void> {
+  const files: Array<[string, string, DetectionConfidence]> = [
+    ["vercel.json", "vercel", "high"],
+    [".vercel", "vercel", "medium"],
+    ["fly.toml", "fly", "high"],
+    ["railway.json", "railway", "high"],
+    ["railway.toml", "railway", "high"],
+    ["supabase/config.toml", "supabase", "high"],
+    ["sentry.properties", "sentry", "high"],
+    ["sentry.client.config.ts", "sentry", "high"],
+    ["sentry.client.config.js", "sentry", "high"],
+    ["sentry.server.config.ts", "sentry", "high"],
+    ["sentry.server.config.js", "sentry", "high"],
+    ["amplify.yml", "aws", "low"],
+    ["wrangler.toml", "cloudflare", "high"],
+    ["wrangler.jsonc", "cloudflare", "high"],
+    ["wrangler.json", "cloudflare", "high"],
+    ["convex/", "convex", "high"],
+    ["convex.config.ts", "convex", "high"],
+    ["firebase.json", "firebase", "high"],
+    [".firebaserc", "firebase", "high"],
+    ["render.yaml", "render", "high"],
+    [".github/workflows", "github", "medium"],
+  ];
+  for (const [relpath, provider, confidence] of files) {
+    const p = join(cwd, relpath);
+    if (existsSync(p)) add(provider, relpath, confidence);
+  }
+
+  // GitHub Actions: any YAML file is a decent signal.
+  const workflows = join(cwd, ".github", "workflows");
+  if (existsSync(workflows)) {
+    try {
+      const files = readdirSync(workflows);
+      for (const f of files) {
+        if (f.endsWith(".yml") || f.endsWith(".yaml")) {
+          add("github", `.github/workflows/${f}`, "high");
+        }
+      }
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+async function scanEnvExample(
+  cwd: string,
+  add: (p: string, s: string, c: DetectionConfidence) => void,
+): Promise<void> {
+  for (const candidate of [".env.example", ".env.sample", ".env.template"]) {
+    const p = join(cwd, candidate);
+    if (!existsSync(p)) continue;
+    const text = await readFile(p, "utf-8");
+    const { parseEnv, detectProvider } = await import("./detect.ts");
+    for (const { key } of parseEnv(text)) {
+      const provider = detectProvider(key);
+      if (provider) add(provider, `${candidate}:${key}`, "medium");
+    }
+  }
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}