@aws-blocks/core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,229 @@
+# @aws-blocks/core
+
+Core primitives for building full-stack applications with the AWS Blocks.
+
+## Key Exports
+
+### Scope
+
+Defines the boundary for your backend resources. The `Scope` class docstring serves as an index to all available Building Blocks.
+
+```typescript
+import { Scope } from '@aws-blocks/core';
+
+const scope = new Scope('my-app');
+```
+
+### ApiNamespace
+
+Define type-safe APIs with automatic frontend/backend integration.
+
+```typescript
+import { ApiNamespace } from '@aws-blocks/core';
+
+export const api = new ApiNamespace(scope, 'api', (context) => ({
+  async greet(name: string) {
+    return { message: `Hello, ${name}!` };
+  }
+}));
+```
+
+Frontend usage (fully typed):
+
+```typescript
+import { api } from 'aws-blocks';
+
+const result = await api.greet('World');
+```
+
+#### Authentication — every method is a public endpoint
+
+Each method you define becomes a public, internet-reachable RPC endpoint. There is **no authentication by default** — a method is callable by anyone until you gate it. Auth is opt-in, per method, by calling an auth Building Block at the top of the handler:
+
+```typescript
+export const api = new ApiNamespace(scope, 'api', (context) => ({
+  // PUBLIC — intentionally callable by anyone.
+  async listPublicPosts() {
+    return db.posts.findPublished();
+  },
+
+  // GATED — requireAuth throws a 401 before the body runs.
+  async createPost(input: NewPost) {
+    const user = await auth.requireAuth(context);
+    return db.posts.create({ ...input, authorId: user.userId });
+  },
+}));
+```
+
+The local mock applies no auth either, so an ungated method passes every local check and still ships callable by anyone. See your auth block's README (e.g. `@aws-blocks/bb-auth-cognito`) for `requireAuth` / `requireRole`.
+
+#### Calling the API over HTTP (JSON-RPC 2.0)
+
+The typed `import { api } from 'aws-blocks'` client is the normal path. The HTTP form below is for manual verification (curl/Postman) and non-JS clients.
+
+`POST` to the RPC path `/aws-blocks/api`:
+
+- Local dev: `http://localhost:3001/aws-blocks/api`
+- Deployed: the API Gateway stage URL + `/aws-blocks/api`
+
+The body is JSON-RPC 2.0:
+
+```json
+{ "jsonrpc": "2.0", "method": "<namespace>.<methodName>", "params": [...], "id": 1 }
+```
+
+- `method` is `<namespace>.<methodName>`, where `<namespace>` is the **export variable name** from `aws-blocks/index.ts` (e.g., `export const api = ...` → `api`).
+- `params` is a POSITIONAL array of the method's arguments. A named object also works (its values are used in order).
+- Errors come back as HTTP `200` with an `error` object in the body (per JSON-RPC), not as a non-2xx status.
+
+Working example:
+
+```bash
+curl -X POST http://localhost:3001/aws-blocks/api \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","method":"api.greet","params":["World"],"id":1}'
+# → {"jsonrpc":"2.0","result":{"message":"Hello, World!"},"id":1}
+```
+
+### ApiError / isBlocksError
+
+Typed error handling across the wire.
+
+```typescript
+import { ApiError, isBlocksError } from '@aws-blocks/core';
+
+// Throw with HTTP status and error name
+throw new ApiError('Not found', 404, { name: 'ItemNotFoundException' });
+
+// Catch with type narrowing
+catch (e) {
+  if (isBlocksError(e, 'ItemNotFoundException')) { ... }
+}
+```
+
+### RawRoute
+
+Path-based HTTP routing Building Block for endpoints that need full request/response control — webhooks, REST APIs, health checks, file downloads. Use `ApiNamespace` (RPC) for typed function calls; use `RawRoute` when you need raw HTTP semantics.
+
+```typescript
+import { RawRoute } from '@aws-blocks/blocks';
+
+// Explicit path
+new RawRoute(scope, 'GetUser', {
+  method: 'GET',
+  path: '/users/{id}',
+  handler: async (context) => {
+    const userId = context.request.params.id;
+    context.response.send({ id: userId });
+  },
+});
+
+// Derived path — path omitted, becomes /health from scope chain
+new RawRoute(scope, 'health', { method: 'GET', handler: async (ctx) => {
+  ctx.response.send({ status: 'ok' });
+}});
+```
+
+Supports exact paths (`/health`), named parameters (`/users/{id}`), and wildcards (`/files/*`). Path can be omitted — it's derived from scope-chain IDs.
+
+📖 **Full RawRoute documentation (see source repo)**
+
+### Pipeline
+
+CDK Pipelines-based CI/CD construct for multi-branch, multi-stage deployments. Creates self-mutating CodePipeline V2 instances with GitHub source via CodeConnections (OAuth).
+
+📖 **Full Pipeline documentation (see source repo)**
+
+### Hosting
+
+CDK construct (from the `/cdk` entry point) that deploys a frontend on CloudFront + S3, with a single-origin API proxy when a backend stack is provided.
+
+```typescript
+import { Hosting } from '@aws-blocks/core/cdk';
+
+new Hosting(stack, 'Web', {
+  root: join(__dirname, '..'),
+  buildCommand: 'npm run build',
+  api: blocksStack,
+});
+```
+
+The `framework` option selects the frontend type: `'spa' | 'static' | 'nextjs'`. When omitted, the framework is auto-detected by reading your app's OWN `package.json` (not `node_modules`): a `next` dependency → `nextjs`; otherwise `spa`; and `static` when there is no `package.json`. Set `framework: 'spa'` explicitly to override auto-detection — e.g. when a stray `next` dependency would otherwise trigger an unwanted Next.js/OpenNext build. Full reference lives in the source JSDoc.
+
+## Building Blocks
+
+Import Building Blocks from their specific packages (or from the `@aws-blocks/blocks` umbrella):
+
+- `@aws-blocks/bb-kv-store` — Key-value storage
+- `@aws-blocks/bb-distributed-table` — Tables with Zod schemas and indexes
+- `@aws-blocks/auth-common` — Auth interfaces and Authenticator component
+- `@aws-blocks/bb-auth-basic` — Username/password authentication
+- `@aws-blocks/bb-data` — SQL database
+- `@aws-blocks/bb-realtime` — Real-time pub/sub
+
+### withAuth (SSR cookie forwarding)
+
+Lives in the `@aws-blocks/core/server` entry point (also re-exported as `@aws-blocks/blocks/server`). During SSR (server components / loaders) the browser's cookies aren't automatically attached to AWS Blocks API calls — `withAuth` reads them and forwards them to every AWS Blocks API call made inside the callback.
+
+```typescript
+import { withAuth } from '@aws-blocks/blocks/server';
+
+// Auto-detects cookies (Next.js detection is built in)
+const posts = await withAuth(() => api.listMyPosts());
+
+// Other frameworks: pass cookies explicitly as the 2nd arg…
+const posts = await withAuth(() => api.listMyPosts(), request.headers.get('cookie'));
+// …or register a provider once via registerCookieProvider.
+```
+
+**Note:** `withAuth` throws a `401` `ApiError` when no cookies are found. Full reference lives in the source JSDoc.
+
+## Local Development
+
+In local dev mode, Building Blocks use mock implementations. No AWS resources needed.
+
+## CORS Configuration
+
+By default, the Lambda handler does **not** set any `Access-Control-Allow-Origin` header. CORS behavior is controlled entirely by the `CORS_ALLOWED_ORIGINS` environment variable.
+
+### When using Hosting (recommended)
+
+If you use the `Hosting` construct with your API, CORS is handled automatically:
+
+- **Same-origin requests** (frontend fetches through the CloudFront proxy at `/aws-blocks/api`) work without CORS headers since the browser treats them as same-origin.
+- **Cross-origin requests** (e.g. direct API Gateway calls) are also covered: when you pass a `BlocksStack` or `BlocksBackend` as the `api` prop, the Hosting construct automatically adds the CloudFront distribution's domain to `CORS_ALLOWED_ORIGINS` on the backend Lambda. You do **not** need to configure CORS manually.
+
+In sandbox mode, the localhost pattern is also preserved so your local dev frontend still works.
+
+### Local development (`npm run dev`)
+
+The dev server automatically allows `localhost` / `127.0.0.1` origins. No configuration needed.
+
+### Sandbox deployments
+
+The sandbox CLI automatically sets `CORS_ALLOWED_ORIGINS=^https?://(localhost|127\.0\.0\.1)(:\d+)?$` so your local frontend can reach the deployed sandbox API.
+
+### Production (frontend hosted separately)
+
+If your frontend is hosted on a different domain (e.g., Vercel, Netlify), set the `CORS_ALLOWED_ORIGINS` environment variable on your Lambda:
+
+```typescript
+// aws-blocks/index.cdk.ts
+blocksStack.handler.addEnvironment(
+  'CORS_ALLOWED_ORIGINS',
+  'https://myapp\\.com,https://staging\\.myapp\\.com'
+);
+```
+
+Each entry is treated as a **regex pattern** (anchored with `^` and `$`). Examples:
+
+| Pattern | Matches |
+|---------|---------|
+| `https://myapp\\.com` | Exact match for `https://myapp.com` |
+| `https://.*\\.myapp\\.com` | Any subdomain of `myapp.com` |
+| `^https?://(localhost\|127\\.0\\.0\\.1)(:\\d+)?$` | Localhost/127.0.0.1, any port, http or https (sandbox) |
+| `.*` | All origins (escape hatch — use with caution) |
+
+Multiple patterns are comma-separated. If a pattern is invalid regex, it falls back to literal string match.
+
+If an origin doesn't match any pattern, the handler omits the `Access-Control-Allow-Origin` header (browser blocks the response) and logs a `[CORS]` warning to CloudWatch.

package/dist/cdk/blocks-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAEnC,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAOvC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;;;EA0GxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC;IAC5C,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAmBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB;CAmB5E"}
+{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAEnC,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQvC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;;;EA0GxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC;IAC5C,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAmBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB;CAsB5E"}

package/dist/cdk/blocks-backend.js

@@ -5,6 +5,7 @@ import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
 import { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
 import { Construct } from 'constructs';
+import { pathToFileURL } from 'node:url';
 import { DEFAULT_NODE_RUNTIME } from './node-version.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
@@ -196,8 +197,11 @@ export class BlocksBackend extends Construct {
     static async create(scope, id, props) {
         assertCdkConditionActive();
         const backend = new BlocksBackend(scope, id, props);
-        // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
-        const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+        // file:// URL (not a raw path) so the cache-busting query works on Windows,
+        // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
+        const backendUrl = pathToFileURL(props.backendCDKPath);
+        backendUrl.searchParams.set('stack', id);
+        const mod = await import(backendUrl.href);
         if (typeof mod.default === 'function') {
             try {
                 await mod.default(backend);

package/dist/cdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEvD,qBAAa,WAAY,SAAQ,GAAG,CAAC,KAAM,YAAW,eAAe;IACnE,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC;IACpD,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C,OAAO;WAcM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CA0B1E;AAED,qBAAa,KAAM,SAAQ,SAAS;IAClC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAO9C,IAAI,OAAO,yCAWV;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAKnD,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACtD,0BAA0B,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IACrH,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAe;IACxD,IAAI,cAAc,IAAI,SAAS,MAAM,EAAE,CAAe;CACvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEvD,qBAAa,WAAY,SAAQ,GAAG,CAAC,KAAM,YAAW,eAAe;IACnE,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC;IACpD,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C,OAAO;WAcM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CA6B1E;AAED,qBAAa,KAAM,SAAQ,SAAS;IAClC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAO9C,IAAI,OAAO,yCAWV;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAKnD,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACtD,0BAA0B,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IACrH,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAe;IACxD,IAAI,cAAc,IAAI,SAAS,MAAM,EAAE,CAAe;CACvD"}

package/dist/cdk/index.js

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
+import { pathToFileURL } from 'node:url';
 import { computeScopeFullId, } from '../common/index.js';
 import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blocks-backend.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
@@ -35,8 +36,11 @@ export class BlocksStack extends cdk.Stack {
         const pipelineScope = globalThis.__PIPELINE_STAGE_SCOPE__;
         const actualScope = pipelineScope || scope;
         const stack = new BlocksStack(actualScope, id, props);
-        // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
-        const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+        // file:// URL (not a raw path) so the cache-busting query works on Windows,
+        // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
+        const backendUrl = pathToFileURL(props.backendCDKPath);
+        backendUrl.searchParams.set('stack', id);
+        const mod = await import(backendUrl.href);
         if (typeof mod.default === 'function') {
             try {
                 await mod.default(stack);

package/dist/client/index.d.ts

@@ -8,7 +8,7 @@ type AsyncAPI<T extends Record<string, (...args: any[]) => any>> = {
  * Middleware can inspect or modify any of these properties before the
  * request is dispatched to the server.
  */
-export interface KitRequest {
+export interface BlocksRequest {
     /** The namespace name this call targets (e.g., 'api', 'auth'). Corresponds to the second argument of `new ApiNamespace(scope, name, handler)` in the backend. */
     apiNamespace: string;
     /** The method being called on the namespace (e.g., 'getUser', 'kvSet'). */
@@ -39,9 +39,9 @@ export interface KitRequest {
  * });
  * ```
  */
-export interface KitMiddleware {
+export interface BlocksMiddleware {
     /** Transform the request before it's sent. Modify the request in place or return a new one. Can be async. */
-    onRequest?: (request: KitRequest) => KitRequest | void | Promise<KitRequest | void>;
+    onRequest?: (request: BlocksRequest) => BlocksRequest | void | Promise<BlocksRequest | void>;
     /** Transform the response data after it's received. Used to hydrate __blocks descriptors. */
     onResponse?: (data: unknown) => unknown;
 }
@@ -64,7 +64,7 @@ export interface KitMiddleware {
  * an explicit `attach(server)` pattern because they need the HTTP server
  * instance passed to them — something unavailable at import time.
  */
-export declare function registerMiddleware(middleware: KitMiddleware): void;
+export declare function registerMiddleware(middleware: BlocksMiddleware): void;
 /**
  * Options for `ApiNamespaceClient`.
  */

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa;IAC5B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACpF,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAElE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC;AAChC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC;AAiBhF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAoHF;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iKAAiK;IACjK,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,wHAAwH;IACxH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6GAA6G;IAC7G,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7F,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAErE;AAqBD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAClF,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,yBAAyB,GAClC,QAAQ,CAAC,CAAC,CAAC,CAyDb;AAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/pipeline/pipeline-construct.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-construct.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline-construct.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAInC,OAAO,EAEL,YAAY,EAIb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,KAAK,EAEV,aAAa,EACb,mBAAmB,EACpB,MAAM,YAAY,CAAC;AA6CpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,qBAAa,QAAQ,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,SAAS;IACxE,iFAAiF;IACjF,SAAgB,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAEjE,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAuB;IAE1D;;;;;OAKG;gBACS,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;KAAE;IA0C7I;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACU,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnD,KAAK,EAAE,SAAS,EAChB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CA6C9B;AA0FD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAmBjE;AA+QD;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,GAAG,CAAC,UAAU;IACzF,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,GAAG,CAAC,KAAK;IAC3E,SAAgB,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;gBAE9C,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC;CAI3E"}
+{"version":3,"file":"pipeline-construct.d.ts","sourceRoot":"","sources":["../../src/pipeline/pipeline-construct.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAInC,OAAO,EAEL,YAAY,EAIb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,OAAO,KAAK,EAEV,aAAa,EACb,mBAAmB,EACpB,MAAM,YAAY,CAAC;AA6CpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,qBAAa,QAAQ,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,SAAS;IACxE,iFAAiF;IACjF,SAAgB,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAEjE,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAuB;IAE1D;;;;;OAKG;gBACS,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;KAAE;IA0C7I;;;;;;;;;;;;;;;;;;;;;;OAsBG;WACU,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnD,KAAK,EAAE,SAAS,EAChB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;CA6C9B;AA0FD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAmBjE;AAiRD;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,GAAG,CAAC,UAAU;IACzF,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACpD;AAED;;;;;GAKG;AACH,qBAAa,WAAW,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,SAAQ,GAAG,CAAC,KAAK;IAC3E,SAAgB,WAAW,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;gBAE9C,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC;CAI3E"}

package/dist/pipeline/pipeline-construct.js

@@ -8,6 +8,7 @@ import { CodeBuildStep, CodePipeline, CodePipelineSource, ManualApprovalStep, Sh
 import { Construct } from 'constructs';
 import * as fs from 'fs';
 import * as path from 'path';
+import { pathToFileURL } from 'node:url';
 /**
  * Resolve a relative file path against the calling file's directory.
  *
@@ -420,8 +421,10 @@ async function importAppFileForStage(stage, stageConfig, appFile) {
     // Capture current beforeExit listeners before import
     const listenersBefore = process.listeners('beforeExit').slice();
     try {
-        // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
-        await import(`${appFile}?stage=${encodeURIComponent(stageConfig.name)}`);
+        // file:// URL (not a raw path) so the cache-busting query works on Windows.
+        const appUrl = pathToFileURL(appFile);
+        appUrl.searchParams.set('stage', stageConfig.name);
+        await import(appUrl.href);
     }
     finally {
         // Remove any beforeExit listeners added during import.

package/dist/scripts/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/scripts/deploy.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,iBAwFlD"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/scripts/deploy.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,iBAwFlD"}

package/dist/scripts/deploy.js

@@ -8,6 +8,7 @@ import { ensureSecrets, loadProductionEnv } from './ensure-secrets.js';
 import { applyExternalMigrations } from './external-migrations-step.js';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+import { runSync } from './run-command.js';
 export async function deploy(options) {
     return trackCommand('deploy', async () => {
         console.log('🏗️  Preparing deployment...');
@@ -42,7 +43,7 @@ export async function deploy(options) {
         console.log('   - Backend API (Lambda + API Gateway)');
         console.log('   - Frontend hosting (S3 + CloudFront)');
         try {
-            execFileSync("npx", [
+            runSync("npx", [
                 "cdk", "deploy",
                 "--require-approval", "never",
                 "--outputs-file", ".blocks-sandbox/outputs.json",

package/dist/scripts/destroy.js

@@ -1,13 +1,13 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { execFileSync } from 'node:child_process';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+import { runSync } from './run-command.js';
 export async function destroy(options) {
     return trackCommand('destroy', async () => {
         console.log('🗑️  Destroying production stack...');
         try {
-            execFileSync("npx", [
+            runSync("npx", [
                 "cdk", "destroy",
                 "--force",
                 "--context", `projectRoot=${options.projectRoot}`,

package/dist/scripts/external-migrations-step.js

@@ -22,10 +22,10 @@
  * exists. Aurora-managed databases run migrations via their in-VPC Lambda, not
  * here.
  */
-import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { findConnectionString } from './ensure-secrets.js';
 import { extractDbRef, dbConnectionParameterName } from '../db-naming.js';
+import { runSync } from './run-command.js';
 const DEFAULT_MIGRATIONS_DIR = './migrations';
 /** Default output dir for db-pull generated files (database.types.ts / database.meta.ts). */
 const DEFAULT_GENERATED_DIR = './aws-blocks';
@@ -50,7 +50,7 @@ export function buildMigrateArgs(stage, migrationsDir, regenerateTypesDir) {
     return args;
 }
 function runMigrateSubprocess(connValue, stage, migrationsDir, regenerateTypesDir) {
-    execFileSync('npx', buildMigrateArgs(stage, migrationsDir, regenerateTypesDir), {
+    runSync('npx', buildMigrateArgs(stage, migrationsDir, regenerateTypesDir), {
         stdio: 'inherit',
         env: { ...process.env, BLOCKS_MIGRATE_URL: connValue },
     });

package/dist/scripts/extract-ts-types.js

@@ -20,7 +20,7 @@ import { existsSync } from 'fs';
  * JSDoc parsers.
  */
 export const BLOCKS_SKIP_CODEGEN_TAG = 'blocksSkipCodegen';
-function hasKitSkipCodegenTag(node) {
+function hasBlocksSkipCodegenTag(node) {
     for (const tag of ts.getJSDocTags(node)) {
         if (tag.tagName.text === BLOCKS_SKIP_CODEGEN_TAG)
             return true;
@@ -51,7 +51,7 @@ export function extractSkipCodegenMethods(sourcePath) {
             if (ts.isMethodDeclaration(prop) &&
                 prop.name &&
                 ts.isIdentifier(prop.name) &&
-                hasKitSkipCodegenTag(prop)) {
+                hasBlocksSkipCodegenTag(prop)) {
                 result.add(prop.name.text);
             }
         }
@@ -253,7 +253,7 @@ function extractMethodTypeInfo(method, checker, sourceFile) {
         transferable = detectTransferable(retType, checker, retTypeNode);
         returnType = tsTypeToJsonSchema(retType, checker);
     }
-    const skipCodegen = hasKitSkipCodegenTag(method) || undefined;
+    const skipCodegen = hasBlocksSkipCodegenTag(method) || undefined;
     return { params, returnType, transferable, skipCodegen };
 }
 /**
@@ -343,7 +343,7 @@ function extractMethodsFromResolvedType(type, checker, result) {
         // the BB-helper file that minted the AsyncAPI<T> shape).
         let skipCodegen;
         const declaration = prop.valueDeclaration;
-        if (declaration && hasKitSkipCodegenTag(declaration)) {
+        if (declaration && hasBlocksSkipCodegenTag(declaration)) {
             skipCodegen = true;
         }
         result.set(propName, { params, returnType, transferable, skipCodegen });

package/dist/scripts/run-command.d.ts

@@ -0,0 +1,9 @@
+import type { ChildProcess, SpawnOptions, SpawnSyncOptions } from 'node:child_process';
+/**
+ * Run a command to completion (stdio inherited) and throw on failure — a
+ * cross-platform drop-in for `execFileSync` where only success/failure matters.
+ */
+export declare function runSync(command: string, args: string[], options?: SpawnSyncOptions): void;
+/** Spawn a long-running command and return the `ChildProcess` (e.g. `cdk watch`). */
+export declare function spawnCommand(command: string, args: string[], options: SpawnOptions): ChildProcess;
+//# sourceMappingURL=run-command.d.ts.map

package/dist/scripts/run-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-command.d.ts","sourceRoot":"","sources":["../../src/scripts/run-command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EACZ,gBAAgB,EACjB,MAAM,oBAAoB,CAAC;AAQ5B;;;GAGG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE,gBAAqB,GAC7B,IAAI,CAYN;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,YAAY,GACpB,YAAY,CAEd"}

package/dist/scripts/run-command.js

@@ -0,0 +1,27 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import spawn from 'cross-spawn';
+// `npm`/`npx`/`cdk`/`tsx` are `.cmd` shims on Windows, which Node's
+// execFileSync/spawn can't resolve (spawnSync ENOENT) and won't run without a
+// shell. cross-spawn resolves the shim and quotes args safely (array form, no
+// shell injection), so these wrappers work on Windows too.
+/**
+ * Run a command to completion (stdio inherited) and throw on failure — a
+ * cross-platform drop-in for `execFileSync` where only success/failure matters.
+ */
+export function runSync(command, args, options = {}) {
+    const result = spawn.sync(command, args, { stdio: 'inherit', ...options });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.signal) {
+        throw new Error(`${command} was terminated by signal ${result.signal}`);
+    }
+    if (typeof result.status === 'number' && result.status !== 0) {
+        throw new Error(`${command} ${args.join(' ')} exited with code ${result.status}`);
+    }
+}
+/** Spawn a long-running command and return the `ChildProcess` (e.g. `cdk watch`). */
+export function spawnCommand(command, args, options) {
+    return spawn(command, args, options);
+}

package/dist/scripts/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAqJzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/scripts/sandbox.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,+BAqJzD;AAED,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,iBAwCvD"}

package/dist/scripts/sandbox.js

@@ -1,6 +1,6 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -9,6 +9,7 @@ import { applyExternalMigrations } from './external-migrations-step.js';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { buildAndSendEvent } from '../telemetry/client.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+import { runSync, spawnCommand } from './run-command.js';
 /**
  * Import the backend definition to populate the Scope BB registry.
  *
@@ -55,7 +56,7 @@ export async function startSandbox(options) {
     console.log("🚀 Deploying to AWS...");
     console.log("   (This may take a few minutes on first deploy)");
     try {
-        execFileSync("npm", [
+        runSync("npm", [
             "exec", "cdk", "--", "deploy",
             "--require-approval", "never",
             "--outputs-file", `${outDir}/outputs.json`,
@@ -112,7 +113,7 @@ export async function startSandbox(options) {
     console.log("\n👀 Starting CDK watch mode...");
     console.log("🌐 Starting local dev server (proxying to AWS)...");
     console.log(`\n   Open http://localhost:${clientPort}\n`);
-    const cdkWatch = spawn("npx", [
+    const cdkWatch = spawnCommand("npx", [
         "cdk", "watch", "--hotswap",
         `--outputs-file`, `${outDir}/outputs.json`,
         `--context`, `projectRoot=${process.cwd()}`,
@@ -133,7 +134,7 @@ export async function startSandbox(options) {
     });
     const devServerCmd = devCommand || `npx tsx watch aws-blocks/scripts/server.ts`;
     const [cmd, ...args] = devServerCmd.split(' ');
-    const devServer = spawn(cmd, args, {
+    const devServer = spawnCommand(cmd, args, {
         stdio: "inherit",
         shell: true,
         env: {
@@ -180,7 +181,7 @@ export async function destroySandbox(backendPath) {
         const retryDelays = [60_000, 120_000]; // 1min, then 2min
         for (let attempt = 0;; attempt++) {
             try {
-                execFileSync("npm", cdkArgs, { stdio: "inherit", env: cdkEnv });
+                runSync("npm", cdkArgs, { stdio: "inherit", env: cdkEnv });
                 console.log(attempt === 0 ? "\n✅ Sandbox destroyed!" : "\n✅ Sandbox destroyed on retry!");
                 return;
             }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CORE_VERSION = "0.1.0";
+export declare const CORE_VERSION = "0.1.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
-export const CORE_VERSION = '0.1.0';
+export const CORE_VERSION = '0.1.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "author": "Amazon Web Services",
   "license": "Apache-2.0",
   "type": "module",
@@ -55,6 +55,7 @@
     "blocks-telemetry": "./dist/scripts/telemetry-cli.js"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/http-proxy": "^1.17.16",
     "@types/node": "^20.0.0",
     "typescript": "^5.3.0",
@@ -64,6 +65,7 @@
     "@aws-blocks/hosting": "*",
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/client-ssm": "^3.700.0",
+    "cross-spawn": "^7.0.6",
     "http-proxy": "^1.18.1"
   },
   "peerDependencies": {

package/src/cdk/blocks-backend.ts

@@ -6,6 +6,7 @@ import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
 import { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
 import { Construct } from 'constructs';
+import { pathToFileURL } from 'node:url';
 import { DEFAULT_NODE_RUNTIME } from './node-version.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
@@ -230,8 +231,11 @@ export class BlocksBackend extends Construct {
   static async create(scope: Construct, id: string, props: BlocksBackendProps) {
     assertCdkConditionActive();
     const backend = new BlocksBackend(scope, id, props);
-    // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
-    const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+    // file:// URL (not a raw path) so the cache-busting query works on Windows,
+    // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
+    const backendUrl = pathToFileURL(props.backendCDKPath);
+    backendUrl.searchParams.set('stack', id);
+    const mod = await import(backendUrl.href);
     if (typeof mod.default === 'function') {
       try {
         await mod.default(backend);

package/src/cdk/index.ts

@@ -3,6 +3,7 @@
 
 import * as cdk from 'aws-cdk-lib';
 import { Construct } from 'constructs';
+import { pathToFileURL } from 'node:url';
 import {
   type BlocksStackProps,
   type BlocksStack as BaseBlocksStack,
@@ -51,8 +52,11 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     const actualScope = pipelineScope || scope;
 
     const stack = new BlocksStack(actualScope, id, props);
-    // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
-    const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+    // file:// URL (not a raw path) so the cache-busting query works on Windows,
+    // where an absolute path like `D:\...` is rejected as URL scheme `d:`.
+    const backendUrl = pathToFileURL(props.backendCDKPath);
+    backendUrl.searchParams.set('stack', id);
+    const mod = await import(backendUrl.href);
     if (typeof mod.default === 'function') {
       try {
         await mod.default(stack);

package/src/client/index.ts

@@ -144,7 +144,7 @@ async function resolveApiUrl(): Promise<string> {
  * Middleware can inspect or modify any of these properties before the
  * request is dispatched to the server.
  */
-export interface KitRequest {
+export interface BlocksRequest {
   /** The namespace name this call targets (e.g., 'api', 'auth'). Corresponds to the second argument of `new ApiNamespace(scope, name, handler)` in the backend. */
   apiNamespace: string;
   /** The method being called on the namespace (e.g., 'getUser', 'kvSet'). */
@@ -176,14 +176,14 @@ export interface KitRequest {
  * });
  * ```
  */
-export interface KitMiddleware {
+export interface BlocksMiddleware {
   /** Transform the request before it's sent. Modify the request in place or return a new one. Can be async. */
-  onRequest?: (request: KitRequest) => KitRequest | void | Promise<KitRequest | void>;
+  onRequest?: (request: BlocksRequest) => BlocksRequest | void | Promise<BlocksRequest | void>;
   /** Transform the response data after it's received. Used to hydrate __blocks descriptors. */
   onResponse?: (data: unknown) => unknown;
 }
 
-const middlewares: KitMiddleware[] = [];
+const middlewares: BlocksMiddleware[] = [];
 
 /**
  * Register client middleware for request/response processing.
@@ -204,11 +204,11 @@ const middlewares: KitMiddleware[] = [];
  * an explicit `attach(server)` pattern because they need the HTTP server
  * instance passed to them — something unavailable at import time.
  */
-export function registerMiddleware(middleware: KitMiddleware): void {
+export function registerMiddleware(middleware: BlocksMiddleware): void {
   middlewares.push(middleware);
 }
 
-async function processRequest(request: KitRequest): Promise<KitRequest> {
+async function processRequest(request: BlocksRequest): Promise<BlocksRequest> {
   for (const mw of middlewares) {
     if (mw.onRequest) {
       const result = await mw.onRequest(request);
@@ -265,7 +265,7 @@ export function ApiNamespaceClient<T extends Record<string, (...args: any[]) =>
       return async (...args: any[]) => {
         const apiUrl = urlOverride ?? await getApiUrl();
         
-        let request: KitRequest = {
+        let request: BlocksRequest = {
           apiNamespace: name,
           method,
           args,

package/src/pipeline/pipeline-construct.ts

@@ -15,6 +15,7 @@ import {
 import { Construct } from 'constructs';
 import * as fs from 'fs';
 import * as path from 'path';
+import { pathToFileURL } from 'node:url';
 import type {
   BranchConfig,
   PipelineProps,
@@ -579,8 +580,10 @@ async function importAppFileForStage<TConfig>(
   const listenersBefore = process.listeners('beforeExit').slice();
 
   try {
-    // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
-    await import(`${appFile}?stage=${encodeURIComponent(stageConfig.name)}`);
+    // file:// URL (not a raw path) so the cache-busting query works on Windows.
+    const appUrl = pathToFileURL(appFile);
+    appUrl.searchParams.set('stage', stageConfig.name);
+    await import(appUrl.href);
   } finally {
     // Remove any beforeExit listeners added during import.
     // The imported file's cdk.App() registers a synth() handler that would

package/src/scripts/deploy.ts

@@ -9,6 +9,7 @@ import { ensureSecrets, loadProductionEnv } from './ensure-secrets.js';
 import { applyExternalMigrations } from './external-migrations-step.js';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+import { runSync } from './run-command.js';
 
 export interface DeployOptions {
   cdkAppPath: string;
@@ -56,7 +57,7 @@ export async function deploy(options: DeployOptions) {
     console.log('   - Frontend hosting (S3 + CloudFront)');
     
     try {
-      execFileSync(
+      runSync(
         "npx",
         [
           "cdk", "deploy",

package/src/scripts/destroy.ts

@@ -1,9 +1,9 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { execFileSync } from 'node:child_process';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+import { runSync } from './run-command.js';
 
 export interface DestroyOptions {
   cdkAppPath: string;
@@ -15,7 +15,7 @@ export async function destroy(options: DestroyOptions) {
     console.log('🗑️  Destroying production stack...');
 
     try {
-      execFileSync(
+      runSync(
         "npx",
         [
           "cdk", "destroy",

package/src/scripts/external-migrations-step.ts

@@ -24,10 +24,10 @@
  * here.
  */
 
-import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { findConnectionString } from './ensure-secrets.js';
 import { extractDbRef, dbConnectionParameterName } from '../db-naming.js';
+import { runSync } from './run-command.js';
 
 const DEFAULT_MIGRATIONS_DIR = './migrations';
 /** Default output dir for db-pull generated files (database.types.ts / database.meta.ts). */
@@ -59,7 +59,7 @@ function runMigrateSubprocess(
   migrationsDir: string,
   regenerateTypesDir?: string,
 ): void {
-  execFileSync('npx', buildMigrateArgs(stage, migrationsDir, regenerateTypesDir), {
+  runSync('npx', buildMigrateArgs(stage, migrationsDir, regenerateTypesDir), {
     stdio: 'inherit',
     env: { ...process.env, BLOCKS_MIGRATE_URL: connValue },
   });

package/src/scripts/extract-ts-types.ts

@@ -48,7 +48,7 @@ export interface MethodTypeInfo {
  */
 export const BLOCKS_SKIP_CODEGEN_TAG = 'blocksSkipCodegen';
 
-function hasKitSkipCodegenTag(node: ts.Node): boolean {
+function hasBlocksSkipCodegenTag(node: ts.Node): boolean {
 	for (const tag of ts.getJSDocTags(node)) {
 		if (tag.tagName.text === BLOCKS_SKIP_CODEGEN_TAG) return true;
 	}
@@ -86,7 +86,7 @@ export function extractSkipCodegenMethods(sourcePath: string): Set<string> {
 				ts.isMethodDeclaration(prop) &&
 				prop.name &&
 				ts.isIdentifier(prop.name) &&
-				hasKitSkipCodegenTag(prop)
+				hasBlocksSkipCodegenTag(prop)
 			) {
 				result.add(prop.name.text);
 			}
@@ -328,7 +328,7 @@ function extractMethodTypeInfo(
 		returnType = tsTypeToJsonSchema(retType, checker);
 	}
 
-	const skipCodegen = hasKitSkipCodegenTag(method) || undefined;
+	const skipCodegen = hasBlocksSkipCodegenTag(method) || undefined;
 	return { params, returnType, transferable, skipCodegen };
 }
 
@@ -429,7 +429,7 @@ function extractMethodsFromResolvedType(
 		// the BB-helper file that minted the AsyncAPI<T> shape).
 		let skipCodegen: true | undefined;
 		const declaration = prop.valueDeclaration;
-		if (declaration && hasKitSkipCodegenTag(declaration)) {
+		if (declaration && hasBlocksSkipCodegenTag(declaration)) {
 			skipCodegen = true;
 		}
 

package/src/scripts/run-command.ts

@@ -0,0 +1,45 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+  ChildProcess,
+  SpawnOptions,
+  SpawnSyncOptions,
+} from 'node:child_process';
+import spawn from 'cross-spawn';
+
+// `npm`/`npx`/`cdk`/`tsx` are `.cmd` shims on Windows, which Node's
+// execFileSync/spawn can't resolve (spawnSync ENOENT) and won't run without a
+// shell. cross-spawn resolves the shim and quotes args safely (array form, no
+// shell injection), so these wrappers work on Windows too.
+
+/**
+ * Run a command to completion (stdio inherited) and throw on failure — a
+ * cross-platform drop-in for `execFileSync` where only success/failure matters.
+ */
+export function runSync(
+  command: string,
+  args: string[],
+  options: SpawnSyncOptions = {},
+): void {
+  const result = spawn.sync(command, args, { stdio: 'inherit', ...options });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.signal) {
+    throw new Error(`${command} was terminated by signal ${result.signal}`);
+  }
+  if (typeof result.status === 'number' && result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} exited with code ${result.status}`);
+  }
+}
+
+/** Spawn a long-running command and return the `ChildProcess` (e.g. `cdk watch`). */
+export function spawnCommand(
+  command: string,
+  args: string[],
+  options: SpawnOptions,
+): ChildProcess {
+  return spawn(command, args, options);
+}

package/src/scripts/sandbox.ts

@@ -1,7 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -10,6 +10,7 @@ import { applyExternalMigrations } from './external-migrations-step.js';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { buildAndSendEvent } from '../telemetry/client.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
+import { runSync, spawnCommand } from './run-command.js';
 
 /**
  * Import the backend definition to populate the Scope BB registry.
@@ -69,7 +70,7 @@ export async function startSandbox(options: SandboxOptions) {
   console.log("   (This may take a few minutes on first deploy)");
 
   try {
-    execFileSync(
+    runSync(
       "npm",
       [
         "exec", "cdk", "--", "deploy",
@@ -138,7 +139,7 @@ export async function startSandbox(options: SandboxOptions) {
   console.log("🌐 Starting local dev server (proxying to AWS)...");
   console.log(`\n   Open http://localhost:${clientPort}\n`);
 
-  const cdkWatch = spawn("npx", [
+  const cdkWatch = spawnCommand("npx", [
     "cdk", "watch", "--hotswap",
     `--outputs-file`, `${outDir}/outputs.json`,
     `--context`, `projectRoot=${process.cwd()}`,
@@ -162,7 +163,7 @@ export async function startSandbox(options: SandboxOptions) {
   const devServerCmd = devCommand || `npx tsx watch aws-blocks/scripts/server.ts`;
   const [cmd, ...args] = devServerCmd.split(' ');
   
-  const devServer = spawn(cmd, args, {
+  const devServer = spawnCommand(cmd, args, {
     stdio: "inherit",
     shell: true,
     env: { 
@@ -212,7 +213,7 @@ export async function destroySandbox(backendPath: string) {
 
     for (let attempt = 0; ; attempt++) {
       try {
-        execFileSync("npm", cdkArgs, { stdio: "inherit", env: cdkEnv });
+        runSync("npm", cdkArgs, { stdio: "inherit", env: cdkEnv });
         console.log(attempt === 0 ? "\n✅ Sandbox destroyed!" : "\n✅ Sandbox destroyed on retry!");
         return;
       } catch (error) {

package/src/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
-export const CORE_VERSION = '0.1.0';
+export const CORE_VERSION = '0.1.2';