@supatype/cli 0.1.5 → 0.1.7

package/src/commands/doctor.ts

@@ -1,10 +1,12 @@
 import type { Command } from "commander"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { info, plain } from "../ui/messages.js"
-import { schemaPathFromProject } from "../project-config.js"
+import { hooksPathFromProject, schemaPathFromProject, serviceRoleRoutes } from "../project-config.js"
 import { resolveTarget, targetSchemaDoctor, schemaPgSchema } from "../resolve-target.js"
 import { loadProjectLink } from "../link.js"
 import { resolveHostEngineDatabaseUrl } from "../dev-compose.js"
+import { hooksReport, type HooksReport } from "../model-hooks.js"
+import { checkServiceRoleRoutes, type ServiceRoleProblems } from "../service-role-check.js"
 
 interface DoctorItem {
   kind: string
@@ -20,12 +22,15 @@ interface DoctorReport {
   unmanagedDrift: DoctorItem[]
 }
 
-function printSection(title: string, items: DoctorItem[]): void {
+/** Exported for tests: the label form is easy to get subtly wrong per item kind. */
+export function printSection(title: string, items: DoctorItem[]): void {
   if (items.length === 0) return
   plain(`\n${title} (${items.length}):\n`)
   for (const item of items) {
     const fields = item.fields.length > 0 ? ` (${item.fields.join(", ")})` : ""
-    plain(`  • ${item.table}.${item.name}${fields}`)
+    // A table's `name` *is* its table, so the usual `table.name` form renders "widget.widget".
+    const label = item.table === item.name ? item.name : `${item.table}.${item.name}`
+    plain(`  • ${label}${fields}`)
     plain(`    ${item.message}`)
   }
 }
@@ -82,6 +87,9 @@ export function registerDoctor(program: Command): void {
         })) as DoctorReport
       }
 
+      printHooks(hooksReport(cwd, hooksPathFromProject(config, cwd), ast))
+      printServiceRoleGrants(checkServiceRoleRoutes(config, cwd), serviceRoleRoutes(config))
+
       printSection("Missing (in AST, not in DB)", report.missing ?? [])
       printSection("Stale managed (stamped, not in AST)", report.staleManaged ?? [])
       printSection("Unmanaged drift (manual decision)", report.unmanagedDrift ?? [])
@@ -101,3 +109,61 @@ export function registerDoctor(program: Command): void {
       }
     })
 }
+
+/**
+ * Whether declared hooks can actually run.
+ *
+ * Worth its own section because every failure here is silent: a hook whose function is missing, or a
+ * stack with functions switched off, produces no error anywhere — the write just succeeds
+ * unvalidated. Drift you cannot see is the thing doctor exists for.
+ */
+export function printHooks(report: HooksReport): void {
+  if (report.declared.length === 0) return
+
+  plain(`\nHooks (${report.declared.length}):\n`)
+  for (const hook of report.declared) {
+    const broken = report.missing.some(
+      (m) => m.model === hook.model && m.event === hook.event,
+    )
+    plain(`  ${broken ? "✗" : "•"} ${hook.model}.${hook.event} → ${hook.function}`)
+  }
+
+  if (report.missing.length > 0) {
+    plain("\n  Those marked ✗ name a function that does not exist, so they never fire.")
+    plain("  Create it with: supatype hooks new <name>")
+  }
+  if (report.functionsDisabled) {
+    plain("\n  functions_enabled is false in .supatype/manifest.json — every hook is inert.")
+    plain("  Regenerate the stack config with: supatype self-host compose")
+  }
+  if (report.mapMissing) {
+    plain("\n  .supatype/manifest.json carries no hook map, so the server has nothing to call.")
+    plain("  Run: supatype push")
+  }
+}
+
+/**
+ * Report which functions may see the service-role key, and which grants do nothing.
+ *
+ * Worth printing even when everything resolves: this is the list of functions that can read and write
+ * past every access rule in the schema, and "which ones are those again?" should be answerable without
+ * opening the config.
+ */
+export function printServiceRoleGrants(
+  problems: ServiceRoleProblems,
+  declared: readonly string[],
+): void {
+  if (declared.length === 0) return
+
+  plain(`\nService-role grants (${declared.length}):\n`)
+  const broken = new Set(problems.missing)
+  for (const name of declared) {
+    plain(`  ${broken.has(name) ? "✗" : "•"} ${name}`)
+  }
+
+  if (broken.size > 0) {
+    plain("\n  Those marked ✗ match no function, so they grant nothing — the function reads no key.")
+  }
+  for (const warning of problems.warnings) plain(warning)
+  plain("\n  These functions bypass every access rule in the schema. Anything not listed cannot.")
+}

package/src/commands/functions.ts

@@ -16,6 +16,7 @@ import { ensureBinary } from "../ensure-binary.js"
 import {
   functionsPathCandidatesFromProject,
   preferredFunctionsPathFromProject,
+  serviceRoleRoutes,
 } from "../project-config.js"
 import {
   discoverTsFunctionsInDir,
@@ -24,6 +25,7 @@ import {
 import { loadProjectLink } from "../link.js"
 import { resolveTarget } from "../resolve-target.js"
 import { targetFetch } from "../target-client.js"
+import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
 import { error, info, plain } from "../ui/messages.js"
 import { nextSteps } from "../ui/next-steps.js"
 
@@ -140,18 +142,19 @@ function scaffoldFunction(cwd: string, name: string): void {
 // Docs: https://supatype.com/docs/edge-functions
 
 export default async function handler(req: Request): Promise<Response> {
-  const { method, url } = req
+  const { method } = req
+  const url = Deno.env.get("SUPATYPE_URL")
 
   // Example: read request body for POST requests
   if (method === "POST") {
     const body = await req.json()
-    return new Response(JSON.stringify({ message: "Hello from ${name}!", received: body }), {
+    return new Response(JSON.stringify({ message: "Hello from ${name}!", received: body, url }), {
       status: 200,
       headers: { "Content-Type": "application/json" },
     })
   }
 
-  return new Response(JSON.stringify({ message: "Hello from ${name}!" }), {
+  return new Response(JSON.stringify({ message: "Hello from ${name}!", url }), {
     status: 200,
     headers: { "Content-Type": "application/json" },
   })
@@ -181,13 +184,27 @@ export default async function handler(req: Request): Promise<Response> {
     )
   }
 
+  const denoTypes = ensureFunctionsDenoTypes(cwd, functionsDir)
+
   const functionsDirLabel = relativeFunctionsDir(cwd, functionsDir)
   info(`Created function: ${functionsDirLabel}/${name}/index.ts`)
-  nextSteps("Next steps:", [
+  if (denoTypes.wroteDenoDts) {
+    info(`Added Deno IDE types: ${functionsDirLabel}/deno.d.ts`)
+  }
+  if (denoTypes.wroteTsconfig) {
+    info(`Added functions tsconfig: ${functionsDirLabel}/tsconfig.json`)
+  }
+  if (denoTypes.rootExclude === "updated") {
+    info('Updated root tsconfig.json to exclude "functions"')
+  }
+
+  const steps = [
     "Local dev:    npx supatype functions serve",
     `Invoke:       npx supatype functions invoke ${name}`,
     "Deploy:       npx supatype functions deploy",
-  ])
+    ...denoTypes.hints,
+  ]
+  nextSteps("Next steps:", steps)
 }
 
 // ─── Discover functions ──────────────────────────────────────────────────────
@@ -422,6 +439,9 @@ async function deployViaTarget(
               source,
               entrypoint: `${fn.name}/index.ts`,
             }],
+            // Sent every deploy, and replaced wholesale by the platform: the config file is the whole
+            // truth, so a name removed from it must stop being entitled to the service-role key.
+            serviceRole: serviceRoleRoutesFor(cwd),
           },
           token: target.token!,
           orgId: target.orgId,
@@ -479,6 +499,9 @@ async function deployCloud(cwd: string, fns: DiscoveredFunction[], env?: string)
             source,
             entrypoint: `${fn.name}/index.ts`,
           }],
+          // Same grants as the target path: both reach the same endpoint, and a project deployed one
+          // way must not end up with a different credential surface than the other.
+          serviceRole: serviceRoleRoutesFor(cwd),
         }),
         signal: AbortSignal.timeout(60_000),
       })
@@ -500,6 +523,20 @@ async function deployCloud(cwd: string, fns: DiscoveredFunction[], env?: string)
   info(`Invoke: https://${linked.ref}.supatype.dev/functions/v1/<name>`)
 }
 
+/**
+ * The project's `functions.serviceRole` list, or undefined when the config cannot be read.
+ *
+ * Undefined rather than `[]`: the platform replaces the stored list wholesale when the field is present,
+ * so sending an empty array because a config failed to load would revoke every grant the project has.
+ */
+export function serviceRoleRoutesFor(cwd: string): string[] | undefined {
+  try {
+    return serviceRoleRoutes(loadConfig(cwd))
+  } catch {
+    return undefined
+  }
+}
+
 function readFunctionSource(fn: DiscoveredFunction): string {
   const stat = statSync(fn.absPath)
   if (stat.isFile()) {

package/src/commands/generate.ts

@@ -2,9 +2,10 @@ import type { Command } from "commander"
 import { mkdirSync, writeFileSync } from "node:fs"
 import { resolve, dirname } from "node:path"
 import { loadConfig, loadSchemaAst } from "../config.js"
-import { schemaPathFromProject } from "../project-config.js"
+import { hooksPathFromProject, schemaPathFromProject } from "../project-config.js"
 import { ensureEngine, engineRequest } from "../engine-client.js"
 import { generateClientAugmentation } from "../augmentation-generator.js"
+import { writeHooksModule } from "../model-hooks.js"
 import { error, info } from "../ui/messages.js"
 
 export function registerGenerate(program: Command): void {
@@ -41,5 +42,8 @@ export function registerGenerate(program: Command): void {
       mkdirSync(dirname(augmentationOutPath), { recursive: true })
       writeFileSync(augmentationOutPath, augmentationCode, "utf8")
       info(`Client augmentation written to ${outputClientPath}`)
+
+      const hooksPath = writeHooksModule(cwd, hooksPathFromProject(config, cwd), ast)
+      if (hooksPath !== null) info(`Hook handler types written to ${hooksPath}`)
     })
 }

package/src/commands/hooks.ts

@@ -0,0 +1,138 @@
+/**
+ * `supatype hooks` — scaffold and inspect model hooks.
+ *
+ * Separate from `supatype functions` because the two are different things wearing the same runtime.
+ * A function is a **public endpoint**: anyone holding the anon key can invoke it. A hook is
+ * **procedural** — only the API server calls it, around a write, and the gateway refuses the route
+ * from outside. Keeping them in separate directories is what makes that boundary structural instead
+ * of a list somebody has to maintain.
+ */
+import type { Command } from "commander"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import { loadConfig, loadSchemaAst } from "../config.js"
+import { hooksPathFromProject, schemaPathFromProject } from "../project-config.js"
+import { declaredHooks, hooksReport } from "../model-hooks.js"
+import { error, info, plain } from "../ui/messages.js"
+
+export function registerHooks(program: Command): void {
+  const hooksCmd = program
+    .command("hooks")
+    .description("Manage model hooks (procedural handlers the API runs around a write)")
+
+  hooksCmd
+    .command("new <name>")
+    .description("Scaffold a hook handler")
+    .action((name: string) => {
+      scaffoldHook(process.cwd(), name)
+    })
+
+  hooksCmd
+    .command("list")
+    .description("Show the hooks the schema declares and whether each one can run")
+    .action(() => {
+      const cwd = process.cwd()
+      const config = loadConfig(cwd)
+      const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+      const report = hooksReport(cwd, hooksPathFromProject(config, cwd), ast)
+
+      if (report.declared.length === 0) {
+        info("No model declares a hook.")
+        return
+      }
+      for (const hook of report.declared) {
+        const broken = report.missing.some((m) => m.model === hook.model && m.event === hook.event)
+        plain(`  ${broken ? "✗" : "•"} ${hook.model}.${hook.event} → ${hook.function}`)
+      }
+      if (report.missing.length > 0) {
+        plain("\n  ✗ names a handler that does not exist, so that hook never fires.")
+      }
+    })
+}
+
+function scaffoldHook(cwd: string, name: string): void {
+  const config = loadConfig(cwd)
+  const hooksDir = hooksPathFromProject(config, cwd)
+  const dir = join(hooksDir, name)
+
+  if (existsSync(dir)) {
+    error(`Hook "${name}" already exists at ${relative(cwd, dir)}`)
+    process.exit(1)
+  }
+
+  const ast = loadSchemaAst(schemaPathFromProject(config, cwd), cwd)
+  const declared = declaredHooks(ast).filter((hook) => hook.function === name)
+
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, "index.ts"), handlerTemplate(name, declared), "utf8")
+
+  info(`Created hook: ${relative(cwd, join(dir, "index.ts"))}`)
+  if (declared.length === 0) {
+    // Scaffolding a handler nothing calls is easy to do and impossible to notice, since a hook that
+    // is never referenced simply never runs.
+    plain("")
+    plain("  No model references it yet. Add it to a model's meta:")
+    plain(`    hooks: { beforeChange: "${name}" }`)
+    plain("  then run `supatype push` to generate its types and register it.")
+  } else {
+    plain("")
+    for (const hook of declared) {
+      plain(`  Wired to ${hook.model}.${hook.event}`)
+    }
+  }
+}
+
+/**
+ * The scaffold deliberately imports from `../_supatype/hooks.ts`, which `push` generates.
+ *
+ * Before the first push that file does not exist, so the handler will not compile — which is the
+ * honest state: the types come from the schema, and a handler typed against a model that has not been
+ * pushed is a handler typed against a guess.
+ */
+function handlerTemplate(name: string, declared: { model: string; event: string }[]): string {
+  const event = declared[0]?.event ?? "beforeChange"
+  const model = declared[0]?.model ?? "YourModel"
+
+  if (event.startsWith("after")) {
+    return `// ${name} — model hook (${event})
+//
+// Runs after the write has succeeded. It cannot change or undo it: a rejection here would be a
+// rejection of something that already happened. Failures are logged, not surfaced to the caller.
+
+import { hook, type AfterChange } from "../_supatype/hooks.ts"
+
+const handler: AfterChange<"your_table"> = async (ctx) => {
+  console.log(\`\${ctx.table} \${ctx.operation} by \${ctx.user?.sub ?? "anon"}\`)
+}
+
+export default hook(handler)
+`
+  }
+
+  return `// ${name} — model hook (${event}) for ${model}
+//
+// Runs before the write reaches Postgres, so it can reject it or rewrite the body.
+//
+// Not a security boundary: hooks fire for writes through the API, and direct SQL, seeds and anything
+// holding the service role bypass them. Invariants belong in the model's access rules or a CHECK.
+
+import { hook, type BeforeChange } from "../_supatype/hooks.ts"
+
+const handler: BeforeChange<"your_table"> = async (ctx) => {
+  if (ctx.operation === "insert") {
+    // \`ctx.rows\` is the submitted rows, typed from the model.
+    return { rows: ctx.rows }
+  }
+
+  // \`ctx.patch\` is the submitted partial; \`ctx.previous()\` reads the rows about to change.
+  // Those come back as stored — unmasked — so do not echo them into a rejection message.
+  return {}
+
+  // Reject with a message the caller sees, and a status of your choosing:
+  //   return { reject: "A post needs a title" }
+  //   return { reject: { message: "Already exists", status: 409, code: "duplicate" } }
+}
+
+export default hook(handler)
+`
+}

package/src/commands/init.ts

@@ -2,6 +2,7 @@ import type { Command } from "commander"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { resolve, join, basename } from "node:path"
 import { spawnSync } from "node:child_process"
+import { randomBytes } from "node:crypto"
 import { p, runClackFlow } from "../ui/clack.js"
 import { ensureNotCancelled } from "../ui/prompts.js"
 import { generateAndWriteKeys } from "./keys.js"
@@ -13,6 +14,7 @@ import {
   ensureComponentBinaries,
   reportComponentBinaryFailures,
 } from "../ensure-component-binaries.js"
+import { ensureFunctionsDenoTypes } from "../functions-deno-types.js"
 import { mergeSupatypePackageJson } from "../init-package-json.js"
 import { cliPackageVersion } from "../cli-package-version.js"
 import {
@@ -792,6 +794,12 @@ function scaffoldHelloFunction(
   if (!existsSync(join(dir, "functions/.env.local"))) {
     write("functions/.env.local", functionsEnvLocalTemplate())
   }
+  const denoTypes = ensureFunctionsDenoTypes(dir, join(dir, "functions"))
+  if (denoTypes.wroteDenoDts) file("created", "functions/deno.d.ts")
+  if (denoTypes.wroteTsconfig) file("created", "functions/tsconfig.json")
+  if (denoTypes.rootExclude === "updated") {
+    file("updated", 'tsconfig.json (exclude "functions")')
+  }
 }
 
 // ─── Templates ───────────────────────────────────────────────────────────────
@@ -1182,13 +1190,28 @@ export type SiteSettings = Model<{
 
 function envTemplate(opts: ScaffoldOptions): string {
   const sections: string[] = []
-  sections.push(`DATABASE_URL=postgresql://supatype_admin:postgres@localhost:5432/${opts.projectName}
-POSTGRES_USER=supatype_admin
-POSTGRES_PASSWORD=postgres
-POSTGRES_DB=${opts.projectName}`)
+  // Generated, not constant. These reach a server: the previous defaults meant a self-host
+  // deployment ran with a password of `postgres` and a JWT secret published in this repo —
+  // and anyone holding that secret can mint a token naming any Postgres role. Safe to generate
+  // only because `supatype dev` no longer overwrites them on every run (see local-secrets.ts).
+  const postgresPassword = randomBytes(24).toString("base64url")
 
-  sections.push(`# JWT — run \`supatype keys\` to generate ANON_KEY and SERVICE_ROLE_KEY
-JWT_SECRET=super-secret-jwt-token-change-in-production
+  sections.push(`DATABASE_URL=postgresql://supatype_admin:${postgresPassword}@localhost:5432/${opts.projectName}
+POSTGRES_USER=supatype_admin
+POSTGRES_PASSWORD=${postgresPassword}
+POSTGRES_DB=${opts.projectName}
+
+# PostgREST's own database credential. It connects as \`authenticator\`, a role that holds no
+# privileges and can only switch to anon/authenticated/service_role — so a request whose JWT
+# names any other role is refused by Postgres rather than honoured.
+#
+# Deliberately NOT the same as POSTGRES_PASSWORD: that one is yours, for direct SQL access, and
+# rotating it should never take the REST API down with it.
+AUTHENTICATOR_PASSWORD=${randomBytes(24).toString("base64url")}`)
+
+  sections.push(`# JWT — ANON_KEY and SERVICE_ROLE_KEY are derived from this secret.
+# Changing it invalidates every issued token; re-run \`supatype keys\` afterwards.
+JWT_SECRET=${randomBytes(48).toString("base64url")}
 ANON_KEY=
 SERVICE_ROLE_KEY=`)
 
@@ -1340,16 +1363,17 @@ function helloFunctionTemplate(): string {
 
 export default async function handler(req: Request): Promise<Response> {
   const { method } = req
+  const url = Deno.env.get("SUPATYPE_URL")
 
   if (method === "POST") {
     const body = await req.json()
-    return new Response(JSON.stringify({ message: "Hello from hello!", received: body }), {
+    return new Response(JSON.stringify({ message: "Hello from hello!", received: body, url }), {
       status: 200,
       headers: { "Content-Type": "application/json" },
     })
   }
 
-  return new Response(JSON.stringify({ message: "Hello from hello!" }), {
+  return new Response(JSON.stringify({ message: "Hello from hello!", url }), {
     status: 200,
     headers: { "Content-Type": "application/json" },
   })
@@ -1435,6 +1459,16 @@ function printNextSteps(args: {
   info(`Supatype project ready${name ? ` in ${name}/` : ""}.`)
   nextSteps(setupComplete ? "Next steps:" : "Finish setup:", steps)
 
+  // Shown once, at creation. These are generated per project rather than shipped as
+  // constants, so this is the moment to say they exist and where they live — nothing prints
+  // them again, and the JWT secret is only echoed as a fingerprint from here on.
+  nextSteps("Secrets — generated for this project, kept in .env:", [
+    "POSTGRES_PASSWORD    direct SQL access as the superuser",
+    "AUTHENTICATOR_PASSWORD    PostgREST's own login; rotating the one above does not affect it",
+    "JWT_SECRET    signs ANON_KEY and SERVICE_ROLE_KEY; changing it invalidates every token",
+    "Keep .env out of version control, and use different values in production.",
+  ])
+
   if (result.app.mode === "none") {
     nextSteps("Static frontend (self-host):", [
       "supatype app add --static ./public",

package/src/commands/internal.ts

@@ -0,0 +1,23 @@
+/**
+ * Hidden internal commands (Homebrew post_install, etc.).
+ */
+
+import type { Command } from "commander"
+import { downloadAll } from "../binary-cache.js"
+import { error, info } from "../ui/messages.js"
+
+export function registerInternalCommands(program: Command): void {
+  program
+    .command("_postinstall", { hidden: true })
+    .description("Prefetch CDN component binaries after install (Homebrew post_install)")
+    .action(async () => {
+      try {
+        info("Prefetching Supatype component binaries for this platform...")
+        await downloadAll(undefined, true)
+        info("Component prefetch complete.")
+      } catch (err) {
+        error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+      }
+    })
+}

package/src/commands/keys.ts

@@ -72,9 +72,11 @@ export function generateAndWriteKeys(
     content = upsertEnvVar(content, "SERVICE_ROLE_KEY", serviceKey)
     content = upsertEnvVar(content, "VITE_SUPATYPE_ANON_KEY", anonKey)
     content = upsertEnvVar(content, "PUBLIC_SUPATYPE_ANON_KEY", anonKey)
+    content = upsertEnvVar(content, "EXPO_PUBLIC_SUPATYPE_ANON_KEY", anonKey)
     const apiUrl = readEnvVar(content, "PUBLIC_SUPATYPE_URL") ?? readEnvVar(content, "API_EXTERNAL_URL")
     if (apiUrl) {
       content = upsertEnvVar(content, "VITE_SUPATYPE_URL", apiUrl)
+      content = upsertEnvVar(content, "EXPO_PUBLIC_SUPATYPE_URL", apiUrl)
     }
     writeFileSync(envPath, content, "utf8")
   }

package/src/commands/link-helpers.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander"
 import { loadConfig } from "../config.js"
+import { loadCloudCredentials } from "../cloud-credentials.js"
 import {
   createCloudLink,
   createSelfHostLink,
@@ -23,7 +24,8 @@ function resolveLinkToken(opts: {
     opts.serviceRoleKey ??
     process.env["SUPATYPE_ACCESS_TOKEN"] ??
     process.env["SUPATYPE_TOKEN"] ??
-    process.env["SERVICE_ROLE_KEY"]
+    process.env["SERVICE_ROLE_KEY"] ??
+    loadCloudCredentials()?.accessToken
   )
 }
 
@@ -211,11 +213,15 @@ export async function runLinkAction(opts: {
   }
 
   if (!token) {
-    error("Authentication required. Set SUPATYPE_ACCESS_TOKEN or pass --token.")
+    error("Authentication required. Run: supatype login  (or set SUPATYPE_ACCESS_TOKEN / pass --token).")
     process.exit(1)
   }
 
   const cloudApiUrl = opts.apiUrl.replace(/\/$/, "")
+  const creds = loadCloudCredentials()
+  const refreshToken =
+    (creds?.apiUrl.replace(/\/$/, "") === cloudApiUrl ? creds.refreshToken : undefined) ??
+    existing?.refreshToken
 
   if (project) {
     const one = await targetFetch<{ slug: string; orgId: string }>(cloudApiUrl, "/api/v1", {
@@ -250,6 +256,7 @@ export async function runLinkAction(opts: {
       orgId: one.orgId,
       environments,
       existing,
+      ...(refreshToken !== undefined ? { refreshToken } : {}),
     })
     saveProjectLink(cwd, link)
     info(`Linked to cloud project: ${project}`)

package/src/commands/login.ts

@@ -0,0 +1,127 @@
+/**
+ * Cloud session login / logout for CLI control-plane auth.
+ * Self-host uses SERVICE_ROLE_KEY via `supatype link --url` — not this command.
+ */
+import type { Command } from "commander"
+import {
+  clearCloudCredentials,
+  cloudPasswordLogin,
+  loadCloudCredentials,
+  persistCloudSession,
+} from "../cloud-credentials.js"
+import { loadProjectLink, saveProjectLink } from "../link.js"
+import { isInteractive } from "../ui/interactive.js"
+import { error, info, plain } from "../ui/messages.js"
+import { ensureNotCancelled, p, printLogo, runClackFlow } from "../ui/prompts.js"
+
+function defaultApiUrl(cwd: string, flag?: string): string {
+  if (flag?.trim()) return flag.trim().replace(/\/$/, "")
+  const link = loadProjectLink(cwd)
+  if (link?.kind === "cloud" && link.cloudApiUrl) {
+    return link.cloudApiUrl.replace(/\/$/, "")
+  }
+  return (process.env["SUPATYPE_API_URL"] ?? "https://api.supatype.com").replace(/\/$/, "")
+}
+
+export function registerLogin(program: Command): void {
+  program
+    .command("login")
+    .description("Sign in to Supatype Cloud (stores refreshable session for push/deploy)")
+    .option("--api-url <url>", "Cloud control plane API URL")
+    .option("--email <email>", "Account email (non-interactive)")
+    .option("--password <password>", "Account password (prefer SUPATYPE_PASSWORD)")
+    .action(async (opts: { apiUrl?: string; email?: string; password?: string }) => {
+      const cwd = process.cwd()
+      const apiUrl = defaultApiUrl(cwd, opts.apiUrl)
+
+      let email = opts.email?.trim() ?? process.env["SUPATYPE_EMAIL"]?.trim()
+      let password =
+        opts.password ?? process.env["SUPATYPE_PASSWORD"] ?? process.env["SUPATYPE_LOGIN_PASSWORD"]
+
+      if ((!email || !password) && isInteractive()) {
+        await runClackFlow(async () => {
+          printLogo()
+          p.intro("Supatype Cloud login")
+          if (!email) {
+            email = ensureNotCancelled(
+              await p.text({
+                message: "Email",
+                placeholder: "you@example.com",
+              }),
+            ).trim()
+          }
+          if (!password) {
+            password = ensureNotCancelled(await p.password({ message: "Password" }))
+          }
+          p.outro("Signing in...")
+        })
+      }
+
+      if (!email || !password) {
+        error(
+          "Email and password required. Pass --email / --password, set SUPATYPE_EMAIL + SUPATYPE_PASSWORD, or run interactively.",
+        )
+        process.exit(1)
+      }
+
+      try {
+        const session = await cloudPasswordLogin(apiUrl, email, password)
+        persistCloudSession(cwd, {
+          apiUrl,
+          accessToken: session.accessToken,
+          ...(session.refreshToken !== undefined ? { refreshToken: session.refreshToken } : {}),
+          ...(session.email !== undefined ? { email: session.email } : { email }),
+        })
+        const link = loadProjectLink(cwd)
+        info(`Logged in to ${apiUrl}${session.email ? ` as ${session.email}` : ""}`)
+        if (link?.kind === "cloud") {
+          info(`Updated cloud session for linked project ${link.projectRef}`)
+        } else if (!session.refreshToken) {
+          plain("Warning: no refresh_token returned — session may expire in ~1h. Update control plane.")
+        } else {
+          plain("Tip: link a project with: supatype link --project <slug>")
+        }
+      } catch (err) {
+        error((err as Error).message)
+        process.exit(1)
+      }
+    })
+
+  program
+    .command("logout")
+    .description("Clear stored Supatype Cloud credentials")
+    .action(() => {
+      const cwd = process.cwd()
+      clearCloudCredentials()
+      const link = loadProjectLink(cwd)
+      if (link?.kind === "cloud") {
+        delete link.token
+        delete link.refreshToken
+        saveProjectLink(cwd, link)
+      }
+      info("Logged out of Supatype Cloud.")
+    })
+
+  program
+    .command("whoami")
+    .description("Show the current Supatype Cloud session")
+    .action(() => {
+      const creds = loadCloudCredentials()
+      const cwd = process.cwd()
+      const link = loadProjectLink(cwd)
+      if (!creds && !(link?.kind === "cloud" && link.token)) {
+        info("Not logged in. Run: supatype login")
+        return
+      }
+      if (creds) {
+        plain(`API:   ${creds.apiUrl}`)
+        if (creds.email) plain(`Email: ${creds.email}`)
+        plain(`Refresh token: ${creds.refreshToken ? "yes" : "no"}`)
+        plain(`Updated: ${creds.updatedAt}`)
+      }
+      if (link?.kind === "cloud") {
+        plain(`Linked project: ${link.projectRef}`)
+        plain(`Link has refresh token: ${link.refreshToken ? "yes" : "no"}`)
+      }
+    })
+}