@supatype/cli 0.1.6 → 0.1.9

package/src/commands/cache.ts

@@ -1,10 +1,16 @@
 /**
- * supatype cache — list and clean cached component binaries + REST Valkey cache.
+ * supatype cache: list and clean cached component binaries + REST Valkey cache.
  */
 
 import type { Command } from "commander"
-import { existsSync, readdirSync, rmSync, statSync } from "node:fs"
-import { join } from "node:path"
+import { existsSync } from "node:fs"
+import {
+  BINARY_COMPONENTS,
+  formatBytes,
+  listCacheEntries,
+  resolveCacheProjectDirs,
+} from "../cache-clean.js"
+import { cleanCachedBinaries } from "../cache-pins.js"
 import { cacheRoot, type Component } from "../binary-cache.js"
 import {
   deleteRestCacheEntry,
@@ -12,9 +18,11 @@ import {
   getRestCacheEntry,
   listRestCacheEntries,
 } from "../rest-cache-admin.js"
-import { error, info, plain } from "../ui/messages.js"
+import { error, info, plain, warn } from "../ui/messages.js"
 
-const COMPONENTS: Component[] = ["engine", "server", "postgres", "deno"]
+function isComponent(value: string): value is Component {
+  return (BINARY_COMPONENTS as readonly string[]).includes(value)
+}
 
 export function registerCache(program: Command): void {
   const cache = program
@@ -24,79 +32,106 @@ export function registerCache(program: Command): void {
   cache
     .command("list")
     .description("List cached component binaries and their sizes")
-    .action(async () => {
+    .option("--project <path>", "Include pins from another project directory", collectPaths, [])
+    .action(async (opts: { project: string[] }) => {
+      const cwd = process.cwd()
+      const projectDirs = resolveCacheProjectDirs(cwd, opts.project)
       const root = cacheRoot()
+
       if (!existsSync(root)) {
         info("Cache is empty.")
         return
       }
 
-      let totalBytes = 0
-      let found = false
-
-      for (const component of COMPONENTS) {
-        const compDir = join(root, component)
-        if (!existsSync(compDir)) continue
-
-        const versions = readdirSync(compDir).filter(
-          (v) => statSync(join(compDir, v)).isDirectory(),
-        )
-        for (const version of versions) {
-          const vDir = join(compDir, version)
-          const size = dirSize(vDir)
-          totalBytes += size
-          found = true
-          plain(`  ${component}@${version}  ${formatBytes(size)}`)
-        }
-      }
-
-      if (!found) {
+      const entries = listCacheEntries(projectDirs)
+      if (entries.length === 0) {
         info("Cache is empty.")
         return
       }
 
+      let totalBytes = 0
+      for (const entry of entries) {
+        totalBytes += entry.bytes
+        const pinLabel = entry.pinned ? "  (pinned)" : ""
+        plain(`  ${entry.component}@${entry.version}  ${formatBytes(entry.bytes)}${pinLabel}`)
+      }
+
       plain(`\nTotal: ${formatBytes(totalBytes)}`)
       info(`Cache root: ${root}`)
+      if (projectDirs.length > 0) {
+        info(`Pin scan: ${projectDirs.length} project(s)`)
+      }
     })
 
   cache
     .command("clean [component] [version]")
     .description(
-      "Remove cached binaries. Optionally specify a component and/or version.\n" +
+      "Remove cached binaries not pinned by local project configs.\n" +
+        "Use --force to remove everything (legacy behavior).\n" +
         "Examples:\n" +
-        "  supatype cache clean           # remove everything\n" +
-        "  supatype cache clean engine    # remove all engine versions\n" +
-        "  supatype cache clean engine 0.4.2",
+        "  supatype cache clean                    # remove unpinned versions\n" +
+        "  supatype cache clean engine             # remove unpinned engine versions\n" +
+        "  supatype cache clean engine 0.4.2       # remove one version (warns if pinned)\n" +
+        "  supatype cache clean --force            # remove all cached binaries",
     )
-    .action(async (component?: string, version?: string) => {
-      const root = cacheRoot()
-      if (!existsSync(root)) {
-        info("Cache is already empty.")
-        return
-      }
+    .option("--dry-run", "Show what would be removed without deleting")
+    .option("--force", "Remove all matching cache entries, ignoring version pins")
+    .option("--project <path>", "Include pins from another project directory", collectPaths, [])
+    .action(
+      async (
+        component?: string,
+        version?: string,
+        opts?: { dryRun?: boolean; force?: boolean; project?: string[] },
+      ) => {
+        const cwd = process.cwd()
+        const projectDirs = resolveCacheProjectDirs(cwd, opts?.project ?? [])
+        const root = cacheRoot()
+
+        if (!existsSync(root)) {
+          info("Cache is already empty.")
+          return
+        }
 
-      const targets = component ? [component as Component] : COMPONENTS
+        if (component && !isComponent(component)) {
+          error(
+            `Unknown component "${component}". Valid: ${BINARY_COMPONENTS.join(", ")}`,
+          )
+          process.exitCode = 1
+          return
+        }
 
-      for (const comp of targets) {
-        const compDir = join(root, comp)
-        if (!existsSync(compDir)) continue
+        const components: Component[] =
+          component !== undefined ? [component as Component] : [...BINARY_COMPONENTS]
+        const result = cleanCachedBinaries({
+          components,
+          ...(version !== undefined && version !== "" ? { version } : {}),
+          ...(opts?.force !== undefined ? { force: opts.force } : {}),
+          ...(opts?.dryRun !== undefined ? { dryRun: opts.dryRun } : {}),
+          projectDirs,
+        })
+
+        for (const message of result.warned) {
+          warn(message)
+        }
 
-        if (version) {
-          const vDir = join(compDir, version)
-          if (!existsSync(vDir)) {
-            info(`${comp}@${version} not cached.`)
-            continue
-          }
-          rmSync(vDir, { recursive: true, force: true })
-          plain(`  removed  ${comp}@${version}`)
-        } else {
-          rmSync(compDir, { recursive: true, force: true })
-          plain(`  removed  ${comp} (all versions)`)
+        for (const entry of result.skipped) {
+          plain(`  kept     ${entry.component}@${entry.version}  (${entry.reason})`)
         }
-      }
 
-      info("Done.")
-    })
+        for (const entry of result.removed) {
+          const prefix = opts?.dryRun ? "would remove" : "removed"
+          plain(`  ${prefix}  ${entry.component}@${entry.version}`)
+        }
+
+        if (result.removed.length === 0 && result.skipped.length === 0) {
+          info("Nothing to clean.")
+        } else if (opts?.dryRun) {
+          info(`Dry run: ${result.removed.length} entr${result.removed.length === 1 ? "y" : "ies"} would be removed.`)
+        } else {
+          info("Done.")
+        }
+      },
+    )
 
   const rest = cache
     .command("rest")
@@ -125,7 +160,7 @@ export function registerCache(program: Command): void {
           )
         }
         if (result.cursor !== "0") {
-          plain(`\n(more available — cursor ${result.cursor})`)
+          plain(`\n(more available: cursor ${result.cursor})`)
         }
       } catch (e) {
         error(e instanceof Error ? e.message : String(e))
@@ -193,26 +228,6 @@ export function registerCache(program: Command): void {
     })
 }
 
-function dirSize(dir: string): number {
-  let total = 0
-  try {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const full = join(dir, entry.name)
-      if (entry.isDirectory()) {
-        total += dirSize(full)
-      } else {
-        total += statSync(full).size
-      }
-    }
-  } catch {
-    // Skip unreadable entries.
-  }
-  return total
-}
-
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
-  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
-  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`
+function collectPaths(value: string, previous: string[]): string[] {
+  return [...previous, value]
 }

package/src/commands/cloud.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander"
 import { readFileSync, writeFileSync, existsSync } from "node:fs"
 import { resolve } from "node:path"
+import { loadCloudCredentials, persistCloudSession } from "../cloud-credentials.js"
 import { loadProjectLink, migrateLegacyLinkFiles } from "../link.js"
 import { targetFetch } from "../target-client.js"
 import { registerEnvs, registerLinkOptions, runLinkAction } from "./link-helpers.js"
@@ -28,7 +29,7 @@ export function loadCloudConfig(cwd: string): CloudConfig | null {
   }
   return {
     apiUrl: link.cloudApiUrl ?? "https://api.supatype.com",
-    token: link.token ?? "",
+    token: link.token ?? loadCloudCredentials()?.accessToken ?? "",
     projectSlug: link.projectRef,
     ...(link.orgId !== undefined ? { orgId: link.orgId } : {}),
   }
@@ -44,19 +45,39 @@ function saveCloudConfig(cwd: string, config: CloudConfig): void {
 }
 
 async function cloudFetch<T>(config: CloudConfig, method: string, path: string, body?: unknown): Promise<T> {
+  const cwd = process.cwd()
+  const creds = loadCloudCredentials()
+  const refreshToken = creds?.refreshToken ?? loadProjectLink(cwd)?.refreshToken
   return targetFetch<T>(config.apiUrl, "/api/v1", {
     method,
     path,
-    body,
+    ...(body !== undefined ? { body } : {}),
     token: config.token,
-    orgId: config.orgId,
+    ...(config.orgId !== undefined ? { orgId: config.orgId } : {}),
+    ...(refreshToken
+      ? {
+          authRefresh: {
+            cloudApiUrl: config.apiUrl,
+            refreshToken,
+            onRefreshed: ({ accessToken, refreshToken: nextRefresh }) => {
+              persistCloudSession(cwd, {
+                apiUrl: config.apiUrl,
+                accessToken,
+                ...(nextRefresh !== undefined ? { refreshToken: nextRefresh } : {}),
+              })
+              config.token = accessToken
+            },
+          },
+        }
+      : {}),
   })
 }
 
 export function isCloudLinked(cwd: string): boolean {
   migrateLegacyLinkFiles(cwd)
   const link = loadProjectLink(cwd)
-  return Boolean(link?.kind === "cloud" && link.projectRef && link.token)
+  if (!(link?.kind === "cloud" && link.projectRef)) return false
+  return Boolean(link.token || loadCloudCredentials()?.accessToken)
 }
 
 export async function pushSchemaToLinkedProject(
@@ -260,15 +281,18 @@ function getCloudConfigOrExit(): CloudConfig {
   const cwd = process.cwd()
   let config = loadCloudConfig(cwd)
   if (!config) {
+    const creds = loadCloudCredentials()
     const token =
       process.env["SUPATYPE_ACCESS_TOKEN"] ??
-      process.env["SUPATYPE_TOKEN"]
-    const apiUrl = process.env["SUPATYPE_API_URL"] ?? "https://api.supatype.com"
+      process.env["SUPATYPE_TOKEN"] ??
+      creds?.accessToken
+    const apiUrl =
+      process.env["SUPATYPE_API_URL"] ?? creds?.apiUrl ?? "https://api.supatype.com"
     if (!token) {
-      error("Not connected to Supatype Cloud. Run: supatype link, or set SUPATYPE_ACCESS_TOKEN.")
+      error("Not connected to Supatype Cloud. Run: supatype login (then supatype link), or set SUPATYPE_ACCESS_TOKEN.")
       process.exit(1)
     }
-    config = { apiUrl, token }
+    config = { apiUrl: apiUrl.replace(/\/$/, ""), token }
   }
   return config
 }

package/src/commands/db.ts

@@ -1,7 +1,8 @@
 /**
  * Database connection commands:
- *   supatype db connection-string  — show the connection string for the linked project
- *   supatype db reset-password     — reset the database password
+ *   supatype db connection-string: show the connection string for the linked project
+ *   supatype db reset-password: reset the database password
+ *   supatype db check: does this database meet what Supatype needs of it?
  */
 
 import type { Command } from "commander"
@@ -10,7 +11,16 @@ import { connectionString } from "../project-config.js"
 import { loadProjectLink } from "../link.js"
 import { resolveTarget } from "../resolve-target.js"
 import { targetFetch } from "../target-client.js"
-import { error, info, plain } from "../ui/messages.js"
+import { error, info, plain, warn } from "../ui/messages.js"
+import {
+  applyRemedies,
+  needsOperatorPassword,
+  operatorRemedies,
+  runPreflight,
+  transactionalRemedies,
+  type CheckResult,
+  type Severity,
+} from "../db-preflight.js"
 
 export function registerDb(program: Command): void {
   const db = program
@@ -110,4 +120,155 @@ export function registerDb(program: Command): void {
         process.exitCode = 1
       }
     })
+
+  db
+    .command("check")
+    .description("Check whether a database meets Supatype's requirements (for external Postgres)")
+    .option("--connection <url>", "Postgres URL to check (else config `connection`, else DATABASE_URL)")
+    .option("--schema <name>", "Schema Supatype will manage (else config `schema.pg_schema`)")
+    .option("--emit", "Print the remediation SQL instead of applying it")
+    .option("--fix", "Apply the remediation in a single transaction")
+    .option(
+      "--authenticator-password <password>",
+      "Password for the `authenticator` role when it has to be created",
+    )
+    .action(async (opts: {
+      connection?: string
+      schema?: string
+      emit?: boolean
+      fix?: boolean
+      authenticatorPassword?: string
+    }) => {
+      if (opts.emit && opts.fix) {
+        error("Pass either --emit or --fix, not both: one prints the SQL, the other runs it.")
+        process.exitCode = 1
+        return
+      }
+
+      const cwd = process.cwd()
+      let url = opts.connection?.trim()
+      let schema = opts.schema?.trim()
+      if (!url || !schema) {
+        try {
+          const config = loadConfig(cwd)
+          url = url ?? connectionString(config)
+          schema = schema ?? config.schema?.pg_schema ?? "public"
+        } catch {
+          // Runnable outside a project, which is the point, an operator should be able to check a
+          // database before committing to any config at all.
+          url = url ?? process.env["DATABASE_URL"]
+          schema = schema ?? "public"
+        }
+      }
+      if (!url) {
+        error("No connection. Pass --connection, set DATABASE_URL, or set `connection` in supatype.config.ts.")
+        process.exitCode = 1
+        return
+      }
+
+      const pgMod = await import("pg")
+      const client = new pgMod.default.Client({ connectionString: url })
+      try {
+        await client.connect()
+      } catch (err) {
+        error(`Could not connect: ${(err as Error).message}`)
+        process.exitCode = 1
+        return
+      }
+
+      try {
+        const report = await runPreflight(client, {
+          schema: schema!,
+          ...(opts.authenticatorPassword !== undefined && {
+            authenticatorPassword: opts.authenticatorPassword,
+          }),
+        })
+
+        const fixable = transactionalRemedies(report)
+        const manual = operatorRemedies(report)
+
+        if (opts.emit) {
+          // Machine-consumable: SQL on stdout, commentary on stderr, so it can be piped to psql.
+          if (fixable.length === 0) {
+            warn("Nothing to emit: no SQL-fixable findings.")
+          } else {
+            plain("BEGIN;")
+            for (const r of fixable) plain(`\n-- ${r.title}\n${r.remedy}`)
+            plain("\nCOMMIT;")
+          }
+          if (manual.length > 0) {
+            warn(`\n${manual.length} finding(s) need operator action and are not included above:`)
+            for (const r of manual) warn(`  ${r.title}, ${r.detail}`)
+          }
+          return
+        }
+
+        printReport(report.results)
+
+        if (opts.fix) {
+          if (fixable.length === 0) {
+            info("Nothing to fix.")
+          } else if (needsOperatorPassword(fixable)) {
+            // The credential is the operator's by decision. Creating the role with a placeholder
+            // password would be worse than refusing, and harder to notice.
+            error(
+              "`authenticator` has to be created and no password was given. Nothing was changed.\n" +
+                "  Re-run with --authenticator-password <password>, or use --emit and apply the SQL yourself.\n" +
+                "  Use the same value for AUTHENTICATOR_PASSWORD in your .env.",
+            )
+            process.exitCode = 1
+            return
+          } else {
+            info(`\nApplying ${fixable.length} remediation(s) in one transaction...`)
+            try {
+              await applyRemedies(client, fixable)
+              info("Applied. Re-run `supatype db check` to confirm.")
+            } catch (err) {
+              error(`Rolled back: the database is unchanged: ${(err as Error).message}`)
+              process.exitCode = 1
+              return
+            }
+          }
+          if (manual.length > 0) {
+            warn(`\n${manual.length} finding(s) cannot be fixed in a transaction:`)
+            for (const r of manual) {
+              warn(`  ${r.title}: needs a server setting change and likely a restart`)
+            }
+          }
+          return
+        }
+
+        if (report.worst === "fail") {
+          plain("")
+          error("This database is not ready. Re-run with --emit to see the SQL, or --fix to apply it.")
+          process.exitCode = 1
+        } else if (fixable.length > 0) {
+          plain("")
+          info("Re-run with --emit to see suggested SQL, or --fix to apply it.")
+        }
+      } catch (err) {
+        // An unexpected failure must not read as a clean bill of health.
+        error(`Preflight could not complete: ${(err as Error).message}`)
+        process.exitCode = 1
+      } finally {
+        await client.end().catch(() => undefined)
+      }
+    })
+}
+
+const SEVERITY_LABEL: Record<Severity, string> = {
+  pass: "ok  ",
+  warn: "note",
+  degrade: "off ",
+  fail: "FAIL",
+}
+
+function printReport(results: readonly CheckResult[]): void {
+  for (const r of results) {
+    const line = `[${SEVERITY_LABEL[r.severity]}] ${r.title}, ${r.detail}`
+    if (r.severity === "fail") error(line)
+    else if (r.severity === "degrade" || r.severity === "warn") warn(line)
+    else plain(line)
+    if (r.impact) plain(`         ${r.impact}`)
+  }
 }

package/src/commands/deploy.ts

@@ -1,14 +1,14 @@
 /**
  * Deploy commands:
- *   supatype deploy              — Supatype Cloud by default (linked via supatype link), else platform projectRef; use --local for engine + DB
- *   supatype deploy --local      — push schema via local engine + optional static app to .supatype/static
- *   supatype deploy --app-only   — only build & deploy the static site
- *   supatype deploy --schema-only — only push schema changes
- *   supatype deploy --skip-build — deploy existing build output (no build step)
- *   supatype deploy --preview    — deploy to a preview URL
- *   supatype deploy rollback     — roll back to previous deployment
- *   supatype deploy status       — show current deployment info
- *   supatype deploy logs <version> — show build logs
+ *   supatype deploy: Supatype Cloud by default (linked via supatype link), else platform projectRef; use --local for engine + DB
+ *   supatype deploy --local: push schema via local engine + optional static app to .supatype/static
+ *   supatype deploy --app-only: only build & deploy the static site
+ *   supatype deploy --schema-only: only push schema changes
+ *   supatype deploy --skip-build: deploy existing build output (no build step)
+ *   supatype deploy --preview: deploy to a preview URL
+ *   supatype deploy rollback: roll back to previous deployment
+ *   supatype deploy status: show current deployment info
+ *   supatype deploy logs <version>, show build logs
  */
 
 import type { Command } from "commander"
@@ -31,7 +31,7 @@ export function registerDeploy(program: Command): void {
   const deploy = program
     .command("deploy")
     .description(
-      "Deploy schema and app — Supatype Cloud by default when linked (`supatype link`); pass --local for engine + your database",
+      "Deploy schema and app, Supatype Cloud by default when linked (`supatype link`); pass --local for engine + your database",
     )
     .option("--local", "Use local schema engine and database_url from config (skip cloud control plane)")
     .option("--environment <name>", "Target environment when linked", "production")
@@ -119,7 +119,7 @@ export function registerDeploy(program: Command): void {
             error("No build section found in supatype.config.ts")
             process.exit(1)
           }
-          // No build config — skip app deployment silently
+          // No build config: skip app deployment silently
           return
         }
 
@@ -151,7 +151,7 @@ export function registerDeploy(program: Command): void {
             buildEnv["NEXT_PUBLIC_SUPATYPE_URL"] = cloudCfg.apiUrl || `https://${cloudCfg.projectSlug}.supatype.dev`
             buildEnv["VITE_SUPATYPE_URL"] = buildEnv["NEXT_PUBLIC_SUPATYPE_URL"]!
             buildEnv["PUBLIC_SUPATYPE_URL"] = buildEnv["NEXT_PUBLIC_SUPATYPE_URL"]!
-            // NEVER inject service_role key — only anon key is safe for client-side
+            // NEVER inject service_role key, only anon key is safe for client-side
           }
 
           // Install dependencies