@empire-builder-kit/nx 1.0.0-rc.38 → 1.0.0-rc.39

package/src/executors/sst-lifecycle/run-sst-command.js

@@ -19,11 +19,16 @@ const child_environment_js_1 = require("../../aws/child-environment.js");
 const identity_js_1 = require("../../aws/identity.js");
 const stages_js_1 = require("../../foundation/stages.js");
 const personal_stage_js_1 = require("../../local-dev/personal-stage.js");
+const task_identity_js_1 = require("../../local-dev/task-identity.js");
 const federated_credential_transport_js_1 = require("../local-deploy/federated-credential-transport.js");
 const index_js_2 = require("../../repository-policy/index.js");
 const index_js_3 = require("../../workspace-deployment/index.js");
 const index_js_4 = require("../../work-markers/index.js");
 const secret_preflight_js_1 = require("./secret-preflight.js");
+const task_native_writer_js_1 = require("../../local-dev/task-native-writer.js");
+const local_deploy_js_1 = require("../local-deploy/local-deploy.js");
+const task_stack_absence_js_1 = require("../dev-task-cleanup/task-stack-absence.js");
+const process_group_js_1 = require("../../local-dev/process-group.js");
 const secret_initialize_js_1 = require("../secret-initialize/secret-initialize.js");
 const generated_secret_retirement_js_1 = require("./generated-secret-retirement.js");
 const sst_environment_source_js_1 = require("./sst-environment-source.js");
@@ -40,8 +45,8 @@ const SST_DEV_MODES = new Set(['basic', 'mono']);
 const AWS_REGION_PATTERN = /^[a-z]{2}(?:-gov)?-[a-z]+-\d$/;
 const AWS_ROLE_ARN_PATTERN = /^arn:(aws|aws-us-gov|aws-cn):iam::\d{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
 const MAX_CALLER_IDENTITY_BYTES = 1024 * 1024;
-const SST_SIGNAL_GRACE_PERIOD_MS = 10_000;
-const SST_SIGNAL_KILL_WAIT_MS = 5_000;
+const SST_SIGNAL_GRACE_PERIOD_MS = process_group_js_1.OWNED_PROCESS_SIGNAL_GRACE_MS;
+const SST_SIGNAL_KILL_WAIT_MS = process_group_js_1.OWNED_PROCESS_KILL_WAIT_MS;
 const SST_PROCESS_GROUP_POLL_MS = 25;
 const GOVERNED_PROCESS_GROUP_ENV = 'EBK_GOVERNED_PROCESS_GROUP';
 function assertGovernedAwsLifecyclePlatform(platform = process.platform) {
@@ -119,15 +124,7 @@ function signalExactGovernedProcessTree(child, signal) {
 function exactGovernedProcessTreeExists(pid) {
     if (process.platform === 'win32')
         return false;
-    try {
-        process.kill(-pid, 0);
-        return true;
-    }
-    catch (error) {
-        if (isMissingProcessError(error))
-            return false;
-        throw error;
-    }
+    return (0, process_group_js_1.exactOwnedProcessGroupExists)(pid);
 }
 async function waitForExactGovernedProcessTreeExit(pid, deadline = Date.now() + SST_SIGNAL_GRACE_PERIOD_MS + SST_SIGNAL_KILL_WAIT_MS) {
     while (exactGovernedProcessTreeExists(pid)) {
@@ -248,6 +245,7 @@ function runGovernedChildProcess(input) {
         });
         let finishing = false;
         let settled = false;
+        let cancellationSignal;
         let spawnError;
         let unregisterSignalCleanup = () => undefined;
         let resolveChildSettled = () => undefined;
@@ -277,6 +275,9 @@ function runGovernedChildProcess(input) {
                 }
             }
             try {
+                // A child may acknowledge cancellation with exit zero. Preserve the
+                // observed parent signal before callers reconcile a successful close.
+                result.signal ??= cancellationSignal ?? null;
                 await input.afterClose?.(result);
             }
             catch (error) {
@@ -285,12 +286,18 @@ function runGovernedChildProcess(input) {
                         ? error
                         : new Error('Governed child close reconciliation failed.');
             }
+            result.signal ??= cancellationSignal ?? null;
             settled = true;
             unregisterSignalCleanup();
             resolveChildSettled();
             resolveChildRun(result);
         };
-        unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => stopExactGovernedProcessTree(child, signal, childSettled, () => settled), 100);
+        unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => {
+            if (settled)
+                return;
+            cancellationSignal ??= signal;
+            return stopExactGovernedProcessTree(child, signal, childSettled, () => settled);
+        }, 100);
         child.once('error', (error) => {
             spawnError = error;
             void finish(null, null);
@@ -323,7 +330,8 @@ function captureSstEnvironmentSource(context) {
     });
 }
 function requiresSourceReconciliation(command, stage) {
-    return (GOVERNED_STAGES.has(stage) &&
+    return ((GOVERNED_STAGES.has(stage) ||
+        (command === 'remove' && /^personal-[a-f0-9]{24}$/.test(stage))) &&
         (command === 'deploy' || command === 'refresh' || command === 'remove'));
 }
 function isGovernedLocalCommand(command) {
@@ -403,6 +411,8 @@ function createSstChildEnvironment(ambient, invocation) {
     delete sanitized.EBK_LOCAL_MUTATION_CAPABILITY_PATH;
     delete sanitized.EBK_GITHUB_JOB_WORKFLOW_REF;
     delete sanitized.EBK_NX_STAGE_LIFECYCLE;
+    delete sanitized.EBK_NX_TASK_CLEANUP;
+    delete sanitized.EBK_NX_TASK_UNLOCK;
     // Nx injects task identity, target, hash, terminal, cache, and invocation
     // metadata into every executor process. Those values describe orchestration,
     // not desired infrastructure. Never let them reach SST, where build tools
@@ -412,7 +422,9 @@ function createSstChildEnvironment(ambient, invocation) {
             delete sanitized[name];
         }
     }
-    return { ...sanitized, ...invocation };
+    const childEnvironment = { ...sanitized, ...invocation };
+    delete childEnvironment.EBK_NX_TASK_UNLOCK;
+    return childEnvironment;
 }
 function assertSafeSstForwardedArguments(args) {
     const reserved = args.find((argument) => {
@@ -535,7 +547,7 @@ function buildSstCommandInvocation(command, options, context, environment = proc
             }
             return {
                 consumerStage: (dependencies.personalStageResolver ??
-                    (0, personal_stage_js_1.createPersonalStageResolver)()).resolve().stage,
+                    (0, personal_stage_js_1.createPersonalStageResolver)()).resolve(context.root).stage,
                 foundationStage: 'development',
                 mapped: true,
             };
@@ -550,7 +562,61 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         stages.mapped) {
         throw new Error(`Full deploy is not permitted for mapped personal stage ${stages.consumerStage}. Use ebk dev against the ${stages.foundationStage} Foundation.`);
     }
+    const taskCleanup = environment.EBK_NX_TASK_CLEANUP !== undefined;
+    const taskUnlock = environment.EBK_NX_TASK_UNLOCK !== undefined;
+    if (taskUnlock) {
+        if (taskCleanup ||
+            command !== 'unlock' ||
+            kind !== 'slice' ||
+            environment.GITHUB_ACTIONS === 'true' ||
+            options.args !== undefined ||
+            options.cwd !== undefined ||
+            options.target !== undefined ||
+            !stages.mapped ||
+            stages.foundationStage !== 'development') {
+            throw new Error('Task unlock is restricted to the current local Slice task.');
+        }
+        const task = (0, task_identity_js_1.resolveTaskIdentity)(context.root);
+        if (environment.EBK_NX_TASK_UNLOCK !== task.taskId ||
+            stages.consumerStage !== `personal-${task.taskId}`) {
+            throw new Error('Task unlock cannot select another task or stage.');
+        }
+        const source = (0, local_deploy_js_1.localWorkingTreeDigest)(context.root);
+        if (source.commit !== environment.EBK_SOURCE_COMMIT ||
+            source.digest !== environment.EBK_LOCAL_SOURCE_TREE) {
+            throw new Error('Task unlock requires the exact authorized source tree.');
+        }
+        (0, task_stack_absence_js_1.resolveStaticTaskApp)({
+            workspaceRoot: context.root,
+            projectRoot: cwd,
+            projectName: context.projectName ?? '',
+        });
+    }
+    else if (command === 'unlock' && stages.mapped) {
+        throw new Error('Personal task unlock requires the current-task governed adapter.');
+    }
+    if (taskCleanup) {
+        if (command !== 'remove' ||
+            kind !== 'slice' ||
+            environment.GITHUB_ACTIONS === 'true' ||
+            options.args !== undefined ||
+            options.cwd !== undefined ||
+            options.target !== undefined ||
+            !stages.mapped ||
+            stages.foundationStage !== 'development')
+            throw new Error('Task cleanup is restricted to the current local Slice task and native removal.');
+        const task = (0, task_identity_js_1.resolveTaskIdentity)(context.root);
+        if (environment.EBK_NX_TASK_CLEANUP !== task.taskId ||
+            stages.consumerStage !== `personal-${task.taskId}`) {
+            throw new Error('Task cleanup cannot select another task or stage.');
+        }
+    }
+    else if (command === 'remove' && stages.mapped) {
+        throw new Error('Personal task removal is owned by ebk dev down; canonical remove cannot select a task.');
+    }
     const operatingPolicy = command === 'dev' ||
+        taskCleanup ||
+        taskUnlock ||
         (DEPLOYMENT_STAGES.has(stages.consumerStage) &&
             (command === 'deploy' ||
                 command === 'refresh' ||
@@ -559,7 +625,7 @@ function buildSstCommandInvocation(command, options, context, environment = proc
         ? (0, index_js_2.readRepositoryOperatingPolicy)(context.root)
         : undefined;
     assertSstLifecyclePolicy(command, stages.consumerStage, environment, operatingPolicy?.deploymentProfile);
-    const authorityStage = command === 'dev'
+    const authorityStage = command === 'dev' || taskCleanup || taskUnlock
         ? 'development'
         : stages.consumerStage;
     const deploymentAccount = operatingPolicy
@@ -568,6 +634,16 @@ function buildSstCommandInvocation(command, options, context, environment = proc
     const deploymentRegion = operatingPolicy
         ? (0, index_js_2.configuredDeploymentRegion)(operatingPolicy.deploymentRegion)
         : undefined;
+    if ((taskCleanup || taskUnlock) && deploymentAccount && deploymentRegion) {
+        // This read cannot create or reassign the binding. The executor separately
+        // verifies the current caller and Foundation owner before constructing SST.
+        const owner = (0, index_js_2.readRepositoryOperatingPolicy)(context.root);
+        (0, task_identity_js_1.assertCurrentTaskEnvironment)(context.root, {
+            accountId: deploymentAccount,
+            region: deploymentRegion,
+            workspaceDeploymentId: owner.workspaceDeploymentId,
+        });
+    }
     if (deploymentRegion &&
         options.region?.trim() &&
         options.region.trim() !== deploymentRegion) {
@@ -662,6 +738,12 @@ function buildSstCommandInvocation(command, options, context, environment = proc
                     ? { AWS_REGION: options.region.trim() }
                     : {}),
             EBK_CONSUMER_STAGE: stages.consumerStage,
+            ...(taskCleanup
+                ? { EBK_NX_TASK_CLEANUP: environment.EBK_NX_TASK_CLEANUP }
+                : {}),
+            ...(taskUnlock
+                ? { EBK_NX_TASK_UNLOCK: environment.EBK_NX_TASK_UNLOCK }
+                : {}),
             ...((committedRoleArn ?? options.expectedRoleArn?.trim())
                 ? {
                     EBK_EXPECTED_DEPLOYMENT_ROLE_ARN: committedRoleArn ?? options.expectedRoleArn?.trim(),
@@ -678,7 +760,41 @@ function buildSstCommandInvocation(command, options, context, environment = proc
     };
 }
 async function runSstLifecyclePreflights(command, options, context, invocation, dependencies = {}, environment = process.env) {
-    const stage = command === 'dev'
+    // Standard Slices contain a Python infrastructure provisioner even when
+    // their application handlers are TypeScript. Fail before SST can partially
+    // create resources; recovery operations must remain available without build
+    // tooling. This is a local prerequisite, not a provider-plan gate.
+    if ((command === 'dev' || command === 'deploy') &&
+        (0, node_fs_1.existsSync)((0, node_path_1.join)(invocation.cwd, 'pyproject.toml'))) {
+        const manifest = (0, node_fs_1.lstatSync)((0, node_path_1.join)(invocation.cwd, 'pyproject.toml'));
+        if (!manifest.isFile() || manifest.isSymbolicLink()) {
+            throw new Error('Python tooling manifest must be a regular project file.');
+        }
+        const childEnvironment = {};
+        for (const key of ['PATH', 'Path', 'PATHEXT', 'SystemRoot', 'SYSTEMROOT']) {
+            if (environment[key] !== undefined)
+                childEnvironment[key] = environment[key];
+        }
+        const result = (0, node_child_process_1.spawnSync)('uv', ['--version'], {
+            cwd: invocation.cwd,
+            env: childEnvironment,
+            encoding: 'utf8',
+            timeout: 5_000,
+            maxBuffer: 4_096,
+            windowsHide: true,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.error ||
+            result.status !== 0 ||
+            !/^uv \d+\.\d+\.\d+\b/.test(result.stdout ?? '')) {
+            // Do not surface arbitrary tool stderr or inherited credential material.
+            throw new Error(`Python tooling for ${context.projectName ?? 'the selected project'} requires uv on PATH. Install the workspace-documented uv version and retry the same EBK command. No SST child started.`);
+        }
+    }
+    const stage = command === 'dev' ||
+        (command === 'remove' && invocation.environment.EBK_NX_TASK_CLEANUP) ||
+        (command === 'unlock' && invocation.environment.EBK_NX_TASK_UNLOCK)
         ? 'development'
         : invocation.environment.EBK_CONSUMER_STAGE;
     await (dependencies.ownership ?? index_js_3.assertWorkspaceStageOwnershipForWorkspace)(context.root, stage, {
@@ -704,14 +820,17 @@ async function runSstLifecyclePreflights(command, options, context, invocation,
     }
 }
 async function runSstCommand(command, options, context, dependencies = {}) {
-    if (command !== 'dev') {
+    const environment = dependencies.environment ?? process.env;
+    if (command !== 'dev' &&
+        !(command === 'remove' && environment.EBK_NX_TASK_CLEANUP !== undefined) &&
+        !(command === 'unlock' && environment.EBK_NX_TASK_UNLOCK !== undefined)) {
         assertGovernedAwsLifecyclePlatform(dependencies.platform);
     }
-    const environment = dependencies.environment ?? process.env;
     const joinsGovernedProcessGroup = process.platform !== 'win32' &&
         environment[GOVERNED_PROCESS_GROUP_ENV] === '1';
     let invocation;
     let environmentSource;
+    let taskWriter;
     try {
         invocation = buildSstCommandInvocation(command, options, context, environment);
         if (requiresSourceReconciliation(command, invocation.environment.EBK_CONSUMER_STAGE)) {
@@ -723,9 +842,27 @@ async function runSstCommand(command, options, context, dependencies = {}) {
         await runSstLifecyclePreflights(command, options, context, invocation, dependencies, environment);
         if (environmentSource)
             (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(environmentSource);
+        if (command === 'dev' ||
+            invocation.environment.EBK_NX_TASK_CLEANUP ||
+            invocation.environment.EBK_NX_TASK_UNLOCK) {
+            // Rebuild after asynchronous authorization: source, task owner, and
+            // committed account/Region must still agree immediately before spawn.
+            const current = buildSstCommandInvocation(command, options, context, environment);
+            if (JSON.stringify(current) !== JSON.stringify(invocation))
+                throw new Error('Task native invocation changed during preflight.');
+            taskWriter = (dependencies.acquireTaskWriter ?? task_native_writer_js_1.acquireTaskNativeWriterLease)(context, invocation.environment.EBK_CONSUMER_STAGE.slice('personal-'.length), command === 'unlock', dependencies.taskNativeWriterEffects);
+            taskWriter.assertCurrent();
+        }
     }
     catch (error) {
         let restorationError;
+        try {
+            // No native child has been spawned during this preflight phase.
+            taskWriter?.release();
+        }
+        catch (releaseError) {
+            devkit_1.logger.error(`Task native writer preflight evidence retained: ${releaseError instanceof Error ? releaseError.message : String(releaseError)}`);
+        }
         if (environmentSource) {
             try {
                 (0, sst_environment_source_js_1.reconcileSstEnvironmentSourceTree)(environmentSource);
@@ -744,14 +881,31 @@ async function runSstCommand(command, options, context, dependencies = {}) {
     }
     devkit_1.logger.info(`Running workspace SST: ${command} --stage ${invocation.environment.EBK_CONSUMER_STAGE} foundationStage=${invocation.environment.EBK_FOUNDATION_STAGE} (${invocation.cwd})`);
     return new Promise((resolve) => {
-        const child = (dependencies.spawnChild ?? node_child_process_1.spawn)(invocation.executable, invocation.args, {
-            cwd: invocation.cwd,
-            detached: process.platform !== 'win32' && !joinsGovernedProcessGroup,
-            env: createSstChildEnvironment(environment, invocation.environment),
-            shell: false,
-            stdio: 'inherit',
-        });
+        let child;
+        try {
+            taskWriter?.assertCurrent();
+            child = (dependencies.spawnChild ?? node_child_process_1.spawn)(invocation.executable, invocation.args, {
+                cwd: invocation.cwd,
+                detached: process.platform !== 'win32' && !joinsGovernedProcessGroup,
+                env: createSstChildEnvironment(environment, invocation.environment),
+                shell: false,
+                stdio: 'inherit',
+            });
+        }
+        catch (error) {
+            try {
+                taskWriter?.release();
+            }
+            catch {
+                /* Keep ambiguous lease evidence. */
+            }
+            devkit_1.logger.error(error instanceof Error ? error.message : String(error));
+            resolve({ success: false });
+            return;
+        }
         let settled = false;
+        let cancellationSignal;
+        let writerRegistrationFailed = false;
         let unregisterSignalCleanup = () => undefined;
         let resolveChildSettled = () => undefined;
         const childSettled = new Promise((resolveChild) => {
@@ -763,11 +917,21 @@ async function runSstCommand(command, options, context, dependencies = {}) {
             settled = true;
             unregisterSignalCleanup();
             resolveChildSettled();
-            resolve({ success });
+            try {
+                if (writerRegistrationFailed)
+                    throw new Error('Native child registration failed.');
+                taskWriter?.release();
+            }
+            catch (error) {
+                success = false;
+                devkit_1.logger.error(`Task native writer evidence retained: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            resolve({ success: success && !cancellationSignal });
         };
         unregisterSignalCleanup = (0, federated_credential_transport_js_1.registerGovernedSignalCleanup)((signal) => {
             if (settled)
                 return;
+            cancellationSignal ??= signal;
             return stopExactGovernedProcessTree(child, signal, childSettled, () => settled, !joinsGovernedProcessGroup);
         }, 100);
         child.on('error', (error) => {
@@ -789,13 +953,19 @@ async function runSstCommand(command, options, context, dependencies = {}) {
                     devkit_1.logger.error(`Failed to stop retained SST descendant process tree: ${error instanceof Error ? error.message : String(error)}`);
                 }
                 if (retainedProcessTree) {
+                    // The leader's exit is not evidence that its native writers ended.
+                    // Keep task lease receipts for explicit, owner-proven recovery.
+                    if (taskWriter)
+                        writerRegistrationFailed = true;
                     devkit_1.logger.error('SST exited before its exact descendant process tree stopped.');
                 }
             }
-            if (code !== 0) {
-                devkit_1.logger.error(signal
-                    ? `SST ${command} terminated with signal ${signal}.`
-                    : `SST ${command} exited with status ${code ?? 'unknown'}.`);
+            if (code !== 0 || cancellationSignal) {
+                devkit_1.logger.error(cancellationSignal
+                    ? `SST ${command} cancelled by ${cancellationSignal}.`
+                    : signal
+                        ? `SST ${command} terminated with signal ${signal}.`
+                        : `SST ${command} exited with status ${code ?? 'unknown'}.`);
                 if (command === 'deploy' || command === 'remove') {
                     devkit_1.logger.error(`If the stack is locked, run pnpm nx run ${context.projectName ?? '<project>'}:unlock --stage=${options.stage}.`);
                 }
@@ -810,10 +980,14 @@ async function runSstCommand(command, options, context, dependencies = {}) {
                     devkit_1.logger.error(`Failed to restore SST tool-owned source: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
-            const applySucceeded = code === 0 && sourceRestored && !retainedProcessTree;
+            const applySucceeded = code === 0 &&
+                !cancellationSignal &&
+                sourceRestored &&
+                !retainedProcessTree;
             let generatedSecretRetirementSucceeded = true;
             if (applySucceeded &&
                 command === 'remove' &&
+                !invocation.environment.EBK_NX_TASK_CLEANUP &&
                 projectKind(context) === 'slice') {
                 try {
                     await (dependencies.generatedSecretRetirement ??
@@ -826,6 +1000,20 @@ async function runSstCommand(command, options, context, dependencies = {}) {
             }
             settle(applySucceeded && generatedSecretRetirementSucceeded);
         });
+        if (taskWriter && child.pid) {
+            try {
+                taskWriter.recordChild(child.pid, !joinsGovernedProcessGroup);
+            }
+            catch (error) {
+                writerRegistrationFailed = true;
+                devkit_1.logger.error(`Task native child identity was not retained: ${error instanceof Error ? error.message : String(error)}`);
+                // Never leave an unrecorded writer running after a failed registration.
+                void stopExactGovernedProcessTree(child, 'SIGTERM', childSettled, () => settled, !joinsGovernedProcessGroup).catch((stopError) => {
+                    writerRegistrationFailed = true;
+                    devkit_1.logger.error(`Unregistered native child termination failed; writer evidence retained: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                });
+            }
+        }
     });
 }
 //# sourceMappingURL=run-sst-command.js.map

package/src/executors/sst-lifecycle/sst-environment-source.d.ts

@@ -11,6 +11,7 @@ interface SstEnvironmentSourceSnapshot {
     relativePath: string;
 }
 export interface SstEnvironmentSourceTreeSnapshot {
+    nextSource?: SstEnvironmentSourceSnapshot;
     projectRoot: string;
     rootPythonSourcePath: string;
     rootSourcePath: string;
@@ -21,5 +22,12 @@ export declare function captureSstEnvironmentSourceTree(input: {
     projectRoot: string;
     workspaceRoot: string;
 }): SstEnvironmentSourceTreeSnapshot;
+/** Capture outside the complete Nx child, including its Next build dependencies.
+ * The inner SST boundary alone starts after those dependencies have run. */
+export declare function captureNextEnvironmentSource(input: {
+    projectRoot: string;
+    workspaceRoot: string;
+}): SstEnvironmentSourceSnapshot | undefined;
+export declare function reconcileNextEnvironmentSource(retained: SstEnvironmentSourceSnapshot | undefined, workspaceRoot: string): void;
 export declare function reconcileSstEnvironmentSourceTree(retained: SstEnvironmentSourceTreeSnapshot): void;
 export {};

package/src/executors/sst-lifecycle/sst-environment-source.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureSstEnvironmentSourceTree = captureSstEnvironmentSourceTree;
+exports.captureNextEnvironmentSource = captureNextEnvironmentSource;
+exports.reconcileNextEnvironmentSource = reconcileNextEnvironmentSource;
 exports.reconcileSstEnvironmentSourceTree = reconcileSstEnvironmentSourceTree;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -180,7 +182,12 @@ function captureSstEnvironmentSourceTree(input) {
     if (!snapshots.some(({ absolutePath }) => absolutePath === rootSourcePath)) {
         throw new Error('SST lifecycle project lacks its exact root environment source.');
     }
+    const nextSource = captureNextEnvironmentSource({
+        projectRoot,
+        workspaceRoot,
+    });
     return {
+        ...(nextSource ? { nextSource } : {}),
         projectRoot,
         rootPythonSourcePath,
         rootSourcePath,
@@ -188,7 +195,54 @@ function captureSstEnvironmentSourceTree(input) {
         workspaceRoot,
     };
 }
+/** Capture outside the complete Nx child, including its Next build dependencies.
+ * The inner SST boundary alone starts after those dependencies have run. */
+function captureNextEnvironmentSource(input) {
+    const nextPath = (0, node_path_1.join)(input.projectRoot, 'web', 'next-env.d.ts');
+    // existsSync follows links and would treat a dangling alias as absence.
+    // Inspect the directory entry so aliases are refused before the child writes.
+    if (!(0, node_fs_1.lstatSync)(nextPath, { throwIfNoEntry: false }))
+        return undefined;
+    const workspaceRoot = (0, node_fs_1.realpathSync)(input.workspaceRoot);
+    const projectRoot = (0, node_fs_1.realpathSync)(input.projectRoot);
+    normalizedRelativePath(workspaceRoot, projectRoot);
+    const nextSource = stableSstEnvironmentSource((0, node_path_1.join)(projectRoot, 'web', 'next-env.d.ts'), workspaceRoot);
+    // Arbitrary declarations remain ordinary source; never normalize or ignore them.
+    return (0, sst_environment_source_format_js_1.isExactGeneratedNextEnvironmentSourceBytes)(nextSource.bytes)
+        ? nextSource
+        : undefined;
+}
+function reconcileNextEnvironmentSource(retained, workspaceRoot) {
+    if (retained) {
+        workspaceRoot = (0, node_fs_1.realpathSync)(workspaceRoot);
+        const current = stableSstEnvironmentSource(retained.absolutePath, workspaceRoot);
+        if (!(0, sst_environment_source_format_js_1.isExactGeneratedNextEnvironmentSourceBytes)(current.bytes))
+            throw new Error('Next lifecycle declaration changed beyond exact generated dev/build output.');
+        restoreExistingSstEnvironmentSource(retained, current, workspaceRoot);
+    }
+}
 function reconcileSstEnvironmentSourceTree(retained) {
+    const failures = [];
+    try {
+        reconcileNextEnvironmentSource(retained.nextSource, retained.workspaceRoot);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    try {
+        reconcileNativeSstEnvironmentSources(retained);
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new Error(failures
+            .map((error) => error instanceof Error ? error.message : String(error))
+            .join('; '));
+}
+function reconcileNativeSstEnvironmentSources(retained) {
     const retainedByPath = new Map(retained.snapshots.map((snapshot) => [snapshot.absolutePath, snapshot]));
     const observed = discoverSstEnvironmentSources(retained);
     const observedByPath = new Map(observed.map((snapshot) => [snapshot.absolutePath, snapshot]));

package/src/executors/sst-lifecycle/task-unlock.d.ts

@@ -0,0 +1,15 @@
+import { type ExecutorContext } from '@nx/devkit';
+import { type TaskAuthorityEffects } from '../../local-dev/task-authority.js';
+import { type TaskNativeWriterEffects } from '../../local-dev/task-native-writer.js';
+import { createLocalFederatedCredentialTransport } from '../local-deploy/federated-credential-transport.js';
+import { runSstCommand, type SstLifecycleOptions } from './run-sst-command.js';
+export interface TaskUnlockDependencies {
+    authority?: TaskAuthorityEffects;
+    createTransport?: typeof createLocalFederatedCredentialTransport;
+    environment?: NodeJS.ProcessEnv;
+    run?: typeof runSstCommand;
+    writers?: TaskNativeWriterEffects;
+}
+export declare function runCurrentTaskUnlock(options: SstLifecycleOptions, context: ExecutorContext, dependencies?: TaskUnlockDependencies): Promise<{
+    success: boolean;
+}>;