@fabrika/installation-init 0.8.2 → 0.9.0-cloudflare.2

package/src/service-environment.ts

@@ -0,0 +1,206 @@
+// The environment fabrika's four platform services read, as one installation's values.
+//
+// The variable NAMES are the services' own (`@fabrika/iam`'s `node/runtime.ts`, Control's and Operations'
+// configuration, the proxy's `readProxyEnv`), so they are the same on every cloud. What a provider supplies
+// is where a service's data lives — a DSN or the cloud's reference to one — and where the proxy dials IAM
+// privately; it adds the variables of its own cloud beside these and writes the result.
+//
+// IAM's Bun runtime reads `ISSUER` and `ENVIRONMENT` UNPREFIXED and everything else with the
+// `FABRIKA_IAM_` prefix. Both spellings below are the ones it actually reads.
+
+import { FABRIKA_SERVICE_TABLE_DIGEST, IAM_PROXY_SECRET_VARIABLE } from '@fabrika/auth-core'
+import { createHmac } from 'node:crypto'
+import type { InstallationEmail } from './email'
+import type { IamOAuthConfig } from './mcp'
+import { type PlatformHosts, platformOrigin } from './proxy-manifest'
+import type { InstallationSecrets } from './secrets'
+
+/** The four services an installation configures. Each is a service of the platform's own topology. */
+export type PlatformService = 'iam' | 'operations' | 'control' | 'proxy'
+
+/** Each service's variables, in the order they are written. */
+export type PlatformServiceEnvironment = Readonly<Record<PlatformService, ReadonlyMap<string, string>>>
+
+/** IAM's OAuth configuration for MCP clients (ADR-0049): written only when the installation enables MCP authoring. */
+export const IAM_OAUTH_CONFIG_VARIABLE = 'FABRIKA_IAM_OAUTH_CONFIG'
+
+/** An object store's coordinates, in the provider's own spelling (values or references to them). */
+export interface PlatformStorage {
+	readonly bucket: string
+	readonly accessKeyId: string
+	readonly secretAccessKey: string
+	readonly endpoint: string
+}
+
+/** Where each service's data lives. */
+export interface PlatformData {
+	readonly iamDatabase: string
+	readonly controlDatabase: string
+	readonly operationsDatabase: string
+	/** Control's run logs. */
+	readonly runLogs: PlatformStorage
+	/** Operations' artifacts and source maps. */
+	readonly operationsBlobs: PlatformStorage
+}
+
+/** Where the installation answers. Both the bring-up and every deploy derive their variables from these. */
+export interface PlatformPlacementInput {
+	readonly environment: string
+	readonly scheme: 'http' | 'https'
+	readonly hosts: PlatformHosts
+	/** The private address the platform proxy dials IAM at, which owns the session (`host:port`). */
+	readonly iamUpstream: string
+}
+
+/** What `installationServiceEnvironment` needs. Everything in it is settled before the first write. */
+export interface InstallationServiceInput extends PlatformPlacementInput {
+	readonly secrets: InstallationSecrets
+	readonly data: PlatformData
+	/** IAM sends its own mail with it, and Control hands it to applications whose job declares `mailer: 'installation'`. */
+	readonly email: InstallationEmail
+}
+
+/** Compared byte-for-byte against a token's `iss`, so it is the PUBLIC issuer, never the private upstream. */
+const proxySessionOwner = (input: PlatformPlacementInput): string =>
+	JSON.stringify({ issuer: platformOrigin(input.scheme, input.hosts.iam), upstream: input.iamUpstream })
+
+/**
+ * EVERY fabrika variable a bring-up places, per service.
+ *
+ * The proxy manifest is deliberately absent: the deploy owns it, in the same run as the code it
+ * describes (ADR-0027).
+ */
+export const installationServiceEnvironment = (input: InstallationServiceInput): PlatformServiceEnvironment => {
+	const { secrets, data } = input
+	const iamOrigin = platformOrigin(input.scheme, input.hosts.iam)
+	const operationsOrigin = platformOrigin(input.scheme, input.hosts.operations)
+	const email = input.email.kind === 'none' ? [] : [...input.email.variables]
+	return {
+		iam: new Map([
+			['FABRIKA_IAM_DATABASE_URL', data.iamDatabase],
+			['ENVIRONMENT', input.environment],
+			['ISSUER', iamOrigin],
+			// Password only, by decision: OIDC needs an identity provider the operator has not been
+			// asked for. Both are STATED because IAM's own defaults are the other way round — OIDC on,
+			// password off — and it refuses to boot with neither.
+			['FABRIKA_IAM_OIDC_ENABLED', 'false'],
+			['FABRIKA_IAM_PASSWORD_ENABLED', 'true'],
+			['FABRIKA_IAM_SIGNING_KEYS', secrets.signingKeys],
+			['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+			['FABRIKA_IAM_PROXY_KEY', secrets.proxyKey],
+			['FABRIKA_IAM_PROVISIONING_KEY', secrets.provisioningKey],
+			...email,
+		]),
+		operations: new Map([
+			['FABRIKA_OPERATIONS_DATABASE_URL', data.operationsDatabase],
+			['FABRIKA_OPERATIONS_BLOB_BUCKET', data.operationsBlobs.bucket],
+			['FABRIKA_OPERATIONS_BLOB_ACCESS_KEY_ID', data.operationsBlobs.accessKeyId],
+			['FABRIKA_OPERATIONS_BLOB_SECRET_ACCESS_KEY', data.operationsBlobs.secretAccessKey],
+			['FABRIKA_OPERATIONS_BLOB_ENDPOINT', data.operationsBlobs.endpoint],
+			['FABRIKA_OPERATIONS_PUBLIC_HOST', input.hosts.operations],
+			['ENVIRONMENT', input.environment],
+			['FABRIKA_IAM_ISSUER', iamOrigin],
+			['OPERATIONS_SYNC_KEY', secrets.operationsSyncKey],
+			['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+		]),
+		control: new Map([
+			['FABRIKA_CONTROL_DATABASE_URL', data.controlDatabase],
+			['ENVIRONMENT', input.environment],
+			// A bare HOST, not an origin: `controlPublicOrigin` accepts either.
+			['FABRIKA_CONTROL_DOMAIN', input.hosts.control],
+			['FABRIKA_IAM_ISSUER', iamOrigin],
+			['OPERATIONS_ARTIFACT_ORIGIN', operationsOrigin],
+			['FABRIKA_CONTROL_RUN_LOGS_BUCKET', data.runLogs.bucket],
+			['FABRIKA_CONTROL_RUN_LOGS_ACCESS_KEY_ID', data.runLogs.accessKeyId],
+			['FABRIKA_CONTROL_RUN_LOGS_SECRET_ACCESS_KEY', data.runLogs.secretAccessKey],
+			['FABRIKA_CONTROL_RUN_LOGS_ENDPOINT', data.runLogs.endpoint],
+			['FABRIKA_IAM_RPC_KEY', secrets.rpcKey],
+			['OPERATIONS_SYNC_KEY', secrets.operationsSyncKey],
+			['FABRIKA_CONTROL_VAULT_KEY', secrets.vaultKey],
+			['FABRIKA_IAM_PROVISIONING_KEY', secrets.provisioningKey],
+			...email,
+		]),
+		proxy: new Map([
+			['ENVIRONMENT', input.environment],
+			['FABRIKA_IAM_ISSUER', iamOrigin],
+			['FABRIKA_IAM_KEY', secrets.proxyKey],
+			['FABRIKA_PROXY_SESSION_OWNER_JSON', proxySessionOwner(input)],
+		]),
+	}
+}
+
+/**
+ * The fabrika variables whose VALUE a bring-up generates, per service.
+ *
+ * Their presence on a live service is what "this project already holds an installation" means, and they
+ * are written as credentials. A provider adds the names of its own that carry a generated value.
+ */
+export const INSTALLATION_SECRET_VARIABLES: Readonly<Record<PlatformService, readonly string[]>> = {
+	iam: ['FABRIKA_IAM_SIGNING_KEYS', 'FABRIKA_IAM_RPC_KEY', 'FABRIKA_IAM_PROXY_KEY', 'FABRIKA_IAM_PROVISIONING_KEY'],
+	operations: ['OPERATIONS_SYNC_KEY', 'FABRIKA_IAM_RPC_KEY'],
+	control: ['FABRIKA_IAM_RPC_KEY', 'OPERATIONS_SYNC_KEY', 'FABRIKA_CONTROL_VAULT_KEY', 'FABRIKA_IAM_PROVISIONING_KEY'],
+	proxy: ['FABRIKA_IAM_KEY'],
+}
+
+/**
+ * The secret the platform proxy sends IAM's route, so IAM honours the client address and request id only from the proxy
+ * (ADR-0022 rule 5). Derived from the provisioning key, which every deploy holds, so each deploy writes the same value
+ * and nothing stores or reads one back. Never from the proxy key: namespace proxies hold that one.
+ */
+export const deriveIamProxySecret = (provisioningKey: string): string =>
+	createHmac('sha256', provisioningKey).update('fabrika-installation-proxy-secret:iam').digest('hex')
+
+/** What a deploy derives the service environment from. */
+export interface DeployedServiceInput extends PlatformPlacementInput {
+	/** `FABRIKA_IAM_PROVISIONING_KEY`, which the IAM proxy secret is derived from. */
+	readonly provisioningKey: string
+	/** The digest of the console table the deploy's manifest publishes (`platformServiceTableDigest`). */
+	readonly controlTableDigest: string
+	/** Present only when the installation enables MCP authoring. */
+	readonly oauthConfig?: IamOAuthConfig
+}
+
+/**
+ * The per-installation configuration a deploy writes, derived from where the installation answers.
+ *
+ * IAM's OAuth configuration is present only when MCP authoring is enabled; without it the variable is left
+ * as it is, and the manifest — whose `/mcp` row then admits no OAuth token — is what turns MCP off.
+ */
+export const deployedServiceEnvironment = (input: DeployedServiceInput): PlatformServiceEnvironment => {
+	const iamOrigin = platformOrigin(input.scheme, input.hosts.iam)
+	const iamProxySecret = deriveIamProxySecret(input.provisioningKey)
+	const iam = new Map([
+		['ENVIRONMENT', input.environment],
+		// The `iss` of every minted token AND the OIDC redirect base, so it must be the address
+		// routed to the proxy in front of this service.
+		['ISSUER', iamOrigin],
+		[IAM_PROXY_SECRET_VARIABLE, iamProxySecret],
+	])
+	if (input.oauthConfig !== undefined) {
+		iam.set(IAM_OAUTH_CONFIG_VARIABLE, JSON.stringify(input.oauthConfig))
+	}
+	return {
+		iam,
+		operations: new Map([
+			['ENVIRONMENT', input.environment],
+			['FABRIKA_IAM_ISSUER', iamOrigin],
+			['FABRIKA_OPERATIONS_PUBLIC_HOST', input.hosts.operations],
+		]),
+		proxy: new Map([
+			['ENVIRONMENT', input.environment],
+			['FABRIKA_IAM_ISSUER', iamOrigin],
+			['FABRIKA_PROXY_SESSION_OWNER_JSON', proxySessionOwner(input)],
+			// Caddy sends it on the session owner's route.
+			[IAM_PROXY_SECRET_VARIABLE, iamProxySecret],
+		]),
+		control: new Map([
+			['ENVIRONMENT', input.environment],
+			['FABRIKA_IAM_ISSUER', iamOrigin],
+			// A bare host: `controlPublicOrigin` accepts either spelling.
+			['FABRIKA_CONTROL_DOMAIN', input.hosts.control],
+			// Control picks its own table, MCP or not, by this digest, and refuses to start under another.
+			[FABRIKA_SERVICE_TABLE_DIGEST, input.controlTableDigest],
+			['OPERATIONS_ARTIFACT_ORIGIN', platformOrigin(input.scheme, input.hosts.operations)],
+		]),
+	}
+}

package/types/src/admin.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The first administrator of a fresh installation — the admin-RPC calls that admit them, as mechanics
+ * rather than a script.
+ *
+ * `platform install` ends with a provisioning key and nobody who can sign in. What it takes to fix
+ * that is provider-neutral: which procedures, in which order, and what makes a second run change
+ * nothing. WHERE an installation's IAM answers, and how an operator names it, is the provider's own
+ * question and stays in its installation package.
+ *
+ * A trap a live bring-up found is encoded here rather than left to each caller: **the grant is
+ * CROSS-APP (`app: null`).** Grants filter to the calling app, so an `admin` grant scoped to the
+ * console's own app id leaves Delivery and Operations working while the Access plane refuses. IAM's
+ * own app id is not a registered app, so naming it would dangle instead.
+ *
+ * The enrollment URL is a CREDENTIAL IN TRANSIT. It is RETURNED, never logged: nothing in this module
+ * prints, and `log.ts` deliberately has no helper that takes a secret value.
+ */
+import { type InferRpcClient, type RpcFetch } from '@fabrika/app';
+import type { IamAdminRpcContract } from '@fabrika/iam-contract';
+/** The built-in cross-app role. It is the one role that carries `iam.admin`, which the Access plane checks. */
+export declare const ADMIN_ROLE_KEY = "admin";
+/** The typed admin surface, exactly as the console reaches it — one contract, so the two cannot drift. */
+export type IamAdminClient = InferRpcClient<IamAdminRpcContract>;
+/**
+ * The slice of that surface this flow calls, and nothing wider.
+ *
+ * `IamAdminClient` satisfies it, so the real client is passed straight in; a caller testing the flow
+ * stands up five procedures instead of the whole administration API.
+ */
+export interface FirstAdministratorApi {
+    readonly principals: Pick<IamAdminClient['principals'], 'get' | 'invite' | 'list'>;
+    readonly grants: Pick<IamAdminClient['grants'], 'create'>;
+    readonly passwords: Pick<IamAdminClient['passwords'], 'issueEnrollment'>;
+}
+export interface IamAdminConnection {
+    /** IAM's PUBLIC origin — the address the proxy fronts, e.g. `https://iam.example.com`. */
+    readonly origin: string;
+    /** The installation's `px_` provisioning key, sent as `Authorization: Bearer`. */
+    readonly provisioningKey: string;
+    /** Override `fetch` (tests). Defaults to the global one. */
+    readonly fetch?: RpcFetch;
+}
+/**
+ * A client for `<origin>/admin/rpc` authenticated by the provisioning key.
+ *
+ * Bearer AND NOTHING ELSE, which is what makes it work at all: IAM's cross-origin guard exempts a
+ * request carrying only `Authorization`, and refuses a credential-less one whatever the admin-origin
+ * registry holds (`iam/src/admin/router.ts`).
+ */
+export declare const createIamAdminClient: ({ origin, provisioningKey, fetch: fetcher }: IamAdminConnection) => IamAdminClient;
+export interface FirstAdministratorRequest {
+    /** The mailbox that identifies the human. Any spelling; IAM stores the normalized form. */
+    readonly email: string;
+    /**
+     * Issue a second enrollment URL when one is already outstanding. Default false, so a re-run prints
+     * nothing new — but an enrollment that expired unopened would otherwise be unrecoverable, because
+     * the only other way to issue one is a console nobody can sign in to yet.
+     */
+    readonly reissueEnrollment?: boolean;
+}
+/** What happened to the password enrollment. Only `issued` carries a URL, and only once. */
+export type EnrollmentOutcome = {
+    readonly state: 'issued';
+    readonly url: string;
+    readonly expiresAt: number;
+} | {
+    readonly state: 'emailed';
+    readonly email: string;
+    readonly expiresAt: number;
+} | {
+    readonly state: 'outstanding';
+} | {
+    readonly state: 'already-set';
+};
+export interface FirstAdministratorResult {
+    readonly principalId: string;
+    /** The normalized mailbox, as IAM holds it. */
+    readonly email: string;
+    readonly principal: 'invited' | 'existing';
+    readonly grant: 'created' | 'present';
+    readonly enrollment: EnrollmentOutcome;
+}
+/**
+ * Admit the first administrator, idempotently.
+ *
+ * Four states are reused rather than rewritten: an existing principal for this mailbox, an existing
+ * cross-app `admin` grant, an outstanding enrollment, and a password that is already set. A re-run
+ * therefore invites nobody twice, grants nothing twice and issues no second URL — and a run that loses
+ * the invite race to a concurrent one converges on the principal that won.
+ */
+export declare const ensureFirstAdministrator: (client: FirstAdministratorApi, request: FirstAdministratorRequest) => Promise<FirstAdministratorResult>;

package/types/src/checkout.d.ts

@@ -0,0 +1,9 @@
+/** `--checkout=<dir>`: where `platform init` keeps the sidecar repository's local checkout. */
+export declare const CHECKOUT_FLAG = "--checkout";
+/**
+ * The sidecar checkout directory: `--checkout`, or `defaultName` in the working directory.
+ *
+ * Refused inside another repository, where it would sit as an untracked nested repository that a
+ * blanket `git add` records as a gitlink.
+ */
+export declare const sidecarCheckoutDir: (explicit: string | undefined, defaultName: string, cwd?: string) => string;

package/types/src/confirmations.d.ts

@@ -0,0 +1,21 @@
+/** The one question `install` and `init` ask. Injected so a flow can be exercised without a TTY. */
+export interface Confirmations {
+    confirm(question: string, defaultYes?: boolean): Promise<boolean>;
+}
+/**
+ * The one way a confirming command runs with nobody watching it.
+ *
+ * Every confirmation defaults to yes, so a pipe carrying blank lines would answer all of them with
+ * nobody reading what they agree to — which is why saying yes unattended is a FLAG and never an
+ * inference: it makes the choice explicit, and it puts it in the shell history of whoever ran it.
+ */
+export declare const UNATTENDED_FLAG = "--yes";
+/**
+ * How a command's confirmations are answered — and the refusal when nothing can answer them.
+ *
+ * Unattended, each question is still printed with the answer it was given, so the run leaves the same
+ * record of what was agreed to that an interactive one does.
+ */
+export declare const confirmations: (unattended: boolean, stdin: {
+    readonly isTTY?: boolean;
+}, announce: (line: string) => void, whatItDoes: string) => Confirmations;

package/types/src/email.d.ts

@@ -0,0 +1,15 @@
+import { type EmailProviderRegistry } from '@fabrika/email';
+import { type CommandEnv } from './options';
+export type InstallationEmail = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'provider';
+    readonly variables: ReadonlyMap<string, string>;
+    readonly secretNames: ReadonlySet<string>;
+};
+export declare const EMAIL_FLAGS: readonly ["--email-provider", "--email-from", "--email-from-name"];
+/** Throws naming flags and variables, never a value. */
+export declare function readInstallationEmail(argv: readonly string[], env: CommandEnv, options: {
+    readonly registry: EmailProviderRegistry;
+    readonly required: boolean;
+}): InstallationEmail;

package/types/src/environment.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Write the collected configuration into the base repo's GitHub **Environment** (not repo-level), so the
+ * platform pipeline reads it per-environment. Secret VALUES go to `gh secret set --env` over STDIN (gh does
+ * the libsodium encryption; the value never hits argv or a log line); non-secret values go to
+ * `gh variable set --env --body`. The environment itself is created (idempotent PUT) first, carrying the
+ * deployment-branch policy that is the only thing an Environment buys over a repository secret — a policy
+ * that restricts nothing until `main` itself carries a branch-protection rule.
+ */
+import { type GhAttempt, type ProtectionOutcome } from './protection';
+import { type ShellAttempt, type ShellStep } from './shell';
+export interface EnvironmentConfig {
+    repo: string;
+    environment: string;
+    /** Secret name → value (written via `gh secret set`). */
+    secrets: Record<string, string>;
+    /** Variable name → value (written via `gh variable set`). */
+    vars: Record<string, string>;
+    /**
+     * Told once whether only a protected branch may use this Environment's secrets, so a provider's
+     * closing summary can restate it. A callback rather than a return value: both providers already
+     * bind this function through a `Promise<void>` collaborator.
+     */
+    onProtection?(outcome: ProtectionOutcome): void;
+}
+/** The child processes `configureEnvironment` drives. Replaced wholesale in tests. */
+export interface EnvironmentEffects {
+    attempt: GhAttempt;
+    run(step: ShellStep): Promise<void>;
+}
+/** Create the GitHub Environment and populate its secrets + variables. */
+export declare function configureEnvironment(config: EnvironmentConfig, effects?: EnvironmentEffects): Promise<void>;
+/** One reviewer in a PUT body: GitHub's GET nests the id under `reviewer`, its PUT wants it flat. */
+interface EnvironmentReviewer {
+    readonly type: string;
+    readonly id: number;
+}
+/** The protection rules a PUT must carry forward, read off `gh api repos/…/environments/<name>`. */
+export interface ExistingEnvironmentProtection {
+    readonly reviewers?: readonly EnvironmentReviewer[];
+    readonly wait_timer?: number;
+}
+/**
+ * Translate a GET's `protection_rules` into the shape a PUT takes. Anything unrecognised is dropped:
+ * a body GitHub rejects would cost the deployment-branch policy, which is what this write is for.
+ */
+export declare function existingEnvironmentProtection(result: ShellAttempt): ExistingEnvironmentProtection;
+/** Trigger the platform workflow (the real deploy runs in GitHub Actions). */
+export declare function triggerPlatformWorkflow(repo: string): Promise<void>;
+export {};

package/types/src/gh.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `gh` CLI helpers. The CLI shells out to `gh` for everything GitHub-side (repo create, secrets, the
+ * deploy trigger) rather than re-implementing the REST API + libsodium secret encryption — `gh` already
+ * does the encryption for `secret set`. These are the small probes shared across scaffold + environment.
+ */
+/** Is the `gh` CLI available + authenticated? `gh auth status` exits non-zero when not logged in. */
+export declare function hasGhCli(): Promise<boolean>;
+/** Does `<org>/<repo>` exist and is it visible to the current `gh` login? */
+export declare function ghRepoExists(repo: string): Promise<boolean>;

package/types/src/index.d.ts

@@ -0,0 +1,18 @@
+export { ADMIN_ROLE_KEY, createIamAdminClient, type EnrollmentOutcome, ensureFirstAdministrator, type FirstAdministratorApi, type FirstAdministratorRequest, type FirstAdministratorResult, type IamAdminClient, type IamAdminConnection, } from './admin';
+export { CHECKOUT_FLAG, sidecarCheckoutDir } from './checkout';
+export { type Confirmations, confirmations, UNATTENDED_FLAG } from './confirmations';
+export { EMAIL_FLAGS, type InstallationEmail, readInstallationEmail } from './email';
+export { configureEnvironment, type EnvironmentConfig, type EnvironmentEffects, type ExistingEnvironmentProtection, existingEnvironmentProtection, triggerPlatformWorkflow, } from './environment';
+export { ghRepoExists, hasGhCli } from './gh';
+export { action, detail, fail, info, ok, step, url, warn } from './log';
+export { type IamOAuthConfig, type McpClient, parseMcpClientsJson, platformIamOAuthConfig } from './mcp';
+export { type CommandEnv, describeArgument, readEnv, readFlag, requiredSetting, setting, shellWord } from './options';
+export { assertPinnedTag } from './pin';
+export { confirm } from './prompt';
+export { branchProtectionCommand, DEPLOYMENT_BRANCH_POLICY, environmentPolicyCommand, environmentReviewerCommand, type GhAttempt, isPlanLimited, PLAN_LIMITED, probeSidecarBranchProtection, type ProtectionOutcome, protectSidecarBranch, } from './protection';
+export { type PlatformHosts, type PlatformOAuthResourceTemplate, type PlatformOAuthScopeGrant, platformOrigin, type PlatformProxyApp, platformProxyAppFor, type PlatformProxyComposition, type PlatformProxyManifest, type PlatformProxyManifestTemplate, type PlatformProxyPlacement, type PlatformProxyService, platformServiceTableDigest, resolvePlatformProxyManifest, } from './proxy-manifest';
+export { INITIAL_SCAFFOLD_COMMIT_MESSAGE, REFRESH_SCAFFOLD_COMMIT_MESSAGE, scaffoldSidecarRepository, type SidecarScaffoldEffects, type SidecarScaffoldInput, type SidecarScaffoldResult, } from './scaffold';
+export { generateInstallationSecrets, generateSigningKeys, generateVaultKey, type InstallationSecrets, randomPxKey, randomSecret } from './secrets';
+export { checkedSecretsFilePath, renderSecretsFile, SECRETS_FILE_FLAG, SECRETS_FILE_VARIABLE, writeSecretsFile } from './secrets-file';
+export { deployedServiceEnvironment, type DeployedServiceInput, deriveIamProxySecret, IAM_OAUTH_CONFIG_VARIABLE, INSTALLATION_SECRET_VARIABLES, installationServiceEnvironment, type InstallationServiceInput, type PlatformData, type PlatformPlacementInput, type PlatformService, type PlatformServiceEnvironment, type PlatformStorage, } from './service-environment';
+export { attempt, capture, probe, run, type ShellAttempt, type ShellStep } from './shell';

package/types/src/log.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Console formatting for the fabrika CLI — a thin, consistent presentation layer over the orchestration
+ * in the other modules. Every line the operator sees during `init` flows through here.
+ *
+ * HARD RULE (see the worker CLAUDE.md): this module NEVER prints a secret VALUE. Callers may pass
+ * secret NAMES, counts, or "✓ set" confirmations — never the bytes of a token / key / PEM / webhook
+ * secret. There is deliberately no helper here that takes a secret value, so a careless caller can't
+ * accidentally route one through formatting.
+ */
+/** A numbered, bold section heading — the spine of the CLI's progress. Resets nothing else. */
+export declare function step(title: string): void;
+/** A plain informational line, slightly indented under the current step. */
+export declare function info(message: string): void;
+/** A dim, secondary detail line (context the operator usually skims). */
+export declare function detail(message: string): void;
+/** A success line (green ✓). */
+export declare function ok(message: string): void;
+/** A non-fatal warning (yellow ⚠) — the CLI keeps going. */
+export declare function warn(message: string): void;
+/** A failure line (red ✗). Does NOT exit — the caller decides whether to throw. */
+export declare function fail(message: string): void;
+/**
+ * A boxed OPERATOR ACTION — something the human must do out-of-band (open a URL, log in, click
+ * "create", paste a value back). These are the hand-off points the whole bring-up is built around, so
+ * they are visually loud and never scroll past unnoticed.
+ */
+export declare function action(title: string, lines: string[]): void;
+/** Render a URL prominently (cyan, underlined) — operators copy these by eye. */
+export declare function url(value: string): string;

package/types/src/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;

package/types/src/options.d.ts

@@ -0,0 +1,9 @@
+export type CommandEnv = Record<string, string | undefined>;
+export declare const readFlag: (argv: readonly string[], name: string) => string | undefined;
+export declare const readEnv: (env: CommandEnv, name: string) => string | undefined;
+export declare const setting: (argv: readonly string[], env: CommandEnv, flag: string, variable: string) => string | undefined;
+export declare const requiredSetting: (value: string | undefined, flag: string, variable: string) => string;
+/** How a refusal names an argument: a flag by its name only, never its value, which may be a pasted credential. */
+export declare const describeArgument: (arg: string) => string;
+/** One argument as a POSIX shell reads it back unchanged, for the rerun command a declined step prints. */
+export declare const shellWord: (arg: string) => string;

package/types/src/pin.d.ts

@@ -0,0 +1,2 @@
+/** The pinned ref, or an error naming what was found. A branch is refused, deliberately and loudly. */
+export declare const assertPinnedTag: (ref: string) => string;

package/types/src/prompt.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one interactive question the fabrika CLI asks: a yes/no confirmation before a step that leaves
+ * the operator's machine. Every other input is a flag or an environment variable, and a run with no
+ * terminal answers confirmations with `--yes` (`confirmations.ts`), so this reads a TTY only.
+ *
+ * A fresh interface per question, closed afterwards: a persistent one holds the terminal in raw mode
+ * (`-icanon -echo`, measured) between questions, and init spawns `git` and `gh` between them — a child
+ * inheriting a raw terminal echoes nothing and stair-steps its output.
+ */
+/** A yes/no confirmation. Defaults to `defaultYes` on an empty answer. */
+export declare function confirm(question: string, defaultYes?: boolean): Promise<boolean>;

package/types/src/protection.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Harden the sidecar repository the operator owns. It holds the installation's entire credential set,
+ * so a push to `main` must not be able to rewrite the pipeline that reads them. ADR-0025 leaves the
+ * repository operator-owned; this only stops it from being weaker than the account it controls.
+ *
+ * GitHub Free offers neither rule on a PRIVATE repository, so a refusal is REPORTED, never fatal: the
+ * operator is told what is unprotected and the exact command that applies it later. Every body travels
+ * over stdin (`gh api --input -`), never on argv.
+ *
+ * An Environment's `protected_branches` policy is only as strong as the branch rule it points at: with no
+ * protection rule on `main`, the policy admits `main` and restricts nothing. The two are reported together
+ * for that reason.
+ */
+import { type ShellAttempt, type ShellStep } from './shell';
+/** No force pushes, no deletions, admins included. No required review: `platform upgrade` pushes to `main`. */
+export declare const BRANCH_PROTECTION_BODY: string;
+/** Only a protected branch may use the Environment's secrets — and only where such a rule exists. */
+export declare const DEPLOYMENT_BRANCH_POLICY: {
+    readonly protected_branches: true;
+    readonly custom_branch_policies: false;
+};
+/** The same policy as a standalone PUT body, for the command an operator runs by hand. */
+export declare const DEPLOYMENT_BRANCH_POLICY_BODY: string;
+/** Whether one hardening rule is in place, plus the command that applies it when it is not. */
+export interface ProtectionOutcome {
+    readonly applied: boolean;
+    /** One short, printable line saying why it is not applied. Absent when it is. */
+    readonly reason?: string;
+    /** The `gh api` invocation that applies this rule later. */
+    readonly command: string;
+}
+/** Run a `gh` step whose failure is an ANSWER rather than an error. The seam tests drive. */
+export type GhAttempt = (step: ShellStep) => Promise<ShellAttempt>;
+export declare const branchProtectionCommand: (repo: string) => string;
+export declare const environmentPolicyCommand: (repo: string, environment: string) => string;
+/** Recommended, never applied by us: an approval click per deploy is the operator's call. */
+export declare const environmentReviewerCommand: (repo: string, environment: string) => string;
+/** The HTTP status `gh` names in its error line (`gh: … (HTTP 403)`), when it names one. */
+export declare const ghHttpStatus: (result: ShellAttempt) => number | undefined;
+/**
+ * The three statuses GitHub answers when a plan does not offer a protection rule. A 422 can also mean a
+ * malformed request, so this is a heuristic — it decides only whether we DEGRADE or give up, never
+ * whether something is safe.
+ */
+export declare const PLAN_LIMITED: ReadonlySet<number>;
+/** True when GitHub's answer is one this code is willing to continue without the rule on. */
+export declare const isPlanLimited: (result: ShellAttempt) => boolean;
+/** One printable line for a refusal — the plan limit when GitHub named one, the exit code otherwise. */
+export declare const unavailableReason: (result: ShellAttempt) => string;
+/** Protect `main` on the sidecar. Reports what is unprotected and never throws. */
+export declare function protectSidecarBranch(repo: string, gh?: GhAttempt): Promise<ProtectionOutcome>;
+/**
+ * Read-only: does `main` already carry a protection rule? For a repository this run did NOT create — a
+ * PUT there would replace whatever the operator configured, so the existing rules are reported, never
+ * overwritten. A 404 is GitHub's answer for "no protection rule", which is exactly what we warn about.
+ */
+export declare function probeSidecarBranchProtection(repo: string, gh?: GhAttempt): Promise<ProtectionOutcome>;