@supatype/cli 0.1.0-alpha.6

package/src/commands/status.ts

@@ -0,0 +1,83 @@
+/**
+ * supatype status — show current state of local dev services.
+ */
+import type { Command } from "commander"
+import { spawnSync } from "node:child_process"
+
+interface ServiceStatus {
+  name: string
+  container: string
+  status: "running" | "stopped" | "error"
+  port?: number
+  uptime?: string
+}
+
+export function registerStatus(program: Command): void {
+  program
+    .command("status")
+    .description("Show current state of local dev services")
+    .action(() => {
+      const services: ServiceStatus[] = [
+        { name: "Postgres", container: "supatype-postgres", port: 5432 },
+        { name: "PostgREST", container: "supatype-postgrest", port: 3000 },
+        { name: "GoTrue", container: "supatype-gotrue", port: 9999 },
+        { name: "Kong", container: "supatype-kong", port: 8000 },
+        { name: "MinIO", container: "supatype-minio", port: 9000 },
+        { name: "Realtime", container: "supatype-realtime", port: 4000 },
+        { name: "Studio", container: "supatype-studio", port: 3100 },
+      ].map((svc) => {
+        const status = getContainerStatus(svc.container)
+        const uptime = getContainerUptime(svc.container)
+        return { ...svc, status, ...(uptime !== undefined && { uptime }) }
+      })
+
+      console.log("Supatype Local Development Stack\n")
+
+      const maxName = Math.max(...services.map((s) => s.name.length))
+      for (const svc of services) {
+        const icon = svc.status === "running" ? "●" : svc.status === "stopped" ? "○" : "✕"
+        const status = svc.status.padEnd(8)
+        const port = svc.port ? `:${svc.port}` : ""
+        const uptime = svc.uptime ? ` (${svc.uptime})` : ""
+        console.log(`  ${icon} ${svc.name.padEnd(maxName)}  ${status}  ${port}${uptime}`)
+      }
+
+      const running = services.filter((s) => s.status === "running")
+      console.log(`\n${running.length}/${services.length} services running`)
+
+      if (running.length > 0) {
+        console.log(`\nAPI URL:    http://localhost:8000`)
+        console.log(`Studio:     http://localhost:3100`)
+        console.log(`Database:   postgresql://postgres:postgres@localhost:5432/postgres`)
+      }
+    })
+}
+
+function getContainerStatus(name: string): "running" | "stopped" | "error" {
+  const result = spawnSync("docker", ["inspect", "--format", "{{.State.Status}}", name], {
+    timeout: 5000,
+  })
+  const status = result.stdout?.toString().trim()
+  if (status === "running") return "running"
+  if (result.status !== 0) return "stopped"
+  return "error"
+}
+
+function getContainerUptime(name: string): string | undefined {
+  const result = spawnSync("docker", ["inspect", "--format", "{{.State.StartedAt}}", name], {
+    timeout: 5000,
+  })
+  if (result.status !== 0) return undefined
+  const startedAt = result.stdout?.toString().trim()
+  if (!startedAt) return undefined
+
+  const started = new Date(startedAt)
+  const now = new Date()
+  const diffMs = now.getTime() - started.getTime()
+  if (diffMs < 0) return undefined
+
+  const hours = Math.floor(diffMs / (1000 * 60 * 60))
+  const minutes = Math.floor((diffMs % (1000 * 60 * 60)) / (1000 * 60))
+  if (hours > 0) return `${hours}h ${minutes}m`
+  return `${minutes}m`
+}

package/src/config.ts

@@ -0,0 +1,190 @@
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+import { evalTsSnippet } from "./tsx-runner.js"
+
+export interface ServiceVersionPin {
+  /** Docker image tag to pin this service to (e.g. "v1.2.3"). When set, `self-host upgrade` skips this service. */
+  version: string
+}
+
+export interface SelfHostConfig {
+  /** Production domain (e.g. "api.example.com"). Used by Caddy for HTTPS. */
+  domain: string
+  /** App service to include in the production stack. */
+  app?: {
+    /** Path to the app's Dockerfile, relative to the project root. */
+    dockerfile: string
+    /** Port the app listens on. */
+    port: number
+  }
+  ssl?: {
+    /** SSL provider. "caddy" = automatic Let's Encrypt. "none" = bring your own. */
+    provider: "caddy" | "none"
+    /** Email for Let's Encrypt registration (required when provider = "caddy"). */
+    email?: string
+  }
+  /**
+   * Pin specific services to fixed Docker image versions.
+   * When a service is pinned, `self-host upgrade` will skip it.
+   * Omit a service or set to `undefined` to allow automatic upgrades.
+   *
+   * @example
+   * services: {
+   *   db: { version: "17-latest" },
+   *   postgrest: { version: "v12.2.8" },
+   * }
+   */
+  services?: {
+    db?: ServiceVersionPin
+    gotrue?: ServiceVersionPin
+    postgrest?: ServiceVersionPin
+    kong?: ServiceVersionPin
+    caddy?: ServiceVersionPin
+    pgbouncer?: ServiceVersionPin
+  }
+}
+
+export type AppFramework = "nextjs" | "astro" | "vite" | "remix-spa" | "sveltekit" | "nuxt" | "static"
+
+export interface AppConfig {
+  /** Framework name. Auto-detected from package.json if not specified. */
+  framework?: AppFramework
+  /** Path to the app directory (default: "./" or "./apps/web" for monorepos). */
+  directory?: string
+  /** Build command (inferred from framework if not specified). */
+  buildCommand?: string
+  /** Output directory (inferred from framework if not specified). */
+  outputDirectory?: string
+  /** Enable SPA fallback routing (default: true for Vite/CRA, false for SSG frameworks). */
+  spa?: boolean
+  /** Environment variables to inject during build. */
+  env?: Record<string, string>
+  /** Custom response headers for the static site. */
+  headers?: Record<string, string>
+}
+
+export interface SupatypeConfig {
+  /** Database connection string. */
+  connection: string
+  /**
+   * Path (or glob) to the schema entry point.
+   * Must export model definitions as named exports.
+   * @example "./schema/index.ts"
+   */
+  schema: string
+  output?: {
+    /** Path for generated TypeScript types. */
+    types?: string
+    /** Path for generated client helpers. */
+    client?: string
+  }
+  /** Self-hosted production deployment configuration. */
+  selfHost?: SelfHostConfig
+  /** Cloud project reference (set by `supatype link --project <ref>`). */
+  projectRef?: string
+  /** Cloud API URL override. */
+  apiUrl?: string
+  /** Cloud access token (prefer SUPATYPE_ACCESS_TOKEN env var). */
+  accessToken?: string
+  /** CORS configuration. */
+  cors?: {
+    /** Allowed origins. Defaults to ['*'] in development. */
+    allowedOrigins?: string[]
+  }
+  /** Static site hosting configuration. */
+  app?: AppConfig
+  /** Registered plugins (provider, field, composite, widget). */
+  plugins?: Array<unknown> | undefined
+  /** Admin panel configuration (see Gap Appendices tasks 47–50). */
+  admin?: {
+    /**
+     * Roles from {ref}_auth.users that grant admin panel access.
+     * Checked against `app_metadata.role` in the project JWT.
+     * @default ["admin"]
+     */
+    roles?: string[]
+  }
+}
+
+/** Identity helper — provides type inference for config files. */
+export function defineConfig(config: SupatypeConfig): SupatypeConfig {
+  return config
+}
+
+const CONFIG_CANDIDATES = [
+  "supatype.config.ts",
+  "supatype.config.js",
+  "supatype.config.mjs",
+]
+
+/** Load and evaluate supatype.config.ts from the given directory. */
+export function loadConfig(cwd: string = process.cwd()): SupatypeConfig {
+  for (const candidate of CONFIG_CANDIDATES) {
+    const configPath = resolve(cwd, candidate)
+    if (!existsSync(configPath)) continue
+
+    const urlPath = "file:///" + configPath.replace(/\\/g, "/")
+
+    // Use dynamic import so we can always access .default —
+    // files without a parent package.json are treated as CJS by tsx,
+    // meaning export default becomes module.exports.default rather than
+    // the namespace default. Dynamic import + fallback handles both.
+    const snippet = `
+const mod = await import(${JSON.stringify(urlPath)})
+const config = mod.default ?? mod
+process.stdout.write(JSON.stringify(config))
+`
+    const result = evalTsSnippet(snippet, { cwd })
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `Failed to load ${candidate}:\n${result.stderr || result.stdout}`,
+      )
+    }
+
+    const parsed = JSON.parse(result.stdout) as SupatypeConfig
+    if (!parsed.connection || !parsed.schema) {
+      throw new Error(
+        `${candidate} must export { connection, schema } via defineConfig()`,
+      )
+    }
+    return parsed
+  }
+
+  throw new Error(
+    "No supatype.config.ts found in the current directory.\n" +
+      "Run: supatype init",
+  )
+}
+
+/** Load schema AST by evaluating the user's schema entry point via tsx. */
+export function loadSchemaAst(
+  schemaPath: string,
+  cwd: string = process.cwd(),
+): unknown {
+  const absPath = resolve(cwd, schemaPath)
+  if (!existsSync(absPath)) {
+    throw new Error(`Schema file not found: ${absPath}`)
+  }
+
+  const urlPath = "file:///" + absPath.replace(/\\/g, "/")
+
+  const snippet = `
+import { serialiseSchema } from "@supatype/schema"
+const mod = await import(${JSON.stringify(urlPath)})
+const { default: _default, ...named } = mod
+const models = Object.fromEntries(
+  Object.entries(named).filter(([, v]) =>
+    v != null && typeof v === "object" && "__modelMeta" in (v as object)
+  )
+)
+process.stdout.write(JSON.stringify(serialiseSchema(models)))
+`
+  const result = evalTsSnippet(snippet, { cwd })
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to load schema from ${absPath}:\n${result.stderr || result.stdout}`,
+    )
+  }
+
+  return JSON.parse(result.stdout)
+}

package/src/engine/cache.ts

@@ -0,0 +1,135 @@
+/**
+ * Local cache management for engine binaries.
+ * Binaries are stored at ~/.supatype/engine/{version}/supatype-engine[.exe]
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs"
+import { readFile, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { homedir } from "node:os"
+import type { PlatformInfo } from "./platform.js"
+
+/**
+ * Root cache directory: ~/.supatype/engine/
+ */
+export function getCacheDir(): string {
+  return join(homedir(), ".supatype", "engine")
+}
+
+/**
+ * Full path to a cached engine binary for a specific version.
+ */
+export function getCachedBinaryPath(version: string, platform: PlatformInfo): string {
+  return join(getCacheDir(), version, platform.binaryName)
+}
+
+/**
+ * Check if a valid cached binary exists for the given version.
+ */
+export function hasCachedBinary(version: string, platform: PlatformInfo): boolean {
+  const path = getCachedBinaryPath(version, platform)
+  return existsSync(path)
+}
+
+/**
+ * Ensure the cache directory for a version exists.
+ */
+export function ensureCacheDir(version: string): string {
+  const dir = join(getCacheDir(), version)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * List all cached engine versions.
+ */
+export function listCachedVersions(): string[] {
+  const cacheDir = getCacheDir()
+  if (!existsSync(cacheDir)) return []
+
+  return readdirSync(cacheDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort()
+}
+
+/**
+ * Remove all cached versions except the specified one.
+ * Returns the total bytes freed.
+ */
+export function pruneCacheExcept(keepVersion: string): { removed: string[]; bytesFreed: number } {
+  const versions = listCachedVersions()
+  const removed: string[] = []
+  let bytesFreed = 0
+
+  for (const version of versions) {
+    if (version === keepVersion) continue
+    const versionDir = join(getCacheDir(), version)
+    bytesFreed += getDirSize(versionDir)
+    rmSync(versionDir, { recursive: true, force: true })
+    removed.push(version)
+  }
+
+  return { removed, bytesFreed }
+}
+
+function getDirSize(dir: string): number {
+  let size = 0
+  if (!existsSync(dir)) return size
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isFile()) {
+      size += statSync(path).size
+    } else if (entry.isDirectory()) {
+      size += getDirSize(path)
+    }
+  }
+  return size
+}
+
+/**
+ * Update check throttling.
+ * Stores last check timestamp in ~/.supatype/update-check.json
+ */
+const UPDATE_CHECK_FILE = join(homedir(), ".supatype", "update-check.json")
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+interface UpdateCheckData {
+  lastCheck: number
+  latestVersion?: string
+}
+
+export async function shouldCheckForUpdates(): Promise<boolean> {
+  // Skip in CI environments
+  if (process.env.CI === "true" || process.env.CI === "1") return false
+
+  try {
+    if (!existsSync(UPDATE_CHECK_FILE)) return true
+    const data: UpdateCheckData = JSON.parse(await readFile(UPDATE_CHECK_FILE, "utf8"))
+    return Date.now() - data.lastCheck > CHECK_INTERVAL_MS
+  } catch {
+    return true
+  }
+}
+
+export async function saveUpdateCheck(latestVersion: string): Promise<void> {
+  const dir = join(homedir(), ".supatype")
+  mkdirSync(dir, { recursive: true })
+
+  const data: UpdateCheckData = {
+    lastCheck: Date.now(),
+    latestVersion,
+  }
+  await writeFile(UPDATE_CHECK_FILE, JSON.stringify(data, null, 2))
+}
+
+export async function getLastKnownLatestVersion(): Promise<string | undefined> {
+  try {
+    if (!existsSync(UPDATE_CHECK_FILE)) return undefined
+    const data: UpdateCheckData = JSON.parse(await readFile(UPDATE_CHECK_FILE, "utf8"))
+    return data.latestVersion
+  } catch {
+    return undefined
+  }
+}

package/src/engine/download.ts

@@ -0,0 +1,143 @@
+/**
+ * Engine binary download with progress bar, retry, and proxy support.
+ */
+
+import { createWriteStream } from "node:fs"
+import { Readable } from "node:stream"
+import { pipeline } from "node:stream/promises"
+
+export interface DownloadOptions {
+  url: string
+  dest: string
+  showProgress?: boolean
+  label?: string
+}
+
+const MAX_RETRIES = 3
+const RETRY_DELAYS = [1000, 3000, 10000]
+
+/**
+ * Download a file with retry and optional progress bar.
+ * Respects HTTP_PROXY / HTTPS_PROXY environment variables.
+ */
+export async function downloadFile(options: DownloadOptions): Promise<void> {
+  const { url, dest, showProgress = false, label } = options
+  let lastError: Error | undefined
+
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    try {
+      await doDownload(url, dest, showProgress, label)
+      return
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err))
+      if (attempt < MAX_RETRIES - 1) {
+        const delay = RETRY_DELAYS[attempt]!
+        process.stderr.write(
+          `Download failed. Retrying (${attempt + 2}/${MAX_RETRIES})...\n`,
+        )
+        await sleep(delay)
+      }
+    }
+  }
+
+  throw new Error(
+    `Failed to download after ${MAX_RETRIES} attempts: ${lastError?.message}`,
+  )
+}
+
+async function doDownload(
+  url: string,
+  dest: string,
+  showProgress: boolean,
+  label?: string,
+): Promise<void> {
+  const fetchOptions = buildFetchOptions(url)
+  const res = await fetch(url, fetchOptions)
+
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText}: ${url}`)
+  }
+
+  if (!res.body) {
+    throw new Error(`No response body: ${url}`)
+  }
+
+  const contentLength = Number(res.headers.get("content-length") || 0)
+  const out = createWriteStream(dest)
+
+  if (showProgress && contentLength > 0 && process.stderr.isTTY) {
+    const progressStream = createProgressStream(contentLength, label)
+    await pipeline(Readable.fromWeb(res.body as any), progressStream, out)
+    // Clear the progress line
+    process.stderr.write("\n")
+  } else {
+    if (showProgress && label) {
+      process.stderr.write(`${label}...\n`)
+    }
+    await pipeline(Readable.fromWeb(res.body as any), out)
+  }
+}
+
+/**
+ * Build fetch options respecting proxy env vars.
+ */
+function buildFetchOptions(url: string): RequestInit {
+  const opts: RequestInit = {}
+
+  // Node.js 18+ fetch supports the proxy via undici dispatcher.
+  // For simplicity, we rely on the global-agent or undici proxy support.
+  // The user should set HTTPS_PROXY or HTTP_PROXY env vars.
+  // Node.js 22+ automatically respects these in fetch().
+  //
+  // For older Node.js, users can install global-agent or similar.
+
+  return opts
+}
+
+/**
+ * Creates a Transform stream that logs download progress to stderr.
+ */
+function createProgressStream(
+  totalBytes: number,
+  label?: string,
+): import("node:stream").Transform {
+  const { Transform } = require("node:stream") as typeof import("node:stream")
+  let downloaded = 0
+
+  return new Transform({
+    transform(chunk: Buffer, _encoding, callback) {
+      downloaded += chunk.length
+      const percent = Math.round((downloaded / totalBytes) * 100)
+      const mb = (downloaded / (1024 * 1024)).toFixed(1)
+      const totalMb = (totalBytes / (1024 * 1024)).toFixed(1)
+      const barWidth = 30
+      const filled = Math.round((percent / 100) * barWidth)
+      const bar = "=".repeat(filled) + " ".repeat(barWidth - filled)
+
+      const prefix = label || "Downloading"
+      process.stderr.write(
+        `\r${prefix} ${mb}MB/${totalMb}MB [${bar}] ${percent}%`,
+      )
+
+      this.push(chunk)
+      callback()
+    },
+  })
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Fetch a JSON file from a URL. Returns undefined on failure.
+ */
+export async function fetchJson<T>(url: string): Promise<T | undefined> {
+  try {
+    const res = await fetch(url)
+    if (!res.ok) return undefined
+    return (await res.json()) as T
+  } catch {
+    return undefined
+  }
+}

package/src/engine/platform.ts

@@ -0,0 +1,66 @@
+/**
+ * Platform detection for engine binary downloads.
+ * Maps Node.js platform/arch to the binary naming convention.
+ */
+
+export interface PlatformInfo {
+  os: "linux" | "darwin" | "win"
+  arch: "x64" | "arm64"
+  binaryName: string
+  ext: string
+}
+
+const PLATFORM_MAP: Record<string, { os: PlatformInfo["os"]; arch: PlatformInfo["arch"] }> = {
+  "darwin-arm64": { os: "darwin", arch: "arm64" },
+  "darwin-x64": { os: "darwin", arch: "x64" },
+  "linux-arm64": { os: "linux", arch: "arm64" },
+  "linux-x64": { os: "linux", arch: "x64" },
+  "win32-x64": { os: "win", arch: "x64" },
+}
+
+const SUPPORTED_PLATFORMS = [
+  "linux-x64",
+  "linux-arm64",
+  "darwin-x64",
+  "darwin-arm64",
+  "win-x64",
+]
+
+/**
+ * Detect the current platform and return the binary info.
+ * Throws on unsupported platforms with a helpful message.
+ */
+export function detectPlatform(): PlatformInfo {
+  const key = `${process.platform}-${process.arch}`
+  const mapped = PLATFORM_MAP[key]
+
+  if (!mapped) {
+    throw new Error(
+      `Supatype engine is not available for ${process.platform}-${process.arch}.\n` +
+      `Supported platforms: ${SUPPORTED_PLATFORMS.join(", ")}`,
+    )
+  }
+
+  const ext = mapped.os === "win" ? ".exe" : ""
+
+  return {
+    os: mapped.os,
+    arch: mapped.arch,
+    binaryName: `supatype-engine${ext}`,
+    ext,
+  }
+}
+
+/**
+ * Build the artifact filename for a given version and platform.
+ */
+export function getArtifactName(version: string, platform: PlatformInfo): string {
+  return `supatype-engine-${version}-${platform.os}-${platform.arch}${platform.ext}`
+}
+
+/**
+ * Build the CDN download URL for a given version and artifact.
+ */
+export function getCdnUrl(baseUrl: string, version: string, filename: string): string {
+  return `${baseUrl}/v${version}/${filename}`
+}