@karmaniverous/smoz 0.2.9 → 0.2.11

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { ZodOpenApiOperationObject, ZodOpenApiPathItemObject, ZodOpenApiPathsObject } from 'zod-openapi';
 import * as aws_lambda from 'aws-lambda';
-import { APIGatewayProxyEvent, Context, APIGatewayProxyEventV2, ALBEvent, SQSEvent, SNSEvent, S3Event, DynamoDBStreamEvent, KinesisStreamEvent, EventBridgeEvent, CloudWatchLogsEvent, SESEvent, CloudFrontRequestEvent, FirehoseTransformationEvent, CognitoUserPoolTriggerEvent } from 'aws-lambda';
+import { APIGatewayProxyEvent, APIGatewayProxyEventV2, ALBEvent, SQSEvent, SNSEvent, S3Event, DynamoDBStreamEvent, KinesisStreamEvent, EventBridgeEvent, CloudWatchLogsEvent, SESEvent, CloudFrontRequestEvent, FirehoseTransformationEvent, CognitoUserPoolTriggerEvent, Context } from 'aws-lambda';
 import { AWS } from '@serverless/typescript';
-import { ZodObject, ZodRawShape, z } from 'zod';
+import { z, ZodObject, ZodRawShape } from 'zod';
 import { MiddlewareObj } from '@middy/core';
 import httpContentNegotiation from '@middy/http-content-negotiation';
 import httpCors from '@middy/http-cors';
@@ -35,6 +35,39 @@ type MakeRequired<T extends object, U extends keyof T> = {
  */
 type BaseOperation = MakeRequired<Omit<ZodOpenApiOperationObject, 'operationId'>, 'summary'>;
 
+/**
+ * baseEventTypeMapSchema
+ * - Schema-first companion to BaseEventTypeMap.
+ * - Now includes a Step Functions event with an optional Payload wrapper.
+ * - Ensures z.infer<typeof baseEventTypeMapSchema> === BaseEventTypeMap.
+ *
+ * @remarks * Consumers typically extend this schema when creating an App to add
+ * project‑local event tokens (e.g., 'step').
+ * Only tokens listed in the app’s `httpEventTypeTokens` are treated as HTTP at runtime.
+ */
+
+declare const baseEventTypeMapSchema: z.ZodObject<{
+    rest: z.ZodCustom<APIGatewayProxyEvent, APIGatewayProxyEvent>;
+    http: z.ZodCustom<APIGatewayProxyEventV2, APIGatewayProxyEventV2>;
+    alb: z.ZodCustom<ALBEvent, ALBEvent>;
+    sqs: z.ZodCustom<SQSEvent, SQSEvent>;
+    sns: z.ZodCustom<SNSEvent, SNSEvent>;
+    s3: z.ZodCustom<S3Event, S3Event>;
+    dynamodb: z.ZodCustom<DynamoDBStreamEvent, DynamoDBStreamEvent>;
+    kinesis: z.ZodCustom<KinesisStreamEvent, KinesisStreamEvent>;
+    eventbridge: z.ZodCustom<EventBridgeEvent<string, unknown>, EventBridgeEvent<string, unknown>>;
+    'cloudwatch-logs': z.ZodCustom<CloudWatchLogsEvent, CloudWatchLogsEvent>;
+    ses: z.ZodCustom<SESEvent, SESEvent>;
+    cloudfront: z.ZodCustom<CloudFrontRequestEvent, CloudFrontRequestEvent>;
+    firehose: z.ZodCustom<FirehoseTransformationEvent, FirehoseTransformationEvent>;
+    'cognito-userpool': z.ZodCustom<CognitoUserPoolTriggerEvent, CognitoUserPoolTriggerEvent>;
+    step: z.ZodObject<{
+        Payload: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$catchall<z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Canonical base event map type (schema‑first). Extend the schema in your App. */
+type BaseEventTypeMap = z.infer<typeof baseEventTypeMapSchema>;
+
 type Dict<T> = Record<string, T>;
 type StagesFactoryInput<GlobalParams extends Record<string, unknown>, StageParams extends Record<string, unknown>> = {
     globalParamsSchema: ZodObject<ZodRawShape>;
@@ -327,36 +360,6 @@ declare const buildSafeDefaults: (args: BuildSafeDefaultsArgs) => {
     onError: M[];
 };
 
-/**
- * baseEventTypeMapSchema
- * - Schema-first companion to BaseEventTypeMap.
- * - Ensures z.infer<typeof baseEventTypeMapSchema> === BaseEventTypeMap.
- *
- * @remarks
- * Consumers typically extend this schema when creating an App to add
- * project‑local event tokens (e.g., 'step').
- * Only tokens listed in the app’s `httpEventTypeTokens` are treated as HTTP at runtime.
- */
-
-declare const baseEventTypeMapSchema: z.ZodObject<{
-    rest: z.ZodCustom<APIGatewayProxyEvent, APIGatewayProxyEvent>;
-    http: z.ZodCustom<APIGatewayProxyEventV2, APIGatewayProxyEventV2>;
-    alb: z.ZodCustom<ALBEvent, ALBEvent>;
-    sqs: z.ZodCustom<SQSEvent, SQSEvent>;
-    sns: z.ZodCustom<SNSEvent, SNSEvent>;
-    s3: z.ZodCustom<S3Event, S3Event>;
-    dynamodb: z.ZodCustom<DynamoDBStreamEvent, DynamoDBStreamEvent>;
-    kinesis: z.ZodCustom<KinesisStreamEvent, KinesisStreamEvent>;
-    eventbridge: z.ZodCustom<EventBridgeEvent<string, unknown>, EventBridgeEvent<string, unknown>>;
-    'cloudwatch-logs': z.ZodCustom<CloudWatchLogsEvent, CloudWatchLogsEvent>;
-    ses: z.ZodCustom<SESEvent, SESEvent>;
-    cloudfront: z.ZodCustom<CloudFrontRequestEvent, CloudFrontRequestEvent>;
-    firehose: z.ZodCustom<FirehoseTransformationEvent, FirehoseTransformationEvent>;
-    'cognito-userpool': z.ZodCustom<CognitoUserPoolTriggerEvent, CognitoUserPoolTriggerEvent>;
-}, z.core.$strip>;
-/** Canonical base event map type (schema‑first). Extend the schema in your App. */
-type BaseEventTypeMap = z.infer<typeof baseEventTypeMapSchema>;
-
 /** HTTP methods supported from zod-openapi's PathItem shape (excluding helper 'id'). */
 type MethodKey = keyof Omit<ZodOpenApiPathItemObject, 'id'>;
 /**
@@ -462,13 +465,14 @@ interface AppInit<GlobalParamsSchema extends ZodObj, StageParamsSchema extends Z
      * @returns a new App instance
      */
     static create<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj>(init: AppInit<GlobalParamsSchema, StageParamsSchema, EventTypeMapSchema>): App<GlobalParamsSchema, StageParamsSchema, EventTypeMapSchema>;
+    static create<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj>(init: Omit<AppInit<GlobalParamsSchema, StageParamsSchema, typeof baseEventTypeMapSchema>, 'eventTypeMapSchema'> & {
+        eventTypeMapSchema?: undefined;
+    }): App<GlobalParamsSchema, StageParamsSchema, typeof baseEventTypeMapSchema>;
     /**
      * Register a function (HTTP or non‑HTTP).
      *
      * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
-     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
-     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
-     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
+     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)   * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)   * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
      * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
      */
     defineFunction<EventType extends Extract<keyof z.infer<EventTypeMapSchema>, string>, EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined>(options: {
@@ -499,6 +503,10 @@ interface AppInit<GlobalParamsSchema extends ZodObj, StageParamsSchema extends Z
             cloudfront: aws_lambda.CloudFrontRequestEvent;
             firehose: aws_lambda.FirehoseTransformationEvent;
             'cognito-userpool': aws_lambda.CognitoUserPoolTriggerEvent;
+            step: {
+                [x: string]: unknown;
+                Payload?: unknown;
+            };
         })[EventType]>) => (event: unknown, context: aws_lambda.Context) => Promise<ResponseSchema extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.output<ResponseSchema> : unknown>;
         openapi: (baseOperation: BaseOperation) => void;
         serverless: (extras: unknown) => void;
@@ -562,7 +570,7 @@ interface EnvAttached<GlobalParamsSchema extends ZodObject<ZodRawShape>, StagePa
  * type R = DeepOverride<A, B>;
  */
 type DeepOverride<T, U> = [T] extends [never] ? U : [U] extends [never] ? T : T extends any[] ? U : U extends any[] ? U : T extends object ? U extends object ? {
-    [K in keyof (T & U)]: K extends keyof U ? DeepOverride<K extends keyof T ? T[K] : never, U[K & keyof U]> : K extends keyof T ? T[K] : never;
+    [K in keyof T | keyof U]: K extends keyof U ? DeepOverride<K extends keyof T ? T[K] : never, K extends keyof U ? U[K] : never> : K extends keyof T ? T[K] : never;
 } : T : U;
 
 /** Event type after applying deep schema overrides. */

package/dist/mjs/index.js

@@ -28,12 +28,23 @@ const baseEventTypeMapSchema = z.object({
     firehose: z.custom(),
     // eslint-disable-next-line @typescript-eslint/no-deprecated -- Upstream AWS types mark this as deprecated; we retain the token for compatibility with existing apps.
     'cognito-userpool': z.custom(),
+    /**
+     * Step Functions → Lambda (Service Integration: Lambda Invoke)
+     *
+     * When Step Functions invokes Lambda via the AWS SDK integration
+     * (e.g., "arn:aws:states:::lambda:invoke"), the event received by the
+     * Lambda handler is an object that wraps the original input under a
+     * "Payload" key. The Payload is already parsed JSON.
+     *
+     * Notes:
+     * - We accept additional keys (e.g., StatusCode/ExecutedVersion in some
+     *   patterns) via passthrough.
+     * - For the common “request/response” integration where Step Functions
+     *   passes state directly, apps can still treat the event via their
+     *   own app-local event map if needed.
+     */
+    step: z.object({ Payload: z.unknown().optional() }).catchall(z.unknown()),
 });
-// Notes:
-// - This list intentionally includes widely used, generic AWS events.
-// - Apps can extend the schema with custom or specialized tokens:
-//     const EventMap = baseEventTypeMapSchema.extend({ step: z.custom<MyStepEvent>() })
-// - Only tokens listed in your App's httpEventTypeTokens are treated as HTTP by the runtime.
 
 /**
  * Stage artifacts factory.
@@ -1041,10 +1052,10 @@ const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
 /**
  * App (schema‑first)
  *
+ * Overloads on create() preserve strong inference when eventTypeMapSchema is omitted.
  * Central orchestrator for a SMOZ application. You provide:
  * - Global/stage parameter schemas and env exposure keys
- * - Serverless defaults (handler filename/export and context map)
- * - Event‑type map schema (extendable: e.g., add 'step')
+ * - Serverless defaults (handler filename/export and context map) * - Event‑type map schema (extendable: e.g., add 'step')
  *
  * The instance:
  * - Validates configuration
@@ -1128,6 +1139,7 @@ const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
      * @param init - initialization object (schemas, serverless defaults, params/envKeys)
      * @returns a new App instance
      */
+    // Implementation (must come after overload signatures)
     static create(init) {
         return new App(init);
     }
@@ -1135,9 +1147,7 @@ const buildAllServerlessFunctions = (registry, serverless, buildFnEnv) => {
      * Register a function (HTTP or non‑HTTP).
      *
      * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
-     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
-     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
-     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
+     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)   * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)   * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
      * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
      */
     defineFunction(options) {

package/package.json

@@ -13,6 +13,7 @@
     "url": "https://github.com/karmaniverous/smoz/issues"
   },
   "dependencies": {
+    "@karmaniverous/get-dotenv": "^5.2.6",
     "@middy/core": "^6.4.5",
     "@middy/http-content-negotiation": "^6.4.5",
     "@middy/http-cors": "^6.4.5",
@@ -23,57 +24,56 @@
     "@middy/http-response-serializer": "^6.4.5",
     "aws-lambda": "^1.0.7",
     "chokidar": "^4.0.3",
-    "commander": "^14.0.1",
-    "http-errors": "^2.0.0",
+    "http-errors": "^2.0.1",
     "package-directory": "^8.1.0",
     "radash": "^12.1.1",
-    "zod": "^4.1.8"
+    "zod": "^4.1.13"
   },
   "description": "John Galt Services back end.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.49.0",
-    "@eslint/js": "^9.35.0",
-    "@rollup/plugin-alias": "^5.1.1",
-    "@rollup/plugin-typescript": "^12.1.4",
-    "@serverless/typescript": "^4.18.2",
-    "@types/aws-lambda": "^8.10.152",
+    "@dotenvx/dotenvx": "^1.51.1",
+    "@eslint/js": "^9.39.1",
+    "@rollup/plugin-alias": "^6.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@serverless/typescript": "^4.23.0",
+    "@types/aws-lambda": "^8.10.159",
     "@types/fs-extra": "^11.0.4",
     "@types/http-errors": "^2.0.5",
-    "@types/node": "^22",
+    "@types/node": "^24",
     "@types/serverless": "^3.12.27",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.0.13",
     "auto-changelog": "^2.5.0",
+    "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-simple-import-sort": "^12.1.1",
-    "eslint": "^9.35.0",
-    "fs-extra": "^11.3.1",
-    "knip": "^5.63.1",
-    "lefthook": "^1.13.0",
+    "fs-extra": "^11.3.2",
+    "knip": "^5.70.2",
+    "lefthook": "^2.0.4",
     "prettier": "^3.6.2",
-    "release-it": "^19.0.4",
-    "rimraf": "^6.0.1",
+    "release-it": "^19.0.6",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.53.3",
     "rollup-plugin-dts": "^6.2.3",
-    "rollup": "^4.50.1",
+    "serverless": "^4.25.0",
     "serverless-apigateway-log-retention": "^1.1.0",
     "serverless-deployment-bucket": "^1.6.0",
     "serverless-domain-manager": "^8.0.0",
     "serverless-offline": "^14.4.0",
     "serverless-plugin-common-excludes": "^4.0.0",
-    "serverless": "^4.18.2",
-    "tsx": "^4.20.5",
-    "typedoc-plugin-mdn-links": "^5.0.9",
+    "tsx": "^4.20.6",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-mdn-links": "^5.0.10",
     "typedoc-plugin-replace-text": "^4.2.0",
-    "typedoc-plugin-zod": "^1.4.2",
-    "typedoc": "^0.28.12",
-    "typescript-eslint": "^8.43.0",
-    "typescript": "^5.9.2",
+    "typedoc-plugin-zod": "^1.4.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.0",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.2.4",
-    "zod-openapi": "^5.4.1"
+    "vitest": "^4.0.13",
+    "zod-openapi": "^5.4.3"
   },
   "engines": {
-    "node": ">=22.19.0 <23"
+    "node": ">=22.19.0"
   },
   "exports": {
     ".": {
@@ -142,15 +142,15 @@
         "npm run knip",
         "npm run build"
       ],
-      "before:npm:release": [
-        "npx auto-changelog -p",
-        "npm run docs",
-        "git add -A"
-      ],
       "after:release": [
         "git switch -c release/${version}",
         "git push -u origin release/${version}",
         "git switch ${branchName}"
+      ],
+      "after:bump": [
+        "npx auto-changelog -p",
+        "npm run docs",
+        "git add CHANGELOG.md"
       ]
     },
     "npm": {
@@ -172,20 +172,19 @@
     "knip": "knip",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "openapi": "tsx src/cli/index.ts register && tsx app/config/openapi && prettier -w app/generated/openapi.json",
-    "package": "tsx src/cli/index.ts register && serverless package",
+    "openapi": "tsx src/cli/index.ts register && tsx src/cli/index.ts openapi",
+    "package": "serverless package",
     "release": "dotenvx run -f .env.local -- release-it",
     "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
     "remove": "serverless remove",
     "smoz": "tsx src/cli/index.ts",
-    "stan:docs": "typedoc --emit none",
     "test": "vitest run",
     "typecheck": "tsx src/cli/index.ts register && tsc -p tsconfig.json --noEmit",
     "templates:typecheck": "tsx scripts/templates-typecheck.ts",
     "templates:lint": "eslint --fix -c templates/default/eslint.config.ts \"templates/default/**/*.{ts,tsx,js,jsx}\" \"templates/default/eslint.config.ts\""
   },
   "type": "module",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "volta": {
     "node": "22.19.0"
   }

package/templates/default/.vscode/extensions.json

@@ -1,8 +1,8 @@
-{
-  "recommendations": [
-    "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode",
-    "redhat.vscode-yaml",
-    "vitest.explorer"
-  ]
-}
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "redhat.vscode-yaml",
+    "vitest.explorer"
+  ]
+}

package/templates/default/README.md

@@ -1,96 +1,98 @@
-# SMOZ App Template
-
-This template provides a minimal, convention‑friendly baseline for new SMOZ apps:
-
-- TypeScript configuration (strict, moduleResolution bundler)
-- ESLint (flat config) + typescript‑eslint + Prettier
-- Vitest baseline config
-- TypeDoc baseline config
-
-## Conventions
-
-- Author code lives under:
-  - `app/config/app.config.ts` — app schemas/config (params, env, http tokens)
-  - `app/functions/<eventType>/...` (e.g., `app/functions/rest/hello/get`)
-- Generated artifacts live under:
-  - `app/generated/`
-    - `register.functions.ts` — side‑effect imports of all `lambda.ts`
-    - `register.openapi.ts` — side‑effect imports of all `openapi.ts`
-    - `register.serverless.ts` — side‑effect imports of per‑function `serverless.ts` (if any)
-    - `openapi.json` — OpenAPI document
-
-## Getting started
-
-1. Install dependencies
-   - Run: `npm install`
-2. Type checking
-   - Run: `npm run typecheck`
-3. Linting
-   - Run: `npm run lint` (or `npm run lint:fix` to auto‑fix)
-4. Tests (baseline suite OK)
-   - Run: `npm run test`
-5. Docs (TypeDoc baseline loads)
-   - Run: `npm run docs`
-6. Generate OpenAPI (if your app config and endpoints are present)
-   - Run: `npm run openapi`
-
-## SMOZ CLI — register
-
-The CLI scans `app/functions/**` for `lambda.ts`, `openapi.ts`, and optional `serverless.ts` and generates side‑effect registration files under `app/generated/`.
-
-- Build CLI (if packaged locally): `npm run cli:build`
-- Register: `npx smoz register`
-  - Idempotent: rewrites files only when content changes
-  - Formats output with Prettier when available
-
-Tip: Commit `app/generated/register.*.ts` so typecheck is stable without running the CLI. Teams often keep `app/generated/openapi.json` untracked in VCS (optional).
-
-## Notes
-
-- HTTP tokens (`rest`, `http`) are configured in your `app.config.ts`. You may widen these tokens per app.
-- Keep function modules small and focused:
-  - `lambda.ts`: define and register function (`app.defineFunction`)
-  - `handler.ts`: business handler exported via `fn.handler`
-  - `openapi.ts`: attach OpenAPI operation via `fn.openapi`
-  - `serverless.ts`: (non‑HTTP only) attach extra events via `fn.serverless`
-
-## Next steps
-
-- Add your first endpoint (e.g., `app/functions/rest/hello/get`)
-- Run the CLI register step
-- Generate OpenAPI
-- Package or deploy with your preferred toolchain
-
-## Params used by serverless.ts
-
-This template references a few params from your app config:
-
-- Global params (app/config/app.config.ts → global.params)
-  - `ESB_MINIFY` (boolean) — controls `build.esbuild.minify`
-  - `ESB_SOURCEMAP` (boolean) — controls `build.esbuild.sourcemap`
-  - `PROFILE`, `REGION`, `SERVICE_NAME`
-- Stage params (app/config/app.config.ts → stage.params.<stage>)
-  - `DOMAIN_NAME` — used by the custom domain plugin config
-  - `DOMAIN_CERTIFICATE_ARN` — ACM certificate ARN for the domain
-  - `STAGE`
-
-Where these are used:
-
-- The esbuild block in `serverless.ts` reads `ESB_MINIFY` and `ESB_SOURCEMAP`
-  to toggle minification and sourcemaps.
-- The `customDomain` section in `serverless.ts` reads `DOMAIN_NAME` and
-  `DOMAIN_CERTIFICATE_ARN`. Update these with your values or remove the
-  custom domain plugin if not needed.
-
-## Path hygiene (cross‑platform)
-
-Windows uses backslashes in paths, which can leak into string comparisons and generated artifacts. Normalize separators consistently using the helper exported by the toolkit:
-```ts
-import { toPosixPath } from '@karmaniverous/smoz';
-
-// Derive the app root as the parent directory of app/config/
-import { fileURLToPath } from 'node:url';
-export const APP_ROOT_ABS = toPosixPath(
-  fileURLToPath(new URL('..', import.meta.url)),
-);
-```
+# SMOZ App Template
+
+This template provides a minimal, convention‑friendly baseline for new SMOZ apps:
+
+- TypeScript configuration (strict, moduleResolution bundler)
+- ESLint (flat config) + typescript‑eslint + Prettier
+- Vitest baseline config
+- TypeDoc baseline config
+
+## Conventions
+
+- Author code lives under:
+  - `app/config/app.config.ts` — app schemas/config (params, env, http tokens)
+  - `app/functions/<eventType>/...` (e.g., `app/functions/rest/hello/get`)
+- Generated artifacts live under:
+  - `app/generated/`
+    - `register.functions.ts` — side‑effect imports of all `lambda.ts`
+    - `register.openapi.ts` — side‑effect imports of all `openapi.ts`
+    - `register.serverless.ts` — side‑effect imports of per‑function `serverless.ts` (if any)
+    - `openapi.json` — OpenAPI document
+
+## Getting started
+
+1. Install dependencies
+   - Run: `npm install`
+2. Type checking
+   - Run: `npm run typecheck`
+3. Linting
+   - Run: `npm run lint` (or `npm run lint:fix` to auto‑fix)
+4. Tests (baseline suite OK)
+   - Run: `npm run test`
+5. Docs (TypeDoc baseline loads)
+   - Run: `npm run docs`
+6. Generate OpenAPI (if your app config and endpoints are present)
+   - Run: `npm run openapi`
+
+## SMOZ CLI — register
+
+The CLI scans `app/functions/**` for `lambda.ts`, `openapi.ts`, and optional `serverless.ts` and generates side‑effect registration files under `app/generated/`.
+
+- Build CLI (if packaged locally): `npm run cli:build`
+- Register: `npx smoz register`
+  - Idempotent: rewrites files only when content changes
+  - Formats output with Prettier when available
+
+Tip: Commit `app/generated/register.*.ts` so typecheck is stable without running the CLI. Teams often keep `app/generated/openapi.json` untracked in VCS (optional).
+
+## Notes
+
+- HTTP tokens (`rest`, `http`) are configured in your `app.config.ts`. You may widen these tokens per app.
+- Keep function modules small and focused:
+  - `lambda.ts`: define and register function (`app.defineFunction`)
+  - `handler.ts`: business handler exported via `fn.handler`
+  - `openapi.ts`: attach OpenAPI operation via `fn.openapi`
+  - `serverless.ts`: (non‑HTTP only) attach extra events via `fn.serverless`
+
+## Next steps
+
+- Add your first endpoint (e.g., `app/functions/rest/hello/get`)
+- Run the CLI register step
+- Generate OpenAPI
+- Package or deploy with your preferred toolchain
+
+## Params used by serverless.ts
+
+This template references a few params from your app config:
+
+- Global params (app/config/app.config.ts → global.params)
+  - `ESB_MINIFY` (boolean) — controls `build.esbuild.minify`
+  - `ESB_SOURCEMAP` (boolean) — controls `build.esbuild.sourcemap`
+  - `PROFILE`, `REGION`, `SERVICE_NAME`
+- Stage params (app/config/app.config.ts → stage.params.<stage>)
+  - `DOMAIN_NAME` — used by the custom domain plugin config
+  - `DOMAIN_CERTIFICATE_ARN` — ACM certificate ARN for the domain
+  - `STAGE`
+  - `STAGE_NAME` — seeded as `${SERVICE_NAME}-${STAGE}` (not consumed yet)
+
+Where these are used:
+
+- The esbuild block in `serverless.ts` reads `ESB_MINIFY` and `ESB_SOURCEMAP`
+  to toggle minification and sourcemaps.
+- The `customDomain` section in `serverless.ts` reads `DOMAIN_NAME` and
+  `DOMAIN_CERTIFICATE_ARN`. Update these with your values or remove the
+  custom domain plugin if not needed.
+
+## Path hygiene (cross‑platform)
+
+Windows uses backslashes in paths, which can leak into string comparisons and generated artifacts. Normalize separators consistently using the helper exported by the toolkit:
+
+```ts
+import { toPosixPath } from '@karmaniverous/smoz';
+
+// Derive the app root as the parent directory of app/config/
+import { fileURLToPath } from 'node:url';
+export const APP_ROOT_ABS = toPosixPath(
+  fileURLToPath(new URL('..', import.meta.url)),
+);
+```

package/templates/default/app/config/app.config.ts

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { App, baseEventTypeMapSchema, toPosixPath } from '@karmaniverous/smoz';
+import { App, toPosixPath } from '@karmaniverous/smoz';
 import { z } from 'zod';
 
 // Derive the app root as the parent directory of app/config/
@@ -22,8 +22,8 @@ export const app = App.create({
     DOMAIN_CERTIFICATE_ARN: z.string(),
     DOMAIN_NAME: z.string(),
     STAGE: z.string(),
+    STAGE_NAME: z.string(),
   }),
-  eventTypeMapSchema: baseEventTypeMapSchema,
   serverless: {
     httpContextEventMap: {
       my: {}, // place a Cognito authorizer here if needed
@@ -50,6 +50,7 @@ export const app = App.create({
           'arn:aws:acm:us-east-1:000000000000:certificate/dev-placeholder',
         DOMAIN_NAME: 'api.dev.example.test',
         STAGE: 'dev',
+        STAGE_NAME: 'my-smoz-app-dev',
       },
     },
     envKeys: ['STAGE'],

package/templates/default/app/generated/openapi.json

@@ -1,8 +1,8 @@
-{
-  "openapi": "3.1.0",
-  "info": { "title": "smoz-app", "version": "0.0.0" },
-  "servers": [
-    { "description": "Dev", "url": "http://localhost" }
-  ],
-  "paths": {}
-}
+{
+  "openapi": "3.1.0",
+  "info": { "title": "smoz-app", "version": "0.0.0" },
+  "servers": [
+    { "description": "Dev", "url": "http://localhost" }
+  ],
+  "paths": {}
+}

package/templates/default/eslint.config.ts

@@ -12,7 +12,6 @@ export default [
   {
     ignores: [
       '.serverless/**',
-      '.stan/**',
       '**/.tsbuild/**',
       '**/generated/**',
       'coverage/**',