Deployment contract

A deployment target has no runtime. Its descriptor carries what genoa build and genoa deploy need: the SvelteKit adapter that shapes the build for the platform, and the procedure that publishes it. A worked example is under adapters .

interface DeploymentDescriptor<O extends object> {
  readonly kind: 'deployment'
  readonly svelteKitAdapter: () => Promise<{ default: SvelteKitAdapterFactory }>
  readonly svelteKitOptions?: (options: O, ctx: { outDir: string }) => Record<string, unknown>
  readonly procedure: () => Promise<{ default: DeployProcedure<O> }>
  readonly secretOptions?: { readonly [K in keyof O]?: SecretEncoding }
  readonly validate?: (options: unknown) => string[]
}

interface DeployContext {
  readonly projectRoot: string
  readonly buildDir: string
  readonly workDir: string
  readonly target: string
}

type DeployProcedure<O extends object> = (options: Resolved<O>, ctx: DeployContext) => Promise<void>
ts
  • svelteKitOptions receives the target's options unresolved: credentials never influence a build.
  • The procedure receives them resolved, on the operator's machine, with buildDir the artifact, workDir an empty scratch directory the deploy owns, and target the target's key.

The declarations as @genoacms/contracts ships them, with the descriptors of the other services:

import type { Resolved, SecretEncoding } from './references.js'

/** SDK-free. The module at the specifier a config entry names. */
interface AdapterDescriptor<Kind extends string, O extends object> {
  readonly kind: Kind
  /** Bare specifier of the runtime module, e.g. '@genoacms/adapter-gcp/storage/runtime'. Never relative. */
  readonly runtime: string
  /** Top-level options that hold references, and how to decode them. A reference anywhere else is refused. */
  readonly secretOptions?: { readonly [K in keyof O]?: SecretEncoding }
  /** Refused by a production build. */
  readonly developmentOnly?: boolean
  /** Checks unresolved options. Returns the reasons they are invalid; an empty array means valid. */
  readonly validate?: (options: unknown) => string[]
}

interface AdapterContext {
  /** The provider's key in the config. For log lines and error messages, never for lookup. */
  readonly name: string
  /** Resources bound to this provider: bucket names for storage, database names for a database, otherwise empty. */
  readonly resources: readonly string[]
  /** Present in the dev server, the CLI and development builds. Absent in a production artifact. */
  readonly projectRoot?: string
}

/** Default export of a runtime module. */
interface AdapterRuntime<O extends object, Instance> {
  readonly create: (options: Resolved<O>, ctx: AdapterContext) => Instance | Promise<Instance>
}

/**
 * A SvelteKit adapter factory, typed structurally so this package needs no dependency on @sveltejs/kit.
 * `adapt` takes `never`: a real adapter's `adapt(builder: Builder)` is assignable to it, where it would
 * not be to `(builder: unknown) => unknown`.
 */
type SvelteKitAdapterFactory = (options?: Record<string, unknown>) => { name: string, adapt: (builder: never) => unknown }

/**
 * Both loaders are functions written inside the descriptor module, so each specifier resolves from
 * the adapter package that declares the dependency. Importing a SvelteKit adapter by name from core
 * fails under strict pnpm, where it is a dependency of the adapter package and of nothing else.
 */
interface DeploymentDescriptor<O extends object> {
  readonly kind: 'deployment'
  readonly svelteKitAdapter: () => Promise<{ default: SvelteKitAdapterFactory }>
  /** Receives unresolved options: credentials never influence the build. */
  readonly svelteKitOptions?: (options: O, ctx: { outDir: string }) => Record<string, unknown>
  /** The origin the built app is served at, given to SvelteKit as `paths.origin`. Receives unresolved options. */
  readonly origin?: (options: O) => string | undefined
  readonly procedure: () => Promise<{ default: DeployProcedure<O> }>
  readonly secretOptions?: { readonly [K in keyof O]?: SecretEncoding }
  readonly validate?: (options: unknown) => string[]
}

interface DeployContext {
  readonly projectRoot: string
  /** Absolute path of the build artifact. */
  readonly buildDir: string
  /** Absolute scratch directory owned by this deploy. It exists and is empty when the procedure starts. */
  readonly workDir: string
  /** The target's key in `deployment.targets`. */
  readonly target: string
}

type DeployProcedure<O extends object> = (options: Resolved<O>, ctx: DeployContext) => Promise<void>

export type { AdapterDescriptor, AdapterContext, AdapterRuntime, SvelteKitAdapterFactory, DeploymentDescriptor, DeployContext, DeployProcedure }
ts
Expand code