@supatype/cli 0.1.0-alpha.7 → 0.1.0-alpha.8

package/src/TYPE-RESOLUTION.md

@@ -0,0 +1,294 @@
+# Type Resolution in the Schema Extractor
+
+`type-extractor.ts` converts TypeScript type definitions into `ExtractedSchemaAst` —
+the JSON handed to the engine binary for SQL generation and client type output.
+
+This document explains how type names are resolved, what patterns are supported,
+and how the three-tier fallback chain works.
+
+---
+
+## The Problem
+
+The extractor uses the TypeScript **parser only** (`ts.createSourceFile`), not the
+full type checker. This is fast and requires no `tsconfig.json`, but it means the
+extractor only sees raw source text — it cannot evaluate what a type alias resolves to.
+
+The consequence is that any indirection breaks resolution:
+
+```typescript
+// Works — extractor sees "Optional" literally
+type Post = Model<{ email: Optional<Email> }>
+
+// Previously broken — extractor sees "Nullable", not "Optional"
+type Nullable<T> = Optional<T>
+type Post = Model<{ email: Nullable<Email> }>
+
+// Previously broken — import rename
+import { Optional as Maybe } from "@supatype/types"
+type Post = Model<{ email: Maybe<Email> }>
+```
+
+Failures were silent — unknown types fell through to `{ kind: "text", pgType: "TEXT" }`
+instead of throwing an error.
+
+---
+
+## Three-Tier Resolution
+
+Every type name encountered in a field definition is resolved through three tiers
+in order. The first tier to succeed wins. If all three fail, an error is thrown.
+
+```
+Tier 1 — syntactic switch      instant    inline primitives and modifiers by name
+Tier 2 — alias registry        instant    user-defined type aliases, import renames
+Tier 3 — TypeScript checker    ~300ms†    conditional types, mapped types
+```
+
+† Tier 3 is **lazy** — the `ts.Program` and `TypeChecker` are only created the first
+time a conditional or mapped type is encountered. Schemas that use only tiers 1 and 2
+pay no cost.
+
+---
+
+## Tier 1 — Syntactic Switch
+
+The existing behaviour. The extractor walks the type reference chain and matches
+names exactly against a hardcoded switch:
+
+```typescript
+switch (typeName) {
+  case "Optional":    flags.required = false;  unwrap(); continue
+  case "Unique":      flags.unique = true;     unwrap(); continue
+  case "PrimaryKey":  flags.primaryKey = true; unwrap(); continue
+  case "UUID":        return { kind: "uuid",  pgType: "UUID" }
+  case "Email":       return { kind: "email", pgType: "TEXT" }
+  // ... all @supatype/types primitives and modifiers
+}
+```
+
+This covers all types used inline with their canonical names.
+
+---
+
+## Tier 2 — Alias Registry
+
+Built once at startup from all source files loaded by `loadSchemaSourceFiles`.
+Covers two sub-cases:
+
+### 2a — Type alias declarations
+
+Any `type X = ...` that is not a `Model<>` declaration is indexed by name:
+
+```typescript
+// These all become entries in the alias registry:
+type Nullable<T>  = Optional<T>
+type UniqueSlug   = Unique<Slug<"title">>
+type AuditId      = PrimaryKey<UUID>
+type MyEnum       = "draft" | "published" | "archived"
+```
+
+When the extractor encounters an unknown name, it looks it up in the registry,
+substitutes any type parameters via text replacement, and re-enters tier 1 with
+the resolved node.
+
+Multi-hop aliases work because the resolution recurses:
+
+```typescript
+type A = B
+type B = Optional<Email>
+// A → B → Optional<Email> → resolved by tier 1
+```
+
+Cycle detection via a `resolving: Set<string>` guard prevents infinite loops and
+throws a descriptive error instead.
+
+### 2b — Import renames
+
+Explicit `as` renames in import statements are indexed per file:
+
+```typescript
+import { Optional as Maybe } from "@supatype/types"
+import { Nullable as MaybeNull } from "./shared/field-types"
+```
+
+Before the tier 1 switch runs, each name is checked against the rename map for
+the current file. `Maybe` becomes `Optional`, `MaybeNull` becomes `Nullable`
+(which is then resolved by 2a).
+
+### File loading
+
+`loadSchemaSourceFiles` follows both `export` declarations (existing) and local
+`import` declarations (new), ensuring that files referenced via import are loaded
+into the source file set and their aliases are available in the registry.
+
+Only relative specifiers (`.`-prefixed) are followed. Bare specifiers and scoped
+packages (`@supatype/types`, `node_modules/*`) are not loaded — their exported
+names are already covered by the tier 1 switch.
+
+---
+
+## Tier 3 — TypeScript Checker
+
+Required for types that cannot be evaluated syntactically:
+
+- **Conditional types**: `T extends U ? A : B` — requires evaluating the constraint
+- **Mapped types**: `{ [K in keyof T]: F<T[K]> }` — requires enumerating `keyof T`
+
+### How it works
+
+1. A lazy `ts.Program` is created from the already-loaded source files using a
+   custom `CompilerHost` that serves them from memory (no disk re-reads).
+
+2. Because our lightweight parse tree and the Program's parse tree are different
+   objects (even for the same file), the node with the unresolvable type is located
+   in the Program's source file by matching `pos`/`end` character positions.
+
+3. `checker.getTypeAtLocation(programNode)` resolves the type fully.
+
+4. `checker.typeToString(type, ..., TypeFormatFlags.UseAliasDefinedOutsideCurrentScope)`
+   converts it back to a string with **alias names preserved** — so `Optional<Email>`
+   stays as `Optional<Email>` rather than expanding to the underlying branded
+   intersection type.
+
+5. The string is re-parsed via `ts.createSourceFile` into a proper TypeNode with
+   valid `pos`/`end` values (so downstream `getText()` calls work).
+
+6. The resolved TypeNode is fed back into the tier 1 switch.
+
+### When tier 3 fires
+
+- A field type is directly a conditional or mapped expression
+- A tier 2 alias body contains a conditional or mapped type (detected by
+  `needsChecker()` before text substitution is attempted — the original node,
+  which has valid source positions, is passed to the checker instead)
+- The `Model<>` fields argument is a mapped type alias:
+  ```typescript
+  type AllOptional<T> = { [K in keyof T]: Optional<T[K]> }
+  type Post = Model<AllOptional<{ email: Email; name: Text }>>
+  ```
+  This is handled in `unwrapModelFields`, which also participates in the
+  three-tier chain.
+
+---
+
+## What Is Supported
+
+```typescript
+// Tier 1 — inline, canonical names
+email:  Optional<Email>
+slug:   Unique<Slug<"title">>
+id:     PrimaryKey<UUID>
+
+// Tier 2a — simple alias
+type Nullable<T>  = Optional<T>
+type UniqueSlug   = Unique<Slug<"title">>
+email: Nullable<Email>
+slug:  UniqueSlug
+
+// Tier 2a — multi-hop
+type A = B
+type B = Nullable<Email>
+email: A
+
+// Tier 2b — import rename of primitive
+import { Optional as Maybe } from "@supatype/types"
+email: Maybe<Email>
+
+// Tier 2b — import rename of local alias
+import { Nullable as MaybeNull } from "./field-types"
+email: MaybeNull<Email>
+
+// Tier 2b — cross-file alias (no rename)
+// helpers.ts: export type Nullable<T> = Optional<T>
+import { Nullable } from "./helpers"
+email: Nullable<Email>
+
+// Tier 3 — conditional type
+type NullableStr<T> = T extends string ? Optional<T> : T
+email: NullableStr<Email>
+
+// Tier 3 — mapped type as fields object
+type AllOptional<T> = { [K in keyof T]: Optional<T[K]> }
+type Post = Model<AllOptional<{ email: Email; name: Text }>>
+```
+
+---
+
+## What Is Not Supported
+
+```typescript
+// Imports from node_modules other than @supatype/types
+import { SomeHelper } from "some-library"
+
+// Conditional / mapped types in alias bodies that reference
+// symbols only available in node_modules (other than @supatype/types)
+
+// TypeScript utility types used as field types
+email: NonNullable<string>    // error — not a @supatype/types primitive
+
+// Namespace-qualified names
+email: Types.Optional<Email>  // error — only identifier references are resolved
+```
+
+---
+
+## Error Behaviour
+
+Unknown types now **throw** instead of silently falling back to
+`{ kind: "text", pgType: "TEXT" }`:
+
+```
+Error: Unknown Supatype type "SomeType" in field "email".
+If this is a type alias, confirm the file defining it is reachable
+from your schema entry point.
+```
+
+Cycles in alias chains throw:
+
+```
+Error: Field "email": circular alias chain detected resolving "A".
+```
+
+Unresolvable conditional/mapped types throw:
+
+```
+Error: Field "email": could not resolve conditional/mapped type via type checker.
+```
+
+---
+
+## Data Structures
+
+```typescript
+// One entry per non-Model type alias declaration across all loaded source files
+type AliasEntry = {
+  typeParams: string[]        // ["T"] for Nullable<T> = Optional<T>
+  body:       ts.TypeNode     // the RHS of the declaration
+  sourceFile: ts.SourceFile   // getText() context for body
+}
+
+// Rename map: sf.fileName → (localName → canonicalName)
+// Only populated for explicit `import { X as Y }` renames
+type ImportRenameMap = Map<string, Map<string, string>>
+
+// Passed to every resolution function; checker is lazy
+type ResolveContext = {
+  aliasRegistry: Map<string, AliasEntry>
+  renameMap:     ImportRenameMap
+  getChecker:    () => CheckerContext
+}
+
+type CheckerContext = {
+  program: ts.Program
+  checker: ts.TypeChecker
+}
+```
+
+---
+
+## Adding a New Tier 1 Primitive
+
+When a new type is added to `@supatype/types`, add a `case` to the `switch` in
+`parseScalarType`. No other changes are needed — tier 2 and tier 3 handle
+aliases and compositions of it automatically.

package/src/app/proxy-dev-app.ts

@@ -0,0 +1,67 @@
+/**
+ * Spawn the frontend dev server during `supatype dev` when app.mode is proxy.
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { detectPackageManager } from "./framework.js"
+import { ProcessManager } from "../process-manager.js"
+import { projectRootFromConfig, type SupatypeProjectConfig } from "../project-config.js"
+
+const DEFAULT_PROXY_DEV_SCRIPT = "start"
+
+/** package.json script name to run (only when app.mode is proxy). */
+export function resolveProxyDevScript(config: SupatypeProjectConfig): string | null {
+  if (config.app?.mode !== "proxy") return null
+  const script = config.app.start?.trim()
+  return script && script.length > 0 ? script : DEFAULT_PROXY_DEV_SCRIPT
+}
+
+/**
+ * Start the configured package.json script for proxy dev.
+ * Returns null when not in proxy mode or when the script is missing.
+ */
+export function startProxyDevApp(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  pidDir: string,
+): ProcessManager | null {
+  const script = resolveProxyDevScript(config)
+  if (!script) return null
+
+  const appDir = projectRootFromConfig(config, cwd)
+  const pkgPath = join(appDir, "package.json")
+  if (!existsSync(pkgPath)) {
+    console.warn(`[supatype] app.mode=proxy but no package.json at ${appDir}; skipping dev app`)
+    return null
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+    scripts?: Record<string, string>
+  }
+  if (!pkg.scripts?.[script]) {
+    console.warn(
+      `[supatype] app.mode=proxy: package.json has no "${script}" script.\n` +
+        `  Add "scripts.${script}" or set app.start in supatype.config.ts`,
+    )
+    return null
+  }
+
+  const pm = detectPackageManager(appDir)
+  const bin = pm
+  const args = pm === "yarn" ? [script] : ["run", script]
+  // pnpm/npm/yarn are .cmd shims on Windows — spawn via shell so PATH resolution works.
+  const useShell = process.platform === "win32"
+
+  console.log(`[supatype] Proxy mode: running ${bin} ${args.join(" ")} (${appDir})`)
+
+  const manager = new ProcessManager(bin, args, {
+    label: "app",
+    pidDir,
+    cwd: appDir,
+    colour: "\x1b[33m",
+    shell: useShell,
+  })
+  manager.start()
+  return manager
+}

package/src/binary-cache.ts

@@ -39,6 +39,17 @@ import { releasePublicKey } from "./release-public-key.js"
  */
 export const VERSION_PIN_LOCAL = "local"
 
+/** True if `overrides.engine` points at a local engine binary (contributor dev). */
+export function hasEngineOverride(config: SupatypeProjectConfig): boolean {
+  const path = config.overrides?.engine
+  return typeof path === "string" && path.trim() !== ""
+}
+
+export function hasStudioOverride(config: SupatypeProjectConfig): boolean {
+  const path = config.overrides?.studio
+  return typeof path === "string" && path.trim() !== ""
+}
+
 /** True if `overrides` contains any non-empty string path (contributor local builds). */
 export function hasMeaningfulOverrides(config: SupatypeProjectConfig): boolean {
   const o = config.overrides
@@ -281,6 +292,15 @@ export async function resolveBinary(
  *   2. If SUPATYPE_RELEASE_PUBLIC_KEY is set: verify minisign signature.
  *   3. Verify SHA256 of downloaded binary against signed checksum.
  */
+/** Download if missing or invalid; return cached path for the given platform. */
+export async function ensureCachedBinary(
+  component: Component,
+  version: string,
+  platform: PlatformId,
+): Promise<string> {
+  return download(component, version, platform)
+}
+
 export async function download(
   component: Component,
   version: string,

package/src/commands/cloud.ts

@@ -7,6 +7,8 @@ interface CloudConfig {
   apiUrl: string
   token: string
   projectSlug?: string
+  /** Organisation UUID — required for schema routes (`X-Org-Id`). */
+  orgId?: string
 }
 
 export function loadCloudConfig(cwd: string): CloudConfig | null {
@@ -25,12 +27,16 @@ function saveCloudConfig(cwd: string, config: CloudConfig): void {
 }
 
 async function cloudFetch<T>(config: CloudConfig, method: string, path: string, body?: unknown): Promise<T> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${config.token}`,
+  }
+  if (config.orgId) {
+    headers["X-Org-Id"] = config.orgId
+  }
   const res = await fetch(`${config.apiUrl}/api/v1${path}`, {
     method,
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${config.token}`,
-    },
+    headers,
     ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
   })
 
@@ -41,21 +47,28 @@ async function cloudFetch<T>(config: CloudConfig, method: string, path: string,
   return json.data as T
 }
 
+/** True when `.supatype/cloud.json` exists with a linked project slug. */
+export function isCloudLinked(cwd: string): boolean {
+  const cfg = loadCloudConfig(cwd)
+  return Boolean(cfg?.projectSlug && cfg.token)
+}
+
 /**
- * Push schema AST to the linked cloud project (control plane `/api/v1/.../deploy`).
- * Invoked by `supatype deploy` by default when `.supatype/cloud.json` is present.
+ * Push schema AST to the linked cloud project (`POST /api/v1/projects/:ref/schema/push`).
+ * Credentials stay server-side; only AST is sent.
  */
-export async function deploySchemaToLinkedProject(
-  cwd: string,
-  environment: string,
-): Promise<void> {
+export async function pushSchemaToLinkedProject(cwd: string, opts?: { force?: boolean }): Promise<void> {
   const config = loadCloudConfig(cwd)
   if (!config?.projectSlug) {
     console.error("Not linked to a cloud project. Run: supatype link")
     process.exit(1)
   }
-
-  console.log(`Deploying schema to ${config.projectSlug} (${environment})...`)
+  if (!config.orgId) {
+    console.error(
+      "Missing orgId in .supatype/cloud.json. Re-run: supatype link --project <slug> (after cloud login).",
+    )
+    process.exit(1)
+  }
 
   const { loadConfig: loadAppConfig, loadSchemaAst } = await import("../config.js")
   const { schemaPathFromProject } = await import("../project-config.js")
@@ -63,25 +76,19 @@ export async function deploySchemaToLinkedProject(
   const appConfig = loadAppConfig(cwd)
   const ast = loadSchemaAst(schemaPathFromProject(appConfig, cwd), cwd)
 
-  const { createHash } = await import("node:crypto")
-  const schemaHash = createHash("sha256").update(JSON.stringify(ast)).digest("hex").slice(0, 16)
+  console.log(`Pushing schema to cloud project ${config.projectSlug}...`)
 
-  const deployment = await cloudFetch<{
-    id: string; status: string; errorMessage?: string
-  }>(config, "POST", `/projects/${config.projectSlug}/deploy`, {
-    environment,
-    schemaHash,
+  const result = await cloudFetch<{ message?: string }>(config, "POST", `/projects/${config.projectSlug}/schema/push`, {
     ast,
+    force: opts?.force ?? true,
   })
 
-  if (deployment.status === "success") {
-    console.log(`\nDeployment successful (${deployment.id})`)
-  } else if (deployment.status === "failed") {
-    console.error(`\nDeployment failed: ${deployment.errorMessage}`)
-    process.exit(1)
-  } else {
-    console.log(`\nDeployment ${deployment.status} (${deployment.id})`)
-  }
+  console.log(result.message ?? "Schema push completed.")
+}
+
+/** @deprecated Use pushSchemaToLinkedProject — kept for deploy command alias */
+export async function deploySchemaToLinkedProject(cwd: string, _environment: string): Promise<void> {
+  await pushSchemaToLinkedProject(cwd)
 }
 
 function prompt(question: string): Promise<string> {
@@ -116,9 +123,10 @@ export function registerCloud(program: Command): void {
 
       if (opts.project) {
         config.projectSlug = opts.project
+        const one = await cloudFetch<{ slug: string; orgId: string }>(config, "GET", `/projects/${opts.project}`)
+        config.orgId = one.orgId
       } else {
-        // List projects and let user choose
-        const projects = await cloudFetch<Array<{ slug: string; name: string; status: string; tier: string }>>(
+        const projects = await cloudFetch<Array<{ slug: string; name: string; status: string; tier: string; orgId: string }>>(
           config, "GET", "/projects",
         )
         if (projects.length === 0) {
@@ -137,7 +145,9 @@ export function registerCloud(program: Command): void {
           console.error("Invalid selection.")
           process.exit(1)
         }
-        config.projectSlug = projects[idx]!.slug
+        const picked = projects[idx]!
+        config.projectSlug = picked.slug
+        config.orgId = picked.orgId
       }
 
       saveCloudConfig(cwd, config)

package/src/commands/deploy.ts

@@ -16,7 +16,7 @@ import { existsSync, readdirSync, statSync, createReadStream } from "node:fs"
 import { join } from "node:path"
 import { loadConfig, loadSchemaAst } from "../config.js"
 import { connectionString, schemaPathFromProject } from "../project-config.js"
-import { deploySchemaToLinkedProject, loadCloudConfig } from "./cloud.js"
+import { deploySchemaToLinkedProject, loadCloudConfig, pushSchemaToLinkedProject } from "./cloud.js"
 import { ensureEngine, engineRequest, type DiffResult } from "../engine-client.js"
 import { resolveAppConfig, validateStaticMode, validateBuildOutput, detectPackageManager } from "../app/framework.js"
 import { TIER_LIMITS, type Tier } from "./deploy-types.js"
@@ -93,23 +93,8 @@ export function registerDeploy(program: Command): void {
             console.log("Schema is up to date.")
           }
         } else if (cloudCfg?.projectSlug) {
-          console.log("=== Schema Push ===")
-          // Platform API — no local Docker needed
-          const apiUrl = cloudCfg.apiUrl || "https://api.supatype.com"
-          const token = cloudCfg.token || process.env["SUPATYPE_ACCESS_TOKEN"] || ""
-
-          const res = await fetch(`${apiUrl}/platform/v1/projects/${cloudCfg.projectSlug}/schema/push`, {
-            method: "POST",
-            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
-            body: JSON.stringify({ ast }),
-          })
-          if (!res.ok) {
-            const body = await res.text()
-            console.error(`Schema push failed: ${res.status} ${body}`)
-            process.exit(1)
-          }
-          const pushData = await res.json() as { operations?: unknown[]; message?: string }
-          console.log(pushData.message ?? `Schema changes applied (${pushData.operations?.length ?? 0} operations).`)
+          console.log("=== Schema Push (cloud) ===")
+          await pushSchemaToLinkedProject(cwd, { force: opts.yes ?? true })
         } else {
           console.error(
             "Not linked to Supatype Cloud. Run: supatype link\n" +