@fabrika/provider-zerops 0.9.0-dev.1 → 0.9.0-dev.2

package/types/src/namespace/update.d.ts

@@ -0,0 +1,6 @@
+import { type ProviderNamespaceUpdates } from '@fabrika/provider-contract';
+import type { ZeropsNamespaceOptions } from './types';
+/** The plan field of a re-pin, which moves only the stored target; the reconcile core queues rebuilds the proxy. */
+export declare const ZEROPS_PROXY_SOURCE_FIELD = "proxySource";
+/** Move a ready namespace's PostgreSQL service to another profile — the one field Zerops changes in place. */
+export declare const createZeropsNamespaceUpdates: (options: ZeropsNamespaceOptions) => ProviderNamespaceUpdates;

package/types/src/namespace/validation.d.ts

@@ -0,0 +1,12 @@
+import type { ZeropsService } from '../api';
+/**
+ * The profile a service is checked against. `declared` is what the stored target says. `changingTo` is
+ * set only while an update moves the service, and `unconfirmed` while it retries an earlier update whose
+ * outcome is unknown: a live service already on either reads as the change in progress, not as drift.
+ */
+export interface ZeropsExpectedProfile {
+    readonly declared?: string;
+    readonly changingTo?: string;
+    readonly unconfirmed?: string;
+}
+export declare const validateService: (service: ZeropsService, projectId: string, expectedBase: string, adopting: boolean, expectedPublic?: boolean, expectedProfile?: ZeropsExpectedProfile) => void;

package/types/src/namespace.d.ts

@@ -0,0 +1,9 @@
+export { zeropsNamespaceTargetCodec } from './namespace/codec';
+export { ZEROPS_NAMESPACE_IAM_ISSUER_VARIABLE, ZEROPS_NAMESPACE_IAM_KEY_VARIABLE, ZEROPS_NAMESPACE_POSTGRES_HOSTNAME, ZEROPS_NAMESPACE_PROXY_HOSTNAME, ZEROPS_NAMESPACE_SUBDOMAIN_VARIABLE, ZEROPS_SHARED_POSTGRES_CONNECTION_STRING, } from './namespace/constants';
+export { ZEROPS_NAMESPACE_CANCELLED, ZEROPS_NAMESPACE_LIFECYCLE, ZEROPS_PROXY_DEPLOY_FAILED, ZEROPS_PROXY_DEPLOY_TIMEOUT, ZEROPS_SUBDOMAIN_NOT_PUBLISHED, } from './namespace/errors';
+export { createZeropsNamespaceOperator } from './namespace/operator';
+export { createZeropsNamespaceCapabilities } from './namespace/provisioning';
+export { republishProxy, type ZeropsProxyApi, type ZeropsProxyRepublishInput } from './namespace/proxy-attempt';
+export { decodeZeropsNamespaceProxySource, verifyZeropsNamespaceProxySource } from './namespace/proxy-source';
+export { compileZeropsNamespaceTopology, zeropsNamespacePreset } from './namespace/topology';
+export type { ZeropsNamespaceOperatorOptions, ZeropsNamespaceOptions, ZeropsNamespacePlanOptions, ZeropsNamespacePostgres, ZeropsNamespacePresetInput, ZeropsNamespaceProxyBuild, ZeropsNamespaceProxyDeployment, ZeropsNamespaceProxySource, ZeropsNamespacePublicAccess, ZeropsNamespaceTarget, ZeropsNamespaceTopology, } from './namespace/types';

package/types/src/plan.d.ts

@@ -0,0 +1,12 @@
+import { type FabrikaManifest } from './manifest';
+import type { ZeropsRuntimeTarget } from './types';
+export type ZeropsStepKind = 'apply-import' | 'verify-exposure' | 'write-service-env' | 'raise-start-memory' | 'size-database' | 'reserve-version' | 'upload-source' | 'trigger-build' | 'await-version' | 'reconcile-schema';
+export interface ZeropsStep {
+    readonly id: string;
+    readonly kind: ZeropsStepKind;
+    readonly description: string;
+}
+/** Resolve the one declared service that receives this repository's code. */
+export declare const resolveDeployHostname: (manifest: FabrikaManifest) => string;
+/** Build the provider-owned deploy order without touching the platform. */
+export declare const buildZeropsPlan: (manifest: FabrikaManifest, target: ZeropsRuntimeTarget) => readonly ZeropsStep[];

package/types/src/provider.d.ts

@@ -0,0 +1,65 @@
+import { type OperationsSourceMapUploadState } from '@fabrika/operations-contract/releases';
+import { type DeployStepResult, type ProviderApprovedAccess, type ProviderDeployInput, type ProviderManagedEnvironment, type ProviderRunEvents } from '@fabrika/provider-contract';
+import { type ZeropsService } from './api';
+import { type ZeropsCollaboratorFactory, type ZeropsCollaborators } from './collaborators';
+import { type ZeropsDevExecution } from './execution';
+import { type FabrikaImportDocument, type FabrikaManifest } from './manifest';
+import type { ZeropsRuntimeTarget } from './types';
+export declare const CANCELLED = "deploy cancelled";
+export interface ZeropsDeployRun {
+    readonly appId: string;
+    readonly env: string;
+    /** Every origin IAM may hand this app a session at; app-wide, because IAM's registry is keyed by app id. */
+    readonly returnOrigins?: readonly string[];
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly vars: Readonly<Record<string, string>>;
+    /** Platform-owned runtime configuration, separate from operator-managed application vars. */
+    readonly managedEnvironment: ProviderManagedEnvironment;
+    readonly target: ZeropsRuntimeTarget;
+    readonly artifact: FabrikaManifest;
+    /** Control's approved access for the environment (ADR-0050); the lock-down and the IAM schema come from it. */
+    readonly access?: ProviderApprovedAccess;
+    /** The run-scoped source-map destination Control minted; the build uploads to it. */
+    readonly artifactUpload?: ProviderDeployInput['artifactUpload'];
+    /** Present for an environment of kind `dev`: the launcher starts instead of the serving entry, on one container. */
+    readonly dev?: ZeropsDevExecution;
+    readonly dryRun: boolean;
+    readonly signal: AbortSignal;
+    readonly events: ProviderRunEvents;
+}
+export interface ZeropsDeployResult {
+    readonly appId: string;
+    readonly env: string;
+    readonly status: 'succeeded' | 'failed';
+    readonly steps: readonly DeployStepResult[];
+    /** Whether the build's source maps reached Operations; absent when the run had no upload to make. */
+    readonly artifactState?: OperationsSourceMapUploadState;
+}
+/** A run stops waiting for its version this long after it started. Zerops' own pipeline limit is 1 hour. */
+export declare const ZEROPS_VERSION_DEADLINE_MS: number;
+/**
+ * Resolve the manifest's declared variables INTO THE DOCUMENT — never into the rendered YAML, where a
+ * value carrying a quote or a newline would be read as structure and could add a service or turn
+ * `envIsolation` off. Only variables the manifest declares resolve; every other placeholder fails the
+ * deploy, and so does a value that names a service outside the app (Zerops resolves `${host_KEY}`
+ * regardless of isolation). The document is re-checked here because this is the last point it is an object.
+ */
+export declare function interpolateManifest(document: FabrikaImportDocument, declared: readonly string[], values: Record<string, string>, ownHostnames: readonly string[]): FabrikaImportDocument;
+/** What raising a minimum RAM calls; the deploy's collaborators, and the live platform-facts probe of the same path. */
+export interface MinRamRaise {
+    zerops: Pick<ZeropsCollaborators, 'api' | 'sleep'>;
+    signal: AbortSignal;
+}
+/**
+ * Sets `service`'s minimum RAM to `minRam` and answers the minimum it reads back. It sends the custom autoscaling it
+ * read WHOLE with only that field changed: the platform resets every field a request leaves out.
+ */
+export declare const raiseMinRam: (env: MinRamRaise, service: ZeropsService, hostname: string, minRam: number, need: string) => Promise<number>;
+/**
+ * Build a Zerops deployer over a specific collaborator FACTORY. Production passes the real one; tests pass
+ * `() => fakes`, which is the whole testability property — one seam, all of this driver's effects.
+ *
+ * A factory rather than a bundle because the Zerops client is authenticated with a token that lives on the
+ * run's target, so it cannot be constructed once at module load the way Cloudflare's bundle is.
+ */
+export declare const createZeropsDeployer: (collaborators?: ZeropsCollaboratorFactory) => (run: ZeropsDeployRun) => Promise<ZeropsDeployResult>;

package/types/src/proxy-manifest-carrier.d.ts

@@ -0,0 +1,16 @@
+/** The path of the proxy manifest in the build archive: the archive's one data file (ADR-0045), read by the proxy build. */
+export declare const ZEROPS_PROXY_MANIFEST_PATH = "proxy.manifest.json";
+/**
+ * How a proxy build receives its manifest.
+ *
+ * - `environment`: the build lifts `FABRIKA_PROXY_MANIFEST_JSON` from the service and writes it to the file, as every
+ *   release before the archive carrier did. A namespace pinned to such a commit keeps its descriptor (ADR-0045), so it
+ *   gets the variable, bound by the Zerops value limit.
+ * - `archive`: the build reads the file the uploaded archive carries.
+ */
+export type ZeropsProxyManifestCarrier = 'environment' | 'archive';
+/**
+ * The carrier a descriptor's proxy setup reads. Decided by the build section Zerops applies (the selected setup's, else
+ * the nearest one it `extends`): a lifted `FABRIKA_PROXY_MANIFEST_JSON` would overwrite an archived file, so it wins.
+ */
+export declare const zeropsProxyManifestCarrier: (descriptorContents: string, setup?: string) => ZeropsProxyManifestCarrier;

package/types/src/schema.generated.d.ts

@@ -0,0 +1,376 @@
+/** Only one project can be defined. */
+export interface ZeropsImportProject {
+    /** The name of the new project. Duplicates are allowed. */
+    name: string;
+    /** Description of the new project. */
+    description?: string;
+    /**
+     * Project core package.
+     * Zerops default: `"LIGHT"`.
+     */
+    corePackage?: 'LIGHT' | 'SERIOUS';
+    /** One or more string tags. Tags do not have functional meaning, they only provide better orientation in projects. */
+    tags?: string[];
+    /** List of environment variables of project configuration. */
+    envVariables?: Record<string, string>;
+    /**
+     * Defines the visibility scope for environment variables. Allowed values: none (no isolation, everyone sees all
+     * variables), service (isolation at service level, each service can only see its own variables). Explicit variable
+     * referencing is still possible regardless of the isolation setting.
+     */
+    envIsolation?: string;
+    /**
+     * Defines who is authorized to access the service via SSH. Values can be combined using spaces (e.g., project vpn). To
+     * exclude a specific access type, use a negative prefix (e.g., -vpn). Allowed values: project (anyone from the project),
+     * vpn (anyone from the VPN), service (anyone from the same service), service@name (anyone from the service named "name").
+     */
+    sshIsolation?: string;
+    /**
+     * When enabled, project domain includes both AAAA records and an A record pointing to Zerops shared IPv4 address. When
+     * disabled, the A record is not defined. If the project has its own dedicated IPv4 address, the domain always contains an
+     * A record with this assigned IPv4 address.
+     */
+    sharedIpv4?: boolean;
+    /** Defines project's primary/fallback location'. */
+    location?: 'eu-central' | 'us-east-1' | 'us-west-1';
+}
+export interface ZeropsImportService {
+    /**
+     * The unique service identifier. Limitations: duplicates in the same project forbidden; maximum 25 characters, lowercase
+     * ASCII letters (a-z) or numbers (0-9) only.
+     */
+    hostname: string;
+    /** Specifies the service type and version. */
+    type: ZeropsServiceType;
+    /**
+     * Deprecated, use Type version only. Defines the operation mode of the service.
+     * @deprecated
+     */
+    mode?: string;
+    /**
+     * List of key-value pairs. Environment variables that are blurred by default in Zerops GUI. Can be edited or deleted in
+     * Zerops GUI.
+     */
+    envSecrets?: Record<string, string>;
+    /**
+     * List of key-value pairs in .env format. Environment variables that are blurred by default in Zerops GUI. Can be edited
+     * or deleted in Zerops GUI.
+     */
+    dotEnvSecrets?: string;
+    /** Insert full nginx config. */
+    nginxConfig?: string;
+    /** Object storage size in GB. */
+    objectStorageSize?: number;
+    /** Select a predefined AWS S3 bucket access policy. */
+    objectStoragePolicy?: 'custom' | 'private' | 'public-read' | 'public-objects-read' | 'public-write' | 'public-read-write';
+    /**
+     * Define your own AWS S3 bucket access policy. See AWS docs for details. Use {{ .BucketName }} placeholder if you need to
+     * use bucket name in your custom policy rules.
+     */
+    objectStorageRawPolicy?: string;
+    /** A URL of a Github or Gitlab repository used for a one-time build of your service. */
+    buildFromGit?: string;
+    /** Set true, if you want to start service without code. */
+    startWithoutCode?: boolean;
+    /**
+     * Set true, if you want to enable a public access to your service via a Zerops subdomain. Not suitable for production.
+     * Zerops default: `false`.
+     */
+    enableSubdomainAccess?: boolean;
+    /**
+     * Services are sorted before creation by priority in descending order, i.e. the higher the priority the sooner the service
+     * is created.
+     */
+    priority?: number;
+    /** Vertical autoscaling settings. */
+    verticalAutoscaling?: ZeropsVerticalAutoscaling;
+    /** Minimum number of containers of the service. */
+    minContainers?: number;
+    /** Maximum number of containers of the service. */
+    maxContainers?: number;
+    /** Defines the autoscaling profile for the service. */
+    profile?: string;
+    /** Json formatted list of overrides for the selected autoscaling profile. */
+    profileOverrides?: unknown;
+    /** Mount shared storages to the service, buildFromGit must be filled. */
+    mount?: string[];
+    /** Set true, if you want to enable CDN for the object storage bucket. Currently only relevant for object storage services. */
+    enableCdn?: boolean;
+    /**
+     * Defines the visibility scope for environment variables. Allowed values: none (no isolation, everyone sees all
+     * variables), service (isolation at service level, each service can only see its own variables). Explicit variable
+     * referencing is still possible regardless of the isolation setting. When set at the service level, these values override
+     * any project-level defined isolation settings.
+     */
+    envIsolation?: string;
+    /**
+     * Defines who is authorized to access the service via SSH. Values can be combined using spaces (e.g., project vpn). To
+     * exclude a specific access type, use a negative prefix (e.g., -vpn). Allowed values: project (anyone from the project),
+     * vpn (anyone from the VPN), service (anyone from the same service), service@name (anyone from the service named "name").
+     * When set at the service level, these values override any project-level defined isolation settings.
+     */
+    sshIsolation?: string;
+    /**
+     * Deprecated, use Type version only. Optionally specifies the OS of the runtime service imported with
+     * 'startWithoutCode=true'.
+     * @deprecated
+     */
+    os?: string;
+    zeropsSetup?: string;
+    zeropsYaml?: ZeropsYaml;
+    /** Override existing service. */
+    override?: boolean;
+}
+/** Specifies the service type and version. */
+export type ZeropsServiceType = 'alpine/bun@1' | 'alpine/bun@1.2' | 'alpine/bun@1.2.2' | 'alpine/bun@1.3' | 'alpine/bun@1.3.9' | 'alpine/bun@canary' | 'alpine/bun@latest' | 'alpine/bun@nightly' | 'alpine/docker@26' | 'alpine/docker@26.1' | 'alpine/docker@26.1.5' | 'alpine/docker@latest' | 'alpine/dotnet@10' | 'alpine/dotnet@8' | 'alpine/dotnet@9' | 'alpine/dotnet@latest' | 'alpine/elixir@1' | 'alpine/elixir@1.16' | 'alpine/elixir@1.16.3' | 'alpine/elixir@latest' | 'alpine/gleam@1' | 'alpine/gleam@1.5' | 'alpine/gleam@1.5.1' | 'alpine/gleam@latest' | 'alpine/go@1' | 'alpine/go@1.22' | 'alpine/go@latest' | 'alpine/golang@1' | 'alpine/golang@1.22' | 'alpine/golang@latest' | 'alpine/java@17' | 'alpine/java@21' | 'alpine/java@latest' | 'alpine/nginx@1.22' | 'alpine/nginx@latest' | 'alpine/nodejs@20' | 'alpine/nodejs@22' | 'alpine/nodejs@24' | 'alpine/nodejs@latest' | 'alpine/php-apache@8.1' | 'alpine/php-apache@8.1+2.4' | 'alpine/php-apache@8.3' | 'alpine/php-apache@8.3+2.4' | 'alpine/php-apache@8.4' | 'alpine/php-apache@8.4+2.4' | 'alpine/php-apache@8.5' | 'alpine/php-apache@8.5+2.4' | 'alpine/php-apache@latest' | 'alpine/php-nginx@8.3' | 'alpine/php-nginx@8.3+1.22' | 'alpine/php-nginx@8.4' | 'alpine/php-nginx@8.4+1.22' | 'alpine/php-nginx@8.5' | 'alpine/php-nginx@8.5+1.28' | 'alpine/php-nginx@latest' | 'alpine/python@3.11' | 'alpine/python@3.12' | 'alpine/python@latest' | 'alpine/ruby@3.3' | 'alpine/ruby@3.4' | 'alpine/ruby@4.0' | 'alpine/ruby@latest' | 'alpine/rust@1' | 'alpine/rust@latest' | 'alpine/rust@nightly' | 'alpine/rust@stable' | 'alpine/static' | 'alpine/static@1.0' | 'alpine/static@latest' | 'alpine/zero@0.1' | 'alpine/zero@latest' | 'alpine/zero@nightly' | 'alpine@3.21' | 'alpine@3.22' | 'alpine@3.23' | 'alpine@3.24' | 'alpine@latest' | 'clickhouse:ha@25.3' | 'clickhouse:single@25.3' | 'elasticsearch:ha@8.16' | 'elasticsearch:ha@9.2' | 'elasticsearch:single@8.16' | 'elasticsearch:single@9.2' | 'kafka:ha@3.9' | 'kafka:single@3.9' | 'mariadb:ha@10.6' | 'mariadb:single@10.6' | 'meilisearch:single@1.10' | 'meilisearch:single@1.20' | 'meilisearch:single@1.44' | 'nats:ha@2.10' | 'nats:ha@2.12' | 'nats:single@2.10' | 'nats:single@2.12' | 'object-storage' | 'objectstorage' | 'postgresql:ha@14' | 'postgresql:ha@16' | 'postgresql:ha@17' | 'postgresql:ha@18' | 'postgresql:single@14' | 'postgresql:single@16' | 'postgresql:single@17' | 'postgresql:single@18' | 'qdrant:ha@1.10' | 'qdrant:ha@1.12' | 'qdrant:single@1.10' | 'qdrant:single@1.12' | 'seaweedfs:ha@3' | 'seaweedfs:single@3' | 'shared-storage:ha' | 'shared-storage:single' | 'sharedstorage:ha' | 'sharedstorage:single' | 'static' | 'typesense:ha@27.1' | 'typesense:ha@30.2' | 'typesense:single@27.1' | 'typesense:single@30.2' | 'ubuntu/bun@1' | 'ubuntu/bun@1.1' | 'ubuntu/bun@1.1.34' | 'ubuntu/bun@1.2' | 'ubuntu/bun@1.2.2' | 'ubuntu/bun@1.3' | 'ubuntu/bun@1.3.9' | 'ubuntu/bun@canary' | 'ubuntu/bun@latest' | 'ubuntu/bun@nightly' | 'ubuntu/deno@2' | 'ubuntu/deno@2.0' | 'ubuntu/deno@2.0.0' | 'ubuntu/deno@latest' | 'ubuntu/dotnet@10' | 'ubuntu/dotnet@8' | 'ubuntu/dotnet@9' | 'ubuntu/dotnet@latest' | 'ubuntu/elixir@1' | 'ubuntu/elixir@1.16' | 'ubuntu/elixir@1.16.2' | 'ubuntu/elixir@latest' | 'ubuntu/gleam@1' | 'ubuntu/gleam@1.5' | 'ubuntu/gleam@1.5.1' | 'ubuntu/gleam@latest' | 'ubuntu/go@1' | 'ubuntu/go@1.22' | 'ubuntu/go@latest' | 'ubuntu/golang@1' | 'ubuntu/golang@1.22' | 'ubuntu/golang@latest' | 'ubuntu/java@17' | 'ubuntu/java@21' | 'ubuntu/java@latest' | 'ubuntu/nginx@1.22' | 'ubuntu/nginx@latest' | 'ubuntu/nodejs@20' | 'ubuntu/nodejs@22' | 'ubuntu/nodejs@24' | 'ubuntu/nodejs@latest' | 'ubuntu/php-apache@8.1' | 'ubuntu/php-apache@8.1+2.4' | 'ubuntu/php-apache@8.3' | 'ubuntu/php-apache@8.3+2.4' | 'ubuntu/php-apache@8.4' | 'ubuntu/php-apache@8.4+2.4' | 'ubuntu/php-apache@8.5' | 'ubuntu/php-apache@8.5+2.4' | 'ubuntu/php-apache@latest' | 'ubuntu/php-nginx@8.3' | 'ubuntu/php-nginx@8.3+1.22' | 'ubuntu/php-nginx@8.4' | 'ubuntu/php-nginx@8.4+1.22' | 'ubuntu/php-nginx@8.5' | 'ubuntu/php-nginx@8.5+1.28' | 'ubuntu/php-nginx@latest' | 'ubuntu/python@3.11' | 'ubuntu/python@3.12' | 'ubuntu/python@3.14' | 'ubuntu/python@latest' | 'ubuntu/ruby@3.3' | 'ubuntu/ruby@3.4' | 'ubuntu/ruby@4.0' | 'ubuntu/ruby@latest' | 'ubuntu/rust@1' | 'ubuntu/rust@latest' | 'ubuntu/rust@nightly' | 'ubuntu/rust@stable' | 'ubuntu/static' | 'ubuntu/static@1.0' | 'ubuntu/static@latest' | 'ubuntu/zero@0.1' | 'ubuntu/zero@latest' | 'ubuntu/zero@nightly' | 'ubuntu@22.04' | 'ubuntu@24.04' | 'ubuntu@26.04' | 'ubuntu@latest' | 'valkey:ha@7.2' | 'valkey:single@7.2' | 'zcp@1' | 'zcp@latest';
+/** Vertical autoscaling settings. */
+export interface ZeropsVerticalAutoscaling {
+    /** Fixed CPU thread count that each container of the service will be set to. */
+    cpu?: number;
+    /** Fixed RAM in GB that each container of the service will be set to. */
+    ram?: number;
+    /** Fixed disk space in GB that each container of the service will be set to. */
+    disk?: number;
+    /** CPU mode that each container of the service will be set to. */
+    cpuMode?: 'DEDICATED' | 'SHARED';
+    /** Minimum CPU thread count that each container of the service can scale down to. */
+    minCpu?: number;
+    /** Maximum CPU thread count that each container of the service can scale up to. */
+    maxCpu?: number;
+    /** Minimum RAM in GB that each container of the service can scale down to. */
+    minRam?: number;
+    /** Maximum RAM in GB that each container of the service can scale up to. */
+    maxRam?: number;
+    /** Minimum disk space in GB that each container of the service can scale down to. */
+    minDisk?: number;
+    /** Maximum disk space in GB that each container of the service can scale up to. */
+    maxDisk?: number;
+    /** Number of CPU cores with which each container starts. */
+    startCpuCoreCount?: number;
+    /** Whether to enable swap memory for containers. Swap is enabled by default. Refer to documentation for more details. */
+    swapEnabled?: boolean;
+    /** Minimum number of unused CPU cores before a container starts scaling. */
+    minFreeCpuCores?: number;
+    /** Minimum percentage of unused CPU cores before a container starts scaling. */
+    minFreeCpuPercent?: number;
+    /** Minimum unused memory in GB before a container starts scaling. */
+    minFreeRamGB?: number;
+    /** Minimum percentage of unused memory before a container starts scaling. */
+    minFreeRamPercent?: number;
+    /** @deprecated */
+    minVCpu?: number;
+    /** @deprecated */
+    maxVCpu?: number;
+}
+export interface ZeropsYaml {
+    /** The top-level element is always zerops. */
+    zerops: ZeropsYamlSetup[];
+}
+export interface ZeropsYamlSetup {
+    /**
+     * The first element setup contains the hostname of your service. A runtime service with the same hostname must exist in
+     * Zerops. Zerops supports the definition of multiple runtime services in a single zerops.yml. This is useful when you use
+     * a monorepo. Just add multiple setup elements in your zerops.yml.
+     */
+    setup: string;
+    /** Build pipeline configuration. */
+    build?: ZeropsYamlBuild;
+    /** Deploy configuration. */
+    deploy?: ZeropsYamlDeploy;
+    /** Runtime configuration. */
+    run?: ZeropsYamlRun;
+}
+/** Build pipeline configuration. */
+export interface ZeropsYamlBuild {
+    /** Deprecated - use base attribute. Sets the operating system for the build environment. */
+    os?: string;
+    /** Sets the base technology for the build environment. */
+    base?: string[];
+    /** Customises the build environment by installing additional dependencies or tools to the base build environment. */
+    prepareCommands?: string[];
+    /** Defines build commands. Zerops triggers each command in the defined order in a dedicated build container. */
+    buildCommands?: string[];
+    deploy?: string[];
+    /**
+     * Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files
+     * or folders, use .deployignore file.
+     */
+    deployFiles: string[];
+    /** Defines which files or folders will be cached for the next build. */
+    cache?: unknown;
+    /**
+     * Defines what files or folders will be copied from the build container to the prepare runtime container. The prepare
+     * runtime container is used to customize your runtime environment.
+     */
+    addToRunPrepare?: string[];
+    /** Defines the environment variables for the build environment. */
+    envVariables?: Record<string, string>;
+}
+/** Deploy configuration. */
+export interface ZeropsYamlDeploy {
+    /** Defines a readiness check. Requires either httpGet object or exec object. */
+    readinessCheck?: ZeropsReadinessCheck;
+    temporaryShutdown?: boolean;
+}
+/** Defines a readiness check. Requires either httpGet object or exec object. */
+export interface ZeropsReadinessCheck {
+    /** Configures the readiness check to request a local URL using a http GET method. */
+    httpGet?: ZeropsHttpGetProbe;
+    /** Configures the readiness check to run a local command. */
+    exec?: ZeropsExecProbe;
+    /** Time until container is marked as failed. */
+    failureTimeout?: number;
+    /** Time interval between readiness check attempts. */
+    retryPeriod?: number;
+}
+/** Configures the readiness check to request a local URL using a http GET method. */
+export interface ZeropsHttpGetProbe {
+    /**
+     * The readiness check is triggered from inside of your runtime container so no https is required. If your application
+     * requires a https request, set scheme: https
+     */
+    scheme?: string;
+    /**
+     * The readiness check is triggered from inside of your runtime container so it always uses the localhost (127.0.0.1). If
+     * you need to add a host to the request header, specify it in the host attribute.
+     */
+    host?: string;
+    /** Defines the port of the HTTP GET request. */
+    port: number;
+    /** Defines the URL path of the HTTP GET request. */
+    path: string;
+}
+/** Configures the readiness check to run a local command. */
+export interface ZeropsExecProbe {
+    /**
+     * Defines a local command to be run. The command has access to the same environment variables. A single string is
+     * required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
+     */
+    command: string;
+}
+/** Runtime configuration. */
+export interface ZeropsYamlRun {
+    /** Defines one or more commands to be run each time a new runtime container is started or a container is restarted. */
+    initCommands?: string[];
+    /** Customises the runtime environment by installing additional dependencies or tools to the base runtime environment. */
+    prepareCommands?: string[];
+    /** Deprecated - use base attribute. Sets the operating system for the runtime environment. */
+    os?: string;
+    /**
+     * Sets the base technology for the runtime environment. If you don't specify the run.base attribute, Zerops keeps the
+     * current version for your runtime.
+     */
+    base?: string;
+    /** Defines the start command for your application. */
+    start?: string;
+    /**
+     * Customizes the folder that will be used as the root of the publicly accessible web server content. This attribute is
+     * available only for runtimes with webservers.
+     */
+    documentRoot?: string;
+    /** Sets the custom webserver configuration. This attribute is available only for runtimes with webservers. */
+    siteConfigPath?: string;
+    envReplace?: ZeropsEnvReplace;
+    /** Defines a health check. */
+    healthCheck?: ZeropsHealthCheck;
+    routing?: ZeropsRouting;
+    /** Specifies one or more internal ports on which your application will listen. */
+    ports?: ZeropsPort[];
+    /** Defines the environment variables for the runtime environment. */
+    envVariables?: Record<string, string>;
+    /** Defines the start commands for the runtime environment. */
+    startCommands?: ZeropsStartCommand[];
+    /**
+     * A list of cron jobs with their respective schedule (timing), the command to run (command), and additional options like
+     * allContainers and workingDir.
+     */
+    crontab?: ZeropsCrontabEntry[];
+}
+export interface ZeropsEnvReplace {
+    target: string[];
+    delimiter: string[];
+}
+/** Defines a health check. */
+export interface ZeropsHealthCheck {
+    /** Configures the health check to request a local URL using a http GET method. */
+    httpGet?: ZeropsHttpGetProbe;
+    /** Configures the health check to run a local command. */
+    exec?: ZeropsExecProbe;
+    /** Time until container fails after consecutive health check failures (reset by success). */
+    failureTimeout?: number;
+    /** Time until container is disconnected and becomes publicly unavailable. */
+    disconnectTimeout?: number;
+    /** Time until container is connected and becomes publicly available. */
+    recoveryTimeout?: number;
+    /** Time interval between health check attempts. */
+    execPeriod?: number;
+}
+export interface ZeropsRouting {
+    root?: string;
+    /**
+     * Content of default Access-Control headers (Allow-Origin, Allow-Methods, Allow-Headers and Expose-Headers), e.g. "'*'
+     * always"
+     */
+    cors?: string;
+    redirects?: ZeropsRoutingRedirect[];
+    headers?: ZeropsRoutingHeader[];
+}
+export interface ZeropsRoutingRedirect {
+    /**
+     * Relative or an absolute (defined by with http://) path to be matched against request location. May contain * at the end
+     * for regex.
+     */
+    from: string;
+    /** Relative or an absolute (defined by with http://) path to redirect user to. */
+    to: string;
+    /**
+     * Which HTTP status code to use for the redirect. If not set, and To and From are relative, an internal/masked redirect
+     * will be used.
+     */
+    status?: number;
+    /**
+     * Whether part of the path after From should be preserved. Used to forward contents of one directory to another in
+     * non-masked redirects.
+     */
+    preservePath?: boolean;
+    /** Whether query parameters should be preserved. Used in non-masked redirects. */
+    preserveQuery?: boolean;
+}
+export interface ZeropsRoutingHeader {
+    /** Relative path to be matched against request location. May contain * at the end for prefix-based match. */
+    for: string;
+    /** Header name as Key and raw content as Value, e.g. "Access-Control-Allow-Origin": "'*' always" */
+    values: Record<string, string>;
+}
+export interface ZeropsPort {
+    /** Defines the protocol. Allowed values are TCP or UDP. Default value is TCP. */
+    protocol?: string;
+    /**
+     * Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for
+     * internal Zerops systems.
+     */
+    port: number;
+    description?: string;
+    /**
+     * Set to true if a web server is running on the port. Zerops uses this information for the configuration of public access.
+     * True is available only in combination with the TCP protocol. Default value is false.
+     */
+    httpSupport?: boolean;
+}
+export interface ZeropsStartCommand {
+    name?: string;
+    command: string;
+    workingDir?: string;
+    /** Defines one or more commands to be run each time a new runtime container is started or a container is restarted. */
+    initCommands?: string[];
+}
+export interface ZeropsCrontabEntry {
+    /** Defines when the cron job runs in standard cron format. */
+    timing: string;
+    /** Specifies the shell command to run at the scheduled time. */
+    command: string;
+    /** The directory where the command will be executed (default: /var/www) */
+    workingDir?: string;
+    /** If set to true, the job runs on all containers; otherwise, it runs on a single container (default: false) */
+    allContainers: boolean;
+}

package/types/src/service-names.d.ts

@@ -0,0 +1,4 @@
+/** Deterministic app prefix for services placed in a shared Zerops namespace. */
+export declare const zeropsSharedServicePrefix: (appId: string) => string;
+/** Build one app-owned service hostname for a shared namespace. */
+export declare const zeropsSharedServiceHostname: (appId: string, localService: string) => string;

package/types/src/service-references.d.ts

@@ -0,0 +1,13 @@
+/** Hosts named by cross-service references in `text`, deduplicated, in order of first appearance. */
+export declare function serviceReferenceHosts(text: string): string[];
+/** The hosts a service of this app may reference: its own declared hostnames plus the namespace's shared services. */
+export declare function allowedReferenceHosts(ownHostnames: readonly string[]): ReadonlySet<string>;
+/** The first referenced host outside `allowed`, or null when every reference stays inside the app. */
+export declare function foreignReferenceHost(text: string, allowed: ReadonlySet<string>): string | null;
+/**
+ * The first reference in `text` to a service variable only the platform may reference, or null. The key is compared
+ * without case, because whether Zerops resolves one case-insensitively is not measured.
+ */
+export declare function platformOnlyServiceReference(text: string): string | null;
+/** Refuse an application value that references a platform-only service variable, naming only the reference. */
+export declare function assertNoPlatformOnlyReference(text: string): void;

package/types/src/source/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_ID_LENGTH = 128;
+export declare const SHA256_PATTERN: RegExp;
+export declare const COMMIT_SHA_PATTERN: RegExp;
+export declare const ID_PATTERN: RegExp;
+export declare const GITHUB_OWNER_PATTERN: RegExp;
+export declare const GITHUB_REPOSITORY_PATTERN: RegExp;

package/types/src/source/port.d.ts

@@ -0,0 +1,60 @@
+import type { ZeropsSourceRepository } from './types';
+/** A private source names its connection; an installation id alone never selects a credential (ADR-0029). */
+export interface ZeropsSourcePrivateBinding {
+    readonly connectionId: string;
+    readonly installationId: number;
+}
+export interface ZeropsSourceResolveInput {
+    readonly repository: ZeropsSourceRepository;
+    readonly requestedRef: string;
+    readonly expectedCommitSha?: string;
+    readonly privateBinding?: ZeropsSourcePrivateBinding;
+    readonly descriptorSha256: string;
+    readonly signal: AbortSignal;
+}
+export interface ZeropsSourceResolution {
+    readonly commitSha: string;
+    readonly descriptorSha256: string;
+}
+/** ADR-0045: the one generated data file a platform archive carries beside the exact commit, at a path the commit lacks. */
+export interface ZeropsSourceDataFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** ADR-0045: platform archives are anonymous, tree-prechecked, keep relative symlinks. */
+export type ZeropsSourceArchive = {
+    readonly kind: 'application';
+    readonly privateBinding?: ZeropsSourcePrivateBinding;
+} | {
+    readonly kind: 'platform';
+    readonly dataFile?: ZeropsSourceDataFile;
+};
+export interface ZeropsSourceUploadInput {
+    readonly repository: ZeropsSourceRepository;
+    readonly commitSha: string;
+    readonly descriptorSha256: string;
+    readonly archive: ZeropsSourceArchive;
+    /** A credential in transit: never logged, persisted, or returned in an error. */
+    readonly uploadUrl: string;
+    readonly signal: AbortSignal;
+}
+export interface ZeropsSourceUploadResult {
+    readonly commitSha: string;
+    readonly descriptorSha256: string;
+    /** The sha256 of the data file the archive carried; absent without one. */
+    readonly dataFileSha256?: string;
+    readonly entryCount: number;
+    readonly expandedBytes: number;
+}
+/** The GitHub source the Zerops composition injects; Control implements it in process. Callers verify what it returns. */
+export interface ZeropsSourcePort {
+    resolve(input: ZeropsSourceResolveInput): Promise<ZeropsSourceResolution>;
+    upload(input: ZeropsSourceUploadInput): Promise<ZeropsSourceUploadResult>;
+}
+/**
+ * The source refused a read for GitHub's rate limit. The read succeeds again once the limit resets, so a namespace
+ * mutation that hits it stays retryable. The message is the user's: whose limit, when it resets, how to avoid it.
+ */
+export declare class ZeropsSourceRateLimitedError extends Error {
+    constructor(message: string);
+}

package/types/src/source/types.d.ts

@@ -0,0 +1,4 @@
+export interface ZeropsSourceRepository {
+    owner: string;
+    name: string;
+}

package/types/src/source/validation.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { ZeropsSourceRepository } from './types';
+export declare function parseSourceWire<T>(schema: z.ZodType<T, z.ZodTypeDef, unknown>, value: unknown, label: string): T;
+export declare const identifierSchema: z.ZodString;
+export declare const commitShaSchema: z.ZodString;
+export declare const sha256Schema: z.ZodString;
+export declare const repositorySchema: z.ZodObject<{
+    owner: z.ZodString;
+    name: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    owner: string;
+}, {
+    name: string;
+    owner: string;
+}>;
+export declare const rejectExplicitUndefined: (value: object, context: z.RefinementCtx) => void;
+export declare const isZeropsUploadDestination: (value: string) => boolean;
+export declare function normalizeZeropsSourceRepository(repoUrl: string): ZeropsSourceRepository;

package/types/src/source.d.ts

@@ -0,0 +1,2 @@
+export type { ZeropsSourceRepository } from './source/types';
+export { isZeropsUploadDestination, normalizeZeropsSourceRepository } from './source/validation';