@vibesdotdev/infra-deploy 0.0.1 → 1.0.0-rc.4

package/dist/cli/run/infra-deploy.run.cli-command.impl.js

@@ -1,271 +1,509 @@
-import { getVibesRuntime } from '@vibesdotdev/runtime';
-import { resolveCurrentEnvironmentConfig } from '@vibesdotdev/config/environment/current';
-import { resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { getCloudflareWorkersDeployClient } from '@vibesdotdev/connector-cloudflare/client';
-import { getDigitalOceanAppDeployClient } from '@vibesdotdev/infra-doks/client';
+import { CapabilityError, CaughtFailureSchema, requireRuntimeCwd, settle } from '@vibesdotdev/kernel';
+import { DeploymentReleaseRequestSchema, DeploymentReleaseResultSchema } from '@vibesdotdev/infra-core/kinds';
+import { z } from 'zod/v4';
+import { readString } from "../shared/option-strings.js";
+import { readCredentialSource } from "../shared/credential-source.js";
+import { getRuntimePath } from '@vibesdotdev/paths';
 import { loadDeploymentConfig } from "../../config-loader.js";
-import { regenerateApp } from "../../regenerate.js";
-function readString(v) {
-    return typeof v === 'string' && v.length > 0 ? v : undefined;
+import { collectDeployReadinessReport } from "../readiness/infra-deploy.readiness.cli-command.impl.js";
+import { resolveRuntimeExecution } from "../shared/runtime-execution.js";
+import { withImmutableDeploymentWorkspace } from "./immutable-deployment-workspace.js";
+import { WorkspaceCompositionLockPathSchema } from '@vibesdotdev/workspace-schemas/isolation';
+import { emitDeploymentMarker } from "./deployment-marker.js";
+import { runDeploySmokeProbe } from "./deploy-smoke.js";
+import { resolveGitRepositoryRoot, resolveGitSourceIdentity } from "./git-source-identity.js";
+import { completeDeploymentRun, startDeploymentRun, deploymentRunStore } from "./deployment-run-ledger.js";
+import { createDeploymentReleaseHost, deploymentModuleEvaluation, providerOptions, resolveDeploymentProvider } from "./deployment-provider.js";
+import { deploymentEnvironmentRunRefusal, formatDeploymentEnvironmentResolution, selectDeploymentEnvironment } from "../../deployment-environment.js";
+function failureMessage(failure) {
+    return failure instanceof Error ? failure.message : failure.description;
 }
+const TruthyBooleanValueSchema = z.union([z.literal(true), z.literal('true')]);
 function readBoolean(v) {
-    return v === true || v === 'true';
+    const parsed = TruthyBooleanValueSchema.safeParse(v);
+    return parsed.success;
 }
-function resolveWorkspaceRoot(workspaceRootDir, appDir, override) {
-    if (override)
-        return resolve(override);
-    if (!workspaceRootDir || workspaceRootDir === '.')
-        return process.cwd();
-    return resolve(appDir, workspaceRootDir);
+function readErrorMessage(value) {
+    const failure = CaughtFailureSchema.parse(value);
+    return failure instanceof Error ? failure.message : failure.description;
 }
-const CLOUDFLARE_API_TOKEN_KEY = 'CLOUDFLARE_API_TOKEN';
-const CLOUDFLARE_ACCOUNT_ID_KEY = 'CLOUDFLARE_ACCOUNT_ID';
-async function resolveCloudflareEnvFromSecretsStore(runtime, ui, environmentOverride) {
-    if (process.env.CLOUDFLARE_API_TOKEN && process.env.CLOUDFLARE_ACCOUNT_ID) {
-        return {};
+export function failedDeploymentConfigLoad(err) {
+    const failure = CaughtFailureSchema.parse(err);
+    if (failure instanceof CapabilityError)
+        return failure;
+    return new CapabilityError(`Failed to load deployment config: ${failure instanceof Error ? failure.message : failure.description}`, 'INVALID_INPUT', { cause: failure });
+}
+export function emitDeployOutputLine(ui, stream, line) {
+    if (stream === 'stderr')
+        ui.error(line);
+    else
+        ui.log(line);
+}
+function readinessEvidenceForLedger(report) {
+    return {
+        status: report.summary.status,
+        generatedAt: report.generatedAt,
+        passing: report.summary.passing,
+        warnings: report.summary.warnings,
+        failures: report.summary.failures,
+        unknown: report.summary.unknown,
+        checks: report.checks
+    };
+}
+/**
+ * The workspace a deploy builds in. An app that declares
+ * `build.workspaceRootDir` builds there (relative to the app). Otherwise it
+ * builds in the bound workspace (`runtime/workspace-path`: `--workspace-root`,
+ * else the nearest workspace root above the invocation cwd), which must
+ * contain the app. An app outside it fails closed: nothing falls back to the
+ * app's repository or an environment variable.
+ */
+function appIsInsideWorkspace(paths, workspace, app) {
+    const relative = paths.relative(workspace, app);
+    return (relative === '' ||
+        (!paths.isAbsolute(relative) &&
+            relative !== '..' &&
+            !relative.startsWith('../') &&
+            !relative.startsWith('..\\')));
+}
+export function deployWorkspaceRoot(paths, workspaceRootDir, appDir, boundWorkspace) {
+    if (workspaceRootDir && workspaceRootDir !== '.')
+        return paths.resolve(appDir, workspaceRootDir);
+    const workspace = paths.resolve(boundWorkspace);
+    const app = paths.resolve(appDir);
+    if (appIsInsideWorkspace(paths, workspace, app))
+        return workspace;
+    throw new CapabilityError(`The app ${app} is outside the bound workspace ${workspace}.`, 'INVALID_INPUT', {
+        reason: 'app-outside-workspace',
+        recoveryHint: "Run from the app's workspace, or pass --workspace-root <dir> for a workspace that contains the app.",
+        details: { appDir: app, workspaceRoot: workspace }
+    });
+}
+function logDeploymentMarkerResult(result, onLine) {
+    if (result.status === 'sent') {
+        const suffix = result.markerId ? ` (${result.markerId})` : '';
+        onLine('stdout', `[deploy-marker] recorded for ${result.appId}${suffix}`);
+        return;
     }
-    if (!runtime.hasKind('secrets/store')) {
-        throw new Error(`Missing secrets/store kind in runtime. Enable secrets backends via plugin config ` +
-            `(for example plugins.auth.secrets=true and plugins.auth.secretsBackends.*) before running deploy.`);
+    if (result.status === 'skipped') {
+        onLine('stderr', `[deploy-marker] skipped: ${result.reason}`);
+        return;
     }
-    let envName = environmentOverride ?? 'local';
-    let envTier = 'local';
-    if (environmentOverride) {
-        envTier = environmentOverride;
+    onLine('stderr', `[deploy-marker] failed: ${result.reason}`);
+}
+function logDeploymentRunLedgerResult(result, onLine) {
+    if (result.status === 'recorded') {
+        onLine('stdout', `[deploy-ledger] recorded run ${result.runId}`);
+        return;
     }
-    else {
-        try {
-            const envConfig = await resolveCurrentEnvironmentConfig();
-            envName = envConfig.name;
-            envTier = envConfig.tier ?? 'local';
-        }
-        catch {
-            // Fall back to local when config environment resolution is unavailable.
-        }
+    if (result.status === 'skipped') {
+        onLine('stderr', `[deploy-ledger] skipped: ${result.reason}`);
+        return;
     }
-    const descriptors = runtime.assets('secrets/store').descriptors();
-    const tierCandidates = new Set([envTier]);
-    if (envTier === 'local' || envTier === 'dev') {
-        // Deploy auth is often run from local shells while credentials live in
-        // staging/production backends (Vault/Cloudflare). Include those tiers as
-        // fallbacks instead of hard-filtering them out.
-        tierCandidates.add('staging');
-        tierCandidates.add('production');
+    onLine('stderr', `[deploy-ledger] failed: ${result.reason}`);
+}
+/**
+ * The fail-closed deploy prologue, extracted as one owner-level seam so the
+ * ordering guarantee is testable via dependency injection (resolver + readiness).
+ *
+ * Resolves the provider environment FIRST, runs readiness UNDER that same
+ * environment when the provider renders under it (so the deployment module
+ * projects post-resolution bindings), then runs the environment gate. If the
+ * projection is a strip (required secrets declared but unbound), it THROWS the
+ * refusal here — before the caller records any ledger entry or dispatches to a
+ * provider. The returned `envOverrides` is the SAME object the provider's
+ * release receives, so nothing downstream reads pre-resolution state.
+ */
+export async function prepareDeployProjection(input, deps = {}) {
+    const collectReadiness = deps.collectReadiness ?? collectDeployReadinessReport;
+    const resolveEnvironment = deps.resolveEnvironment ?? (() => input.implementation.environment({
+        environment: input.selectedEnvironment,
+        credentialSource: input.credentialSource,
+        log: input.ui
+    }));
+    const providerEnvironment = await resolveEnvironment();
+    const envOverrides = providerEnvironment.variables;
+    const readinessInput = {
+        appDir: input.appDir,
+        workspaceRoot: input.workspaceRoot,
+        displayBase: input.displayBase,
+        environment: input.selectedEnvironment,
+        provider: input.provider,
+        runtime: input.runtime,
+        execution: input.execution,
+        // execute() loaded the deployment module before the provider environment
+        // was resolved. A same-process import would reuse that stale module; the
+        // fresh evaluation renders under the resolved projection, passed as data.
+        freshDeploymentProjection: providerEnvironment.projected
+    };
+    if (providerEnvironment.projected) {
+        readinessInput.projectionEnvironment = envOverrides;
     }
-    const candidates = descriptors
-        .filter((d) => {
-        if (environmentOverride)
-            return true;
-        if (!d.tiers || d.tiers.length === 0)
-            return true;
-        return d.tiers.some((tier) => tierCandidates.has(tier));
-    })
-        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
-    const out = {};
-    for (const descriptor of candidates) {
-        const store = (await runtime
-            .query('secrets/store')
-            .withId(descriptor.id)
-            .resolve());
-        if (!process.env.CLOUDFLARE_API_TOKEN && !out.CLOUDFLARE_API_TOKEN) {
-            const value = await store.get(envName, CLOUDFLARE_API_TOKEN_KEY);
-            if (value && value.length > 0) {
-                out.CLOUDFLARE_API_TOKEN = value;
-            }
-        }
-        if (!process.env.CLOUDFLARE_ACCOUNT_ID && !out.CLOUDFLARE_ACCOUNT_ID) {
-            const value = await store.get(envName, CLOUDFLARE_ACCOUNT_ID_KEY);
-            if (value && value.length > 0) {
-                out.CLOUDFLARE_ACCOUNT_ID = value;
-            }
-        }
-        if (out.CLOUDFLARE_API_TOKEN && out.CLOUDFLARE_ACCOUNT_ID)
-            break;
+    const readinessReport = await collectReadiness(readinessInput);
+    const environmentResolution = readinessReport.environmentResolution;
+    if (input.emitEnvironmentLine) {
+        input.ui.info(`[environment] ${formatDeploymentEnvironmentResolution(environmentResolution)}`);
     }
-    if (Object.keys(out).length > 0) {
-        ui.info(`Resolved Cloudflare deploy credentials from secrets store (${envName}/${envTier}).`);
+    const environmentRefusal = deploymentEnvironmentRunRefusal(environmentResolution, {
+        environment: input.targetEnvironment,
+        providerEnvironment: input.wranglerEnvironmentOverride
+    });
+    if (environmentRefusal) {
+        throw new CapabilityError(environmentRefusal.message, environmentRefusal.code, {
+            details: environmentResolution,
+            recoveryHint: environmentRefusal.recoveryHint
+        });
     }
-    return out;
+    return { envOverrides, readinessReport, environmentResolution };
+}
+/** The marker/ledger record of a release; one shape for every provider. */
+function releaseRecord(release, providerTraceRefOverride) {
+    return {
+        deployedUrl: release.deployedUrl,
+        externalDeploymentId: release.externalDeploymentId,
+        providerTraceRef: providerTraceRefOverride ?? release.providerTraceRef
+    };
 }
 export default {
-    async execute(args, opts) {
-        const runtime = getVibesRuntime();
-        const ui = (await runtime.context('cli/ui'));
-        const pathArg = readString(args.path) ?? process.cwd();
+    async execute(args, opts, context) {
+        const { runtime } = context;
+        const cwd = requireRuntimeCwd(runtime);
+        const ui = await runtime.context('cli/ui');
+        const execution = await resolveRuntimeExecution(runtime);
+        const paths = await getRuntimePath(runtime);
+        const pathArg = paths.resolve(cwd, readString(args.path) ?? '.');
         const output = readString(opts.output) ?? 'text';
         const skipBuild = readBoolean(opts.skipBuild);
+        const inPlace = readBoolean(opts.inPlace);
         const skipD1Migrations = readBoolean(opts.skipD1Migrations);
         const dryRun = readBoolean(opts.dryRun);
-        const workspaceRootOverride = readString(opts.workspaceRoot);
         const targetEnvironment = readString(opts.environment);
-        let loaded;
-        try {
-            loaded = await loadDeploymentConfig(pathArg);
-        }
-        catch (err) {
-            ui.error(`Failed to load deployment config: ${err.message}`);
-            process.exitCode = 1;
-            return;
+        const credentialSource = readCredentialSource(opts);
+        const wranglerEnvironmentOverride = readString(opts.wranglerEnv);
+        const selectedEnvironment = selectDeploymentEnvironment({
+            environment: targetEnvironment,
+            providerEnvironment: wranglerEnvironmentOverride
+        });
+        const logsRef = readString(opts.logsRef);
+        const providerTraceRefOverride = readString(opts.providerTraceRef);
+        const remediationUrl = readString(opts.remediationUrl);
+        // Identity load: provider and app directory are needed to resolve the
+        // projection. Readiness and the provider's render re-evaluate under the
+        // resolved projection, passed as data; this load renders under an empty one.
+        const loadedOutcome = await settle(async () => loadDeploymentConfig(pathArg, { runtime, projectionEnvironment: {} }));
+        if (!loadedOutcome.ok) {
+            throw failedDeploymentConfigLoad(loadedOutcome.cause);
         }
+        const loaded = loadedOutcome.value;
         const { deployment, provider, appDir } = loaded;
+        // The provider the deployment declares, resolved through the runtime; its
+        // own schema refuses options it cannot honour before anything is recorded.
+        const { implementation } = await resolveDeploymentProvider(runtime, provider);
+        const options = providerOptions(opts);
+        implementation.validateOptions(options);
+        const appRepositoryRoot = await resolveGitRepositoryRoot(runtime, execution, appDir);
+        const workspaceRoot = deployWorkspaceRoot(paths, deployment.build.workspaceRootDir, appDir, await runtime.context('runtime/workspace-path'));
+        // Fail-closed prologue: resolve the provider environment FIRST, run readiness
+        // under it, and refuse a stripped projection — all BEFORE the ledger and the
+        // release below. See prepareDeployProjection. The returned envOverrides is the
+        // object the release receives, so nothing downstream reads pre-resolution state.
+        const { envOverrides, readinessReport, environmentResolution } = await prepareDeployProjection({
+            provider,
+            implementation,
+            appDir,
+            workspaceRoot,
+            displayBase: cwd,
+            selectedEnvironment,
+            targetEnvironment,
+            wranglerEnvironmentOverride,
+            credentialSource,
+            runtime,
+            execution,
+            ui,
+            emitEnvironmentLine: output === 'text'
+        });
+        const readinessEvidence = readinessEvidenceForLedger(readinessReport);
         if (output === 'text') {
             ui.info(`Deploying ${deployment.appName} (${deployment.appId}) via ${provider}`);
         }
-        const onLine = (_stream, line) => {
+        const onLine = (stream, line) => {
             if (output === 'text')
-                ui.log(line);
+                emitDeployOutputLine(ui, stream, line);
         };
+        // One resolution, passed explicitly to every marker/ledger site: manual
+        // deploys otherwise record NULL commits (only CI env vars were read).
+        const sourceIdentity = await resolveGitSourceIdentity(runtime, execution, appDir);
+        // Bake the deployed commit into the build so the LIVE origin can report which
+        // build it is serving. `apps/sveltekit-version.mjs` already reads
+        // `VIBES_BUILD_VERSION` into `kit.version.name`, which SvelteKit publishes at
+        // `/_app/version.json` — public, pre-auth, no API token. Without this it falls
+        // back to `Date.now()`, which changes per build but cannot be compared against
+        // anything, so a deploy could not be distinguished from a stale worker.
+        if (sourceIdentity.commit) {
+            envOverrides.VIBES_BUILD_VERSION = sourceIdentity.commit;
+        }
+        const startedRun = await startDeploymentRun(runtime, {
+            store: deploymentRunStore(runtime),
+            deployment,
+            provider,
+            environment: environmentResolution.environment,
+            appDir,
+            dryRun,
+            skipBuild,
+            skipD1Migrations,
+            branch: readString(opts.branch) ?? sourceIdentity.branch,
+            commit: sourceIdentity.commit,
+            logsRef,
+            providerTraceRef: providerTraceRefOverride,
+            remediationUrl,
+            readinessEvidence
+        });
+        const deploymentRunId = startedRun.status === 'recorded' ? startedRun.runId : undefined;
+        if (output === 'text')
+            logDeploymentRunLedgerResult(startedRun, onLine);
+        if (!dryRun && startedRun.status !== 'recorded') {
+            throw new CapabilityError('Refusing real deploy because the deployment run ledger could not be recorded.', 'UNAVAILABLE', { details: { ledgerStatus: startedRun.status, reason: startedRun.reason } });
+        }
         try {
-            switch (provider) {
-                case 'cloudflare-workers': {
-                    const environment = readString(opts.wranglerEnv);
-                    const workspaceRoot = resolveWorkspaceRoot(deployment.build.workspaceRootDir, appDir, workspaceRootOverride);
-                    // Run generic pre-deploy commands (provider-agnostic hooks)
-                    if (deployment.preDeployCommands.length > 0) {
-                        onLine('stdout', `Running ${deployment.preDeployCommands.length} pre-deploy command(s)...`);
-                        for (const cmd of deployment.preDeployCommands) {
-                            if (cmd.description) {
-                                onLine('stdout', `  ${cmd.description}`);
-                            }
-                            if (dryRun) {
-                                onLine('stdout', `  [dry-run] ${cmd.command}`);
-                                continue;
-                            }
-                            const [bin, ...args] = cmd.command.split(' ').filter(Boolean);
-                            if (!bin)
-                                continue;
-                            const child = spawnSync(bin, args, {
-                                cwd: appDir,
-                                stdio: 'inherit',
-                                env: process.env
-                            });
-                            if (child.status !== 0) {
-                                throw new Error(`Pre-deploy command failed: ${cmd.command} (exit=${child.status ?? child.error?.message ?? 'unknown'})`);
-                            }
-                        }
-                        onLine('stdout', 'Pre-deploy commands complete.');
-                    }
-                    // Regen gate: refuse to deploy a stale wrangler.jsonc. For apps with
-                    // `managed: true` in deployment.config.ts, this enforces that what's
-                    // on disk matches what the typed config would produce. Unmanaged apps
-                    // pass through (the gate is opt-in until every app is migrated).
-                    const regen = await regenerateApp(appDir, { mode: 'check' });
-                    if (regen.status === 'drift') {
-                        const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-                        const isKvIdDrift = regen.diff &&
-                            /^[\+\-]\s+"id":\s*"[^"]*"/m.test(regen.diff) &&
-                            !uuidRe.test(regen.diff.replace(/"id":\s*"([^"]*)"/g, '$1').slice(0, 36));
-                        if (!isKvIdDrift) {
-                            const detail = regen.diff ? `\n${regen.diff}` : '';
-                            throw new Error(`wrangler.jsonc drift for ${regen.appId} — regenerate before deploy (run \`vibes infra deploy regenerate ${appDir}\`)${detail}`);
-                        }
-                        onLine('stdout', `[regen] wrangler.jsonc verified (unchanged — kv namespace IDs resolved)`);
-                    }
-                    if (regen.status === 'error') {
-                        throw new Error(`regenerate check failed for ${appDir}: ${regen.reason ?? 'unknown error'}`);
-                    }
-                    if (regen.status === 'updated' || regen.status === 'unchanged') {
-                        onLine('stdout', `[regen] wrangler.jsonc verified (${regen.status})`);
-                    }
-                    else if (regen.status === 'skipped') {
-                        onLine('stdout', `[regen] skipped: ${regen.reason ?? 'not managed'}`);
-                    }
-                    const client = await getCloudflareWorkersDeployClient();
-                    const envOverrides = await resolveCloudflareEnvFromSecretsStore(runtime, ui, targetEnvironment);
-                    // Provisioning for KV, D1, R2 is now always attempted when declared
-                    // (creation + ID reconciliation happens in the client using REST API).
-                    // Migrations remain opt-in via autoMigrateD1 for safety.
-                    const rawConfig = loaded.raw;
-                    const autoMigrateD1 = rawConfig.autoMigrateD1 === true && !skipD1Migrations;
-                    if (skipD1Migrations) {
-                        onLine('stdout', 'Skipping D1 migrations for this deploy.');
-                    }
-                    const generatedWranglerConfig = typeof rawConfig.generateWranglerConfig === 'function'
-                        ? rawConfig.generateWranglerConfig()
-                        : loaded.wranglerJsoncString
-                            ? JSON.parse(loaded.wranglerJsoncString.replace(/^\s*\/\/.*$/gm, ''))
-                            : rawConfig;
-                    const d1Databases = (rawConfig.d1Databases ??
-                        rawConfig.d1_databases ??
-                        generatedWranglerConfig.d1Databases ??
-                        generatedWranglerConfig.d1_databases) ?? undefined;
-                    const r2Buckets = rawConfig.r2_buckets ?? undefined;
-                    const result = await client.deployWorker({
+            let release;
+            const variables = { ...envOverrides };
+            if (sourceIdentity.commit)
+                variables.VIBES_BUILD_VERSION = sourceIdentity.commit;
+            const releaseInProcess = async (host, compositionDigest) => {
+                return DeploymentReleaseResultSchema.parse(await implementation.release({
+                    ...DeploymentReleaseRequestSchema.parse({
                         appDir,
                         workspaceRoot,
-                        workerName: deployment.appId,
-                        buildCommand: deployment.build.buildCommand,
-                        skipBuild,
+                        repositoryRoot: appRepositoryRoot,
+                        environment: environmentResolution.environment,
+                        providerEnvironment: environmentResolution.providerEnvironment ?? null,
                         dryRun,
-                        environment,
-                        envOverrides,
-                        kvNamespaces: deployment.kvNamespaces,
-                        d1Databases: autoMigrateD1 ? d1Databases : undefined,
-                        r2Buckets,
-                        onLine
+                        skipBuild,
+                        source: {
+                            commit: sourceIdentity.commit,
+                            branch: sourceIdentity.branch,
+                            compositionDigest
+                        },
+                        options
+                    }),
+                    deployment,
+                    module: deploymentModuleEvaluation(loaded),
+                    variables,
+                    host,
+                    log: ui,
+                    onLine
+                }));
+            };
+            if (dryRun || inPlace) {
+                release = await releaseInProcess(createDeploymentReleaseHost({
+                    runtime,
+                    execution,
+                    deployment,
+                    appDir,
+                    workspaceRoot,
+                    environment: environmentResolution.environment,
+                    credentialSource,
+                    skipBuild,
+                    dryRun,
+                    onLine
+                }));
+            }
+            else if (skipBuild) {
+                // The receipt is the bytes already in this workspace. A fresh composition
+                // does not contain them, so the composition owner only names the identity
+                // and the release host seals those bytes before provider effects.
+                const isolation = runtime.hasKind('workspace/isolation')
+                    ? await runtime.query('workspace/isolation').resolve()
+                    : undefined;
+                if (!isolation || !appRepositoryRoot || !sourceIdentity.commit) {
+                    throw new CapabilityError('Skip-build requires a matching immutable source, composition and artifact receipt.', 'INVALID_INPUT', {
+                        reason: 'skip-build-immutable-receipt-required'
                     });
-                    if (output === 'json') {
-                        ui.json({
-                            ok: true,
-                            provider: 'cloudflare-workers',
-                            workerName: result.workerName,
-                            deployedUrl: result.deployedUrl
-                        });
-                    }
-                    else if (!dryRun) {
-                        ui.success(result.deployedUrl
-                            ? `Deployed Worker ${result.workerName} at ${result.deployedUrl}`
-                            : `Deployed Worker ${result.workerName}`);
-                    }
-                    return;
                 }
-                case 'digitalocean-app': {
-                    const doAppId = readString(opts.doAppId);
-                    const doRegion = readString(opts.doRegion);
-                    const doGitRepo = readString(opts.doGitRepo);
-                    const doGitBranch = readString(opts.doGitBranch);
-                    const client = await getDigitalOceanAppDeployClient();
-                    const result = await client.deployApp({
-                        deployment,
-                        appId: doAppId,
-                        region: doRegion,
-                        git: doGitRepo ? { repoCloneUrl: doGitRepo, branch: doGitBranch ?? 'main' } : undefined,
-                        dryRun,
-                        onLine
+                const reference = await isolation.prepareComposition(appRepositoryRoot);
+                if (reference.parent.repoPath !== workspaceRoot || reference.source.commit !== sourceIdentity.commit) {
+                    throw new CapabilityError('Skip-build requires a matching immutable source, composition and artifact receipt.', 'INVALID_INPUT', {
+                        reason: 'skip-build-immutable-receipt-required'
                     });
-                    if (output === 'json') {
-                        ui.json({
-                            ok: true,
-                            provider: 'digitalocean-app',
-                            appId: result.appId,
-                            liveUrl: result.liveUrl
+                }
+                const assertSource = async () => {
+                    const current = await isolation.prepareComposition(appRepositoryRoot);
+                    if (current.digest !== reference.digest || current.source.commit !== reference.source.commit) {
+                        throw new CapabilityError('Deployment source identity does not match its admitted composition.', 'CONFLICT', {
+                            reason: 'deployment-source-identity-mismatch'
                         });
                     }
-                    else if (!dryRun) {
-                        ui.success(result.liveUrl
-                            ? `Deployed DO App ${result.appId} at ${result.liveUrl}`
-                            : `Deployed DO App ${result.appId}`);
+                };
+                release = await releaseInProcess(createDeploymentReleaseHost({
+                    runtime,
+                    execution,
+                    deployment,
+                    appDir,
+                    workspaceRoot,
+                    environment: environmentResolution.environment,
+                    credentialSource,
+                    skipBuild,
+                    dryRun,
+                    onLine,
+                    immutableBuild: {
+                        compositionDigest: reference.digest,
+                        sourceCommit: reference.source.commit,
+                        lockFiles: WorkspaceCompositionLockPathSchema.options,
+                        assertSource
                     }
-                    return;
-                }
-                default: {
-                    ui.error(`Unsupported provider: ${provider}`);
-                    ui.info('Supported providers: cloudflare-workers, digitalocean-app');
-                    process.exitCode = 1;
-                    return;
+                }), reference.digest);
+            }
+            else {
+                if (!appRepositoryRoot) {
+                    throw new CapabilityError('Immutable deployment requires a source repository.', 'INVALID_INPUT', {
+                        reason: 'deployment-source-repository-missing'
+                    });
                 }
+                release = await withImmutableDeploymentWorkspace({
+                    runtime,
+                    appDir,
+                    workspaceRoot,
+                    repositoryRoot: appRepositoryRoot,
+                    expectedCommit: sourceIdentity.commit,
+                    provider,
+                    appId: deployment.appId,
+                    options,
+                    selectedEnvironment,
+                    targetEnvironment,
+                    wranglerEnvironmentOverride,
+                    credentialSource,
+                    skipBuild,
+                    dryRun,
+                    sourceIdentity,
+                    ui,
+                    onLine
+                });
             }
+            const record = releaseRecord(release, providerTraceRefOverride);
+            // Live-probe BEFORE recording the marker so the marker states what is
+            // actually serving, not what the upload claimed (the marker path has
+            // produced a false DEPLOY FAILED under rate limiting before).
+            const smokeEnabled = opts.smoke !== false;
+            const smokeResult = release.probe && smokeEnabled
+                ? await runDeploySmokeProbe({
+                    runtime,
+                    deployment,
+                    deployedUrl: release.deployedUrl,
+                    environmentResolution,
+                    // Same SHA baked into the build above. Passing it turns the
+                    // probe from "the origin answered" into "the build I just
+                    // shipped is the one serving".
+                    expectedVersion: sourceIdentity.commit,
+                    onLine
+                })
+                : undefined;
+            if (smokeResult && !smokeResult.ok) {
+                // Throw into the shared failure path below — it records the failed
+                // marker + ledger row exactly once and owns the exit envelope.
+                // No blanket rollback advice: the smoke detail already carries the
+                // remedy that fits the specific failure.
+                throw new Error(`smoke probe: ${release.externalDeploymentId ?? deployment.appId} uploaded but ${smokeResult.url ?? 'its origin'} did not pass the post-deploy check within the retry window (${smokeResult.detail}). The upload itself succeeded — confirm what is actually serving before reverting anything.`);
+            }
+            const smokeNotes = smokeResult
+                ? smokeResult.skipped
+                    ? `smoke SKIPPED: ${smokeResult.detail}`
+                    : `smoke ok: ${smokeResult.detail}`
+                : undefined;
+            const released = release.status === 'released';
+            const deploymentMarker = released
+                ? await emitDeploymentMarker({
+                    runtime,
+                    deployment,
+                    provider,
+                    environment: environmentResolution.environment,
+                    ...record,
+                    deploymentRunId,
+                    commit: sourceIdentity.commit,
+                    branch: sourceIdentity.branch,
+                    logsRef,
+                    remediationUrl,
+                    notes: smokeNotes ?? release.notes
+                })
+                : undefined;
+            const deploymentRun = await completeDeploymentRun({
+                store: deploymentRunStore(runtime),
+                runId: deploymentRunId,
+                status: released ? 'succeeded' : 'dry_run',
+                ...record,
+                logsRef,
+                remediationUrl,
+                marker: deploymentMarker,
+                readinessEvidence,
+                notes: smokeNotes ?? release.notes
+            });
+            if (output === 'json') {
+                ui.json({
+                    ok: true,
+                    provider,
+                    ...release.result,
+                    environmentResolution,
+                    deploymentMarker,
+                    deploymentRun
+                });
+                return;
+            }
+            if (release.summary)
+                ui.success(release.summary);
+            if (deploymentMarker)
+                logDeploymentMarkerResult(deploymentMarker, onLine);
+            logDeploymentRunLedgerResult(deploymentRun, onLine);
         }
         catch (err) {
-            const message = err.message;
-            if (output === 'json') {
-                ui.json({ ok: false, error: message });
+            // A coded error from the release (e.g. a refused provider option) is an
+            // input/validation failure, not a deploy that failed mid-flight — let it
+            // propagate without emitting a failure marker or ledger row.
+            if (err instanceof CapabilityError)
+                throw err;
+            const message = readErrorMessage(err);
+            const summary = message.split('\n')[0];
+            const markerEnvironment = environmentResolution.environment;
+            let deploymentMarker = undefined;
+            if (!dryRun) {
+                const markerOutcome = await settle(() => emitDeploymentMarker({
+                    runtime,
+                    deployment,
+                    provider,
+                    environment: markerEnvironment,
+                    status: 'failed',
+                    deploymentRunId,
+                    logsRef,
+                    providerTraceRef: providerTraceRefOverride,
+                    remediationUrl,
+                    notes: summary
+                }));
+                deploymentMarker = markerOutcome.ok
+                    ? markerOutcome.value
+                    : {
+                        status: 'failed',
+                        reason: `failure marker emission failed: ${failureMessage(markerOutcome.cause)}`
+                    };
             }
-            else {
-                ui.error(message);
+            const deploymentRun = await completeDeploymentRun({
+                store: deploymentRunStore(runtime),
+                runId: deploymentRunId,
+                status: 'failed',
+                marker: deploymentMarker,
+                logsRef,
+                providerTraceRef: providerTraceRefOverride,
+                remediationUrl,
+                readinessEvidence,
+                error: summary
+            });
+            // Record the marker/ledger rows before propagating, then throw so the
+            // surface owns the exit code and the failure envelope. The marker/ledger
+            // lines read success-ish ("recorded run <id>") even on failure, so the
+            // thrown message must be unambiguous.
+            if (output === 'text') {
+                if (deploymentMarker)
+                    logDeploymentMarkerResult(deploymentMarker, onLine);
+                logDeploymentRunLedgerResult(deploymentRun, onLine);
             }
-            process.exitCode = 1;
+            throw new CapabilityError(`DEPLOY FAILED — ${deployment.appId} (${provider}${markerEnvironment ? `, ${markerEnvironment}` : ''}): ${message}`, 'INTERNAL', { cause: err, details: { deploymentMarker, deploymentRun } });
         }
     }
 };