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

package/src/schema-ast-v2.ts

@@ -0,0 +1,324 @@
+/**
+ * AST v2 wire format — canonical types and emitters.
+ * Parsers build {@link ParsedField}; only `emitField` / `emitModel` / `emitSchema` produce JSON.
+ */
+
+export const AST_VERSION = 2 as const
+
+export type DefaultAst =
+  | { kind: "value"; value: string | number | boolean | null }
+  | { kind: "now" }
+  | { kind: "genRandomUuid" }
+  | { kind: "expression"; expr: string }
+
+export interface DbFieldAnnotations {
+  pgType?: string
+  unique?: boolean
+  index?: boolean
+  foreignKey?: string
+  serverGenerated?: boolean
+  elementType?: string
+}
+
+export interface PlatformFieldAnnotations {
+  editor?: string
+  readOnly?: boolean
+}
+
+export interface FieldAnnotations {
+  db?: DbFieldAnnotations
+  platform?: PlatformFieldAnnotations
+}
+
+/** Kernel facts only — never db/platform keys at this layer. */
+export interface KernelFieldFacts {
+  required?: boolean
+  primaryKey?: boolean
+  default?: DefaultAst
+  localized?: boolean
+  cardinality?: string
+  target?: string
+  values?: string[]
+  from?: string
+  sources?: string[]
+  template?: string
+  bucket?: string
+  accessMode?: string
+  geoType?: string
+  srid?: number
+  dimensions?: number
+  blocks?: BlockDefinitionAst[]
+  check?: string
+  precision?: number
+  scale?: number
+  references?: string
+  through?: string
+  onDelete?: string
+  onUpdate?: string
+  uniqueFk?: boolean
+  plugin?: string
+  fieldType?: string
+  tsType?: string
+  index?: boolean
+}
+
+/** Internal parse result — not serialized. */
+export interface ParsedField {
+  kind: string
+  kernel: KernelFieldFacts
+  db: DbFieldAnnotations
+  platform: PlatformFieldAnnotations
+}
+
+export type FieldAstV2 = {
+  kind: string
+  annotations?: FieldAnnotations
+} & Record<string, unknown>
+
+export interface BlockDefinitionAst {
+  name: string
+  label?: string
+  icon?: string
+  fields: Record<string, FieldAstV2>
+}
+
+export interface ModelAstV2 {
+  name: string
+  fields: Record<string, FieldAstV2>
+  options: Record<string, unknown>
+  annotations: {
+    db: { tableName: string; indexes: unknown[] }
+    platform: { access: Record<string, unknown> }
+  }
+}
+
+export interface ExtractedStorageBucketAst {
+  id: string
+  public: boolean
+  accessMode?: "public" | "private" | "custom"
+  allowedMimeTypes?: string[]
+  fileSizeLimit?: number
+  access?: Record<string, unknown>
+  s3BucketPolicy?: string
+}
+
+export interface ExtractedSchemaAstV2 {
+  astVersion: typeof AST_VERSION
+  models: ModelAstV2[]
+  storageBuckets?: ExtractedStorageBucketAst[]
+  locales?: string[]
+  defaultLocale?: string
+}
+
+const DEFAULT_DB_BY_KIND: Record<string, Partial<DbFieldAnnotations>> = {
+  text: { pgType: "TEXT" },
+  richText: { pgType: "JSONB" },
+  integer: { pgType: "INTEGER" },
+  smallInt: { pgType: "SMALLINT" },
+  bigInt: { pgType: "BIGINT" },
+  float: { pgType: "DOUBLE PRECISION" },
+  boolean: { pgType: "BOOLEAN" },
+  datetime: { pgType: "TIMESTAMPTZ" },
+  date: { pgType: "DATE" },
+  timestamp: { pgType: "TIMESTAMP WITH TIME ZONE" },
+  uuid: { pgType: "UUID" },
+  email: { pgType: "TEXT" },
+  url: { pgType: "TEXT" },
+  slug: { pgType: "TEXT" },
+  enum: { pgType: "TEXT" },
+  json: { pgType: "JSONB" },
+  decimal: { pgType: "TEXT" },
+  bytes: { pgType: "BYTEA" },
+  serial: { pgType: "SERIAL" },
+  bigSerial: { pgType: "BIGSERIAL" },
+  money: { pgType: "TEXT" },
+  ip: { pgType: "TEXT" },
+  cidr: { pgType: "TEXT" },
+  macaddr: { pgType: "TEXT" },
+  xml: { pgType: "TEXT" },
+  tsQuery: { pgType: "TEXT" },
+  tsVector: { pgType: "TEXT" },
+  color: { pgType: "TEXT" },
+  array: { pgType: "ARRAY" },
+  image: { pgType: "JSONB" },
+  file: { pgType: "JSONB" },
+  geo: { pgType: "GEOGRAPHY" },
+  vector: { pgType: "VECTOR" },
+  blocks: { pgType: "JSONB" },
+}
+
+const DEFAULT_PLATFORM_BY_KIND: Record<string, Partial<PlatformFieldAnnotations>> = {
+  richText: { editor: "rich" },
+}
+
+const COMPOSITE_KINDS = new Set(["timestamps", "publishable", "softDelete"])
+
+function hasKeys(obj: Record<string, unknown>): boolean {
+  return Object.keys(obj).length > 0
+}
+
+function stripUndefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v
+  }
+  return out as Partial<T>
+}
+
+/** Start a parsed field with kind defaults for db/platform namespaces. */
+export function defaultPgTypeForKind(kind: string): string {
+  return DEFAULT_DB_BY_KIND[kind]?.pgType ?? "TEXT"
+}
+
+/** Flat wire shape for fields nested inside `blocks` definitions (engine FieldAst serde). */
+export function emitBlockNestedField(field: FieldAstV2): FieldAstV2 {
+  const annotations = (field.annotations ?? {}) as FieldAnnotations
+  const db = annotations.db ?? {}
+  const platform = annotations.platform ?? {}
+
+  const wire: FieldAstV2 = {
+    kind: field.kind,
+    pgType: db.pgType ?? defaultPgTypeForKind(String(field.kind)),
+    required: field.required ?? false,
+    unique: db.unique ?? false,
+    localized: field.localized ?? false,
+  }
+
+  if (platform.readOnly) wire.readOnly = true
+  if (field.primaryKey) wire.primaryKey = true
+  if (field.default !== undefined) wire.default = field.default
+  if (field.from !== undefined) wire.from = field.from
+  if (field.values !== undefined) wire.values = field.values
+  if (field.bucket !== undefined) wire.bucket = field.bucket
+  if (field.accessMode !== undefined) wire.accessMode = field.accessMode
+  if (field.geoType !== undefined) wire.geoType = field.geoType
+  if (field.srid !== undefined) wire.srid = field.srid
+  if (field.dimensions !== undefined) wire.dimensions = field.dimensions
+  if (field.check !== undefined) wire.check = field.check
+  if (field.precision !== undefined) wire.precision = field.precision
+  if (field.scale !== undefined) wire.scale = field.scale
+  if (field.sources !== undefined) wire.sources = field.sources
+  if (field.template !== undefined) wire.template = field.template
+  if (field.plugin !== undefined) wire.plugin = field.plugin
+  if (field.fieldType !== undefined) wire.fieldType = field.fieldType
+  if (field.tsType !== undefined) wire.tsType = field.tsType
+
+  return wire
+}
+
+export function scalar(
+  kind: string,
+  extra?: {
+    kernel?: Partial<KernelFieldFacts>
+    db?: Partial<DbFieldAnnotations>
+    platform?: Partial<PlatformFieldAnnotations>
+  },
+): ParsedField {
+  return {
+    kind,
+    kernel: { ...(extra?.kernel ?? {}) },
+    db: { ...DEFAULT_DB_BY_KIND[kind], ...stripUndefined(extra?.db ?? {}) },
+    platform: { ...DEFAULT_PLATFORM_BY_KIND[kind], ...stripUndefined(extra?.platform ?? {}) },
+  }
+}
+
+export function emitField(parsed: ParsedField): FieldAstV2 {
+  if (COMPOSITE_KINDS.has(parsed.kind)) {
+    return { kind: parsed.kind }
+  }
+
+  const db = stripUndefined({
+    ...DEFAULT_DB_BY_KIND[parsed.kind],
+    ...parsed.db,
+  }) as DbFieldAnnotations
+
+  const platform = stripUndefined({
+    ...DEFAULT_PLATFORM_BY_KIND[parsed.kind],
+    ...parsed.platform,
+  }) as PlatformFieldAnnotations
+
+  const wire: FieldAstV2 = { kind: parsed.kind }
+
+  const kernel = parsed.kernel
+  if (kernel.required !== undefined) wire.required = kernel.required
+  if (kernel.primaryKey) wire.primaryKey = true
+  if (kernel.default !== undefined) wire.default = kernel.default
+  if (kernel.localized) wire.localized = true
+  if (kernel.cardinality !== undefined) wire.cardinality = kernel.cardinality
+  if (kernel.target !== undefined) wire.target = kernel.target
+  if (kernel.values !== undefined) wire.values = kernel.values
+  if (kernel.from !== undefined) wire.from = kernel.from
+  if (kernel.sources !== undefined && kernel.sources.length > 0) wire.sources = kernel.sources
+  if (kernel.template !== undefined) wire.template = kernel.template
+  if (kernel.bucket !== undefined) wire.bucket = kernel.bucket
+  if (kernel.accessMode !== undefined) wire.accessMode = kernel.accessMode
+  if (kernel.geoType !== undefined) wire.geoType = kernel.geoType
+  if (kernel.srid !== undefined) wire.srid = kernel.srid
+  if (kernel.dimensions !== undefined) wire.dimensions = kernel.dimensions
+  if (kernel.blocks !== undefined) {
+    wire.blocks = kernel.blocks.map((blockDef) => ({
+      ...blockDef,
+      fields: Object.fromEntries(
+        Object.entries(blockDef.fields).map(([name, nested]) => [
+          name,
+          emitBlockNestedField(nested),
+        ]),
+      ),
+    }))
+  }
+  if (kernel.check !== undefined) wire.check = kernel.check
+  if (kernel.precision !== undefined) wire.precision = kernel.precision
+  if (kernel.scale !== undefined) wire.scale = kernel.scale
+  if (kernel.references !== undefined) wire.references = kernel.references
+  if (kernel.through !== undefined) wire.through = kernel.through
+  if (kernel.onDelete !== undefined) wire.onDelete = kernel.onDelete
+  if (kernel.onUpdate !== undefined) wire.onUpdate = kernel.onUpdate
+  if (kernel.uniqueFk) wire.uniqueFk = true
+  if (kernel.plugin !== undefined) wire.plugin = kernel.plugin
+  if (kernel.fieldType !== undefined) wire.fieldType = kernel.fieldType
+  if (kernel.tsType !== undefined) wire.tsType = kernel.tsType
+  if (parsed.kind === "blocks" && kernel.index !== undefined) wire.index = kernel.index
+
+  const annotations: FieldAnnotations = {}
+  if (hasKeys(db as Record<string, unknown>)) annotations.db = db
+  if (hasKeys(platform as Record<string, unknown>)) annotations.platform = platform
+  if (hasKeys(annotations as Record<string, unknown>)) wire.annotations = annotations
+
+  return wire
+}
+
+export function emitModel(
+  name: string,
+  fields: Record<string, FieldAstV2>,
+  options: Record<string, unknown>,
+  tableName: string,
+  access: Record<string, unknown>,
+): ModelAstV2 {
+  return {
+    name,
+    fields,
+    options,
+    annotations: {
+      db: { tableName, indexes: [] },
+      platform: { access },
+    },
+  }
+}
+
+export function emitSchema(
+  models: ModelAstV2[],
+  extras?: {
+    storageBuckets?: ExtractedSchemaAstV2["storageBuckets"]
+    locales?: string[]
+    defaultLocale?: string
+  },
+): ExtractedSchemaAstV2 {
+  return {
+    astVersion: AST_VERSION,
+    models,
+    ...(extras?.storageBuckets !== undefined &&
+      extras.storageBuckets.length > 0 && { storageBuckets: extras.storageBuckets }),
+    ...(extras?.locales !== undefined && extras.locales.length > 0 && { locales: extras.locales }),
+    ...(extras?.defaultLocale !== undefined && { defaultLocale: extras.defaultLocale }),
+  }
+}

package/src/seed.ts

@@ -0,0 +1,43 @@
+import pg from "pg"
+
+export interface SeedSql {
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<pg.QueryResult>
+  end(): Promise<void>
+}
+
+/** Lightweight tagged-template SQL helper for project `seed.ts` scripts. */
+export function sql(connectionString: string): SeedSql {
+  const client = new pg.Client({ connectionString })
+  let connected = false
+
+  const ensureConnected = async (): Promise<void> => {
+    if (!connected) {
+      await client.connect()
+      connected = true
+    }
+  }
+
+  const tag = async (
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<pg.QueryResult> => {
+    await ensureConnected()
+    let text = ""
+    for (let i = 0; i < strings.length; i++) {
+      text += strings[i]
+      if (i < values.length) {
+        text += `$${i + 1}`
+      }
+    }
+    return client.query(text, values)
+  }
+
+  return Object.assign(tag, {
+    end: async (): Promise<void> => {
+      if (connected) {
+        await client.end()
+        connected = false
+      }
+    },
+  })
+}

package/src/self-host-compose.ts

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs"
 import { dirname, join, relative, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
-import type { SupatypeProjectConfig } from "./project-config.js"
+import { preferredFunctionsPathFromProject, type SupatypeProjectConfig } from "./project-config.js"
+import { hasEngineOverride, hasStudioOverride } from "./binary-cache.js"
 import { buildKongDeclarative } from "./kong-config.js"
 
 export interface SelfHostComposePaths {
@@ -33,43 +34,138 @@ export function staticDirForCompose(config: SupatypeProjectConfig): string | und
   return dir && dir.length > 0 ? dir : "./public"
 }
 
-function projectMountPath(cwd: string): string {
-  const composeDir = resolve(cwd, ".supatype", "self-host")
-  let rel = relative(composeDir, resolve(cwd)).replace(/\\/g, "/")
+/**
+ * Bind-mount source for `/project` in generated compose files.
+ * Paths are resolved from `--project-directory` (always the project root in `runDockerCompose`),
+ * not from the compose file directory — use `.` not `../..`.
+ */
+function projectMountPath(_cwd: string): string {
+  return "."
+}
+
+/** Paths in generated compose are resolved from `--project-directory` (project root). */
+function relativeFromProjectRoot(cwd: string, target: string): string {
+  let rel = relative(resolve(cwd), resolve(target)).replace(/\\/g, "/")
   if (!rel.startsWith(".") && !rel.startsWith("/")) {
     rel = `./${rel}`
   }
-  return rel || "../.."
+  return rel
+}
+
+function kongMountPath(_cwd: string): string {
+  return ".supatype/self-host/kong.yml"
 }
 
-function serverAppEnvForCompose(config: SupatypeProjectConfig): string {
+/** Host Vite dev server as seen from Kong inside Docker Compose. */
+export const COMPOSE_STUDIO_HOST_URL = "http://host.docker.internal:3002"
+
+/** Local monorepo Studio image for `supatype dev` (dogfooding). */
+function studioServiceBlock(cwd: string, devLocal: boolean): string {
+  if (!devLocal) {
+    return `    image: \${SUPATYPE_STUDIO_IMAGE:-supatype/studio:latest}`
+  }
+  const monorepoRoot = resolve(cwd, "..", "supatype")
+  const studioDockerfile = join(monorepoRoot, "packages", "studio", "Dockerfile")
+  if (!existsSync(studioDockerfile) || !existsSync(join(monorepoRoot, "pnpm-workspace.yaml"))) {
+    return `    image: \${SUPATYPE_STUDIO_IMAGE:-supatype/studio:latest}`
+  }
+  const context = relativeFromProjectRoot(cwd, monorepoRoot)
+  return `    build:
+      context: ${context}
+      dockerfile: packages/studio/Dockerfile
+    image: supatype/studio:dev-local`
+}
+
+/** Host dev app (Astro/Vite on the machine) as seen from inside compose services. */
+function proxyUpstreamForCompose(upstream: string, devLocal: boolean): string {
+  const trimmed = upstream.trim()
+  if (!devLocal) return trimmed
+  try {
+    const url = new URL(trimmed)
+    if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+      url.hostname = "host.docker.internal"
+      return url.toString()
+    }
+  } catch {
+    // keep literal upstream when not a URL
+  }
+  return trimmed
+}
+
+function serverAppEnvForCompose(config: SupatypeProjectConfig, devLocal: boolean): string {
   const mode = config.app.mode ?? "none"
   const lines = [`      SUPATYPE_APP_MODE: ${mode}`]
   if (mode === "static") {
     const dir = staticDirForCompose(config) ?? "./public"
     lines.push(`      SUPATYPE_APP_STATIC_DIR: /project/${dir.replace(/^\.\//, "")}`)
   } else if (mode === "proxy" && config.app.upstream?.trim()) {
-    lines.push(`      SUPATYPE_APP_UPSTREAM: ${config.app.upstream.trim()}`)
+    lines.push(`      SUPATYPE_APP_UPSTREAM: ${proxyUpstreamForCompose(config.app.upstream, devLocal)}`)
   }
   return lines.join("\n")
 }
 
-export function renderSelfHostCompose(config: SupatypeProjectConfig, cwd: string = process.cwd()): string {
+export interface SelfHostComposeOptions {
+  /** `supatype dev` with provider docker: internal-only db/server; Kong on host :18473. */
+  devLocal?: boolean
+}
+
+export function renderSelfHostCompose(
+  config: SupatypeProjectConfig,
+  cwd: string = process.cwd(),
+  options?: SelfHostComposeOptions,
+): string {
   const projectMount = projectMountPath(cwd)
-  const appEnv = serverAppEnvForCompose(config)
+  const kongMount = kongMountPath(cwd)
+  const devLocal = options?.devLocal === true
+  const studioHostDev = devLocal && hasStudioOverride(config)
+  const appEnv = serverAppEnvForCompose(config, devLocal)
+  const studioService = studioServiceBlock(cwd, devLocal)
+  const studioBlock = studioHostDev
+    ? ""
+    : `
+  studio:
+${studioService}
+    environment:
+      SUPATYPE_CLOUD_JSON: '{"url":"\${API_EXTERNAL_URL:-http://localhost:18473}","anonKey":"\${ANON_KEY:-}"}'
+    expose:
+      - "3002"
+`
+  const kongDependsOn = studioHostDev
+    ? `      - server`
+    : `      - server
+      - studio`
+  const publishDbToHost = !devLocal || hasEngineOverride(config)
+  const dbPorts = publishDbToHost
+    ? devLocal
+      ? `    ports:
+      - "127.0.0.1:\${SUPATYPE_DEV_DB_PORT:-54329}:5432"
+`
+      : `    ports:
+      - "5432:5432"
+`
+    : ""
+  const serverPorts = devLocal
+    ? ""
+    : `    ports:
+      - "9999:9999"
+`
+  const minioPorts = devLocal
+    ? ""
+    : `    ports:
+      - "9000:9000"
+      - "9001:9001"
+`
 
   return `# Generated by supatype self-host compose
 # Kong → supatype-server (unified gateway) → internal PostgREST / storage / etc.
 services:
   db:
-    image: \${SUPATYPE_POSTGRES_IMAGE:-supatype/postgres:17-latest}
+    image: \${SUPATYPE_POSTGRES_IMAGE:-supatype/postgres:latest}
     environment:
       POSTGRES_USER: \${POSTGRES_USER:-supatype_admin}
       POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:-postgres}
       POSTGRES_DB: \${POSTGRES_DB:-supatype}
-    ports:
-      - "5432:5432"
-    volumes:
+${dbPorts}    volumes:
       - db-data:/var/lib/postgresql/data
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U \${POSTGRES_USER:-supatype_admin}"]
@@ -83,7 +179,7 @@ services:
       - "3000"
     environment:
       PGRST_DB_URI: postgresql://\${POSTGRES_USER:-supatype_admin}:\${POSTGRES_PASSWORD:-postgres}@db:5432/\${POSTGRES_DB:-supatype}
-      PGRST_DB_SCHEMA: "public, supatype"
+      PGRST_DB_SCHEMA: "public, supatype, graphql_public"
       PGRST_DB_ANON_ROLE: anon
       PGRST_JWT_SECRET: \${JWT_SECRET:-super-secret-jwt-token-change-in-production}
       PGRST_DB_EXTRA_SEARCH_PATH: public,extensions
@@ -122,19 +218,20 @@ services:
       SUPATYPE_URL: \${API_EXTERNAL_URL:-http://localhost:18473}
       SUPATYPE_ANON_KEY: \${ANON_KEY:-}
       SUPATYPE_SERVICE_ROLE_KEY: \${SERVICE_ROLE_KEY:-}
+      STRIPE_SECRET_KEY: \${STRIPE_SECRET_KEY:-}
+      STRIPE_WEBHOOK_SECRET: \${STRIPE_WEBHOOK_SECRET:-}
+      SITE_URL: \${SITE_URL:-\${API_EXTERNAL_URL:-http://localhost:18473}}
     depends_on:
       db:
         condition: service_healthy
 
   server:
     image: \${SUPATYPE_SERVER_IMAGE:-\${SUPATYPE_AUTH_IMAGE:-supatype/server:latest}}
-    ports:
-      - "9999:9999"
-    volumes:
+${serverPorts}    volumes:
       - ${projectMount}:/project:ro
     working_dir: /project
     environment:
-      SUPATYPE_MODE: standalone
+      SUPATYPE_MODE: ${devLocal ? "dev" : "standalone"}
       SUPATYPE_MANIFEST_PATH: /project/.supatype/manifest.json
       SUPATYPE_ADMIN_CONFIG_PATH: /project/.supatype/admin-config.json
       SUPATYPE_API_CONFIG_PATH: /project/.supatype/api-config.json
@@ -162,6 +259,7 @@ ${appEnv}
       GOTRUE_JWT_ADMIN_ROLES: service_role,supatype_admin
       GOTRUE_MAILER_AUTOCONFIRM: \${GOTRUE_MAILER_AUTOCONFIRM:-true}
       GOTRUE_DISABLE_SIGNUP: \${DISABLE_SIGNUP:-false}
+${devLocal ? "      STUDIO_OPEN_DEV: \"1\"\n" : ""}
     depends_on:
       db:
         condition: service_healthy
@@ -178,17 +276,20 @@ ${appEnv}
     environment:
       MINIO_ROOT_USER: supatype
       MINIO_ROOT_PASSWORD: supatype-secret
-    ports:
-      - "9000:9000"
-      - "9001:9001"
-    volumes:
+${minioPorts}    volumes:
       - minio-data:/data
 
-  studio:
-    image: \${SUPATYPE_STUDIO_IMAGE:-supatype/studio:latest}
-    expose:
-      - "3002"
-
+  schema-engine:
+    image: \${SUPATYPE_ENGINE_IMAGE:-supatype/schema-engine:latest}
+    profiles: ["tools"]
+    entrypoint: ["supatype-engine"]
+    volumes:
+      - ${projectMount}:/project
+    working_dir: /project
+    depends_on:
+      db:
+        condition: service_healthy
+${studioBlock}
   kong:
     image: kong:3.6
     environment:
@@ -199,12 +300,11 @@ ${appEnv}
       KONG_PROXY_ERROR_LOG: /dev/stderr
       KONG_ADMIN_ERROR_LOG: /dev/stderr
     volumes:
-      - ./kong.yml:/etc/kong/kong.yml:ro
+      - ${kongMount}:/etc/kong/kong.yml:ro
     ports:
-      - "18473:8000"
+      - "\${SUPATYPE_KONG_PORT:-18473}:8000"
     depends_on:
-      - server
-      - studio
+${kongDependsOn}
 
 volumes:
   db-data:
@@ -226,24 +326,50 @@ function ensureComposeManifest(cwd: string): void {
   writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8")
 }
 
-export function writeSelfHostCompose(cwd: string, config: SupatypeProjectConfig): SelfHostComposePaths {
+function ensureProjectFunctionsDir(cwd: string, config: SupatypeProjectConfig): void {
+  mkdirSync(preferredFunctionsPathFromProject(config, cwd), { recursive: true })
+}
+
+export function writeSelfHostCompose(
+  cwd: string,
+  config: SupatypeProjectConfig,
+  options?: SelfHostComposeOptions,
+): SelfHostComposePaths {
   const paths = selfHostComposePaths(cwd)
   mkdirSync(paths.dir, { recursive: true })
+  ensureProjectFunctionsDir(cwd, config)
   ensureComposeManifest(cwd)
-  writeFileSync(paths.composePath, renderSelfHostCompose(config, cwd), "utf8")
+  writeFileSync(paths.composePath, renderSelfHostCompose(config, cwd, options), "utf8")
+  const studioHostDev = options?.devLocal === true && hasStudioOverride(config)
   writeFileSync(
     paths.kongPath,
     buildKongDeclarative({
       unifiedGateway: true,
+      ...(studioHostDev && {
+        studioServiceUrl: COMPOSE_STUDIO_HOST_URL,
+        studioStripPath: false,
+      }),
     }),
     "utf8",
   )
   return paths
 }
 
-export function runDockerCompose(composePath: string, args: string[], projectRoot: string = process.cwd()): number {
+export function runDockerCompose(
+  composePath: string,
+  args: string[],
+  projectRoot: string = process.cwd(),
+  composeProject?: string,
+): number {
   const envFile = resolve(projectRoot, ".env")
-  const composeArgs = ["compose", "-f", composePath]
+  const composeArgs = ["compose"]
+  // Per-project name isolates containers/volumes/network so multiple Supatype
+  // projects on one machine never share a database (default would be the
+  // ".supatype/self-host" dir name, identical for every project).
+  if (composeProject) composeArgs.push("-p", composeProject)
+  // Resolve ${VAR} in compose.yml from the project root .env (not .supatype/self-host/).
+  composeArgs.push("--project-directory", projectRoot)
+  composeArgs.push("-f", composePath)
   if (existsSync(envFile)) {
     composeArgs.push("--env-file", envFile)
   }
@@ -251,7 +377,13 @@ export function runDockerCompose(composePath: string, args: string[], projectRoo
   const result = spawnSync(
     "docker",
     composeArgs,
-    { stdio: "inherit", cwd: dirname(composePath) },
+    { stdio: "inherit", cwd: projectRoot },
   )
   return result.status ?? 1
 }
+
+/** Compose project name for a Supatype project — isolates docker state per project. */
+export function composeProjectName(projectName: string): string {
+  const slug = projectName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "")
+  return `supatype-${slug || "project"}`
+}

package/src/studio-admin-roles.ts

@@ -0,0 +1,16 @@
+import type { SupatypeProjectConfig } from "./project-config.js"
+
+export const DEFAULT_STUDIO_ADMIN_ROLES = ["admin", "supatype_admin"] as const
+
+/** Studio admin roles from `supatype.config.ts` `admin.roles` or defaults. */
+export function studioAdminRoles(cfg: SupatypeProjectConfig): string[] {
+  const roles = cfg.admin?.roles
+  if (roles !== undefined && roles.length > 0) return roles
+  return [...DEFAULT_STUDIO_ADMIN_ROLES]
+}
+
+/** Merge `adminRoles` into engine admin-config JSON for Studio and supatype-server. */
+export function withAdminRoles(admin: unknown, cfg: SupatypeProjectConfig): Record<string, unknown> {
+  const base = typeof admin === "object" && admin !== null ? (admin as Record<string, unknown>) : {}
+  return { ...base, adminRoles: studioAdminRoles(cfg) }
+}