@ashlr/stack-core 0.1.1

package/src/providers/turso.ts

@@ -0,0 +1,197 @@
+import type { ServiceEntry } from "../config.ts";
+import { StackError } from "../errors.ts";
+import { addSecret, revealSecret } from "../phantom.ts";
+import { fetchWithRetry } from "../http.ts";
+import type {
+  AuthHandle,
+  HealthStatus,
+  Materialized,
+  Provider,
+  ProviderContext,
+  ProvisionOpts,
+  Resource,
+} from "./_base.ts";
+
+/**
+ * Turso — LibSQL-backed edge database. v1 uses a user-created Platform API
+ * token (https://app.turso.tech/settings/api-tokens). Provision creates a new
+ * database; materialize surfaces the URL + an auto-issued auth token.
+ *
+ * API reference: https://docs.turso.tech/api-reference/introduction
+ */
+
+const API = "https://api.turso.tech/v1";
+const PLATFORM_TOKEN_SECRET = "TURSO_PLATFORM_TOKEN";
+
+const turso: Provider = {
+  name: "turso",
+  displayName: "Turso",
+  category: "database",
+  authKind: "pat",
+  docs: "https://docs.turso.tech",
+
+  async login(ctx: ProviderContext): Promise<AuthHandle> {
+    const cached = await tryRevealSecret(PLATFORM_TOKEN_SECRET);
+    if (cached) {
+      const identity = await fetchIdentity(cached);
+      if (identity) return { token: cached, identity };
+      ctx.log({ level: "warn", msg: "Cached Turso token invalid." });
+    }
+    if (!ctx.interactive) throw new StackError("TURSO_AUTH_REQUIRED", "No valid Turso token in vault.");
+    process.stderr.write(
+      "\n  Create a Platform API token at https://app.turso.tech/settings/api-tokens\n  Paste it here: ",
+    );
+    const token = (await readLine()).trim();
+    const identity = await fetchIdentity(token);
+    if (!identity) throw new StackError("TURSO_AUTH_INVALID", "Turso rejected that token.");
+    await addSecret(PLATFORM_TOKEN_SECRET, token);
+    return { token, identity };
+  },
+
+  async provision(ctx, auth, opts: ProvisionOpts): Promise<Resource> {
+    const orgs = await fetchOrganizations(auth.token);
+    if (orgs.length === 0) throw new StackError("TURSO_NO_ORGS", "Turso returned no organizations.");
+    const orgSlug = (opts.hints?.orgSlug as string | undefined) ?? orgs[0].slug;
+    if (opts.existingResourceId) {
+      const [existingOrg, dbName] = opts.existingResourceId.split("/");
+      return {
+        id: opts.existingResourceId,
+        displayName: dbName,
+        meta: { org_slug: existingOrg, db_name: dbName },
+      };
+    }
+    const dbName = `stack-${Date.now().toString(36)}`;
+    const group = (opts.hints?.group as string | undefined) ?? "default";
+    const res = await fetch(`${API}/organizations/${orgSlug}/databases`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${auth.token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ name: dbName, group }),
+    });
+    if (!res.ok)
+      throw new StackError(
+        "TURSO_CREATE_FAILED",
+        `Turso DB creation failed (${res.status}): ${await res.text()}`,
+      );
+    const body = (await res.json()) as { database: { Name: string; Hostname: string } };
+    ctx.log({ level: "info", msg: `Created Turso DB ${body.database.Name}.` });
+    return {
+      id: `${orgSlug}/${body.database.Name}`,
+      displayName: body.database.Name,
+      meta: {
+        org_slug: orgSlug,
+        db_name: body.database.Name,
+        hostname: body.database.Hostname,
+      },
+    };
+  },
+
+  async materialize(_ctx, resource, auth): Promise<Materialized> {
+    const [orgSlug, dbName] = resource.id.split("/");
+    const dbToken = await mintDbToken(auth.token, orgSlug, dbName);
+    const hostname =
+      (resource.meta?.hostname as string | undefined) ?? `${dbName}-${orgSlug}.turso.io`;
+    const libsqlUrl = `libsql://${hostname}`;
+    return {
+      secrets: {
+        TURSO_DATABASE_URL: libsqlUrl,
+        TURSO_AUTH_TOKEN: dbToken,
+        TURSO_PLATFORM_TOKEN: auth.token,
+      },
+      urls: { dashboard: `https://app.turso.tech/${orgSlug}/databases/${dbName}` },
+    };
+  },
+
+  async healthcheck(_ctx, entry: ServiceEntry): Promise<HealthStatus> {
+    const token = await tryRevealSecret(PLATFORM_TOKEN_SECRET);
+    if (!token) return { kind: "error", detail: `${PLATFORM_TOKEN_SECRET} missing` };
+    if (!entry.resource_id) return { kind: "warn", detail: "no resource_id" };
+    const [orgSlug, dbName] = entry.resource_id.split("/");
+    const start = Date.now();
+    // Idempotent GET — healthcheck loops on this.
+    const res = await fetchWithRetry(`${API}/organizations/${orgSlug}/databases/${dbName}`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const latencyMs = Date.now() - start;
+    return res.ok ? { kind: "ok", latencyMs } : { kind: "error", detail: `HTTP ${res.status}` };
+  },
+
+  dashboardUrl(entry: ServiceEntry): string {
+    if (!entry.resource_id) return "https://app.turso.tech";
+    const [orgSlug, dbName] = entry.resource_id.split("/");
+    return `https://app.turso.tech/${orgSlug}/databases/${dbName}`;
+  },
+};
+
+export default turso;
+
+async function fetchIdentity(token: string): Promise<Record<string, string> | undefined> {
+  try {
+    // Idempotent GET — retry transient failures during token validation.
+    const res = await fetchWithRetry(`${API}/auth/validate`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as Record<string, unknown>;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(body)) if (typeof v === "string") out[k] = v;
+    return out;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchOrganizations(token: string): Promise<Array<{ slug: string; name: string }>> {
+  // Idempotent GET — retry transient 429/5xx.
+  const res = await fetchWithRetry(`${API}/organizations`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (!res.ok) return [];
+  return (await res.json()) as Array<{ slug: string; name: string }>;
+}
+
+async function mintDbToken(
+  platformToken: string,
+  orgSlug: string,
+  dbName: string,
+): Promise<string> {
+  const res = await fetch(`${API}/organizations/${orgSlug}/databases/${dbName}/auth/tokens`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${platformToken}`, "content-type": "application/json" },
+    body: JSON.stringify({ expiration: "never", authorization: "full-access" }),
+  });
+  if (!res.ok)
+    throw new StackError(
+      "TURSO_TOKEN_FAILED",
+      `Turso token mint failed (${res.status}): ${await res.text()}`,
+    );
+  const body = (await res.json()) as { jwt: string };
+  return body.jwt;
+}
+
+async function tryRevealSecret(key: string): Promise<string | undefined> {
+  try {
+    const v = await revealSecret(key);
+    return v.length > 0 ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function readLine(): Promise<string> {
+  return new Promise((resolve) => {
+    let buf = "";
+    const onData = (chunk: Buffer) => {
+      buf += chunk.toString();
+      if (buf.includes("\n")) {
+        process.stdin.off("data", onData);
+        process.stdin.pause();
+        resolve(buf.split("\n")[0]);
+      }
+    };
+    process.stdin.resume();
+    process.stdin.on("data", onData);
+  });
+}

package/src/providers/upstash.ts

@@ -0,0 +1,32 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+/**
+ * Upstash uses HTTP Basic auth with email + Management API key. For v1 we
+ * accept a single pasted string in the form "email:token" which becomes the
+ * base64 Authorization header. Thicker provisioning (create Redis / Kafka /
+ * QStash) lands in a future wave.
+ */
+export default makeApiKeyProvider({
+  name: "upstash",
+  displayName: "Upstash",
+  category: "database",
+  docs: "https://upstash.com/docs/devops/developer-api",
+  secretName: "UPSTASH_MANAGEMENT_TOKEN",
+  howTo:
+    "Grab a Management API key at https://console.upstash.com/account/api; paste as email:token",
+  dashboard: "https://console.upstash.com",
+  async verify(key) {
+    try {
+      const basic = Buffer.from(key).toString("base64");
+      const res = await verifyFetch("https://api.upstash.com/v2/redis/databases", {
+        headers: { Authorization: `Basic ${basic}` },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as unknown[];
+      return { databases: String(Array.isArray(body) ? body.length : 0) };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/providers/vercel.ts

@@ -0,0 +1,134 @@
+import type { ServiceEntry } from "../config.ts";
+import { StackError } from "../errors.ts";
+import { addSecret } from "../phantom.ts";
+import { fetchWithRetry } from "../http.ts";
+import { readLine, tryRevealSecret } from "./_helpers.ts";
+import type {
+  AuthHandle,
+  HealthStatus,
+  Materialized,
+  Provider,
+  ProviderContext,
+  ProvisionOpts,
+  Resource,
+} from "./_base.ts";
+
+/**
+ * Vercel provider.
+ *
+ * v1 takes a personal access token (users create one at
+ * https://vercel.com/account/tokens). Provision either creates a new project
+ * or attaches to an existing one by id. Materialize stores the token + links
+ * the project for future `stack sync --platform vercel` calls.
+ */
+
+const API = "https://api.vercel.com";
+const TOKEN_SECRET = "VERCEL_TOKEN";
+
+const vercel: Provider = {
+  name: "vercel",
+  displayName: "Vercel",
+  category: "deploy",
+  authKind: "pat",
+  docs: "https://vercel.com/docs/rest-api",
+
+  async login(ctx: ProviderContext): Promise<AuthHandle> {
+    const cached = await tryRevealSecret(TOKEN_SECRET);
+    if (cached) {
+      const identity = await fetchUser(cached);
+      if (identity) return { token: cached, identity };
+      ctx.log({ level: "warn", msg: "Cached Vercel token invalid; re-entering." });
+    }
+    if (!ctx.interactive)
+      throw new StackError("VERCEL_AUTH_REQUIRED", "No valid Vercel token in vault.");
+    process.stderr.write(
+      "\n  Create a Vercel token at https://vercel.com/account/tokens\n  Paste it here: ",
+    );
+    const token = (await readLine()).trim();
+    const identity = await fetchUser(token);
+    if (!identity) throw new StackError("VERCEL_AUTH_INVALID", "Vercel rejected that token.");
+    await addSecret(TOKEN_SECRET, token);
+    return { token, identity };
+  },
+
+  async provision(ctx, auth, opts: ProvisionOpts): Promise<Resource> {
+    if (opts.existingResourceId) {
+      const project = await fetchProject(auth.token, opts.existingResourceId);
+      if (!project)
+        throw new StackError("VERCEL_PROJECT_NOT_FOUND", `No Vercel project ${opts.existingResourceId}.`);
+      return { id: project.id, displayName: project.name };
+    }
+    const name = `stack-${Date.now().toString(36)}`;
+    const res = await fetch(`${API}/v11/projects`, {
+      method: "POST",
+      headers: authHeaders(auth.token),
+      body: JSON.stringify({ name, framework: null }),
+    });
+    if (!res.ok) {
+      throw new StackError(
+        "VERCEL_CREATE_FAILED",
+        `Vercel project creation failed (${res.status}): ${await res.text()}`,
+      );
+    }
+    const project = (await res.json()) as { id: string; name: string };
+    ctx.log({ level: "info", msg: `Vercel project ${project.name} created.` });
+    return { id: project.id, displayName: project.name };
+  },
+
+  async materialize(_ctx, resource, auth): Promise<Materialized> {
+    return {
+      secrets: { [TOKEN_SECRET]: auth.token },
+      urls: {
+        project: `https://vercel.com/dashboard/${resource.id}`,
+      },
+    };
+  },
+
+  async healthcheck(_ctx, entry: ServiceEntry): Promise<HealthStatus> {
+    const token = await tryRevealSecret(TOKEN_SECRET);
+    if (!token) return { kind: "error", detail: `${TOKEN_SECRET} missing from vault` };
+    if (!entry.resource_id) return { kind: "warn", detail: "no resource_id" };
+    const start = Date.now();
+    const project = await fetchProject(token, entry.resource_id);
+    const latencyMs = Date.now() - start;
+    return project ? { kind: "ok", latencyMs } : { kind: "error", detail: "project not found" };
+  },
+
+  dashboardUrl(entry: ServiceEntry): string {
+    return entry.resource_id
+      ? `https://vercel.com/dashboard/${entry.resource_id}`
+      : "https://vercel.com/dashboard";
+  },
+};
+
+export default vercel;
+
+function authHeaders(token: string): HeadersInit {
+  return { Authorization: `Bearer ${token}`, "content-type": "application/json" };
+}
+
+async function fetchUser(token: string): Promise<Record<string, string> | undefined> {
+  try {
+    // Idempotent GET — retry transient failures during login validation + healthcheck.
+    const res = await fetchWithRetry(`${API}/v2/user`, { headers: authHeaders(token) });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as { user?: { uid?: string; email?: string; username?: string } };
+    if (!body.user) return undefined;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(body.user))
+      if (typeof v === "string") out[k] = v;
+    return out;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchProject(token: string, id: string): Promise<{ id: string; name: string } | undefined> {
+  // Idempotent GET — healthcheck reads this on every `stack status` call.
+  const res = await fetchWithRetry(`${API}/v9/projects/${id}`, { headers: authHeaders(token) });
+  if (res.status === 404) return undefined;
+  if (!res.ok) return undefined;
+  return (await res.json()) as { id: string; name: string };
+}
+
+

package/src/providers/xai.ts

@@ -0,0 +1,24 @@
+import { makeApiKeyProvider } from "./_api-key.ts";
+import { verifyFetch } from "./_helpers.ts";
+
+export default makeApiKeyProvider({
+  name: "xai",
+  displayName: "xAI",
+  category: "ai",
+  docs: "https://docs.x.ai/api",
+  secretName: "XAI_API_KEY",
+  howTo: "Create a key at https://console.x.ai",
+  dashboard: "https://console.x.ai",
+  async verify(key) {
+    try {
+      const res = await verifyFetch("https://api.x.ai/v1/models", {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!res.ok) return undefined;
+      const body = (await res.json()) as { data?: Array<{ id: string }> };
+      return { models: String(body.data?.length ?? 0) };
+    } catch {
+      return undefined;
+    }
+  },
+});

package/src/registry.ts

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, resolve } from "node:path";
+import {
+  CONFIG_FILENAME,
+  hasConfig,
+  readConfig,
+  resolveConfigPath,
+} from "./config.ts";
+
+/**
+ * Machine-global registry of every Stack-enabled project this user has
+ * touched. Lives at ~/.stack/projects.json and is the backbone of cross-project
+ * commands like `stack projects list` and `stack doctor --all`.
+ *
+ * Auto-maintained: every write of .stack.toml (via writeConfig) calls
+ * `registerProject(cwd)`. Paths that no longer exist get pruned on next read.
+ */
+
+export interface RegistryEntry {
+  /** Absolute canonical path to the project root (where .stack.toml lives). */
+  path: string;
+  /** Derived from the directory basename. */
+  name: string;
+  /** project_id from .stack.local.toml. */
+  project_id: string;
+  /** Template (if any) the project was seeded from. */
+  template?: string;
+  /** Service names in this project. */
+  services: string[];
+  /** Last time Stack touched this entry, ISO timestamp. */
+  last_seen: string;
+}
+
+interface RegistryFile {
+  version: "1";
+  projects: RegistryEntry[];
+}
+
+export function registryPath(): string {
+  const base = process.env.STACK_REGISTRY_DIR ?? resolve(homedir(), ".stack");
+  return resolve(base, "projects.json");
+}
+
+async function readRegistryRaw(): Promise<RegistryFile> {
+  const path = registryPath();
+  if (!existsSync(path)) return { version: "1", projects: [] };
+  try {
+    const raw = await readFile(path, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<RegistryFile>;
+    return { version: "1", projects: parsed.projects ?? [] };
+  } catch {
+    return { version: "1", projects: [] };
+  }
+}
+
+async function writeRegistryRaw(file: RegistryFile): Promise<void> {
+  const path = registryPath();
+  const dir = resolve(path, "..");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  await writeFile(path, `${JSON.stringify(file, null, 2)}\n`, "utf-8");
+}
+
+export async function registerProject(cwd: string): Promise<RegistryEntry | undefined> {
+  const path = resolve(cwd);
+  if (!hasConfig(path)) return undefined;
+  const config = await readConfig(path);
+  const entry: RegistryEntry = {
+    path,
+    name: basename(path),
+    project_id: config.stack.project_id,
+    template: config.stack.template,
+    services: Object.keys(config.services),
+    last_seen: new Date().toISOString(),
+  };
+  const file = await readRegistryRaw();
+  const filtered = file.projects.filter((p) => p.path !== path);
+  filtered.push(entry);
+  filtered.sort((a, b) => a.name.localeCompare(b.name));
+  await writeRegistryRaw({ version: "1", projects: filtered });
+  return entry;
+}
+
+export async function unregisterProject(path: string): Promise<void> {
+  const resolved = resolve(path);
+  const file = await readRegistryRaw();
+  await writeRegistryRaw({
+    version: "1",
+    projects: file.projects.filter((p) => p.path !== resolved),
+  });
+}
+
+export async function listProjects(opts: { prune?: boolean } = {}): Promise<RegistryEntry[]> {
+  const file = await readRegistryRaw();
+  if (opts.prune === false) return file.projects;
+  // Drop entries whose .stack.toml has been deleted.
+  const alive = file.projects.filter((p) => existsSync(resolveConfigPath(p.path)));
+  if (alive.length !== file.projects.length) {
+    await writeRegistryRaw({ version: "1", projects: alive });
+  }
+  return alive;
+}
+
+export async function findProjectByName(name: string): Promise<RegistryEntry | undefined> {
+  const projects = await listProjects();
+  const exact = projects.find((p) => p.name === name);
+  if (exact) return exact;
+  return projects.find((p) => p.name.toLowerCase() === name.toLowerCase());
+}
+
+export function configFilename(): string {
+  return CONFIG_FILENAME;
+}

package/src/templates.ts

@@ -0,0 +1,39 @@
+import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseToml } from "smol-toml";
+import type { StackConfig } from "./config.ts";
+
+/**
+ * Starter `.stack.toml` templates live in `templates/<name>/stack.toml` at the
+ * monorepo root, and are also published with the CLI so `stack init --template`
+ * works globally after install.
+ */
+
+export function resolveTemplatesDir(): string | undefined {
+  const candidates = [
+    resolve(join(process.cwd(), "templates")),
+    // When running from source inside the monorepo:
+    resolve(join(fileURLToPath(dirname(import.meta.url)), "..", "..", "..", "..", "templates")),
+  ];
+  return candidates.find((p) => existsSync(p));
+}
+
+export function listTemplates(): string[] {
+  const dir = resolveTemplatesDir();
+  if (!dir) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export async function loadTemplate(name: string): Promise<StackConfig | undefined> {
+  const dir = resolveTemplatesDir();
+  if (!dir) return undefined;
+  const path = join(dir, name, "stack.toml");
+  if (!existsSync(path)) return undefined;
+  const raw = await readFile(path, "utf-8");
+  return parseToml(raw) as unknown as StackConfig;
+}