cdk-local 0.2.0 → 0.3.1

package/README.md

@@ -2,6 +2,8 @@
 
 Local runner for your CDK app's Lambda functions, API Gateway, and ECS tasks/services. Run it with no AWS account, or bind it to your deployed stack to hit real AWS resources and data. A native, CDK-first alternative to `sam local`.
 
+![cdkl start-api serving a local CDK app's HTTP API; curl in the right pane reaches the local Lambda](assets/cdkl-start-api.gif)
+
 ## Why cdk-local
 
 Two pains, one tool:
@@ -62,6 +64,8 @@ Invoke a single Lambda function with an event payload.
 cdkl invoke MyStack/MyFunction --event ./event.json
 ```
 
+![cdkl invoke against a local sample CDK app — no AWS account, no deploy](assets/cdkl-invoke.gif)
+
 #### API Gateway — `start-api`
 
 Serve your API Gateway routes (REST v1 / HTTP v2 / Function URL / WebSocket) on a local HTTP server.
@@ -91,6 +95,11 @@ A local API talking to real AWS — point a frontend at it for end-to-end debugg
 
 ```bash
 cdkl start-api MyStack/MyApi --from-cfn-stack MyStack
+
+# Typical shape — the bare flag auto-resolves to the routed stack's
+# name (here `MyStack`). Pass an explicit value only when the deployed
+# CFn stack name differs from the CDK stack name.
+cdkl start-api MyStack/MyApi --from-cfn-stack
 ```
 
 #### Lambda — `invoke`
@@ -112,6 +121,21 @@ cdkl start-service MyStack/MyService --from-cfn-stack MyStack
 
 Use this for production debugging, integration verification with real AWS resources, and validating real IAM permissions before deploy.
 
+## `--watch` (hot reload)
+
+Pass `--watch` to `cdkl start-api` and the server hot-reloads when your CDK app's synth output (or any routed Lambda's asset directory) changes:
+
+```bash
+cdkl start-api MyStack/MyApi --watch
+```
+
+- 500 ms debounced [chokidar](https://github.com/paulmillr/chokidar) file watcher on `cdk.out/` + every routed Lambda's asset dir.
+- Re-synths and re-discovers routes on each firing — adding a new route to your CDK app shows up locally on save.
+- Synth failures keep the previous version serving (warn-and-continue, never crashes the server).
+- Compatible with `--from-cfn-stack`: each reload re-reads the deployed CloudFormation stack so a deploy event picks up new ARNs without restarting the server.
+
+See [docs/local-emulation.md](docs/local-emulation.md#hot-reload---watch) for the full lifecycle, file-list update semantics, and known limitations.
+
 ## Override env vars without a state source
 
 When env-var values in your CDK template are CloudFormation intrinsics (`Ref`, `Fn::GetAtt`, `Fn::ImportValue`), cdk-local cannot resolve them without a state source — it drops them with a warning that names the affected key. To inject literal values instead, use `--env-vars <file>` (SAM-compatible JSON shape):

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import { i as createLocalInvokeCommand, n as createLocalRunTaskCommand, r as createLocalStartApiCommand, t as createLocalStartServiceCommand } from "./local-start-service-BydO4FOA.js";
+import { i as createLocalInvokeCommand, n as createLocalRunTaskCommand, r as createLocalStartApiCommand, t as createLocalStartServiceCommand } from "./local-start-service-EZy1JNYK.js";
 import { Command } from "commander";
 
 //#region src/cli/index.ts
 const program = new Command();
-program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.2.0");
+program.name("cdkl").description("Run AWS CDK stacks locally with Docker.").version("0.3.1");
 program.addCommand(createLocalInvokeCommand());
 program.addCommand(createLocalStartApiCommand());
 program.addCommand(createLocalRunTaskCommand());

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/state.ts","../src/local/state-resolver.ts","../src/local/local-state-provider.ts","../src/cli/commands/local-state-source.ts","../src/cli/commands/local-invoke.ts","../src/cli/commands/local-start-api.ts","../src/cli/commands/local-run-task.ts","../src/cli/commands/local-start-service.ts","../src/local/cfn-local-state-provider.ts"],"mappings":";;;;UAuLiB,aAAA;EAEf,UAAA;EAGA,YAAA;EAGA,UAAA,EAAY,MAAA;EAcZ,kBAAA,GAAqB,MAAA;EAGrB,UAAA,GAAa,MAAA;EAGb,YAAA;EAGA,QAAA,GAAW,MAAA;EAmBX,cAAA;EAMA,mBAAA;EAyBA,aAAA;AAAA;;;UCxIe,gBAAA;EACf,SAAA;EACA,MAAA;EACA,SAAA;EACA,SAAA;AAAA;AAAA,UAqBe,kBAAA;EAOf,aAAA,CAAc,UAAA,WAAqB,OAAA;EAQnC,qBAAA,CACE,aAAA,UACA,cAAA,UACA,UAAA,WACC,OAAA;AAAA;AAAA,UAGY,mBAAA;EAEf,SAAA,EAAW,MAAA,SAAe,aAAA;EAE1B,gBAAA,GAAmB,gBAAA;EAOnB,kBAAA,GAAqB,kBAAA;EAOrB,cAAA;AAAA;;;UCrJe,gBAAA;EAQf,SAAA,EAAW,MAAA,SAAe,aAAA;EAO1B,OAAA,EAAS,MAAA;EAOT,MAAA;AAAA;AAAA,UAsBe,kBAAA;EAAA,SAMN,KAAA;EAQT,IAAA,CAAK,SAAA,UAAmB,WAAA,uBAAkC,OAAA,CAAQ,gBAAA;EAalE,uBAAA,CAAwB,cAAA,WAAyB,OAAA,CAAQ,kBAAA;EAKzD,OAAA;AAAA;;;UC/Ee,uBAAA;EAOf,YAAA;EAEA,MAAA;EAEA,OAAA;EAMA,WAAA;EAAA,CAEC,GAAA;AAAA;AAAA,KAQS,yBAAA,IAA6B,OAAA,EAAS,uBAAA,KAA4B,kBAAA;AAAA,KAUlE,mBAAA,GAAsB,MAAA,SAAe,yBAAA;AAAA,iBAUjC,mBAAA,CAAoB,YAAA,oBAAgC,SAAA;AAAA,iBAapD,gBAAA,CAAiB,IAAA,EAAM,IAAA,CAAK,uBAAA;AAAA,iBAgB5B,gBAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,6BACd,WAAA;AAAA,cAqBW,qBAAA,SAA8B,KAAA;cAC7B,OAAA;AAAA;AAAA,iBAkBE,wCAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,mBACd,gBAAA;AAAA,iBAiCc,wBAAA,CACd,OAAA,EAAS,uBAAA,EACT,SAAA,UACA,WAAA,sBACA,mBAAA,GAAsB,mBAAA,GACrB,kBAAA;;;UCtEc,+BAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAu2BR,wBAAA,CAAyB,IAAA,GAAM,+BAAA,GAAuC,OAAA;;;UC5vBrE,iCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAmqFR,0BAAA,CAA2B,IAAA,GAAM,iCAAA,GAAyC,OAAA;;;UCpzFzE,gCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAkeR,yBAAA,CAA0B,IAAA,GAAM,gCAAA,GAAwC,OAAA;;;UCtevE,qCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA+oBR,8BAAA,CACd,IAAA,GAAM,qCAAA,GACL,OAAA;;;UC5qBc,4BAAA;EAOf,YAAA;EAKA,MAAA;EAiBA,OAAA;AAAA;AAAA,cAGW,qBAAA,YAAiC,kBAAA;EAAA,SAG5B,KAAA;EAAA,iBACC,YAAA;EAAA,iBACA,MAAA;EAAA,QAKT,MAAA;EAAA,iBACS,aAAA;EAAA,QAQT,QAAA;cAEI,IAAA,EAAM,4BAAA;EAAA,QAOV,SAAA;EA+BK,IAAA,CACX,UAAA,UACA,YAAA,uBACC,OAAA,CAAQ,gBAAA;EA8DE,uBAAA,CACX,eAAA,WACC,OAAA,CAAQ,kBAAA;EAiEJ,OAAA,CAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/state.ts","../src/local/state-resolver.ts","../src/local/local-state-provider.ts","../src/cli/commands/local-state-source.ts","../src/cli/commands/local-invoke.ts","../src/cli/commands/local-start-api.ts","../src/cli/commands/local-run-task.ts","../src/cli/commands/local-start-service.ts","../src/local/cfn-local-state-provider.ts"],"mappings":";;;;UAuLiB,aAAA;EAEf,UAAA;EAGA,YAAA;EAGA,UAAA,EAAY,MAAA;EAcZ,kBAAA,GAAqB,MAAA;EAGrB,UAAA,GAAa,MAAA;EAGb,YAAA;EAGA,QAAA,GAAW,MAAA;EAmBX,cAAA;EAMA,mBAAA;EAyBA,aAAA;AAAA;;;UCxIe,gBAAA;EACf,SAAA;EACA,MAAA;EACA,SAAA;EACA,SAAA;AAAA;AAAA,UAqBe,kBAAA;EAOf,aAAA,CAAc,UAAA,WAAqB,OAAA;EAQnC,qBAAA,CACE,aAAA,UACA,cAAA,UACA,UAAA,WACC,OAAA;AAAA;AAAA,UAGY,mBAAA;EAEf,SAAA,EAAW,MAAA,SAAe,aAAA;EAE1B,gBAAA,GAAmB,gBAAA;EAOnB,kBAAA,GAAqB,kBAAA;EAOrB,cAAA;AAAA;;;UCrJe,gBAAA;EAQf,SAAA,EAAW,MAAA,SAAe,aAAA;EAO1B,OAAA,EAAS,MAAA;EAOT,MAAA;AAAA;AAAA,UAsBe,kBAAA;EAAA,SAMN,KAAA;EAQT,IAAA,CAAK,SAAA,UAAmB,WAAA,uBAAkC,OAAA,CAAQ,gBAAA;EAalE,uBAAA,CAAwB,cAAA,WAAyB,OAAA,CAAQ,kBAAA;EAKzD,OAAA;AAAA;;;UC/Ee,uBAAA;EAOf,YAAA;EAEA,MAAA;EAEA,OAAA;EAMA,WAAA;EAAA,CAEC,GAAA;AAAA;AAAA,KAQS,yBAAA,IAA6B,OAAA,EAAS,uBAAA,KAA4B,kBAAA;AAAA,KAUlE,mBAAA,GAAsB,MAAA,SAAe,yBAAA;AAAA,iBAUjC,mBAAA,CAAoB,YAAA,oBAAgC,SAAA;AAAA,iBAapD,gBAAA,CAAiB,IAAA,EAAM,IAAA,CAAK,uBAAA;AAAA,iBAgB5B,gBAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,6BACd,WAAA;AAAA,cAqBW,qBAAA,SAA8B,KAAA;cAC7B,OAAA;AAAA;AAAA,iBAkBE,wCAAA,CACd,OAAA,EAAS,IAAA,CAAK,uBAAA,mBACd,gBAAA;AAAA,iBAiCc,wBAAA,CACd,OAAA,EAAS,uBAAA,EACT,SAAA,UACA,WAAA,sBACA,mBAAA,GAAsB,mBAAA,GACrB,kBAAA;;;UCtEc,+BAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAu2BR,wBAAA,CAAyB,IAAA,GAAM,+BAAA,GAAuC,OAAA;;;UC5vBrE,iCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA0wFR,0BAAA,CAA2B,IAAA,GAAM,iCAAA,GAAyC,OAAA;;;UC35FzE,gCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBAkeR,yBAAA,CAA0B,IAAA,GAAM,gCAAA,GAAwC,OAAA;;;UCtevE,qCAAA;EACf,mBAAA,GAAsB,mBAAA;AAAA;AAAA,iBA+oBR,8BAAA,CACd,IAAA,GAAM,qCAAA,GACL,OAAA;;;UC5qBc,4BAAA;EAOf,YAAA;EAKA,MAAA;EAiBA,OAAA;AAAA;AAAA,cAGW,qBAAA,YAAiC,kBAAA;EAAA,SAG5B,KAAA;EAAA,iBACC,YAAA;EAAA,iBACA,MAAA;EAAA,QAKT,MAAA;EAAA,iBACS,aAAA;EAAA,QAQT,QAAA;cAEI,IAAA,EAAM,4BAAA;EAAA,QAOV,SAAA;EA+BK,IAAA,CACX,UAAA,UACA,YAAA,uBACC,OAAA,CAAQ,gBAAA;EA8DE,uBAAA,CACX,eAAA,WACC,OAAA,CAAQ,kBAAA;EAiEJ,OAAA,CAAA;AAAA"}

package/dist/index.js

@@ -1,3 +1,3 @@
-import { a as LocalStateSourceError, c as rejectExplicitCfnStackWithMultipleStacks, d as CfnLocalStateProvider, i as createLocalInvokeCommand, l as resolveCfnRegion, n as createLocalRunTaskCommand, o as createLocalStateProvider, r as createLocalStartApiCommand, s as isCfnFlagPresent, t as createLocalStartServiceCommand, u as resolveCfnStackName } from "./local-start-service-BydO4FOA.js";
+import { a as LocalStateSourceError, c as rejectExplicitCfnStackWithMultipleStacks, d as CfnLocalStateProvider, i as createLocalInvokeCommand, l as resolveCfnRegion, n as createLocalRunTaskCommand, o as createLocalStateProvider, r as createLocalStartApiCommand, s as isCfnFlagPresent, t as createLocalStartServiceCommand, u as resolveCfnStackName } from "./local-start-service-EZy1JNYK.js";
 
 export { CfnLocalStateProvider, LocalStateSourceError, createLocalInvokeCommand, createLocalRunTaskCommand, createLocalStartApiCommand, createLocalStartServiceCommand, createLocalStateProvider, isCfnFlagPresent, rejectExplicitCfnStackWithMultipleStacks, resolveCfnRegion, resolveCfnStackName };

package/dist/{local-start-service-BydO4FOA.js → local-start-service-EZy1JNYK.js}

@@ -13936,6 +13936,7 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 	const jwksWarnedUrls = /* @__PURE__ */ new Set();
 	let sigV4CredentialsLoader;
 	const sigV4WarnedForeignIds = /* @__PURE__ */ new Set();
+	const fromCfnTipEmitted = { value: false };
 	/**
 	* One synth + discover + build pass. Returns the next-state
 	* material. Reused on initial boot AND every hot-reload firing.
@@ -13960,8 +13961,13 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 		};
 		const { stacks } = await synthesizer.synthesize(synthOpts);
 		const cfnStackFallback = typeof options.fromCfnStack === "string" ? options.fromCfnStack : void 0;
-		const targetStacks = pickTargetStacks(stacks, options.stack, cfnStackFallback);
+		const targetStackPrefix = target?.includes("/") === true ? target.slice(0, target.indexOf("/")) : void 0;
+		const targetStacks = pickTargetStacks(stacks, options.stack, cfnStackFallback, targetStackPrefix);
 		if (targetStacks.length === 0) throw new Error("No stacks matched. Pass --stack <name> (or --from-cfn-stack <name>) or run from a single-stack app.");
+		const routedStackNames = targetStacks.map((s) => s.stackName);
+		tryEmitFromCfnRedundancyTipOnce(options.fromCfnStack, routedStackNames, fromCfnTipEmitted, (routedStackName) => {
+			logger.info(`tip: --from-cfn-stack value matches the routed stack name (${routedStackName}); you can omit the value: \`cdkl start-api ... --from-cfn-stack\` (bare flag) resolves to the same value.`);
+		});
 		const routes = discoverRoutes(targetStacks);
 		const wsDiscovery = discoverWebSocketApis(targetStacks);
 		if (wsDiscovery.errors.length > 0) for (const e of wsDiscovery.errors) logger.warn(`WebSocket discovery: ${e}`);
@@ -14338,12 +14344,57 @@ async function localStartApiCommand(target, options, extraStateProviders) {
 * routing rules.
 */
 /** @internal exported for unit tests. */
-function pickTargetStacks(stacks, pattern, cfnStackFallback) {
-	const effective = pattern ?? cfnStackFallback;
+function pickTargetStacks(stacks, pattern, cfnStackFallback, targetFallback) {
+	const effective = pattern ?? cfnStackFallback ?? targetFallback;
 	if (effective) return matchStacks(stacks, [effective]);
 	if (stacks.length === 1) return stacks;
 	if (stacks.length === 0) return [];
-	throw new Error(`Multi-stack app: pass --stack <name> (or --from-cfn-stack <name>) to pick a target. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	throw new Error(`Multi-stack app: pass --stack <name>, --from-cfn-stack <name>, or a stack-qualified target like "<StackName>/<construct>" to pick a target. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+}
+/**
+* Decide whether the `--from-cfn-stack <name>` redundancy tip should
+* fire for the current invocation. Fires only when:
+*  - `fromCfnStack` is a non-empty STRING (explicit value, not bare `true`)
+*  - exactly ONE stack is routed
+*  - the explicit value equals the routed stack's `stackName`
+*
+* Extracted as a pure function so it can be unit-tested without booting
+* the full server. See improvement A in the start-api UX PR.
+*
+* @internal exported for unit tests.
+*/
+function shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames) {
+	if (typeof fromCfnStack !== "string") return false;
+	if (fromCfnStack.length === 0) return false;
+	if (routedStackNames.length !== 1) return false;
+	return fromCfnStack === routedStackNames[0];
+}
+/**
+* One-shot wrapper around `shouldEmitFromCfnRedundancyTip` for the
+* `--watch` hot-reload path. `synthesizeAndBuild` re-runs on every
+* reload firing, so without a gate the tip would re-emit on every
+* reload — noisy. This helper consults the caller-supplied ref:
+*  - If the predicate fires AND the ref is still `false`, calls `emit`
+*    and flips the ref to `true`.
+*  - On subsequent invocations the ref is `true` and the helper is a
+*    no-op for the rest of the ref's lifetime.
+*  - When the predicate does NOT fire (no `--from-cfn-stack` value /
+*    intentionally-different value / multi-stack run), the ref stays
+*    `false` so a future reload whose synthesized stacks change in a
+*    way that DOES make the value redundant still emits the tip once.
+*
+* The ref is owned by `localStartApiCommand` (one per server boot), so
+* independent server invocations get independent flags.
+*
+* @internal exported for unit tests.
+*/
+function tryEmitFromCfnRedundancyTipOnce(fromCfnStack, routedStackNames, emittedRef, emit) {
+	if (emittedRef.value) return;
+	if (!shouldEmitFromCfnRedundancyTip(fromCfnStack, routedStackNames)) return;
+	const routedStackName = routedStackNames[0];
+	if (routedStackName === void 0) return;
+	emit(routedStackName);
+	emittedRef.value = true;
 }
 /**
 * Distinct, stable list of Lambda logical IDs reachable through any
@@ -17837,4 +17888,4 @@ function createLocalStartServiceCommand(opts = {}) {
 
 //#endregion
 export { LocalStateSourceError as a, rejectExplicitCfnStackWithMultipleStacks as c, CfnLocalStateProvider as d, createLocalInvokeCommand as i, resolveCfnRegion as l, createLocalRunTaskCommand as n, createLocalStateProvider as o, createLocalStartApiCommand as r, isCfnFlagPresent as s, createLocalStartServiceCommand as t, resolveCfnStackName as u };
-//# sourceMappingURL=local-start-service-BydO4FOA.js.map
+//# sourceMappingURL=local-start-service-EZy1JNYK.js.map