@go-to-k/cdkd 0.115.4 → 0.116.0

package/README.md

@@ -4,15 +4,14 @@ Drop-in CDK CLI for existing CDK apps — faster deploys via AWS SDK instead of
 
 - **Drop-in CDK compatible** — your existing CDK app code runs as-is.
 - **Up to 15x faster deploys than the AWS CDK CLI (CloudFormation)**
-- **Run AWS resources locally without deploying** — invoke Lambdas, run ECS tasks, and serve API Gateway routes from Docker.
+- **Local dev for CDK apps** — invoke Lambdas, serve API Gateway routes, and run ECS tasks directly from your CDK code, no `cdk synth → sam local` round-trip.
 
 ![cdkd demo](https://github.com/user-attachments/assets/0128730d-186d-4bd3-abea-aabc80ba4dd5)
 
 **cdkd complements the AWS CDK CLI rather than replacing it.** Use cdkd in dev/test for rapid iteration and SAM-style local execution; use the AWS CDK CLI in production for full CloudFormation tooling. Bidirectional migration is supported — [import an existing CloudFormation stack](#importing-existing-resources) into cdkd for iteration, or [export back to CloudFormation](#exporting-a-stack-back-to-cloudformation) when ready for production.
 
-> **⚠️ WARNING: NOT PRODUCTION READY**
->
-> An experimental project exploring direct SDK provisioning as an alternative to the AWS CDK CLI — **NOT a replacement** and **NOT suitable for production use**. Features are incomplete, APIs may change without notice, and bugs may affect your AWS infrastructure. Use at your own risk in development / testing environments only.
+> [!IMPORTANT]
+> cdkd is for dev/test workflows only — early in development, not yet production-ready.
 
 ## Features
 

package/dist/cli.js

@@ -43862,7 +43862,17 @@ async function localInvokeCommand(target, options) {
 			if (stateAudit && stateAudit.unresolved.some((u) => u.key === key)) continue;
 			logger.warn(`Environment variable ${key} contains a CloudFormation intrinsic and was dropped. Override it with --env-vars (e.g. {"${lambda.logicalId}":{"${key}":"<literal>"}}) or pass --from-state to recover deployed values.`);
 		}
-		if (options.fromState && !options.assumeRole && stateForRoleHint) suggestAssumeRoleFromState(stateForRoleHint, lambda.logicalId);
+		let resolvedAssumeRoleArn;
+		if (typeof options.assumeRole === "string") resolvedAssumeRoleArn = options.assumeRole;
+		else if (options.assumeRole === true) if (!stateForRoleHint) logger.warn("--assume-role passed without an ARN, but no cdkd state was loaded. Pair it with --from-state, or pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.");
+		else {
+			const arn = resolveExecutionRoleArnFromState(stateForRoleHint, lambda.logicalId);
+			if (arn) {
+				resolvedAssumeRoleArn = arn;
+				logger.info(`--assume-role: auto-resolved execution role from cdkd state: ${arn}`);
+			} else logger.warn(`--assume-role: could not resolve the execution role ARN from cdkd state for '${lambda.logicalId}'. Pass the ARN explicitly: --assume-role <arn>. Falling back to the developer's shell credentials.`);
+		}
+		else if (options.assumeRole === void 0 && options.fromState && stateForRoleHint) suggestAssumeRoleFromState(stateForRoleHint, lambda.logicalId);
 		const event = await readEvent(options);
 		const dockerEnv = {
 			AWS_LAMBDA_FUNCTION_NAME: lambda.logicalId,
@@ -43873,14 +43883,22 @@ async function localInvokeCommand(target, options) {
 			AWS_LAMBDA_LOG_STREAM_NAME: "local",
 			...envResult.resolved
 		};
-		if (options.assumeRole) {
+		let assumeSucceeded = false;
+		if (resolvedAssumeRoleArn) {
 			const stsRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"];
-			const creds = await assumeLambdaExecutionRole(options.assumeRole, stsRegion);
-			dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
-			dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
-			dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
-			if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
-		} else forwardAwsEnv(dockerEnv);
+			try {
+				const creds = await assumeLambdaExecutionRole(resolvedAssumeRoleArn, stsRegion);
+				dockerEnv["AWS_ACCESS_KEY_ID"] = creds.accessKeyId;
+				dockerEnv["AWS_SECRET_ACCESS_KEY"] = creds.secretAccessKey;
+				dockerEnv["AWS_SESSION_TOKEN"] = creds.sessionToken;
+				if (stsRegion) dockerEnv["AWS_REGION"] = stsRegion;
+				assumeSucceeded = true;
+			} catch (err) {
+				const reason = err instanceof Error ? err.message : String(err);
+				logger.warn(`--assume-role: STS AssumeRole(${resolvedAssumeRoleArn}) failed: ${reason}. Falling back to the developer's shell credentials.`);
+			}
+		}
+		if (!assumeSucceeded) forwardAwsEnv(dockerEnv);
 		let debugPort;
 		if (options.debugPort) {
 			debugPort = Number(options.debugPort);
@@ -44171,11 +44189,10 @@ async function readStdin() {
 /**
 * Assume the Lambda execution role and return temporary credentials.
 *
-* Q1 recommendation B (PR 1): closes the "developer has admin creds, the
-* deployed function has narrow ones" skew that SAM users routinely hit.
-* Off by default; opt-in via `--assume-role <arn>`. PR 2's `--from-state`
-* will add auto-resolution from the template's `Role` property; for now
-* the user supplies the ARN explicitly.
+* Closes the "developer has admin creds, the deployed function has narrow
+* ones" skew that SAM users routinely hit. Off by default; opt-in via
+* `--assume-role <arn>` (explicit) or `--assume-role` (bare, auto-resolved
+* from cdkd state via `resolveExecutionRoleArnFromState`).
 *
 * Mirrors the env-var-write pattern from `applyRoleArnIfSet` in
 * `src/utils/role-arn.ts` but writes the temp creds onto the container's
@@ -44250,26 +44267,51 @@ function materializeInlineCode(handler, source, fileExtension) {
 	return dir;
 }
 /**
-* When `--from-state` is set but `--assume-role` is not, log the function's
-* deployed execution role ARN once as a hint. Helps users discover the
-* scoped-credentials path without us silently auto-assuming (auto-assume
-* is a future PR's scope).
+* When `--from-state` is set but `--assume-role` was NOT passed (not even
+* bare), log the function's deployed execution role ARN once as a hint.
+* This is the pre-(#442) behavior — kept for backward compatibility with
+* users who don't want auto-assume. The bare-`--assume-role` path opts
+* in to actually assuming the resolved ARN; this hint path stays
+* informational only.
 */
 function suggestAssumeRoleFromState(state, logicalId) {
 	const logger = getLogger();
+	const roleArn = resolveExecutionRoleArnFromState(state, logicalId);
+	if (roleArn) logger.info(`Hint: the deployed function uses execution role ${roleArn}. Re-run with --assume-role to invoke under the deployed function's narrow permissions.`);
+}
+/**
+* Resolve the execution-role ARN for a Lambda from cdkd state. Used by
+* both the `--assume-role` auto-resolve path and the legacy hint path.
+*
+* Resolution rules (mirrors the v1 scope spelled out in (#442)):
+*
+*   - Literal-string `Role` starting with `arn:` → returned verbatim.
+*   - `{ Fn::GetAtt: [<RoleId>, 'Arn'] }` or `{ Ref: <RoleId> }` → looked up
+*     against the sibling IAM Role resource's `attributes.Arn` (recorded
+*     at deploy time by `IAMRoleProvider.create` / drift refresh).
+*   - Any other shape (`Fn::Sub` / `Fn::Join` / cross-stack imports) → not
+*     resolved in v1; the caller surfaces a warn and falls back to dev
+*     creds. Once real CDK apps emit those shapes for `Role` we can
+*     extend the resolver per `feedback_verify_cdk_synth_shape_before_resolver.md`.
+*
+* Returns `undefined` when state has no entry for the Lambda, the `Role`
+* is missing entirely, the referenced sibling has no `Arn` attribute
+* captured, or the shape is one we don't try to resolve.
+*
+* Exported for unit testing.
+*/
+function resolveExecutionRoleArnFromState(state, logicalId) {
 	const lambda = state.resources[logicalId];
-	if (!lambda) return;
+	if (!lambda) return void 0;
 	const roleRef = lambda.properties?.["Role"] ?? lambda.observedProperties?.["Role"];
-	let roleArn;
-	if (typeof roleRef === "string" && roleRef.startsWith("arn:")) roleArn = roleRef;
-	else if (typeof roleRef === "object" && roleRef !== null) {
+	if (typeof roleRef === "string" && roleRef.startsWith("arn:")) return roleRef;
+	if (typeof roleRef === "object" && roleRef !== null) {
 		const refLogicalId = pickReferencedLogicalId(roleRef);
 		if (refLogicalId) {
 			const cached = state.resources[refLogicalId]?.attributes?.["Arn"];
-			if (typeof cached === "string" && cached.startsWith("arn:")) roleArn = cached;
+			if (typeof cached === "string" && cached.startsWith("arn:")) return cached;
 		}
 	}
-	if (roleArn) logger.info(`Hint: the deployed function uses execution role ${roleArn}. Re-run with --assume-role <that-arn> to invoke under the deployed function's narrow permissions.`);
 }
 /**
 * Walk a single-key intrinsic and return the referenced logical ID, or
@@ -44293,7 +44335,7 @@ function pickReferencedLogicalId(intrinsic) {
 */
 function createLocalCommand() {
 	const local = new Command("local").description("Local execution of Lambda functions (RIE) and ECS task definitions (Docker required)");
-	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role <arn>", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default).")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
+	const invoke = new Command("invoke").description("Run a Lambda function locally in a Docker container (RIE-backed). Target accepts a CDK display path (MyStack/MyApi/Handler) or stack-qualified logical ID (MyStack:MyApiHandler1234ABCD). Single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the Lambda to invoke").addOption(new Option("-e, --event <file>", "JSON event payload file (default: {})")).addOption(new Option("--event-stdin", "Read event JSON from stdin").default(false)).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"LogicalId\":{\"KEY\":\"VALUE\"}})")).addOption(new Option("--no-pull", "Skip docker pull (use cached image) — no-op for IMAGE local-build path; `docker build` does not pull base layers by default")).addOption(new Option("--no-build", "Skip docker build on the IMAGE local-build path (use the previously-built tag). Requires the deterministic tag to already be in the local registry; errors with an actionable message when missing. No-op for ZIP Lambdas and the IMAGE ECR-pull path. Compatible with --no-pull.")).addOption(new Option("--debug-port <port>", "Node --inspect-brk port (default: off)")).addOption(new Option("--container-host <host>", "Host to bind the RIE port to").default("127.0.0.1")).addOption(new Option("--assume-role [arn]", "Assume the Lambda's deployed execution role and forward STS-issued temp credentials to the container so the handler runs with the deployed function's narrow permissions (closes the \"developer admin / function narrow\" skew). Three forms: (1) `--assume-role <arn>` assumes the explicit ARN; (2) `--assume-role` (bare) auto-resolves the function's execution role ARN from cdkd state (requires --from-state); (3) `--no-assume-role` explicitly opts out (forces dev creds even with --from-state). Off by default — when omitted, the developer's shell credentials are forwarded unchanged (SAM-compatible default). STS failures degrade to a warn + dev-creds fallback.")).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Ref / Fn::GetAtt / Fn::Sub in env vars with the deployed physical IDs / attributes. Off by default — keep PR 1 warn-and-drop semantics; turn on for stacks already deployed via cdkd deploy.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localInvokeCommand));
 	[
 		...commonOptions,
 		...appOptions,
@@ -45581,7 +45623,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.115.4");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.116.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());