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

package/types/src/installation/deploy.d.ts

@@ -0,0 +1,96 @@
+import type { SchemaReconciler } from '@fabrika/provider-contract';
+import { type Sleeper, type ZeropsApi, type ZeropsServiceEnv } from '../index';
+import { type CheckerPublication } from './checker-release';
+import type { PlatformDeployInput } from './deploy-options';
+import { type PlatformSourcePreparer } from './installation-source';
+import type { DeployLog } from './log';
+import type { PreparedPlatformSource } from './platform-source';
+import { type PlatformUploadFetch } from './platform-upload';
+/**
+ * The four services this command touches, in the order it RESOLVES and WRITES them.
+ *
+ * It is no longer the order they are deployed in — that is `PLATFORM_CONCURRENT_DEPLOY` followed by
+ * `PLATFORM_SEQUENTIAL_DEPLOY`, and the two stages concatenate back to this list (pinned by
+ * `deploy-order.test.ts` in `@fabrika/platform-artifacts`). What this list still decides is which services must exist
+ * and which environment is written, both of which happen for ALL FOUR before any of them is deployed.
+ *
+ * Each name is a service hostname in the topology AND the `zerops.yaml` setup name the pipeline
+ * selects — the platform's own "setup name defaults to the hostname" rule.
+ * `deploy-order.test.ts` in `@fabrika/platform-artifacts` pins both against the declarations that own them.
+ */
+export declare const PLATFORM_DEPLOY_ORDER: readonly ["iam", "operations", "proxy", "control"];
+export type PlatformDeployService = (typeof PLATFORM_DEPLOY_ORDER)[number];
+/**
+ * The two services built AT ONCE, because nothing orders them against each other.
+ *
+ * Neither calls a sibling at boot: IAM holds no sibling origin at all, and Operations only
+ * CONSTRUCTS its IAM client (the first request is the first call). Each readiness gate hits the
+ * service's own `/healthz`, and no deploy-written variable of one is read by another's BUILD — the
+ * only build-time read on the whole path is the proxy reading its own manifest. So the order among them was arbitrary, and paying for it sequentially cost about 3 min 45 s
+ * of the ~9 min 35 s a warm five-service roll took (two measured runs, 2026-08-21).
+ *
+ * What is NOT arbitrary stays: every environment write happens before any of these starts, the proxy
+ * is deployed after both, and control after the proxy (ADR-0022 — the enforcement point ahead of
+ * the service whose table just widened). `deploy-order.test.ts` in `@fabrika/platform-artifacts` and
+ * `__tests__/deploy.test.ts` fail if that sequence changes.
+ */
+export declare const PLATFORM_CONCURRENT_DEPLOY: readonly ["iam", "operations"];
+/** What is deployed after the concurrent stage, one at a time and in this order. */
+export declare const PLATFORM_SEQUENTIAL_DEPLOY: readonly ["proxy", "control"];
+/** The proxy's hostname. The only publicly routed service, and the one that carries the manifest. */
+export declare const PLATFORM_PROXY_SERVICE = "proxy";
+/**
+ * What deploying ONE service needs. Narrower than the whole command's collaborators so the bring-up
+ * (`install.ts`), which deploys the proxy alone before any manifest exists, can reuse `deployPlatformService`
+ * without inventing an IAM reconciler it has no use for.
+ */
+export interface PlatformServiceDeployCollaborators {
+    readonly uploadFetch: PlatformUploadFetch;
+    readonly api: ZeropsApi;
+    readonly sleep: Sleeper;
+    readonly log: DeployLog;
+    readonly signal: AbortSignal;
+}
+/** Everything `deployPlatform` reaches the outside world through. */
+export interface PlatformDeployCollaborators extends PlatformServiceDeployCollaborators {
+    readonly prepareSource: PlatformSourcePreparer;
+    readonly checkerPublished: CheckerPublication;
+    readonly reconcileSchema: SchemaReconciler;
+}
+/** The prepared snapshot shared by every build in an installation run. */
+export interface PlatformServiceDeployInput {
+    readonly source: PreparedPlatformSource;
+    readonly dryRun: boolean;
+    /** The proxy's manifest, which its archive carries as the one data file (ADR-0045); the proxy is refused without it. */
+    readonly proxyManifest?: string;
+}
+/** One resolved platform service. */
+export interface ResolvedService {
+    readonly hostname: PlatformDeployService;
+    readonly id: string;
+}
+export declare const serviceOf: (services: ReadonlyMap<PlatformDeployService, ResolvedService>, hostname: PlatformDeployService) => ResolvedService;
+/** One service's environment by key. A sensitive record carries no value. Values are never logged. */
+export type LiveServiceEnv = ReadonlyMap<string, ZeropsServiceEnv>;
+/** Read one service's environment by key. */
+export declare const readServiceEnv: (serviceId: string, { api, signal }: Pick<PlatformServiceDeployCollaborators, "api" | "signal">) => Promise<LiveServiceEnv>;
+/**
+ * Deploy ONE service and wait for it to become the active version.
+ *
+ * A failed deploy throws, which stops the sequence: the platform keeps the previous version serving
+ * (`deploy.readinessCheck` is a real gate, live-verified), so a failure here leaves the installation
+ * consistent — old code behind the manifest that was written for it.
+ *
+ * Exported for the BRING-UP, which builds the proxy on its own before any manifest exists so that the
+ * service publishes the HTTP ports its public hostnames are named after (`install.ts`, pass 1). That is
+ * one service, not an order — the order below stays this file's.
+ */
+export declare const deployPlatformService: (service: ResolvedService, input: PlatformServiceDeployInput, collaborators: PlatformServiceDeployCollaborators) => Promise<void>;
+/**
+ * Bring one Zerops platform installation to this checkout, unattended.
+ *
+ * Every step is idempotent and the whole sequence fails closed: nothing is deployed until the manifest
+ * and the environment name have been applied, and nothing after a failed step runs.
+ */
+export declare const deployPlatform: (input: PlatformDeployInput, collaborators: PlatformDeployCollaborators) => Promise<void>;
+export declare const deployPreparedPlatform: (input: PlatformDeployInput, collaborators: PlatformDeployCollaborators, source: PreparedPlatformSource) => Promise<void>;

package/types/src/installation/generated/platform-console-schema.d.ts

@@ -0,0 +1,2 @@
+import type { AppSchema } from '@fabrika/auth-core';
+export declare const PLATFORM_CONSOLE_APP_SCHEMA: AppSchema;

package/types/src/installation/generated/platform-proxy-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { PlatformProxyManifestTemplate } from '../proxy-manifest';
+export declare const PLATFORM_PROXY_MANIFEST_TEMPLATE: PlatformProxyManifestTemplate;

package/types/src/installation/hosts.d.ts

@@ -0,0 +1,38 @@
+import type { PlatformProxyService } from './proxy-manifest';
+/** The public hostname of each platform service, without a scheme and without a port. */
+export type PlatformHosts = Readonly<Record<PlatformProxyService, string>>;
+/** Everything the deploy needs to know about where this installation answers. */
+export interface PlatformPlacement {
+    readonly hosts: PlatformHosts;
+    /** The scheme the BROWSER speaks. Configuration, never a header — see `ProxyApp.scheme`. */
+    readonly scheme: 'http' | 'https';
+    /**
+     * Whether the proxy's public entry point is Zerops' generated subdomain. True only on the derived
+     * path: a custom-domain installation must not additionally publish a `.zerops.app` address.
+     */
+    readonly zeropsSubdomain: boolean;
+}
+/** The Zerops variable naming one URL per published HTTP port. READ_ONLY, written by the platform. */
+export declare const ZEROPS_SUBDOMAIN_VARIABLE = "zeropsSubdomain";
+/**
+ * Map the proxy's generated subdomains by the listener port each one fronts.
+ *
+ * The host form is `<hostname>-<hash>-<port>.<region>.zerops.app`, one line per HTTP port. Read as
+ * URLs rather than by splitting on `-`, so a hostname that itself contains a digit-suffixed segment
+ * cannot be misread: the port is the trailing `-<digits>` of the FIRST label only.
+ */
+export declare const parseZeropsSubdomains: (value: string) => Map<number, string>;
+/** One platform app's listener, as the committed template assigns it. */
+export interface PlatformListener {
+    readonly service: PlatformProxyService;
+    readonly port: number;
+}
+/**
+ * Bind every platform service to the generated subdomain of its listener.
+ *
+ * Throws naming every port it could not find, because the alternative — writing a manifest with a
+ * guessed or missing host — is a proxy that fronts nothing at an address the console then bounces to.
+ */
+export declare const derivePlatformHosts: (subdomains: string, listeners: readonly PlatformListener[]) => PlatformHosts;
+/** `https://<host>` — the origin a browser, a token's `iss` and a return-origin registry all use. */
+export declare const platformOrigin: (scheme: "http" | "https", host: string) => string;

package/types/src/installation/index.d.ts

@@ -0,0 +1,9 @@
+import type { InstallationCli } from '@fabrika/provider-contract/installation';
+export { PLATFORM_CONCURRENT_DEPLOY, PLATFORM_DEPLOY_ORDER, PLATFORM_PROXY_SERVICE, PLATFORM_SEQUENTIAL_DEPLOY } from './deploy';
+export { PLATFORM_CONSOLE_APP_SCHEMA } from './generated/platform-console-schema';
+export { PLATFORM_PROXY_MANIFEST_TEMPLATE } from './generated/platform-proxy-manifest';
+export { type IamOAuthConfig, type McpClient, parseMcpClientsJson, platformIamOAuthConfig } from './mcp';
+export { type PlatformOAuthResourceTemplate, type PlatformProxyApp, platformProxyAppFor, type PlatformProxyComposition, type PlatformProxyManifest, type PlatformProxyManifestTemplate, type PlatformProxyPlacement, type PlatformProxyService, platformServiceTableDigest, resolvePlatformProxyManifest, } from './proxy-manifest';
+/** The operator's guide of this release, shipped beside this module. */
+export declare const readInstallationGuide: () => Promise<string>;
+export declare const installationCli: InstallationCli;

package/types/src/installation/init-options.d.ts

@@ -0,0 +1,38 @@
+import { type CommandEnv } from '@fabrika/installation-init';
+/** Every input `runInit` takes from the operator. */
+export interface InitInput {
+    /** Names the GitHub Environment, the default repository and the local checkout directory. */
+    readonly installation: string;
+    readonly repo: string;
+    /** The sidecar's local checkout: `--checkout`, or `fabrika-zerops-<installation>` in the working directory. */
+    readonly checkoutDir: string;
+    /** The published fabrika-platform tag the sidecar pins in `fabrika.ref`. */
+    readonly fabrikaRef: string;
+    readonly projectId: string;
+    /** The name this installation calls itself — written to every service as `ENVIRONMENT`. */
+    readonly environmentName: string;
+    /** All three or none: none derives them from the proxy's Zerops subdomains. */
+    readonly hosts?: {
+        readonly iam: string;
+        readonly control: string;
+        readonly operations: string;
+    };
+    /** Region API base, when the installation is not on the default one. */
+    readonly apiBaseUrl?: string;
+    /** The Zerops INTEGRATION token `platform install` minted. Environment only. */
+    readonly accessToken: string;
+    /** The `px_` key this installation's IAM was seeded with. Environment only. */
+    readonly provisioningKey: string;
+    /** `--yes`: answer every confirmation yes. */
+    readonly unattended: boolean;
+}
+/**
+ * The installation's environment name, refused when it claims to be local.
+ *
+ * The same refusal the services enforce at boot: `local` is the value `localDevLogin`, the ephemeral
+ * signing key and the credential-less caller path are all gated on, and a deployed installation is
+ * never a loopback address.
+ */
+export declare const checkedEnvironmentName: (declared: string) => string;
+/** Parse the command's arguments and environment into the one input `runInit` takes. */
+export declare const parseInitArgs: (argv: readonly string[], env: CommandEnv, cwd?: string) => InitInput;

package/types/src/installation/init.d.ts

@@ -0,0 +1,60 @@
+import { type Confirmations, type EnvironmentConfig, type SidecarScaffoldInput, type SidecarScaffoldResult } from '@fabrika/installation-init';
+import { type ZeropsApi } from '../index';
+import type { InitInput } from './init-options';
+import type { InitLog } from './log';
+/** Everything `runInit` does outside the operator's own disk. Every one of them is confirmed first. */
+export interface InitEffects {
+    /** Only decides how the scaffold confirmation is phrased; the scaffold itself re-reads it. */
+    repositoryExists(repo: string): Promise<boolean>;
+    scaffold(input: SidecarScaffoldInput): Promise<SidecarScaffoldResult>;
+    configureEnvironment(config: EnvironmentConfig): Promise<void>;
+    triggerWorkflow(repo: string): Promise<void>;
+    /** Read one Zerops project's name — the cheapest proof that the token and the project id agree. */
+    describeProject(input: {
+        projectId: string;
+        accessToken: string;
+        apiBaseUrl?: string;
+    }): Promise<string>;
+    inspectPlatform(input: InspectPlatformInput): Promise<PlatformInspection>;
+}
+export interface InitCollaborators {
+    readonly log: InitLog;
+    readonly prompts: Confirmations;
+    readonly effects: InitEffects;
+}
+/** Where this installation answers, as far as `init` needs to know it. */
+interface Placement {
+    readonly hosts?: {
+        readonly iam: string;
+        readonly control: string;
+        readonly operations: string;
+    };
+}
+export interface InspectPlatformInput {
+    readonly projectId: string;
+    readonly accessToken: string;
+    readonly apiBaseUrl?: string;
+}
+/** What `init` reads off the live installation to print origins it can verify. Values are never logged. */
+export interface PlatformInspection {
+    readonly controlEnv: ReadonlyMap<string, string>;
+    readonly proxyEnv: ReadonlyMap<string, string>;
+    readonly proxyPublished: boolean;
+}
+/** Read `control` and `proxy` without writing anything. */
+export declare const inspectPlatform: (projectId: string, api: ZeropsApi, signal: AbortSignal) => Promise<PlatformInspection>;
+/**
+ * IAM's PUBLIC origin as the installation itself records it, or nothing when init would have to guess.
+ *
+ * `platform install` writes it to `control` as `FABRIKA_IAM_ISSUER`, so this reads the live value
+ * rather than re-deriving one — and refuses it when the operator named a different IAM host, because
+ * a printed origin an operator then pastes into `FABRIKA_IAM_RPC_URL` must be the one that answers.
+ */
+export declare const platformIamOrigin: (placement: Placement, platform: PlatformInspection) => string | undefined;
+/** Return a verified live console URL, or no URL when init would have to guess. */
+export declare const sourceConnectionSettingsUrl: (placement: Placement, platform: PlatformInspection) => string | undefined;
+/** Run the whole thing for `<installation>`. */
+export declare const runInit: (input: InitInput, collaborators: InitCollaborators) => Promise<void>;
+/** The real collaborators: a TTY, `gh`, git, and one read of the Zerops API. */
+export declare const consoleInitCollaborators: (input: InitInput) => InitCollaborators;
+export {};

package/types/src/installation/install-collaborators.d.ts

@@ -0,0 +1,24 @@
+import type { Confirmations } from '@fabrika/installation-init';
+import type { SchemaReconciler } from '@fabrika/provider-contract';
+import type { Sleeper, ZeropsApi } from '../index';
+import type { CheckerPublication } from './checker-release';
+import type { PlatformSourcePreparer } from './installation-source';
+import type { InitLog } from './log';
+import type { PlatformUploadFetch } from './platform-upload';
+/** The one question this command asks. Injected so the flow can be exercised without a TTY. */
+export type InstallPrompts = Confirmations;
+/** Everything `runInstall` reaches the outside world through. */
+export interface InstallCollaborators {
+    readonly prepareSource: PlatformSourcePreparer;
+    readonly checkerPublished: CheckerPublication;
+    readonly uploadFetch: PlatformUploadFetch;
+    readonly api: ZeropsApi;
+    readonly reconcileSchema: SchemaReconciler;
+    readonly sleep: Sleeper;
+    readonly log: InitLog;
+    readonly prompts: InstallPrompts;
+    readonly signal: AbortSignal;
+    /** Create the local secrets file (`--secrets-file`) with this text. Never logged. */
+    readonly storeSecrets: (text: string) => Promise<void>;
+}
+export declare const assertRunning: (signal: AbortSignal) => void;

package/types/src/installation/install-environment.d.ts

@@ -0,0 +1,70 @@
+import type { InstallationEmail } from '@fabrika/installation-init';
+import type { ZeropsNamespaceProxySource } from '../index';
+import type { PlatformDeployService, ResolvedService } from './deploy';
+import { type PlatformHosts } from './hosts';
+import { type InstallCollaborators } from './install-collaborators';
+import type { InstallationSecrets } from './secrets';
+import type { PlatformTier } from './topology/topology';
+/** The private address the proxy dials IAM at inside the project, and pass 1's placeholder issuer. */
+export declare const PRIVATE_IAM_UPSTREAM = "iam:3000";
+/**
+ * The three variables pass 1 writes on the proxy, and nothing else.
+ *
+ * `FABRIKA_IAM_ISSUER` is the private address rather than the public issuer because the public one is not known
+ * yet; `deployPlatform` corrects it in pass 2, before the manifest it belongs to is applied. The pass-1 manifest is
+ * `PASS_ONE_PROXY_MANIFEST`, which the proxy's archive carries.
+ */
+export declare const passOneProxyEnv: (secrets: InstallationSecrets) => ReadonlyMap<string, string>;
+/** EMPTY on purpose: the only legal document before the hosts exist. The proxy comes up answering 404. */
+export declare const PASS_ONE_PROXY_MANIFEST: string;
+/** What `installationServiceEnv` needs. Everything in it is settled before the first write. */
+export interface InstallationEnvInput {
+    readonly environment: string;
+    readonly tier: PlatformTier;
+    readonly scheme: 'http' | 'https';
+    readonly hosts: PlatformHosts;
+    readonly clientId: string;
+    readonly proxySource: ZeropsNamespaceProxySource;
+    readonly apiBaseUrl?: string;
+    readonly secrets: InstallationSecrets;
+    /** The Zerops integration token minted for the control plane. Never logged, never printed. */
+    readonly zeropsAccessToken: string;
+    /** IAM sends its own mail with it, and Control hands it to applications whose job declares `mailer: 'installation'`. */
+    readonly email: InstallationEmail;
+}
+/**
+ * EVERY variable this command places, per service.
+ *
+ * Pure, and exported, because the matrix is the thing most worth pinning: a name that is right on
+ * Cloudflare and wrong on Bun is a silent no-op rather than a failure. Two spelling rules run through
+ * it, both verified against the runtimes rather than assumed:
+ *
+ *   • IAM's Bun runtime reads `ISSUER` and `ENVIRONMENT` UNPREFIXED and everything else with the
+ *     `FABRIKA_IAM_` prefix (`packages/iam/src/node/runtime.ts`). The prefixed spellings below are the
+ *     ones that file actually reads; the unprefixed ones are the ones it actually reads too.
+ *   • No key any service declares in its own `zerops.yaml` appears here — `PORT`,
+ *     `FABRIKA_IAM_RPC_URL`, `FABRIKA_OPERATIONS_URL`, `FABRIKA_CONTROL_ASSETS_DIR`,
+ *     `FABRIKA_CONTROL_URL`, `FABRIKA_PROXY_MANIFEST`, `FABRIKA_PROXY_PORT`. The env API refuses those
+ *     (`provider-zerops/src/api.ts`), because the conflict cannot be resolved to a record id.
+ *
+ * The proxy manifest is deliberately absent: pass 1 writes an empty one and `deployPlatform` owns the
+ * real one, in the same run as the code it describes (ADR-0027).
+ */
+export declare const installationServiceEnv: (input: InstallationEnvInput) => ReadonlyMap<PlatformDeployService, ReadonlyMap<string, string>>;
+/**
+ * The keys whose VALUE this command generates, per service.
+ *
+ * Their presence on a live service is what "this project already holds an installation" means, and it is
+ * checked by KEY only — a value is never read back for comparison. `__tests__/install.test.ts` pins this
+ * against the matrix above, so a new generated secret cannot be added without appearing here.
+ */
+export declare const GENERATED_SECRET_KEYS: ReadonlyMap<PlatformDeployService, readonly string[]>;
+/**
+ * Write a set of variables, reporting the KEYS — never a value, not even in a debug line.
+ *
+ * Write-first and unconditional: a generated secret cannot be read back to compare, and `PUT
+ * /user-data/{id}` replaces in place, so a repeat costs a call and nothing else. Exactly the `sensitive`
+ * keys are written sensitive (the generated secrets and the operator's mail credentials); everything else
+ * stays readable, because `platform deploy` compares and merges it later.
+ */
+export declare const writeServiceEnv: (service: ResolvedService, desired: ReadonlyMap<string, string>, { api, log, signal }: InstallCollaborators, sensitive: ReadonlySet<string>) => Promise<void>;

package/types/src/installation/install-options.d.ts

@@ -0,0 +1,49 @@
+import { type InstallationEmail } from '@fabrika/installation-init';
+import type { PlatformTier } from './topology/topology';
+/**
+ * Where the installation's project comes from.
+ *
+ * A UNION rather than an optional id beside a boolean, because the two mistakes worth making
+ * unrepresentable are "neither" and "both": the parser is the only place that can tell them apart, and
+ * downstream code must not have to ask a second time.
+ */
+export type InstallProjectSource = 
+/** One the operator created, empty, by hand. */
+{
+    readonly kind: 'existing';
+    readonly projectId: string;
+}
+/** One this command creates, from the same declaration the provisioning import is compiled from. */
+ | {
+    readonly kind: 'create';
+    readonly projectName: string;
+};
+/** Every input `runInstall` takes from the operator. */
+export interface PlatformInstallInput {
+    /** The project this installation is brought up in — named, or created here. */
+    readonly project: InstallProjectSource;
+    /** The client the project belongs to — required, because the control plane's token is minted on it. */
+    readonly clientId: string;
+    /** Zerops personal access token. Environment only. */
+    readonly accessToken: string;
+    /** Region API base, when the installation is not on the default one. */
+    readonly apiBaseUrl?: string;
+    /** The name this installation calls itself — written to every platform service as `ENVIRONMENT`. */
+    readonly environment: string;
+    /** The scheme a browser speaks to this installation. */
+    readonly scheme: 'http' | 'https';
+    readonly sourceDir: string;
+    /** Where every credential this run creates is written, mode 0600, before the first is placed. */
+    readonly secretsFile: string;
+    readonly tier: PlatformTier;
+    /** The installation's mail transport, written on `iam` and `control`; `none` when the operator named no provider. */
+    readonly email: InstallationEmail;
+    /** `--yes`: answer every confirmation yes, for a bring-up with nobody at the keyboard. */
+    readonly unattended: boolean;
+}
+/** The canonical public release repository used for namespace proxy source identities. */
+export declare const FABRIKA_REPOSITORY_URL = "https://github.com/contember/fabrika-platform";
+/** `--create-project`: bring the project up too, instead of naming one the operator made. */
+export declare const CREATE_PROJECT_FLAG = "--create-project";
+/** Parse the command's arguments and environment into the one input `runInstall` takes. */
+export declare const parsePlatformInstallArgs: (argv: readonly string[], env: Record<string, string | undefined>) => PlatformInstallInput;

package/types/src/installation/install-project.d.ts

@@ -0,0 +1,13 @@
+import { type InstallCollaborators } from './install-collaborators';
+import type { PlatformInstallInput } from './install-options';
+/**
+ * Settle which project this run installs into — the operator's, or one created here.
+ *
+ * ONE confirmation either way, and both cover the token check and the read that follows: a created project is read back
+ * through the same `resolveProject` an operator-made one goes through, so the core package is checked on
+ * the project that will actually be installed into rather than on the document that asked for it.
+ */
+export declare const resolveInstallationProject: (input: PlatformInstallInput, environment: string, collaborators: InstallCollaborators) => Promise<{
+    id: string;
+    name: string;
+}>;

package/types/src/installation/install-provisioning.d.ts

@@ -0,0 +1,58 @@
+import { type ZeropsService, type ZeropsServiceStatus } from '../index';
+import { type PlatformDeployService, type ResolvedService } from './deploy';
+import { type InstallCollaborators } from './install-collaborators';
+import { type CompiledDocument, type CompiledTopology, type PlatformTier } from './topology/topology';
+/** The topology this command installs for a tier, so the project document and the services document cannot drift. */
+export declare const installationTopology: (environment: string, tier: PlatformTier) => CompiledTopology;
+/**
+ * The services-only provisioning document (WU2), compiled from the declaration the committed artifact
+ * is rendered from.
+ *
+ * Not read off disk: `gen:check` already proves
+ * `packages/platform-artifacts/generated/platform{,-light}.services.provision.zerops-import.yaml` is this exact text,
+ * and a value needs no filesystem in a published package.
+ */
+export declare const provisioningDocument: (environment: string, tier: PlatformTier) => CompiledDocument;
+/** One service of the provisioning document that the project already has. */
+interface ExistingService {
+    readonly id: string;
+    readonly status?: ZeropsServiceStatus;
+}
+/**
+ * Every service of the provisioning document that the project already has, by hostname.
+ *
+ * The STATUS travels with the id because `NEW` is not a service this command may touch: measured live,
+ * a service holds NO environment at all — not even the platform's generated keys — until it leaves that
+ * state, so both a read and a write against one are meaningless rather than merely early.
+ */
+export declare const existingServices: (declared: readonly string[], services: readonly ZeropsService[]) => Map<string, ExistingService>;
+/**
+ * Refuse a service the platform is still creating.
+ *
+ * Not a wait: this command holds no process id for a service some earlier run imported, and a sleep
+ * would be a guess at a number the platform never promised. The whole light topology settles in about a
+ * minute, so "run it again shortly" is both true and cheap.
+ */
+export declare const assertNoServiceIsBeingCreated: (existing: ReadonlyMap<string, ExistingService>) => void;
+/**
+ * Refuse a project that already carries this installation's generated secrets.
+ *
+ * By KEY, never by value. Re-running a bring-up would roll a fresh vault KEK — whose loss is
+ * unrecoverable by design — and fresh signing keys, invalidating every live token, so the safe answer to
+ * "was this already installed?" is to stop and say so. `platform deploy` is the command for an
+ * installation that exists.
+ */
+export declare const assertNotAlreadyInstalled: (existing: ReadonlyMap<string, ExistingService>, collaborators: InstallCollaborators) => Promise<void>;
+/**
+ * Import the topology, unless the project already has it.
+ *
+ * Three outcomes, and the middle one is the one that costs something to get wrong: re-applying a
+ * `startWithoutCode: true` document at a service that carries code activates an EMPTY app version and
+ * demotes the running one to `BACKUP` (`docs/reference/zerops-platform.md`). A PARTIAL set is refused
+ * rather than completed, because an import applies as one document and cannot skip the services that
+ * are already there.
+ */
+export declare const provision: (projectId: string, document: CompiledDocument, existing: ReadonlyMap<string, ExistingService>, collaborators: InstallCollaborators) => Promise<void>;
+/** Resolve the four platform services by hostname, naming the whole set that is missing rather than the first. */
+export declare const resolvePlatformServices: (projectId: string, { api, signal }: InstallCollaborators) => Promise<Map<PlatformDeployService, ResolvedService>>;
+export { serviceOf } from './deploy';

package/types/src/installation/install-secrets.d.ts

@@ -0,0 +1,30 @@
+import type { InstallationSecrets } from './secrets';
+/** `--secrets-file`: where the local copy goes. A new file, outside the source checkout. */
+export declare const SECRETS_FILE_FLAG = "--secrets-file";
+export declare const SECRETS_FILE_VARIABLE = "FABRIKA_PLATFORM_SECRETS_FILE";
+/**
+ * Settle the path before anything is contacted.
+ *
+ * Refused when it exists, because overwriting one would destroy another installation's only copy, and
+ * when it is inside the source checkout, where it would dirty the checkout `platform deploy` uploads
+ * and could be committed.
+ */
+export declare const checkedSecretsFilePath: (path: string, sourceDir: string) => string;
+/** What the file records beside the credentials, so it identifies its installation on its own. */
+export interface InstallationSecretsRecord {
+    readonly environment: string;
+    readonly projectId: string;
+    readonly clientId: string;
+    readonly secrets: InstallationSecrets;
+    /** The integration token minted for the control plane. */
+    readonly zeropsAccessToken: string;
+}
+/**
+ * The file's text: shell-sourceable assignments, named as the commands that read them name them.
+ *
+ * `FABRIKA_ZEROPS_ACCESS_TOKEN` is the INTEGRATION token, which is what `platform init` and
+ * `platform deploy` take; the personal token the install ran with is not written.
+ */
+export declare const renderSecretsFile: (record: InstallationSecretsRecord) => string;
+/** Create the file with mode 0600, failing rather than replacing one that appeared since the check. */
+export declare const writeSecretsFile: (path: string, text: string) => Promise<void>;

package/types/src/installation/install-token.d.ts

@@ -0,0 +1,10 @@
+import type { InstallCollaborators } from './install-collaborators';
+/**
+ * Refuse an integration token before anything is created.
+ *
+ * The install mints an integration token at step 4, and an integration token is refused that mint. Without
+ * this read the mistake costs a billed project and six imported services first.
+ */
+export declare const assertPersonalAccessToken: ({ api, signal }: InstallCollaborators) => Promise<void>;
+/** Translate the mint's refusal of an integration token into the fix and the way back into this project. */
+export declare const explainMintFailure: (failure: unknown, projectId: string) => unknown;

package/types/src/installation/install.d.ts

@@ -0,0 +1,23 @@
+import type { SchemaReconciler } from '@fabrika/provider-contract';
+import { type InstallCollaborators, type InstallPrompts } from './install-collaborators';
+import type { PlatformInstallInput } from './install-options';
+export type { InstallCollaborators, InstallPrompts } from './install-collaborators';
+export { GENERATED_SECRET_KEYS, type InstallationEnvInput, installationServiceEnv } from './install-environment';
+/**
+ * Bring up one Zerops platform installation, in a project the operator created empty or in one created
+ * here.
+ *
+ * Every step that leaves this machine is confirmed first, and declining any of them stops there with
+ * what to run instead. Nothing after the project step and before the import is a mutation, so a declined
+ * install leaves the project exactly as it was.
+ */
+export declare const runInstall: (input: PlatformInstallInput, collaborators: InstallCollaborators) => Promise<void>;
+/**
+ * The confirmations stand between a stray invocation and an installation: this command generates six
+ * credentials, mints a Zerops token on the account and deploys.
+ */
+export declare const installPrompts: (input: PlatformInstallInput, stdin: {
+    readonly isTTY?: boolean;
+}, announce: (line: string) => void) => InstallPrompts;
+/** The real collaborators: a TTY for the confirmations, the Zerops API, and IAM's own schema reconciler. */
+export declare const consoleInstallCollaborators: (input: PlatformInstallInput, reconcileSchema: SchemaReconciler) => InstallCollaborators;

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

@@ -0,0 +1,8 @@
+import { type ZeropsNamespaceProxySource } from '../index';
+import { type PreparedPlatformSource } from './platform-source';
+export type PlatformSourcePreparer = (sourceDir: string, signal: AbortSignal) => Promise<PreparedPlatformSource>;
+export declare const prepareInstallationSource: PlatformSourcePreparer;
+export declare const validateInstallationSetups: (source: PreparedPlatformSource, setups: readonly string[]) => void;
+export declare const FABRIKA_ZEROPS_PROXY_SOURCE_JSON = "FABRIKA_ZEROPS_PROXY_SOURCE_JSON";
+export declare const serializeNamespaceProxySource: (source: ZeropsNamespaceProxySource) => string;
+export declare const prepareNamespaceProxySource: (source: PreparedPlatformSource) => Promise<ZeropsNamespaceProxySource>;

package/types/src/installation/log.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Progress reporting for `fabrika platform deploy --provider=zerops` and for `platform init`.
+ *
+ * HARD RULE, the same one `@fabrika/installation-init`'s `log.ts` states: **nothing here ever
+ * prints a secret VALUE, and there is deliberately no helper that accepts one.** Callers may pass a
+ * variable NAME, a count, or a "✓ written" confirmation. The Zerops access token and the IAM
+ * provisioning key are the two credentials this command holds; neither has a formatting path.
+ *
+ * A caught error is never passed through here either — `ZeropsApiError` (`src/api/errors.ts`)
+ * already redacts the platform's message on the calls that carry a value, but a raw error from
+ * anywhere else may quote a URL with an embedded token. Log a short sentence, never an error object.
+ *
+ * Only INTERFACES and test doubles live here. The console bindings live with the flow that uses them,
+ * so nothing on the deploy path imports the interactive `platform init` machinery.
+ */
+/** Where the command's progress goes. Injected so a test can read the transcript instead of stdout. */
+export interface DeployLog {
+    /** A numbered stage of the sequence. */
+    step(title: string): void;
+    /** A detail line under the current stage. */
+    info(message: string): void;
+    /** Something the operator should notice but which does not stop the deploy. */
+    warn(message: string): void;
+}
+/** The real console log. Stateful only in its step counter. */
+export declare const consoleDeployLog: () => DeployLog;
+/** A log that records every line, for tests and for `--dry-run` assertions. */
+export declare const recordingDeployLog: () => DeployLog & {
+    readonly lines: readonly string[];
+};
+/**
+ * What `platform init` reports. Two lines more than a deploy: a confirmation of something that
+ * happened, and the boxed hand-off an operator must not scroll past.
+ */
+export interface InitLog extends DeployLog {
+    /** Something outward-facing succeeded. Names a key or a repository, never a value. */
+    ok(message: string): void;
+    /** A boxed OPERATOR ACTION — what to run when a confirmation was declined, or what is left to do. */
+    action(title: string, lines: readonly string[]): void;
+}
+/** A log that records every line, so a test can assert on the transcript — including what is NOT in it. */
+export declare const recordingInitLog: () => InitLog & {
+    readonly lines: readonly string[];
+};

package/types/src/installation/machine-key.d.ts

@@ -0,0 +1,19 @@
+/** What the calling verb knows about this installation. Both fields are omitted when it would guess. */
+export interface MachineKeyNextStep {
+    /** IAM's PUBLIC origin — the address `FABRIKA_IAM_RPC_URL` takes. */
+    readonly iamOrigin?: string;
+    /** The sidecar GitHub Environment that also holds the provisioning key, when its name is known. */
+    readonly sidecarEnvironment?: string;
+}
+/** The boxed hand-off's title. Exported so a test names it once. */
+export declare const MACHINE_KEY_NEXT_STEP_TITLE = "NEXT \u2014 mint a machine key for `fabrika control`";
+/** The command the block leads to, with the three flags `key issue` requires. */
+export declare const MACHINE_KEY_ISSUE_COMMAND = "fabrika control key issue --label=<name> --permissions=<a,b,c> --expires-in=<seconds>";
+/**
+ * The lines of the block, in the order an operator uses them.
+ *
+ * The origin is the one VALUE printed, because it is not a credential: it is where the installation
+ * answers, and the rebuild that motivated this block failed precisely because an operator guessed it.
+ * The two keys are named and located; a value for either would come from the environment anyway.
+ */
+export declare const machineKeyNextStepLines: (step?: MachineKeyNextStep) => readonly string[];

package/types/src/installation/mcp.d.ts

@@ -0,0 +1,18 @@
+import { type OAuthManagedClient, type OAuthResourceDto } from '@fabrika/iam-contract';
+import { type PlatformProxyComposition, type PlatformProxyManifestTemplate } from './proxy-manifest';
+/** One operator-registered MCP client: its CIMD identity, plus where IAM fetches it when that differs. */
+export interface McpClient extends OAuthManagedClient {
+    readonly metadataUrl?: string;
+}
+/** The document IAM parses from `FABRIKA_IAM_OAUTH_CONFIG`. */
+export interface IamOAuthConfig {
+    readonly clients: readonly McpClient[];
+    readonly resources: readonly OAuthResourceDto[];
+}
+/**
+ * Parse the operator's MCP client list — a JSON array. Anything malformed, an empty list or a repeated
+ * client id is refused here, before a deploy writes a value IAM would refuse to boot with.
+ */
+export declare const parseMcpClientsJson: (raw: string) => readonly McpClient[];
+/** IAM's OAuth configuration for one placed installation: the clients, and one resource per app that serves one. */
+export declare const platformIamOAuthConfig: (template: PlatformProxyManifestTemplate, composition: PlatformProxyComposition, clients: readonly McpClient[]) => IamOAuthConfig;