@karmaniverous/smoz 0.2.10 → 0.2.11

package/dist/index.d.ts

@@ -570,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/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.13",
-    "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.10",
+  "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

@@ -22,6 +22,7 @@ export const app = App.create({
     DOMAIN_CERTIFICATE_ARN: z.string(),
     DOMAIN_NAME: z.string(),
     STAGE: z.string(),
+    STAGE_NAME: z.string(),
   }),
   serverless: {
     httpContextEventMap: {
@@ -49,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/**',

package/templates/default/gitignore

@@ -1,42 +1,42 @@
-# Dependencies
-node_modules/
-
-# Build outputs and caches
-dist/
-.tsbuild/
-**/.tsbuild/
-*.tsbuildinfo
-**/.rollup.cache/
-
-# Serverless packaging
-.serverless/
-
-# Test coverage
-coverage/
-
-# Generated artifacts
-# Teams often keep registers tracked for typecheck stability,
-# but the OpenAPI JSON is usually untracked.
-app/generated/openapi.json
-
-# Environment files (local only; do not commit secrets)
-.env
-.env.local
-.env.*.local
-
-# Logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-
-# OS / editor files
-.DS_Store
-Thumbs.db
-.idea/
-.vscode/
-
-# Misc
-*.swp
-*.swo
+# Dependencies
+node_modules/
+
+# Build outputs and caches
+dist/
+.tsbuild/
+**/.tsbuild/
+*.tsbuildinfo
+**/.rollup.cache/
+
+# Serverless packaging
+.serverless/
+
+# Test coverage
+coverage/
+
+# Generated artifacts
+# Teams often keep registers tracked for typecheck stability,
+# but the OpenAPI JSON is usually untracked.
+app/generated/openapi.json
+
+# Environment files (local only; do not commit secrets)
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS / editor files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Misc
+*.swp
+*.swo

package/templates/default/package.json

@@ -33,16 +33,15 @@
   },
   "name": "smoz-template-default",
   "scripts": {
-    "register": "smoz register",
-    "openapi": "smoz register && tsx app/config/openapi && prettier -w app/generated/openapi.json",
-    "package": "smoz register && serverless package",
     "dev": "smoz dev",
-    "dev:offline": "smoz dev --local offline",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint .",
+    "docs": "typedoc",
     "lint:fix": "eslint --fix .",
+    "lint": "eslint .",
+    "openapi": "smoz openapi",
+    "package": "serverless package",
+    "register": "smoz register",
     "test": "vitest run",
-    "docs": "typedoc"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "type": "module",
   "version": "0.0.0",

package/templates/default/tsconfig.base.json

@@ -1,21 +1,21 @@
-{
-  "compilerOptions": {
-    "allowSyntheticDefaultImports": true,
-    "emitDeclarationOnly": false,
-    "exactOptionalPropertyTypes": true,
-    "module": "esnext",
-    "moduleDetection": "force",
-    "moduleResolution": "bundler",
-    "noEmit": true,
-    "noUncheckedIndexedAccess": true,
-    "noUncheckedSideEffectImports": true,
-    "resolveJsonModule": true,
-    "rootDir": ".",
-    "skipLibCheck": true,
-    "strict": true,
-    "stripInternal": true,
-    "target": "esnext",
-    "types": ["node"],
-    "verbatimModuleSyntax": true
-  }
-}
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "emitDeclarationOnly": false,
+    "exactOptionalPropertyTypes": true,
+    "module": "esnext",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "noUncheckedSideEffectImports": true,
+    "resolveJsonModule": true,
+    "rootDir": ".",
+    "skipLibCheck": true,
+    "strict": true,
+    "stripInternal": true,
+    "target": "esnext",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  }
+}

package/templates/default/tsconfig.downstream.json

@@ -1,13 +1,13 @@
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "outDir": ".tsbuild",
-    "paths": {
-      "@/*": ["*"]
-    },
-    "tsBuildInfoFile": ".tsbuild/tsconfig.tsbuildinfo"
-  },
-  "exclude": [".serverless/**", "node_modules/**", "app/generated/**"],
-  "extends": "./tsconfig.base.json",
-  "include": ["**/*", "**/*.json"]
-}
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": ".tsbuild",
+    "paths": {
+      "@/*": ["*"]
+    },
+    "tsBuildInfoFile": ".tsbuild/tsconfig.tsbuildinfo"
+  },
+  "exclude": [".serverless/**", "node_modules/**", "app/generated/**"],
+  "extends": "./tsconfig.base.json",
+  "include": ["**/*", "**/*.json"]
+}

package/templates/default/tsconfig.eslint.json

@@ -1,3 +1,3 @@
-{
-  "extends": "./tsconfig.json"
+{
+  "extends": "./tsconfig.json"
 }

package/templates/default/tsconfig.json

@@ -1,26 +1,26 @@
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "outDir": ".tsbuild",
-    "paths": {
-      "@/*": ["*"],
-      "@karmaniverous/smoz": [
-        "../../dist/index",
-        "../../dist/index.d.ts"
-      ]
-    },
-    "typeRoots": [
-      "./types",
-      "../../node_modules/@types"
-    ],
-    "tsBuildInfoFile": ".tsbuild/tsconfig.tsbuildinfo"
-  },
-  "exclude": [
-    ".serverless/**",
-    "node_modules/**",
-    "app/generated/**",
-    "dist/**"
-  ],
-  "extends": "./tsconfig.base.json",
-  "include": ["**/*", "**/*.json"]
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": ".tsbuild",
+    "paths": {
+      "@/*": ["*"],
+      "@karmaniverous/smoz": [
+        "../../dist/index",
+        "../../dist/index.d.ts"
+      ]
+    },
+    "typeRoots": [
+      "./types",
+      "../../node_modules/@types"
+    ],
+    "tsBuildInfoFile": ".tsbuild/tsconfig.tsbuildinfo"
+  },
+  "exclude": [
+    ".serverless/**",
+    "node_modules/**",
+    "app/generated/**",
+    "dist/**"
+  ],
+  "extends": "./tsconfig.base.json",
+  "include": ["**/*", "**/*.json"]
 }