@empire-builder-kit/nx 1.0.0-rc.2 → 1.0.0-rc.21

package/src/executors/local-deploy/local-deploy.js

@@ -0,0 +1,911 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareLocalSstBackend = prepareLocalSstBackend;
+exports.localPlanSummaryDigest = localPlanSummaryDigest;
+exports.runLocalDeploy = runLocalDeploy;
+const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const client_sts_1 = require("@aws-sdk/client-sts");
+const client_ssm_1 = require("@aws-sdk/client-ssm");
+const credential_providers_1 = require("@aws-sdk/credential-providers");
+const devkit_1 = require("@nx/devkit");
+const index_js_1 = require("../../infrastructure-change/index.js");
+const local_capability_js_1 = require("../../infrastructure-change/local-capability.js");
+const index_js_2 = require("../../repository-policy/index.js");
+const source_authority_js_1 = require("../../release/source-authority.js");
+const private_state_js_1 = require("../../local-dev/private-state.js");
+const infrastructure_plan_js_1 = require("../infrastructure-plan/infrastructure-plan.js");
+const sst_environment_source_js_1 = require("../sst-lifecycle/sst-environment-source.js");
+const local_approval_js_1 = require("./local-approval.js");
+const SHA = /^[a-f0-9]{40}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const MAX_PLAN_BYTES = 2 * 1024 * 1024;
+const ROLE = /^arn:(aws|aws-us-gov|aws-cn):iam::\d{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
+const AMBIENT_CREDENTIAL_KEYS = [
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AWS_SECURITY_TOKEN',
+    'AWS_ROLE_ARN',
+    'AWS_ROLE_SESSION_NAME',
+    'AWS_WEB_IDENTITY_TOKEN_FILE',
+    'AWS_CONTAINER_AUTHORIZATION_TOKEN',
+    'AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE',
+    'AWS_CONTAINER_CREDENTIALS_FULL_URI',
+    'AWS_CONTAINER_CREDENTIALS_RELATIVE_URI',
+];
+const PROTECTED_PLAN_KEYS = [
+    'EBK_LOCAL_MUTATION_CAPABILITY_NONCE',
+    'EBK_LOCAL_MUTATION_CAPABILITY_PATH',
+    'EBK_LOCAL_PLAN_APPROVER_ARN',
+    'EBK_LOCAL_PLAN_MATERIAL_DIGEST',
+    'EBK_LOCAL_PLAN_SUMMARY_DIGEST',
+    'AWS_PLAN_GENERATED_OBJECT_ARNS_JSON',
+    'AWS_PLAN_GENERATED_PARAMETER_ARNS_JSON',
+    'AWS_PLAN_GENERATED_SECRET_ARNS_JSON',
+    'AWS_PLAN_PROVIDER_REFRESH_POLICY_JSON',
+    'AWS_PLAN_STATE_KMS_KEY_ARN',
+    'EBK_RELEASE_SOURCE_COMMIT',
+];
+function projectEvidencePath(context, project, name) {
+    const configured = context.projectsConfigurations?.projects[project]?.root;
+    if (!configured) {
+        throw new Error(`Local deployment references unknown project ${project}.`);
+    }
+    return (0, node_path_1.join)((0, node_path_1.isAbsolute)(configured) ? configured : (0, node_path_1.join)(context.root, configured), '.ebk', 'evidence', name);
+}
+function writeLocalMutationCapability(input) {
+    const nonce = (0, node_crypto_1.randomBytes)(32).toString('hex');
+    const directory = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'ebk-local-mutation-'));
+    (0, private_state_js_1.ensurePrivateDirectory)(directory);
+    const path = (0, node_path_1.join)(directory, 'capability.json');
+    const planContents = (0, node_fs_1.readFileSync)(projectEvidencePath(input.context, input.project, 'infrastructure-plan.json'), 'utf8');
+    const authorizationContents = (0, node_fs_1.readFileSync)(projectEvidencePath(input.context, input.project, 'infrastructure-plan-authorization.json'), 'utf8');
+    const capability = (0, local_capability_js_1.createLocalMutationCapability)({
+        actorArn: input.actorArn,
+        authorizationContents,
+        deploymentProfile: input.deploymentProfile,
+        deploymentSourceCommit: input.deploymentSourceCommit,
+        deploymentSourceTree: input.deploymentSourceTree,
+        expectedRoleArn: input.expectedRoleArn,
+        issuedAt: input.issuedAt,
+        nonce,
+        plan: input.plan,
+        planContents,
+        project: input.project,
+        releaseSourceTree: input.releaseSourceTree,
+    });
+    (0, private_state_js_1.atomicWritePrivateFile)(path, `${JSON.stringify(capability, null, 2)}\n`);
+    return { directory, nonce, path };
+}
+function digest(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+}
+function ssmParameterAuthority(value, expectedName) {
+    const parameter = record(value, expectedName);
+    if (parameter['Name'] !== expectedName ||
+        parameter['Type'] !== 'SecureString' ||
+        typeof parameter['Version'] !== 'number' ||
+        !Number.isSafeInteger(parameter['Version']) ||
+        parameter['Version'] < 1) {
+        throw new Error(`Local SST backend parameter ${expectedName} is missing or malformed.`);
+    }
+    return {
+        name: expectedName,
+        type: parameter['Type'],
+        version: parameter['Version'],
+    };
+}
+/** @internal */
+async function prepareLocalSstBackend(input, dependencies = {}) {
+    if (input.applications.length === 0 ||
+        new Set(input.applications).size !== input.applications.length ||
+        input.applications.some((application) => !/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(application))) {
+        throw new Error('Local SST backend requires a unique exact application inventory.');
+    }
+    const client = new client_ssm_1.SSMClient({
+        region: input.region,
+        ...(input.profile
+            ? { credentials: (0, credential_providers_1.fromIni)({ profile: input.profile }) }
+            : {}),
+    });
+    const send = dependencies.send ??
+        (async (command) => client.send(command));
+    const bootstrapResponse = await send(new client_ssm_1.GetParameterCommand({ Name: '/sst/bootstrap' }));
+    const bootstrapParameter = bootstrapResponse.Parameter;
+    let bootstrap;
+    try {
+        bootstrap = record(JSON.parse(bootstrapParameter?.Value ?? ''), 'Local SST bootstrap value');
+    }
+    catch {
+        throw new Error('Local deployment requires an existing exact SST v5 account bootstrap.');
+    }
+    const exactBootstrapKeys = [
+        'appsyncHttp',
+        'appsyncRealtime',
+        'asset',
+        'assetEcrRegistryId',
+        'assetEcrUrl',
+        'state',
+        'version',
+    ];
+    const state = bootstrap['state'];
+    if (bootstrapParameter?.Name !== '/sst/bootstrap' ||
+        bootstrapParameter.Type !== 'String' ||
+        typeof bootstrapParameter.Version !== 'number' ||
+        !Number.isSafeInteger(bootstrapParameter.Version) ||
+        bootstrapParameter.Version < 1 ||
+        Object.keys(bootstrap).sort().join(',') !== exactBootstrapKeys.join(',') ||
+        bootstrap['version'] !== 5 ||
+        typeof state !== 'string' ||
+        !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(state) ||
+        typeof bootstrap['asset'] !== 'string' ||
+        !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(bootstrap['asset']) ||
+        bootstrap['assetEcrRegistryId'] !== input.account ||
+        bootstrap['assetEcrUrl'] !==
+            `${input.account}.dkr.ecr.${input.region}.amazonaws.com/sst-asset` ||
+        typeof bootstrap['appsyncHttp'] !== 'string' ||
+        typeof bootstrap['appsyncRealtime'] !== 'string') {
+        throw new Error('Local deployment requires an existing exact SST v5 account bootstrap.');
+    }
+    const parameterAuthority = new Map();
+    const missingApplications = [];
+    const createdApplications = [];
+    for (const application of input.applications) {
+        const name = `/sst/passphrase/${application}/${input.stage}`;
+        try {
+            const observed = await send(new client_ssm_1.GetParameterCommand({ Name: name }));
+            parameterAuthority.set(application, ssmParameterAuthority(observed.Parameter, name));
+        }
+        catch (error) {
+            if (!(error instanceof Error) || error.name !== 'ParameterNotFound') {
+                throw error;
+            }
+            missingApplications.push(application);
+        }
+    }
+    for (const application of missingApplications) {
+        const name = `/sst/passphrase/${application}/${input.stage}`;
+        await send(new client_ssm_1.PutParameterCommand({
+            Description: `SST state passphrase for ${application}/${input.stage}`,
+            Name: name,
+            Overwrite: false,
+            Type: 'SecureString',
+            Value: dependencies.passphrase?.() ?? (0, node_crypto_1.randomBytes)(32).toString('base64'),
+        }));
+        createdApplications.push(application);
+        const observed = await send(new client_ssm_1.GetParameterCommand({ Name: name }));
+        parameterAuthority.set(application, ssmParameterAuthority(observed.Parameter, name));
+    }
+    const parameters = input.applications.map((application) => {
+        const authority = parameterAuthority.get(application);
+        if (!authority) {
+            throw new Error(`Local SST backend parameter authority is absent for ${application}.`);
+        }
+        return authority;
+    });
+    return {
+        authorityDigest: digest(JSON.stringify({
+            applications: [...input.applications],
+            bootstrap: {
+                name: bootstrapParameter.Name,
+                type: bootstrapParameter.Type,
+                version: bootstrapParameter.Version,
+            },
+            parameters,
+            region: input.region,
+            stage: input.stage,
+            state,
+        })),
+        createdApplications,
+        stateBucketArn: `arn:aws:s3:::${state}`,
+    };
+}
+function git(root, args, run) {
+    const result = run('git', args, {
+        cwd: root,
+        encoding: 'utf8',
+        env: process.env,
+        maxBuffer: 1024 * 1024,
+        shell: false,
+    });
+    if (result.status !== 0) {
+        throw new Error(`Local deployment Git preflight failed: ${String(result.stderr).trim()}`);
+    }
+    return String(result.stdout).trim();
+}
+function gitRaw(root, args, run) {
+    const result = run('git', args, {
+        cwd: root,
+        encoding: 'utf8',
+        env: process.env,
+        maxBuffer: 1024 * 1024,
+        shell: false,
+    });
+    if (result.status !== 0 || String(result.stderr) !== '') {
+        throw new Error(`Local deployment Git reconciliation failed: ${String(result.stderr).trim()}`);
+    }
+    return String(result.stdout);
+}
+function toolOwnedSourceSnapshots(context, projects) {
+    const workspaceRoot = (0, node_fs_1.realpathSync)(context.root);
+    return projects.map((project) => {
+        const configured = context.projectsConfigurations?.projects[project]?.root;
+        if (!configured) {
+            throw new Error(`Local deployment tool-owned source references unknown project ${project}.`);
+        }
+        return (0, sst_environment_source_js_1.captureSstEnvironmentSourceTree)({
+            projectRoot: (0, node_path_1.isAbsolute)(configured)
+                ? configured
+                : (0, node_path_1.join)(workspaceRoot, configured),
+            workspaceRoot,
+        });
+    });
+}
+function nulSeparatedPaths(value) {
+    return value.split('\0').filter((entry) => entry !== '');
+}
+function reconcileToolOwnedSource(root, snapshots, run) {
+    for (const snapshot of snapshots) {
+        (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(snapshot);
+    }
+    const remaining = [
+        ...nulSeparatedPaths(gitRaw(root, ['diff', 'HEAD', '--name-only', '--no-renames', '-z'], run)),
+        ...nulSeparatedPaths(gitRaw(root, ['ls-files', '--others', '--exclude-standard', '-z'], run)),
+    ];
+    if (remaining.length > 0) {
+        throw new Error(`Local deployment child changed source outside exact tool-owned files: ${remaining.sort().join(', ')}.`);
+    }
+}
+function projectInventory(context, stage, phase, action) {
+    const projects = Object.entries(context.projectsConfigurations?.projects ?? {}).map(([name, configuration]) => ({
+        name,
+        tags: configuration.tags,
+        targets: configuration.targets,
+    }));
+    const policy = (0, index_js_2.readRepositoryOperatingPolicy)(context.root);
+    const foundations = projects
+        .filter(({ tags }) => tags?.includes('scope:foundation'))
+        .map(({ name }) => name);
+    if (foundations.length !== 1) {
+        throw new Error('Local deployment requires exactly one Foundation project.');
+    }
+    if (phase === 'foundation-bootstrap') {
+        return foundations;
+    }
+    if (stage !== 'development') {
+        return (0, index_js_2.createProtectedDeploymentPlan)(policy, {
+            action,
+            projects,
+            stage,
+        }).orderedProjects;
+    }
+    const slices = projects
+        .filter(({ tags }) => tags?.includes('type:slice'))
+        .map(({ name }) => name)
+        .sort();
+    return [foundations[0], ...slices];
+}
+function runNx(context, project, target, forwarded, environment, run) {
+    const result = run(process.execPath, [
+        (0, node_path_1.join)(context.root, 'node_modules', 'nx', 'dist', 'bin', 'nx.js'),
+        'run',
+        `${project}:${target}`,
+        '--',
+        ...forwarded,
+    ], {
+        cwd: context.root,
+        encoding: 'utf8',
+        env: environment,
+        maxBuffer: 16 * 1024 * 1024,
+        shell: false,
+        stdio: 'inherit',
+    });
+    if (result.status !== 0) {
+        throw new Error(`Local ${target} failed for ${project}.`);
+    }
+}
+function runNxWithToolOwnedSourceReconciliation(context, project, target, forwarded, environment, snapshots, run, acceptExecutionFailure) {
+    let executionError;
+    try {
+        runNx(context, project, target, forwarded, environment, run);
+    }
+    catch (error) {
+        executionError = error;
+    }
+    let reconciliationError;
+    try {
+        reconcileToolOwnedSource(context.root, snapshots, run);
+    }
+    catch (error) {
+        reconciliationError = error;
+    }
+    if (executionError !== undefined && reconciliationError !== undefined) {
+        throw new Error(`Local ${target} and tool-owned source reconciliation both failed for ${project}. Execution: ${executionError instanceof Error ? executionError.message : String(executionError)} Reconciliation: ${reconciliationError instanceof Error ? reconciliationError.message : String(reconciliationError)}`);
+    }
+    if (reconciliationError !== undefined)
+        throw reconciliationError;
+    if (executionError !== undefined) {
+        let accepted = false;
+        try {
+            accepted = acceptExecutionFailure?.() === true;
+        }
+        catch {
+            accepted = false;
+        }
+        if (!accepted)
+            throw executionError;
+    }
+}
+function record(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object.`);
+    }
+    return value;
+}
+function retainedPlan(context, project, deploymentSourceCommit, account, region, stage, action) {
+    const configured = context.projectsConfigurations?.projects[project]?.root;
+    if (!configured) {
+        throw new Error(`Local deployment references unknown project ${project}.`);
+    }
+    const workspaceRoot = (0, node_fs_1.realpathSync)(context.root);
+    const projectRoot = (0, node_fs_1.realpathSync)((0, node_path_1.isAbsolute)(configured) ? configured : (0, node_path_1.join)(workspaceRoot, configured));
+    const projectRelative = (0, node_path_1.relative)(workspaceRoot, projectRoot);
+    if (projectRelative === '..' ||
+        projectRelative.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
+        (0, node_path_1.isAbsolute)(projectRelative)) {
+        throw new Error(`Local deployment project ${project} escapes the workspace.`);
+    }
+    const path = (0, node_path_1.join)(projectRoot, '.ebk', 'evidence', 'infrastructure-plan.json');
+    const before = (0, node_fs_1.lstatSync)(path, { bigint: true });
+    if (!before.isFile() ||
+        before.nlink !== 1n ||
+        before.size > BigInt(MAX_PLAN_BYTES)) {
+        throw new Error(`Local deployment plan for ${project} is not one bounded regular file.`);
+    }
+    const bytes = (0, node_fs_1.readFileSync)(path);
+    const after = (0, node_fs_1.lstatSync)(path, { bigint: true });
+    if (before.dev !== after.dev ||
+        before.ino !== after.ino ||
+        before.mode !== after.mode ||
+        before.nlink !== after.nlink ||
+        before.size !== after.size ||
+        before.mtimeNs !== after.mtimeNs ||
+        before.ctimeNs !== after.ctimeNs ||
+        BigInt(bytes.byteLength) !== after.size) {
+        throw new Error(`Local deployment plan for ${project} changed while it was read.`);
+    }
+    let parsed;
+    try {
+        parsed = record(JSON.parse(bytes.toString('utf8')), `${project} plan`);
+    }
+    catch {
+        throw new Error(`Local deployment plan for ${project} is invalid JSON.`);
+    }
+    const plan = parsed;
+    if (plan.kind !== index_js_1.INFRASTRUCTURE_PLAN_KIND ||
+        plan.schemaVersion !== index_js_1.INFRASTRUCTURE_CHANGE_SCHEMA_VERSION ||
+        plan.action !== action ||
+        !SHA.test(plan.sourceCommit) ||
+        plan.target?.accountFingerprint !== digest(account) ||
+        plan.target?.region !== region ||
+        plan.target?.stage !== stage ||
+        !Array.isArray(plan.projects) ||
+        plan.projects.length !== 1 ||
+        plan.projects[0] !== project ||
+        !SHA256.test(plan.materialDigest) ||
+        (0, index_js_1.computeMaterialPlanDigest)(plan) !== plan.materialDigest) {
+        throw new Error(`Local deployment plan for ${project} is not the exact current deployment authority.`);
+    }
+    if (plan.sourceCommit !== deploymentSourceCommit) {
+        try {
+            (0, source_authority_js_1.validateReviewedReleaseCheckout)({
+                deploymentSourceCommit,
+                releaseSourceCommit: plan.sourceCommit,
+                repositoryRoot: context.root,
+                reviewedSourceCommit: deploymentSourceCommit,
+            });
+        }
+        catch {
+            throw new Error(`Local deployment plan for ${project} is not bound through one exact approval-only source transition.`);
+        }
+    }
+    return plan;
+}
+function hasExactPendingLocalAuthorizationRefusal(context, project, plan) {
+    const path = projectEvidencePath(context, project, 'infrastructure-plan-authorization.json');
+    try {
+        const before = (0, node_fs_1.lstatSync)(path, { bigint: true });
+        if (!before.isFile() ||
+            before.nlink !== 1n ||
+            before.size > BigInt(MAX_PLAN_BYTES)) {
+            return false;
+        }
+        const bytes = (0, node_fs_1.readFileSync)(path);
+        const after = (0, node_fs_1.lstatSync)(path, { bigint: true });
+        if (before.dev !== after.dev ||
+            before.ino !== after.ino ||
+            before.mode !== after.mode ||
+            before.nlink !== after.nlink ||
+            before.size !== after.size ||
+            before.mtimeNs !== after.mtimeNs ||
+            before.ctimeNs !== after.ctimeNs ||
+            BigInt(bytes.byteLength) !== after.size) {
+            return false;
+        }
+        const authorization = record(JSON.parse(bytes.toString('utf8')), `${project} authorization`);
+        return (authorization.kind === 'ebk-infrastructure-authorization' &&
+            authorization.schemaVersion === index_js_1.INFRASTRUCTURE_CHANGE_SCHEMA_VERSION &&
+            authorization.action === 'deploy' &&
+            authorization.approval === undefined &&
+            authorization.localGovernance === undefined &&
+            authorization.governanceEvidenceDigests === undefined &&
+            authorization.plannedMaterialDigest === plan.materialDigest &&
+            authorization.recomputedMaterialDigest === plan.materialDigest &&
+            Array.isArray(authorization.sourceChangesSincePlan) &&
+            authorization.sourceChangesSincePlan.length === 0 &&
+            authorization.validation.allowed === false &&
+            authorization.validation.outcome === 'plan-risk-blocked' &&
+            authorization.validation.findings.length === 1 &&
+            authorization.validation.findings[0]?.code === 'approval-missing');
+    }
+    catch {
+        return false;
+    }
+}
+/** @internal */
+function localPlanSummaryDigest(input) {
+    const action = input.action ?? 'deploy';
+    if ((action !== 'deploy' && action !== 'refresh') ||
+        !/^\d{12}$/.test(input.account) ||
+        !SHA.test(input.sourceCommit) ||
+        !/^[a-z]{2}(?:-gov)?-[a-z]+-\d$/.test(input.region) ||
+        input.orderedProjects.length === 0 ||
+        new Set(input.orderedProjects).size !== input.orderedProjects.length ||
+        Object.keys(input.plans).length !== input.orderedProjects.length) {
+        throw new Error('Local deployment plan summary input is invalid.');
+    }
+    const plans = input.orderedProjects.map((project) => {
+        const plan = input.plans[project];
+        if (!plan ||
+            plan.action !== action ||
+            plan.projects.length !== 1 ||
+            plan.projects[0] !== project ||
+            !SHA256.test(plan.materialDigest)) {
+            throw new Error(`Local deployment plan summary omitted exact project ${project}.`);
+        }
+        return { materialDigest: plan.materialDigest, project };
+    });
+    return digest(JSON.stringify({
+        accountFingerprint: digest(input.account),
+        action,
+        orderedProjects: [...input.orderedProjects],
+        phase: input.phase,
+        plans,
+        region: input.region,
+        sourceCommit: input.sourceCommit,
+        stage: input.stage,
+    }));
+}
+function retainEvidence(root, evidence) {
+    const directory = (0, node_path_1.join)(root, '.ebk', 'evidence', 'local-deployment');
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.chmodSync)(directory, 0o700);
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(directory, 'latest.json'), `${JSON.stringify(evidence, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+const REFRESH_FRAMEWORK_TAG_OBSERVATION_PATHS = new Map([
+    ['/inputs/tagsAll/ebk:framework-version', true],
+    ['/outputs/tags/ebk:framework-version', false],
+    ['/outputs/tagsAll/ebk:framework-version', false],
+]);
+function isFrameworkTagProviderObservation(resource) {
+    if (resource.operation !== 'update' ||
+        resource.replacement ||
+        resource.resourceType !== 'aws:ssm/parameter:Parameter' ||
+        resource.changedProperties.length !==
+            REFRESH_FRAMEWORK_TAG_OBSERVATION_PATHS.size) {
+        return false;
+    }
+    const observed = new Set();
+    for (const property of resource.changedProperties) {
+        const expectedInputDiff = REFRESH_FRAMEWORK_TAG_OBSERVATION_PATHS.get(property.path);
+        if (expectedInputDiff === undefined ||
+            property.inputDiff !== expectedInputDiff ||
+            property.kind !== 'update' ||
+            property.sensitive ||
+            observed.has(property.path)) {
+            return false;
+        }
+        observed.add(property.path);
+    }
+    return observed.size === REFRESH_FRAMEWORK_TAG_OBSERVATION_PATHS.size;
+}
+function isSemanticallyConvergedRefresh(plan) {
+    if (plan.action !== 'refresh' ||
+        plan.state.locked ||
+        !plan.diff.complete ||
+        plan.diff.failures.length > 0) {
+        return false;
+    }
+    if (plan.diff.resources.length === 0) {
+        return plan.driftStatus === 'no-drift';
+    }
+    if (plan.driftStatus !== 'drift-detected' ||
+        !plan.diff.resources.every(isFrameworkTagProviderObservation) ||
+        plan.requiredApprovals.some((approval) => ![
+            'deployment-review',
+            'drift-decision-and-state-recovery',
+            'point-of-no-return',
+        ].includes(approval))) {
+        return false;
+    }
+    const observedResourceIds = new Set(plan.diff.resources.map(({ logicalId }) => logicalId));
+    return plan.resourceFindings.every((finding) => (finding.resourceId === undefined &&
+        finding.class === 'stateful-or-destructive' &&
+        finding.code === 'protected-state-refresh' &&
+        finding.disposition === 'block') ||
+        (finding.resourceId !== undefined &&
+            observedResourceIds.has(finding.resourceId) &&
+            finding.class === 'in-place-reviewed' &&
+            finding.code === 'in-place-update' &&
+            finding.disposition === 'review'));
+}
+function isSemanticallyConvergedDeploy(plan) {
+    if (plan.action !== 'deploy' ||
+        plan.state.locked !== false ||
+        !plan.diff.complete ||
+        plan.diff.failures.length > 0) {
+        return false;
+    }
+    if (plan.diff.resources.length === 0) {
+        return (plan.aggregateRisk === 'no-change' &&
+            plan.driftStatus === 'no-drift' &&
+            plan.requiredApprovals.length === 0 &&
+            plan.resourceFindings.length === 0);
+    }
+    if (plan.aggregateRisk !== 'in-place-reviewed' ||
+        (plan.driftStatus !== 'no-drift' &&
+            plan.driftStatus !== 'drift-detected') ||
+        plan.requiredApprovals.length !== 1 ||
+        plan.requiredApprovals[0] !== 'deployment-review') {
+        return false;
+    }
+    const providerReads = new Map();
+    for (const resource of plan.diff.resources) {
+        const retainedResourceType = providerReads.get(resource.logicalId);
+        if (resource.operation !== 'read' ||
+            resource.providerOperation !== 'read' ||
+            resource.replacement ||
+            resource.changedProperties.length > 0 ||
+            (retainedResourceType !== undefined &&
+                retainedResourceType !== resource.resourceType)) {
+            return false;
+        }
+        providerReads.set(resource.logicalId, resource.resourceType);
+    }
+    if (plan.resourceFindings.length !== providerReads.size) {
+        return false;
+    }
+    const providerReadFindings = new Set();
+    for (const finding of plan.resourceFindings) {
+        if (finding.resourceId === undefined ||
+            !providerReads.has(finding.resourceId) ||
+            finding.class !== 'in-place-reviewed' ||
+            finding.code !== 'provider-read' ||
+            finding.disposition !== 'review' ||
+            providerReadFindings.has(finding.resourceId)) {
+            return false;
+        }
+        providerReadFindings.add(finding.resourceId);
+    }
+    return providerReadFindings.size === providerReads.size;
+}
+function isFreshInvocationPlan(plan, invocationStartedAt, observedAt) {
+    const started = Date.parse(invocationStartedAt);
+    const generated = Date.parse(plan.generatedAt);
+    const observed = observedAt.getTime();
+    const expires = Date.parse(plan.expiresAt);
+    return (Number.isFinite(started) &&
+        Number.isFinite(generated) &&
+        Number.isFinite(observed) &&
+        Number.isFinite(expires) &&
+        generated >= started &&
+        generated <= observed &&
+        expires > observed);
+}
+async function runLocalDeploy(options, context, dependencies = {}) {
+    const run = dependencies.run ?? node_child_process_1.spawnSync;
+    if (process.env.GITHUB_ACTIONS === 'true') {
+        throw new Error('Local deployment is not a GitHub Actions authority mode.');
+    }
+    const policy = (0, index_js_2.readRepositoryOperatingPolicy)(context.root);
+    const action = options.action ?? 'deploy';
+    if (action !== 'deploy' && action !== 'refresh') {
+        throw new Error('Local infrastructure action is invalid.');
+    }
+    const phase = options.phase ?? 'full-stage';
+    if (phase !== 'foundation-bootstrap' && phase !== 'full-stage') {
+        throw new Error('Local deployment phase is invalid.');
+    }
+    if ((0, index_js_2.requiresGithubDeployment)(policy.deploymentProfile, options.stage)) {
+        throw new Error(`The ${policy.deploymentProfile} deployment profile requires GitHub deployment authority for ${options.stage}.`);
+    }
+    const accounts = (0, index_js_2.configuredDeploymentAccountTopology)(policy.deploymentProfile, policy.deploymentAccounts);
+    const region = (0, index_js_2.configuredDeploymentRegion)(policy.deploymentRegion);
+    const expectedAccount = accounts[options.stage];
+    if (!ROLE.test(options.expectedRoleArn)) {
+        throw new Error('Local deployment requires one exact expected IAM role ARN.');
+    }
+    const status = git(context.root, ['status', '--porcelain=v1', '--untracked-files=all'], run);
+    if (status !== '') {
+        throw new Error('Local deployment requires a completely clean source tree.');
+    }
+    const sourceCommit = git(context.root, ['rev-parse', 'HEAD'], run);
+    const sourceTree = git(context.root, ['rev-parse', 'HEAD^{tree}'], run);
+    if (!SHA.test(sourceCommit) || !SHA.test(sourceTree)) {
+        throw new Error('Local deployment could not bind one immutable Git source.');
+    }
+    const expectedConfirmation = (0, infrastructure_plan_js_1.localProductionConfirmation)({
+        action,
+        accountId: expectedAccount,
+        region,
+        sourceCommit,
+    });
+    if (options.stage === 'production' &&
+        options.confirmation !== expectedConfirmation) {
+        throw new Error(`Local production ${action} requires --confirmation=${expectedConfirmation}.`);
+    }
+    const caller = await (dependencies.caller ??
+        (async (targetRegion) => new client_sts_1.STSClient({
+            region: targetRegion,
+            ...(options.profile
+                ? { credentials: (0, credential_providers_1.fromIni)({ profile: options.profile }) }
+                : {}),
+        }).send(new client_sts_1.GetCallerIdentityCommand({}))))(region);
+    const account = caller.Account?.trim() ?? '';
+    const arn = caller.Arn?.trim() ?? '';
+    if (account !== expectedAccount ||
+        !(0, infrastructure_plan_js_1.matchesExpectedAssumedRoleArn)(expectedAccount, arn, options.expectedRoleArn)) {
+        throw new Error('Local AWS caller does not match the committed account and exact temporary assumed role.');
+    }
+    const orderedProjects = projectInventory(context, options.stage, phase, action);
+    const sourceSnapshots = toolOwnedSourceSnapshots(context, orderedProjects);
+    const startedAt = (dependencies.now ?? (() => new Date()))().toISOString();
+    let backend;
+    let result = 'failed';
+    let planDigests = {};
+    let planSummaryDigest = null;
+    let deployNoOpProjects = [];
+    const mutatedProjects = [];
+    let operatorAcknowledgementDigest = null;
+    let replanRequiredProject = null;
+    let refreshNoOpProjects = [];
+    try {
+        backend = await (dependencies.backend ?? prepareLocalSstBackend)({
+            account: expectedAccount,
+            applications: orderedProjects,
+            ...(options.profile ? { profile: options.profile } : {}),
+            region,
+            stage: options.stage,
+        });
+        const environment = {
+            ...process.env,
+            AWS_EXPECTED_ACCOUNT_ID: expectedAccount,
+            AWS_PLAN_ROLE_ARN: options.expectedRoleArn,
+            AWS_PLAN_SST_APPS_JSON: JSON.stringify(orderedProjects),
+            AWS_PLAN_STATE_BUCKET_ARN: backend.stateBucketArn,
+            ...(options.profile ? { AWS_PROFILE: options.profile } : {}),
+            AWS_REGION: region,
+            // Local deployment's reviewed clean Git commit is the one stage-wide
+            // workload-role candidate shared by Foundation and every Slice. Never
+            // accept an ambient candidate identity from the caller.
+            EBK_ACTION: action,
+            EBK_CANDIDATE_IDENTITY: sourceCommit,
+            EBK_LOCAL_DEPLOYMENT_MODE: 'federated',
+            EBK_LOCAL_SOURCE_TREE: sourceTree,
+            EBK_SOURCE_COMMIT: sourceCommit,
+            EBK_STAGE: options.stage,
+            ORDERED_PROJECTS: orderedProjects.join(','),
+        };
+        for (const key of PROTECTED_PLAN_KEYS)
+            delete environment[key];
+        if (options.profile) {
+            for (const key of AMBIENT_CREDENTIAL_KEYS)
+                delete environment[key];
+        }
+        const common = [
+            `--stage=${options.stage}`,
+            `--expectedRoleArn=${options.expectedRoleArn}`,
+            `--region=${region}`,
+            ...(options.profile ? [`--profile=${options.profile}`] : []),
+        ];
+        for (const project of orderedProjects) {
+            runNxWithToolOwnedSourceReconciliation(context, project, 'infrastructure-plan', [`--action=${action}`, ...common], environment, sourceSnapshots, run, action === 'deploy'
+                ? () => {
+                    const plan = retainedPlan(context, project, sourceCommit, expectedAccount, region, options.stage, action);
+                    const accepted = isFreshInvocationPlan(plan, startedAt, (dependencies.now ?? (() => new Date()))()) &&
+                        isSemanticallyConvergedDeploy(plan) &&
+                        hasExactPendingLocalAuthorizationRefusal(context, project, plan);
+                    if (accepted) {
+                        devkit_1.logger.info(`Local infrastructure-plan for ${project} returned a conservative non-success after emitting one fresh provider-read-only semantic convergence record.`);
+                    }
+                    return accepted;
+                }
+                : undefined);
+        }
+        const plans = Object.fromEntries(orderedProjects.map((project) => [
+            project,
+            retainedPlan(context, project, sourceCommit, expectedAccount, region, options.stage, action),
+        ]));
+        planDigests = Object.fromEntries(orderedProjects.map((project) => [
+            project,
+            plans[project].materialDigest,
+        ]));
+        planSummaryDigest = localPlanSummaryDigest({
+            account: expectedAccount,
+            action,
+            orderedProjects,
+            phase,
+            plans,
+            region,
+            sourceCommit,
+            stage: options.stage,
+        });
+        const approvalEnvironment = {
+            ...environment,
+            EBK_LOCAL_PLAN_APPROVER_ARN: arn,
+            EBK_LOCAL_PLAN_SUMMARY_DIGEST: planSummaryDigest,
+        };
+        const planEnvironment = (project) => plans[project].requiredApprovals.length > 0
+            ? {
+                ...approvalEnvironment,
+                EBK_LOCAL_PLAN_MATERIAL_DIGEST: plans[project].materialDigest,
+            }
+            : environment;
+        deployNoOpProjects =
+            action === 'deploy'
+                ? orderedProjects.filter((project) => isSemanticallyConvergedDeploy(plans[project]))
+                : [];
+        refreshNoOpProjects =
+            action === 'refresh'
+                ? orderedProjects.filter((project) => isSemanticallyConvergedRefresh(plans[project]))
+                : [];
+        const mutationNoOpProjectSet = new Set([
+            ...deployNoOpProjects,
+            ...refreshNoOpProjects,
+        ]);
+        const materialProjectIndex = orderedProjects.findIndex((project) => !mutationNoOpProjectSet.has(project));
+        if (materialProjectIndex >= 0) {
+            const project = orderedProjects[materialProjectIndex];
+            const plan = plans[project];
+            const challenge = `approve:${action}:${options.stage}:${project}:${plan.materialDigest}`;
+            devkit_1.logger.info(`[ebk-local-deployment-review]\n${JSON.stringify({
+                action,
+                challenge,
+                firstMaterialProject: project,
+                orderedProjects,
+                plan: {
+                    aggregateRisk: plan.aggregateRisk,
+                    diff: plan.diff,
+                    materialDigest: plan.materialDigest,
+                    requiredApprovals: plan.requiredApprovals,
+                    resourceFindings: plan.resourceFindings,
+                    stateDigest: plan.state.digest,
+                },
+                planSummaryDigest,
+                sourceCommit,
+                stage: options.stage,
+            }, null, 2)}`);
+            let acknowledged = false;
+            try {
+                acknowledged = await (dependencies.approve ?? (0, local_approval_js_1.createTtyLocalMutationApprover)())({
+                    action,
+                    challenge,
+                    planDigest: plan.materialDigest,
+                    project,
+                    stage: options.stage,
+                });
+            }
+            catch (error) {
+                if (error instanceof local_approval_js_1.LocalMutationApprovalUnavailableError) {
+                    result = 'review-required';
+                }
+                throw error;
+            }
+            if (!acknowledged) {
+                result = 'review-required';
+                throw new Error(`Local ${action} acknowledgement was declined for ${project}.`);
+            }
+            operatorAcknowledgementDigest = digest(challenge);
+            const issuedAt = (dependencies.now ?? (() => new Date()))();
+            (0, infrastructure_plan_js_1.authorizeRetainedLocalInfrastructurePlan)({
+                context: { ...context, projectName: project },
+                environment: planEnvironment(project),
+                now: issuedAt,
+                plan,
+            });
+            if (retainedPlan(context, project, sourceCommit, expectedAccount, region, options.stage, action).materialDigest !== planDigests[project]) {
+                throw new Error(`Local deployment plan for ${project} changed before invocation-scoped authority was established.`);
+            }
+            const capability = writeLocalMutationCapability({
+                actorArn: arn,
+                context,
+                deploymentProfile: policy.deploymentProfile,
+                deploymentSourceCommit: sourceCommit,
+                deploymentSourceTree: sourceTree,
+                expectedRoleArn: options.expectedRoleArn,
+                issuedAt,
+                plan,
+                project,
+                releaseSourceTree: git(context.root, ['rev-parse', `${plan.sourceCommit}^{tree}`], run),
+            });
+            try {
+                runNxWithToolOwnedSourceReconciliation(context, project, action, [
+                    ...common,
+                    ...(options.stage === 'production'
+                        ? [`--localProductionConfirmation=${expectedConfirmation}`]
+                        : []),
+                ], {
+                    ...environment,
+                    EBK_LOCAL_MUTATION_CAPABILITY_NONCE: capability.nonce,
+                    EBK_LOCAL_MUTATION_CAPABILITY_PATH: capability.path,
+                }, sourceSnapshots, run);
+            }
+            finally {
+                (0, node_fs_1.rmSync)(capability.directory, { force: true, recursive: true });
+            }
+            mutatedProjects.push(project);
+            result = 'replan-required';
+            replanRequiredProject = orderedProjects[materialProjectIndex + 1] ?? null;
+            throw new Error(replanRequiredProject
+                ? `Local deployment applied ${project} and requires a new complete-stage plan before ${replanRequiredProject}. Rerun and acknowledge the new current plan before any further mutation.`
+                : `Local deployment applied ${project} and requires a new complete-stage plan before accepting stage convergence. Rerun and require every current project to be a semantic no-op.`);
+        }
+        result = 'succeeded';
+        return { success: true };
+    }
+    finally {
+        retainEvidence(context.root, {
+            account: expectedAccount,
+            action,
+            actorArnDigest: digest(arn),
+            backendAuthorityDigest: backend?.authorityDigest ?? null,
+            backendCreatedApplications: backend
+                ? [...backend.createdApplications]
+                : [],
+            completedAt: (dependencies.now ?? (() => new Date()))().toISOString(),
+            deployNoOpProjects,
+            kind: 'ebk-local-deployment-evidence',
+            mutatedProjects,
+            orderedProjects,
+            operatorAcknowledgementDigest,
+            planDigests,
+            planSummaryDigest,
+            phase,
+            profile: policy.deploymentProfile,
+            replanRequiredProject,
+            refreshNoOpProjects,
+            region,
+            result,
+            schemaVersion: 1,
+            sourceCommit,
+            sourceDigest: digest(`${sourceCommit}:${sourceTree}`),
+            stage: options.stage,
+            startedAt,
+        });
+    }
+}
+const executor = async (options, context) => {
+    try {
+        return await runLocalDeploy(options, context);
+    }
+    catch (error) {
+        devkit_1.logger.error(error instanceof Error ? error.message : String(error));
+        return { success: false };
+    }
+};
+exports.default = executor;
+//# sourceMappingURL=local-deploy.js.map