@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.41

package/src/blueprints/external-sandbox.d.ts

@@ -1,5 +1,5 @@
 import { type ChildProcessWithoutNullStreams } from 'node:child_process';
-export declare const EXTERNAL_BLUEPRINT_SANDBOX_IMAGE: "node:22-alpine@sha256:16e22a550f3863206a3f701448c45f7912c6896a62de43add43bb9c86130c3e2";
+export declare const EXTERNAL_BLUEPRINT_SANDBOX_IMAGE: "node:22-alpine@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402";
 export declare const EXTERNAL_BLUEPRINT_CONTAINER_AUTO_REMOVE: "--rm";
 export declare const EXTERNAL_BLUEPRINT_SANDBOX_FLAGS: readonly ["--network=none", "--read-only", "--cap-drop=ALL", "--security-opt=no-new-privileges", "--pids-limit=64", "--memory=256m", "--memory-swap=256m", "--cpus=1", "--ulimit=nofile=256:256", "--tmpfs=/tmp:rw,noexec,nosuid,nodev,size=16m,mode=1777"];
 export type ExternalBlueprintSource = 'installed' | 'local';

package/src/blueprints/external-sandbox.js

@@ -160,7 +160,7 @@ function packagePathSegments(name, label) {
     }
     return segments;
 }
-function assertLinuxMuslPortableManifest(manifest) {
+function assertLinuxMuslPortableManifest(manifest, registryDependency) {
     if (manifest.optionalDependencies !== undefined) {
         if (!isRecord(manifest.optionalDependencies)) {
             throw new Error(`External Blueprint package ${manifest.name}@${manifest.version} has a malformed optional dependency map.`);
@@ -212,7 +212,8 @@ function assertLinuxMuslPortableManifest(manifest) {
             'postinstall',
             'prepare',
             'prepublish',
-        ].find((name) => Object.prototype.hasOwnProperty.call(manifest.scripts, name));
+        ].find((name) => Object.prototype.hasOwnProperty.call(manifest.scripts, name) &&
+            !(name === 'prepublish' && registryDependency));
         if (installScript) {
             throw new Error(`External Blueprint package ${manifest.name}@${manifest.version} declares unsupported install/build script ${installScript}.`);
         }
@@ -225,7 +226,7 @@ function assertLinuxMuslPortableManifest(manifest) {
         throw new Error(`External Blueprint package ${manifest.name}@${manifest.version} declares unsupported native build dependency ${buildDependency}.`);
     }
 }
-function readPackageManifest(packageRoot, expectedName, expectedVersion) {
+function readPackageManifest(packageRoot, expectedName, expectedVersion, registryDependencyAuthority) {
     const manifestPath = (0, node_path_1.join)(packageRoot, 'package.json');
     let descriptor;
     let bytes;
@@ -283,7 +284,15 @@ function readPackageManifest(packageRoot, expectedName, expectedVersion) {
     }
     packagePathSegments(value.name, 'External Blueprint dependency name');
     const manifest = value;
-    assertLinuxMuslPortableManifest(manifest);
+    if (registryDependencyAuthority) {
+        assertInstalledPackageAuthority(registryDependencyAuthority, packageRoot, manifest);
+    }
+    // A registry dependency may ship prepublish metadata alongside ready JS.
+    // This is not a publish-only hook: npm install can execute it. The sandbox
+    // runs Node directly, never a package manager or build script. Missing built
+    // files therefore fail execution; hooks cannot be used to manufacture them.
+    // Publisher roots never receive this dependency-only admission.
+    assertLinuxMuslPortableManifest(manifest, !!registryDependencyAuthority);
     return manifest;
 }
 function manifestDependencyInventory(manifest) {
@@ -460,7 +469,7 @@ function resolveInstalledDependencyRoot(workspaceRoot, packageRoot, dependency,
             throw new Error('External Blueprint dependency closure escapes the canonical workspace.');
         }
         assertInstalledPackageRoot(installedAuthority, canonical);
-        readPackageManifest(canonical, dependency.name);
+        readPackageManifest(canonical, dependency.name, undefined, installedAuthority);
         return canonical;
     }
     if (dependency.optional)
@@ -513,7 +522,7 @@ function copyPackageBytes(sourceRoot, destinationRoot, budget) {
     };
     visit(sourceRoot, destinationRoot, 0);
 }
-function discoverPackage(workspaceRoot, sourceRoot, packagesRoot, packages, budget, installedAuthority, requiresRegistryAuthority) {
+function discoverPackage(workspaceRoot, sourceRoot, packagesRoot, packages, budget, installedAuthority, packageKind) {
     const existing = packages.get(sourceRoot);
     if (existing)
         return existing;
@@ -521,13 +530,14 @@ function discoverPackage(workspaceRoot, sourceRoot, packagesRoot, packages, budg
     if (budget.packages > MAX_CLOSURE_PACKAGES) {
         throw new Error('External Blueprint dependency closure exceeds its fixed package bound.');
     }
+    const requiresRegistryAuthority = packageKind !== 'local-publisher';
     if (requiresRegistryAuthority && !installedAuthority) {
         throw new Error('Local external Blueprint dependencies require canonical pnpm registry and lockfile authority.');
     }
     if (requiresRegistryAuthority && installedAuthority) {
         assertInstalledPackageRoot(installedAuthority, sourceRoot);
     }
-    const manifest = readPackageManifest(sourceRoot);
+    const manifest = readPackageManifest(sourceRoot, undefined, undefined, packageKind === 'dependency' ? installedAuthority : undefined);
     if (requiresRegistryAuthority && installedAuthority) {
         assertInstalledPackageAuthority(installedAuthority, sourceRoot, manifest);
     }
@@ -546,7 +556,7 @@ function discoverPackage(workspaceRoot, sourceRoot, packagesRoot, packages, budg
         const dependencyRoot = resolveInstalledDependencyRoot(workspaceRoot, sourceRoot, dependency, installedAuthority);
         if (dependencyRoot === undefined)
             continue;
-        node.dependencies.set(dependency.name, discoverPackage(workspaceRoot, dependencyRoot, packagesRoot, packages, budget, installedAuthority, true));
+        node.dependencies.set(dependency.name, discoverPackage(workspaceRoot, dependencyRoot, packagesRoot, packages, budget, installedAuthority, 'dependency'));
     }
     return node;
 }
@@ -602,7 +612,9 @@ function stageExternalBlueprintClosure(workspaceRoot, packageRoot, generatorPath
         (0, node_fs_1.mkdirSync)(packagesRoot, { recursive: true, mode: 0o700 });
         (0, node_fs_1.chmodSync)(packagesRoot, 0o700);
         const packages = new Map();
-        const root = discoverPackage(workspaceRoot, packageRoot, packagesRoot, packages, { bytes: 0, directories: 0, files: 0, packages: 0 }, installedAuthority, authority.source === 'installed');
+        const root = discoverPackage(workspaceRoot, packageRoot, packagesRoot, packages, { bytes: 0, directories: 0, files: 0, packages: 0 }, installedAuthority, authority.source === 'installed'
+            ? 'installed-publisher'
+            : 'local-publisher');
         linkStagedPackageGraph(stageRoot, root, packages);
         const containerGeneratorUrl = `file://${node_path_1.posix.join('/sandbox/node_modules', ...packageSegments, ...generatorChild
             .split(node_path_1.sep)

package/src/blueprints/manifest.d.ts

@@ -73,7 +73,7 @@ export declare const blueprintManifestSchema: {
             readonly properties: {
                 readonly capabilities: {
                     readonly items: {
-                        readonly enum: readonly ["network", "routing", "container-compute", "postgres", "identity", "events", "observability", "configuration", "deployment"];
+                        readonly enum: readonly ["key-value", "routing", "identity", "events", "observability", "configuration", "deployment", "network", "container-compute", "postgres"];
                         readonly type: "string";
                     };
                     readonly type: "array";

package/src/blueprints/resolver.js

@@ -7,6 +7,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const semver_1 = require("semver");
+const capability_plan_js_1 = require("../foundation/capability-plan.js");
 const blueprint_trust_js_1 = require("../supply-chain/blueprint-trust.js");
 const blueprint_trust_git_js_1 = require("../supply-chain/blueprint-trust-git.js");
 const inputs_js_1 = require("./inputs.js");
@@ -21,7 +22,31 @@ const MAX_PNPM_LOCKFILE_BYTES = 32 * 1024 * 1024;
 const builtInInputSchema = {
     $schema: 'https://json-schema.org/draft/2020-12/schema',
     additionalProperties: false,
-    properties: {},
+    properties: {
+        sql: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['reason'],
+            properties: {
+                reason: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 512,
+                    pattern: '^[^\\u0000-\\u001f\\u007f]+$',
+                },
+            },
+        },
+        dependencySlices: {
+            type: 'array',
+            maxItems: 64,
+            uniqueItems: true,
+            items: {
+                type: 'string',
+                maxLength: 63,
+                pattern: '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$',
+            },
+        },
+    },
     type: 'object',
 };
 function readEngineVersion() {
@@ -42,19 +67,7 @@ function createBuiltInManifest(engineVersion) {
     return {
         $schema: 'https://empirebuilderkit.dev/schemas/blueprint-v1.json',
         engine: engineVersion,
-        foundation: {
-            capabilities: [
-                'network',
-                'routing',
-                'postgres',
-                'identity',
-                'events',
-                'observability',
-                'configuration',
-                'deployment',
-            ],
-            contract: '^1',
-        },
+        foundation: (0, capability_plan_js_1.standardPersistenceRequirement)({}),
         generator: './built-in/standard.js',
         inputs: './built-in/standard-inputs.json',
         kind: 'slice',
@@ -340,7 +353,7 @@ function resolveBlueprint({ engineVersion, localAuthoringPackages = [], localPac
         throw new Error(`Blueprint manifest identity ${manifestResult.value.name}@${manifestResult.value.version} does not match requested ${parsed.name}@${parsed.version}.`);
     }
     if (!(0, semver_1.satisfies)(resolvedEngineVersion, manifestResult.value.engine)) {
-        throw new Error(`Blueprint ${parsed.name}@${parsed.version} requires EBK engine ${manifestResult.value.engine}, but this workspace provides ${resolvedEngineVersion}.`);
+        throw new Error(`Blueprint ${parsed.name}@${parsed.version} requires EBK engine ${manifestResult.value.engine}, but this workspace provides ${resolvedEngineVersion}. Use a compatible reviewed recipe, or revalidate your adopter-owned recipe against this engine in a disposable workspace before updating its engine declaration, version and trust record.`);
     }
     resolveManifestAssets(packageRoot, manifestResult.value);
     if (localRoot) {

package/src/cli/bootstrap.d.ts

@@ -27,5 +27,5 @@ export declare function launchBlueprintAuthority(workspaceRoot: string, io: Requ
     childPath?: string;
     nodeExecutable?: string;
 }): 0 | 1;
-export declare function runEbkBootstrap(arguments_: readonly string[], io?: BootstrapIo, dependencies?: BootstrapDependencies): Promise<0 | 1 | 2>;
+export declare function runEbkBootstrap(arguments_: readonly string[], io?: BootstrapIo, dependencies?: BootstrapDependencies): Promise<number>;
 export {};

package/src/cli/deploy-runtime.d.ts

@@ -0,0 +1,30 @@
+import { runGovernedChildProcess } from '../executors/sst-lifecycle/run-sst-command.js';
+import type { DeployCliCommand } from './dev-command.js';
+export declare const DEPLOY_RESULT_KIND = "ebk-deploy-result";
+export declare const DEPLOY_RECEIPT_PATH = ".ebk/evidence/deployment/latest.json";
+export interface DeployResultProject {
+    outcome: string;
+    project: string;
+    target: string;
+}
+/** The development-only `--json` result: the executor's own written receipt
+ * (already secret-free evidence) and per-project status. It is printed after
+ * the run and carries no authority; protected stages never produce it. */
+export interface DeployJsonResult {
+    exitCode: number;
+    kind: typeof DEPLOY_RESULT_KIND;
+    outcome: 'failed' | 'receipt-unavailable' | 'review-required' | 'succeeded';
+    projects: DeployResultProject[];
+    receipt: Record<string, unknown> | null;
+    receiptPath: typeof DEPLOY_RECEIPT_PATH;
+    schemaVersion: 1;
+    stage: 'development';
+}
+export interface DeployCommandOutput {
+    now?: () => number;
+    stdout: (value: string) => void;
+}
+/** The CLI selects the existing workspace lifecycle, never an individual SST
+ * child. All policy, identity, TTY, migration, smoke and receipt decisions
+ * remain in the generated Nx target and its executor. */
+export declare function executeDeployCommand(command: DeployCliCommand, workspaceRoot: string, environment: NodeJS.ProcessEnv, run?: typeof runGovernedChildProcess, output?: DeployCommandOutput): Promise<number>;

package/src/cli/deploy-runtime.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPLOY_RECEIPT_PATH = exports.DEPLOY_RESULT_KIND = void 0;
+exports.executeDeployCommand = executeDeployCommand;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const run_sst_command_js_1 = require("../executors/sst-lifecycle/run-sst-command.js");
+const errors_js_1 = require("../local-dev/errors.js");
+const nx_workspace_js_1 = require("../local-dev/nx-workspace.js");
+exports.DEPLOY_RESULT_KIND = 'ebk-deploy-result';
+exports.DEPLOY_RECEIPT_PATH = '.ebk/evidence/deployment/latest.json';
+const MAX_DEPLOY_RECEIPT_BYTES = 1024 * 1024;
+const MAX_DEPLOY_RECEIPT_CHILDREN = 4096;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function boundedText(value) {
+    return typeof value === 'string' && value.length > 0 && value.length <= 256;
+}
+/** Reads only a fresh, regular, bounded development receipt written by this
+ * run. A stale receipt left by an earlier run (for example when the
+ * workspace-health dependency fails before the executor invalidates it) is
+ * reported as unavailable, never as this run's result. */
+function readFreshDevelopmentReceipt(workspaceRoot, startedAtMs) {
+    let descriptor;
+    let source;
+    try {
+        const receiptPath = (0, node_path_1.join)(workspaceRoot, exports.DEPLOY_RECEIPT_PATH);
+        // Windows has no O_NOFOLLOW, so the receipt file itself must not be a
+        // symbolic link, and the opened file must be the one lstat saw (exact
+        // 64-bit identity). A filesystem whose fstat identity differs from lstat
+        // reports the receipt as unavailable.
+        const entry = (0, node_fs_1.lstatSync)(receiptPath, { bigint: true });
+        if (entry.isSymbolicLink() || !entry.isFile())
+            return undefined;
+        descriptor = (0, node_fs_1.openSync)(receiptPath, 
+        // O_NOFOLLOW refuses a symbolic link at the receipt path itself.
+        node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW ?? 0));
+        const stat = (0, node_fs_1.fstatSync)(descriptor, { bigint: true });
+        if (!stat.isFile() ||
+            stat.dev !== entry.dev ||
+            stat.ino !== entry.ino ||
+            stat.size > BigInt(MAX_DEPLOY_RECEIPT_BYTES)) {
+            return undefined;
+        }
+        const size = Number(stat.size);
+        const buffer = Buffer.alloc(size);
+        let offset = 0;
+        while (offset < size) {
+            const read = (0, node_fs_1.readSync)(descriptor, buffer, offset, size - offset, null);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        source = buffer.subarray(0, offset).toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (descriptor !== undefined)
+            (0, node_fs_1.closeSync)(descriptor);
+    }
+    let receipt;
+    try {
+        receipt = JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(receipt) ||
+        receipt.kind !== 'ebk-deployment-receipt' ||
+        receipt.schemaVersion !== 1 ||
+        receipt.stage !== 'development' ||
+        typeof receipt.startedAt !== 'string' ||
+        !Number.isFinite(Date.parse(receipt.startedAt)) ||
+        Date.parse(receipt.startedAt) < startedAtMs ||
+        !['failed', 'review-required', 'succeeded'].includes(String(receipt.outcome)) ||
+        !Array.isArray(receipt.children) ||
+        receipt.children.length > MAX_DEPLOY_RECEIPT_CHILDREN) {
+        return undefined;
+    }
+    const projects = [];
+    for (const child of receipt.children) {
+        if (!isRecord(child) ||
+            !boundedText(child.project) ||
+            !boundedText(child.target) ||
+            !boundedText(child.outcome)) {
+            return undefined;
+        }
+        projects.push({
+            outcome: child.outcome,
+            project: child.project,
+            target: child.target,
+        });
+    }
+    return { projects, receipt };
+}
+/** The CLI selects the existing workspace lifecycle, never an individual SST
+ * child. All policy, identity, TTY, migration, smoke and receipt decisions
+ * remain in the generated Nx target and its executor. */
+async function executeDeployCommand(command, workspaceRoot, environment, run = run_sst_command_js_1.runGovernedChildProcess, output) {
+    const structured = command.json === true;
+    if (structured && (command.stage !== 'development' || !output)) {
+        // Parsing already refuses this; fail closed if a caller bypasses it.
+        throw new errors_js_1.LocalDevContractError('invalid-input', 'ebk deploy --json is available only for development; staging and production keep native output and the interactive acknowledgement.');
+    }
+    let project;
+    try {
+        project = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(workspaceRoot, 'project.json'), 'utf8'));
+    }
+    catch {
+        throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', 'ebk deploy requires the generated root project.json. Run the supported workspace upgrade and workspace-health check.');
+    }
+    const target = project?.targets?.['deploy-local'];
+    if (typeof project?.name !== 'string' ||
+        !/^[a-zA-Z0-9@][a-zA-Z0-9@/._-]{0,213}$/.test(project.name) ||
+        target?.executor !== '@empire-builder-kit/nx:local-deploy' ||
+        target.cache !== false ||
+        !Array.isArray(target.dependsOn) ||
+        !target.dependsOn.includes('workspace-health')) {
+        throw new errors_js_1.LocalDevContractError('prerequisite-unavailable', 'ebk deploy requires the generated, non-cacheable workspace deploy-local target. Run the supported workspace upgrade and workspace-health check.');
+    }
+    const nx = (0, nx_workspace_js_1.resolveWorkspaceNxRuntime)(workspaceRoot);
+    const startedAtMs = (output?.now ?? Date.now)();
+    const result = await run({
+        executable: process.execPath,
+        args: [
+            nx.binary,
+            'run',
+            `${project.name}:deploy-local`,
+            '--',
+            `--stage=${command.stage}`,
+            `--expectedRoleArn=${command.expectedRoleArn}`,
+            ...(command.profile ? [`--profile=${command.profile}`] : []),
+            ...(command.slices ? [`--slices=${command.slices.join(',')}`] : []),
+        ],
+        cwd: workspaceRoot,
+        environment: {
+            ...environment,
+            // Stream native diagnostics and preserve the inherited TTY. This target
+            // is never served from cache and receives no skip/approval overrides.
+            NX_TUI: 'false',
+            NX_TASKS_RUNNER_DYNAMIC_OUTPUT: 'false',
+        },
+        // With --json, native output moves to stderr so stdout carries only the
+        // structured result; stdin stays inherited.
+        ...(structured ? { stdio: ['inherit', 2, 'inherit'] } : {}),
+    });
+    if (result.error)
+        throw result.error;
+    const exitCode = result.signal
+        ? 128 + (node_os_1.constants.signals[result.signal] ?? 1)
+        : (result.status ?? 1);
+    if (structured && output) {
+        const fresh = readFreshDevelopmentReceipt(workspaceRoot, startedAtMs);
+        const payload = {
+            exitCode,
+            kind: exports.DEPLOY_RESULT_KIND,
+            outcome: fresh
+                ? fresh.receipt.outcome
+                : 'receipt-unavailable',
+            projects: fresh?.projects ?? [],
+            receipt: fresh?.receipt ?? null,
+            receiptPath: exports.DEPLOY_RECEIPT_PATH,
+            schemaVersion: 1,
+            stage: 'development',
+        };
+        output.stdout(`${JSON.stringify(payload, null, 2)}\n`);
+    }
+    return exitCode;
+}
+//# sourceMappingURL=deploy-runtime.js.map

package/src/cli/dev-command.d.ts

@@ -1,11 +1,11 @@
 import { type LocalDevContextInput } from '../local-dev/local-context.js';
 import { type AgentCliCommand } from './agent-command.js';
 export declare const EBK_AGENT_COMMANDS: readonly ["context", "handoff", "plan", "resume", "upgrade-preview"];
-export declare const EBK_DEV_COMMANDS: readonly ["configure", "doctor", "down", "logs", "prune", "ps", "restart", "setup", "status", "tail", "up"];
+export declare const EBK_DEV_COMMANDS: readonly ["attach", "configure", "doctor", "down", "logs", "prune", "ps", "restart", "setup", "status", "tail", "up"];
 export declare const EBK_SECRET_COMMANDS: readonly ["remove", "set"];
 export type CliHelpCommand = {
     kind: 'help';
-    namespace?: 'agent' | 'dev' | 'secret';
+    namespace?: 'agent' | 'deploy' | 'dev' | 'secret';
 };
 export type CliVersionCommand = {
     kind: 'version';
@@ -49,6 +49,10 @@ export interface DevLifecycleCommand extends DevCommandBase {
 export interface DevStatusCommand extends DevCommandBase {
     command: 'status';
 }
+export interface DevAttachCommand extends DevCommandBase {
+    command: 'attach';
+    taskId: string;
+}
 export interface DevDoctorCommand extends DevCommandBase {
     command: 'doctor';
     environmentOnly: boolean;
@@ -80,13 +84,23 @@ export interface DevPruneCommand extends DevCommandBase {
     command: 'prune';
     fleetId?: string;
 }
-export type DevCliCommand = DevConfigureCommand | DevDoctorCommand | DevLifecycleCommand | DevLogsCommand | DevPruneCommand | DevPsCommand | DevSetupCommand | DevStatusCommand | DevTailCommand | DevUpCommand;
+export type DevCliCommand = DevAttachCommand | DevConfigureCommand | DevDoctorCommand | DevLifecycleCommand | DevLogsCommand | DevPruneCommand | DevPsCommand | DevSetupCommand | DevStatusCommand | DevTailCommand | DevUpCommand;
 export interface SecretCliCommand {
     command: 'remove' | 'set';
     kind: 'secret';
     logicalName: string;
     slice: string;
 }
-export type ParsedEbkCommand = AgentCliCommand | CliHelpCommand | CliVersionCommand | DevCliCommand | SecretCliCommand;
+export interface DeployCliCommand {
+    kind: 'deploy';
+    command: 'deploy';
+    stage: 'development' | 'staging' | 'production';
+    profile?: string;
+    expectedRoleArn: string;
+    /** Development only: print one bounded receipt result on stdout. */
+    json?: true;
+    slices?: string[];
+}
+export type ParsedEbkCommand = AgentCliCommand | CliHelpCommand | CliVersionCommand | DeployCliCommand | DevCliCommand | SecretCliCommand;
 export declare function parseEbkArguments(arguments_: readonly string[]): ParsedEbkCommand;
 export {};

package/src/cli/dev-command.js

@@ -6,6 +6,7 @@ const errors_js_1 = require("../local-dev/errors.js");
 const local_context_js_1 = require("../local-dev/local-context.js");
 const identity_js_1 = require("../local-dev/identity.js");
 const personal_stage_js_1 = require("../local-dev/personal-stage.js");
+const task_identity_js_1 = require("../local-dev/task-identity.js");
 const agent_command_js_1 = require("./agent-command.js");
 exports.EBK_AGENT_COMMANDS = [
     'context',
@@ -15,6 +16,7 @@ exports.EBK_AGENT_COMMANDS = [
     'upgrade-preview',
 ];
 exports.EBK_DEV_COMMANDS = [
+    'attach',
     'configure',
     'doctor',
     'down',
@@ -486,6 +488,64 @@ function parseSecret(arguments_) {
     };
 }
 function parseEbkArguments(arguments_) {
+    // Canonical deploy stages are explicit; personal dev/secret stages remain
+    // resolver-owned and must continue rejecting stage overrides.
+    if (arguments_[0] === 'deploy') {
+        if (arguments_.length === 2 && arguments_[1] === '--help') {
+            return { kind: 'help', namespace: 'deploy' };
+        }
+        const tokens = parseTokens(arguments_.slice(1), {
+            stage: {
+                kind: 'string',
+                values: ['development', 'staging', 'production'],
+            },
+            profile: { kind: 'string' },
+            expectedRoleArn: { kind: 'string' },
+            json: { kind: 'flag' },
+        });
+        const stages = ['development', 'staging', 'production'];
+        const positionalStage = stages.includes(tokens.positionals[0])
+            ? tokens.positionals[0]
+            : undefined;
+        if (positionalStage && tokens.options.stage !== undefined) {
+            return usageError('ebk deploy accepts one stage, positional or --stage, not both.');
+        }
+        const stage = positionalStage ?? stringOption(tokens, 'stage') ?? 'development';
+        if (stage !== 'development' &&
+            stage !== 'staging' &&
+            stage !== 'production') {
+            return usageError('ebk deploy stage must be development, staging, or production.');
+        }
+        const json = booleanOption(tokens, 'json');
+        if (json && stage !== 'development') {
+            // Protected stages keep native output and the human-typed TTY
+            // acknowledgement; a structured mode must never stand in for either.
+            return usageError('ebk deploy --json is available only for development; staging and production keep native output and the interactive acknowledgement.');
+        }
+        const expectedRoleArn = stringOption(tokens, 'expectedRoleArn');
+        if (!expectedRoleArn ||
+            !/^arn:(aws|aws-us-gov|aws-cn):iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/.test(expectedRoleArn)) {
+            return usageError('ebk deploy requires --expectedRoleArn=<exact-stage-deployment-role-arn>. See ebk deploy --help.');
+        }
+        const profile = stringOption(tokens, 'profile');
+        const slices = tokens.positionals.slice(positionalStage ? 1 : 0);
+        if (slices.length > 64 ||
+            new Set(slices).size !== slices.length ||
+            slices.some((slice) => !SLICE_PATTERN.test(slice) || stages.includes(slice))) {
+            return usageError('ebk deploy requires unique Slice names after the optional stage.');
+        }
+        return {
+            kind: 'deploy',
+            command: 'deploy',
+            stage,
+            expectedRoleArn,
+            ...(profile === undefined
+                ? {}
+                : { profile: (0, local_context_js_1.normalizeLocalDevProfile)(profile) }),
+            ...(json ? { json: true } : {}),
+            ...(slices.length === 0 ? {} : { slices }),
+        };
+    }
     (0, personal_stage_js_1.rejectExplicitStageArguments)(arguments_);
     if (arguments_.length === 0 || arguments_[0] === '--help') {
         if (arguments_.length > 1) {
@@ -532,6 +592,17 @@ function parseEbkArguments(arguments_) {
     const command = arguments_[1];
     const rest = arguments_.slice(2);
     switch (command) {
+        case 'attach': {
+            const tokens = parseTokens(rest, JSON_OPTION);
+            if (tokens.positionals.length !== 1)
+                return usageError('ebk dev attach requires exactly one task ID.');
+            return {
+                command: 'attach',
+                kind: 'dev',
+                json: booleanOption(tokens, 'json'),
+                taskId: (0, task_identity_js_1.requireTaskId)(tokens.positionals[0]),
+            };
+        }
         case 'configure':
             return parseConfigure(rest);
         case 'setup':

package/src/cli/main.d.ts

@@ -16,8 +16,12 @@ import { type FleetRuntimePaths } from '../local-dev/runtime-paths.js';
 import { assertSecretSliceClaimAuthority } from '../local-dev/secret-slice-claim.js';
 import { type HiddenSecretInputReader, type HumanSecretCeremony, type PersonalSecretConfirmation, type PersonalSecretValueValidator, type PersonalSstSecretStore } from '../secrets/personal-command.js';
 import type { SecretMetadataDeclaration } from '../secrets/model.js';
+import { assertWorkspaceStageOwnershipForWorkspace } from '../workspace-deployment/index.js';
+import { attachStoppedTask } from '../local-dev/task-attachment.js';
+import { bindTaskEnvironment } from '../local-dev/task-identity.js';
 import { type DevCliCommand, type DevSliceSelector } from './dev-command.js';
 import type { AgentCliCommand } from './agent-command.js';
+import { executeDeployCommand } from './deploy-runtime.js';
 import { executeDeveloperAgentCommand } from './agent-runtime.js';
 import { type LoadedPersonalOperatorSecret, type PersonalSecretAwsContext } from './personal-secret-runtime.js';
 export interface EbkCliIo {
@@ -64,13 +68,17 @@ interface WorkspaceFilesystemIdentity {
 }
 export declare function sameWorkspaceRealpath(left: string, right: string, currentPlatform?: NodeJS.Platform, inspectIdentity?: (path: string) => WorkspaceFilesystemIdentity): boolean;
 export interface EbkCliDependencies {
+    bindTask: typeof bindTaskEnvironment;
+    attachTask: typeof attachStoppedTask;
     acquireSecretLedgerLock: typeof acquirePersonalSecretLedgerLock;
     appData: () => string;
     assertSecretSliceClaim: typeof assertSecretSliceClaimAuthority;
+    assertWorkspaceOwnership: typeof assertWorkspaceStageOwnershipForWorkspace;
     changeDirectory: (workspaceRoot: string) => void;
     client: (paths: FleetRuntimePaths) => FleetClientPort;
     discoverContext: (explicit: LocalDevContextInput, environment: NodeJS.ProcessEnv) => Promise<LocalDevContextDiscovery>;
     executeAgent: typeof executeDeveloperAgentCommand;
+    executeDeploy: typeof executeDeployCommand;
     followLogs: typeof followFleetLogs;
     frameworkVersion: () => string;
     gitCommonDirectory: (workspaceRoot: string) => string;
@@ -127,5 +135,5 @@ export declare function runAgentCommandCore(command: AgentCliCommand, io?: EbkCl
  * Nx never calls back through argv parsing or the CLI entry point.
  */
 export declare function runDevCommandCore(command: DevCliCommand, io?: EbkCliIo, overrides?: Partial<EbkCliDependencies>): Promise<0 | 1 | 2>;
-export declare function runEbkCli(arguments_: readonly string[], io?: EbkCliIo, overrides?: Partial<EbkCliDependencies>): Promise<0 | 1 | 2>;
+export declare function runEbkCli(arguments_: readonly string[], io?: EbkCliIo, overrides?: Partial<EbkCliDependencies>): Promise<number>;
 export {};