@karmaniverous/smoz 0.1.2

package/dist/mjs/serverless-plugin.js

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+/* REQUIREMENTS ADDRESSED
+ * - Provide a lightweight Serverless Framework plugin that ensures registers are fresh
+ *   by running `smoz register` before package/deploy.
+ * - Keep it simple: spawn Node to run the packaged CJS CLI, inherit stdio, and fail fast.
+ *
+ * Notes:
+ * - This file is bundled to dist/cjs/serverless-plugin.js and exported via the "./serverless-plugin" subpath.
+ * - Serverless v4 loads CJS plugins via `require`; exporting a default class allows
+ *   rollup to wrap it for CJS while preserving the ESM entry for completeness.
+ */
+const runRegister = () => {
+    // Resolve the packaged CLI entry relative to the compiled CJS plugin:
+    // dist/cjs/serverless-plugin.js -> ../cli/index.cjs
+    const cliPath = path.resolve(__dirname, '../cli/index.cjs');
+    const res = spawnSync(process.execPath, [cliPath, 'register'], {
+        stdio: 'inherit',
+        shell: false,
+    });
+    const code = typeof res.status === 'number' ? String(res.status) : 'unknown';
+    if (res.status !== 0)
+        throw new Error(`smoz register failed (exit code ${code})`);
+};
+// Minimal Serverless v4 plugin: register hooks that run before package/deploy.
+class SmozRegisterPlugin {
+    hooks;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(_serverless, _options) {
+        this.hooks = {
+            // Package lifecycle
+            'before:package:initialize': runRegister,
+            // Deploy lifecycles where functions/artifacts can be (re)built
+            'before:deploy:function:initialize': runRegister,
+            'before:deploy:deploy': runRegister,
+        };
+    }
+}
+
+export { SmozRegisterPlugin as default };

package/dist/serverless-plugin.d.ts

@@ -0,0 +1,6 @@
+declare class SmozRegisterPlugin {
+    hooks: Record<string, () => void>;
+    constructor(_serverless?: any, _options?: any);
+}
+
+export { SmozRegisterPlugin as default };

package/package.json

@@ -0,0 +1,190 @@
+{
+  "author": "Jason Williscroft",
+  "auto-changelog": {
+    "output": "CHANGELOG.md",
+    "unreleased": true,
+    "commitLimit": false,
+    "hideCredit": true
+  },
+  "bin": {
+    "smoz": "dist/cli/index.cjs"
+  },
+  "bugs": {
+    "url": "https://github.com/karmaniverous/smoz/issues"
+  },
+  "dependencies": {
+    "@karmaniverous/cached-axios": "^0.2.0",
+    "@middy/core": "^6.4.5",
+    "@middy/http-content-negotiation": "^6.4.5",
+    "@middy/http-cors": "^6.4.5",
+    "@middy/http-error-handler": "^6.4.5",
+    "@middy/http-event-normalizer": "^6.4.5",
+    "@middy/http-header-normalizer": "^6.4.5",
+    "@middy/http-json-body-parser": "^6.4.5",
+    "@middy/http-response-serializer": "^6.4.5",
+    "aws-lambda": "^1.0.7",
+    "chokidar": "^4.0.3",
+    "commander": "^14.0.0",
+    "http-errors": "^2.0.0",
+    "package-directory": "^8.1.0",
+    "radash": "^12.1.1",
+    "zod": "^4.1.6"
+  },
+  "description": "John Galt Services back end.",
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.49.0",
+    "@eslint/js": "^9.35.0",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@serverless/typescript": "^4.18.2",
+    "@types/aws-lambda": "^8.10.152",
+    "@types/fs-extra": "^11.0.4",
+    "@types/http-errors": "^2.0.5",
+    "@types/serverless": "^3.12.27",
+    "@vitest/coverage-v8": "^3.2.4",
+    "auto-changelog": "^2.5.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "fs-extra": "^11.3.1",
+    "knip": "^5.63.1",
+    "lefthook": "^1.12.4",
+    "orval": "^7.11.2",
+    "pkg-dir": "^9.0.0",
+    "prettier": "^3.6.2",
+    "release-it": "^19.0.4",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.50.1",
+    "rollup-plugin-dts": "^6.2.3",
+    "serverless": "^4.18.2",
+    "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",
+    "tsx": "^4.20.5",
+    "typedoc": "^0.28.12",
+    "typedoc-plugin-mdn-links": "^5.0.9",
+    "typedoc-plugin-replace-text": "^4.2.0",
+    "typedoc-plugin-zod": "^1.4.2",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.43.0",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4",
+    "zod-openapi": "^5.4.1"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/mjs/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./serverless-plugin": {
+      "import": "./dist/mjs/serverless-plugin.js",
+      "require": "./dist/cjs/serverless-plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "homepage": "https://github.com/karmaniverous/smoz#readme",
+  "keywords": [
+    "smoz",
+    "serverless",
+    "serverless-framework",
+    "aws-lambda",
+    "middy",
+    "openapi",
+    "openapi-3-1",
+    "zod",
+    "typescript",
+    "api-gateway",
+    "http-middleware",
+    "validation",
+    "schema-first",
+    "lambda-handlers",
+    "openapi-generator",
+    "api-docs",
+    "content-negotiation",
+    "cors",
+    "error-handling",
+    "toolkit"
+  ],
+  "license": "BSD-3-Clause",
+  "main": "dist/cjs/index.js",
+  "module": "dist/mjs/index.js",
+  "name": "@karmaniverous/smoz",
+  "publishConfig": {
+    "access": "public"
+  },
+  "release-it": {
+    "git": {
+      "changelog": "npx auto-changelog --stdout --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "commitMessage": "chore: release v${version}",
+      "requireBranch": "main"
+    },
+    "github": {
+      "release": true
+    },
+    "hooks": {
+      "after:init": [
+        "npm run lint",
+        "npm run test",
+        "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}"
+      ]
+    },
+    "npm": {
+      "publish": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/smoz.git"
+  },
+  "scripts": {
+    "build": "rimraf dist && rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "build:cli": "rollup --config cli.rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "changelog": "auto-changelog",
+    "deploy": "tsx src/cli/index.ts register && serverless deploy",
+    "diagrams": "cd diagrams/src && plantuml -tpng -o ../out -r .",
+    "docs": "typedoc",
+    "domain:create": "serverless create_domain",
+    "domain:delete": "serverless delete_domain",
+    "generate": "cd services/activecampaign && orval",
+    "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",
+    "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:build": "rimraf stan.dist && rollup --config stan.rollup.config.ts --configPlugin @rollup/plugin-typescript && rimraf stan.dist",
+    "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/.check/eslint.templates.config.ts \"templates/**/*.{ts,tsx,js,jsx}\" && eslint --fix --no-ignore templates/.check/eslint.templates.config.ts"
+  },
+  "type": "module",
+  "version": "0.1.2"
+}

package/templates/.check/eslint.minimal.config.ts

@@ -0,0 +1,41 @@
+import eslint from '@eslint/js';
+import prettierConfig from 'eslint-config-prettier';
+import prettierPlugin from 'eslint-plugin-prettier';
+import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort';
+import tseslint from 'typescript-eslint';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const tsconfigRootDir = dirname(fileURLToPath(import.meta.url));
+
+export default tseslint.config(
+  {    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.tsbuild/**',
+    ],
+  },
+  eslint.configs.recommended,
+  tseslint.configs.strictTypeChecked,
+  prettierConfig,
+  {
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        project: ['./tsconfig.minimal.json'],
+        tsconfigRootDir,
+      },
+    },
+    plugins: {      prettier: prettierPlugin,
+      'simple-import-sort': simpleImportSortPlugin,
+    },
+    rules: {
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-unused-expressions': 'off',
+      '@typescript-eslint/no-unused-vars': 'error',
+      'no-unused-vars': 'off',
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+    },
+  },
+);

package/templates/.check/eslint.templates.config.ts

@@ -0,0 +1,60 @@
+import eslint from '@eslint/js';
+import prettierConfig from 'eslint-config-prettier';
+import prettierPlugin from 'eslint-plugin-prettier';
+import simpleImportSortPlugin from 'eslint-plugin-simple-import-sort';
+import { dirname } from 'path';
+import tseslint from 'typescript-eslint';
+import { fileURLToPath } from 'url';
+
+// Unified ESLint config for all templates under templates/*
+// - Uses projectService so type info is picked up from each template's tsconfig.json
+// - ESLint drives Prettier via 'prettier/prettier': 'error'
+const tsconfigRootDir = dirname(fileURLToPath(import.meta.url));
+
+export default [
+  {
+    ignores: [
+      '**/node_modules/**',
+      '**/dist/**',
+      '**/.tsbuild/**',
+      '**/generated/**',
+      '**/.check/**',
+    ],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  prettierConfig,
+  {
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        // Let the project service discover the nearest tsconfig.json per file
+        // (typed where possible; falls back to default project when unmatched).
+        project: true,
+        projectService: true,
+        allowDefaultProject: true,
+        tsconfigRootDir,
+      },
+    },
+    plugins: {
+      prettier: prettierPlugin,
+      'simple-import-sort': simpleImportSortPlugin,
+    },
+    rules: {
+      // Formatting via Prettier
+      'prettier/prettier': 'error',
+      // Code-quality and sorting
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-empty-object-type': 'off',
+      '@typescript-eslint/no-unused-expressions': 'off',
+      '@typescript-eslint/no-unused-vars': 'error',
+      'no-unused-vars': 'off',
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      // Keep strictness reasonable for templates
+      '@typescript-eslint/no-unsafe-assignment': 'error',
+      '@typescript-eslint/no-unsafe-member-access': 'error',
+      '@typescript-eslint/no-unsafe-return': 'error',
+    },
+  },
+];

package/templates/.check/tsconfig.eslintconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../project/tsconfig.base.json",
+  "include": [
+    "./eslint.templates.config.ts"
+  ]
+}

package/templates/.check/tsconfig.minimal.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../project/tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "../../templates/minimal",
+    "baseUrl": "../../templates/minimal",
+    "paths": {
+      "@/*": ["*"],
+      "@karmaniverous/smoz": ["../../.stan/dist/index.d.ts"]
+    },
+    "types": ["node"]
+  },  "include": [
+    "../../templates/minimal/**/*.ts"
+  ]
+}

package/templates/.manifests/package.minimal.json

@@ -0,0 +1,19 @@
+{
+  "dependencies": {
+    "zod": "^4.1.5",
+    "@middy/core": "^6.4.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.41.0",
+    "eslint": "^9.34.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-simple-import-sort": "^12.1.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix ."
+  }
+}

package/templates/.manifests/package.project.json

@@ -0,0 +1,23 @@
+{
+  "dependencies": {
+    "zod": "^4.1.5",
+    "@middy/core": "^6.4.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.41.0",
+    "eslint": "^9.34.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "vitest": "^3.2.4",
+    "typedoc": "^0.28.11"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "test": "vitest run",
+    "docs": "typedoc"
+  }
+}

package/templates/minimal/app/config/app.config.ts

@@ -0,0 +1,50 @@
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { App, baseEventTypeMapSchema, toPosixPath } from '@karmaniverous/smoz';
+import { z } from 'zod';
+
+// Derive the app root as the parent directory of app/config/
+export const APP_ROOT_ABS = toPosixPath(
+  fileURLToPath(new URL('..', import.meta.url)),
+);
+
+export const app = App.create({
+  appRootAbs: APP_ROOT_ABS,
+  globalParamsSchema: z.object({
+    PROFILE: z.string(),
+    REGION: z.string(),
+    SERVICE_NAME: z.string(),
+  }),
+  stageParamsSchema: z.object({
+    STAGE: z.string(),
+  }),
+  eventTypeMapSchema: baseEventTypeMapSchema,
+  serverless: {
+    httpContextEventMap: {
+      my: {}, // place a Cognito authorizer here if needed
+      private: { private: true },
+      public: {},
+    },
+    defaultHandlerFileName: 'handler',
+    defaultHandlerFileExport: 'handler',
+  },
+  global: {
+    params: {
+      PROFILE: 'dev',
+      REGION: 'us-east-1',
+      SERVICE_NAME: 'my-smoz-app',
+    },
+    envKeys: ['PROFILE', 'REGION', 'SERVICE_NAME'] as const,
+  },
+  stage: {
+    params: {
+      dev: { STAGE: 'dev' },
+    },
+    envKeys: ['STAGE'] as const,
+  },
+});
+
+export const ENDPOINTS_ROOT_REST = toPosixPath(
+  join(APP_ROOT_ABS, 'functions', 'rest'),
+);

package/templates/minimal/app/config/openapi.ts

@@ -0,0 +1,45 @@
+import * as path from 'node:path';
+
+import * as fs from 'fs-extra';
+import { packageDirectorySync } from 'pkg-dir';
+import { createDocument } from 'zod-openapi';
+
+import { app } from '@/app/config/app.config';
+/**
+ * Template note:
+ * - Templates do NOT commit generated register files under app/generated; they
+ *   are declared via ambient types (templates/minimal/types/registers.d.ts) so
+ *   TypeScript can typecheck without artifacts.
+ * - To ensure side effects still run (endpoint registration) and to satisfy
+ *   noUncheckedSideEffectImports, import the register module as a namespace and
+ *   reference it via `void`.
+ * - In real apps, `smoz init` seeds placeholders and `smoz register` rewrites
+ *   app/generated/register.*.ts at author time.
+ */
+import * as __register_openapi from '@/app/generated/register.openapi';
+void __register_openapi;
+console.log('Generating OpenAPI document...');
+
+const paths = app.buildAllOpenApiPaths();
+export const doc = createDocument({
+  openapi: '3.1.0',
+  servers: [{ description: 'Dev', url: 'http://localhost' }],
+  info: {
+    title: process.env.npm_package_name ?? 'smoz-app',
+    version: process.env.npm_package_version ?? '0.0.0',
+  },
+  paths,
+});
+
+const pkgDir = packageDirectorySync();
+if (!pkgDir) {
+  throw new Error('Could not resolve package root directory');
+}
+const outDir = path.join(pkgDir, 'app', 'generated');
+fs.ensureDirSync(outDir);
+fs.writeFileSync(
+  path.join(outDir, 'openapi.json'),
+  JSON.stringify(doc, null, 2),
+);
+
+console.log('Done!');

package/templates/minimal/app/functions/rest/hello/get/handler.ts

@@ -0,0 +1,18 @@
+import type { z } from 'zod';
+
+import type { responseSchema } from './lambda';
+import { fn } from './lambda';
+
+type Response = z.infer<typeof responseSchema>;
+
+type FnHandlerApi<T> = {
+  handler: (impl: () => Promise<T> | T) => (...args: unknown[]) => Promise<T>;
+};
+
+const reg = fn as unknown as FnHandlerApi<Response>;
+
+export const handler = reg.handler(async () => {
+  const res: Response = { ok: true };
+  await Promise.resolve(); // satisfy require-await without adding complexity
+  return res;
+});

package/templates/minimal/app/functions/rest/hello/get/lambda.ts

@@ -0,0 +1,28 @@
+import { join } from 'node:path';
+
+import { toPosixPath } from '@karmaniverous/smoz';
+import { z } from 'zod';
+
+import { app, APP_ROOT_ABS } from '@/app/config/app.config';
+
+export const eventSchema = z.object({}).optional();
+export const responseSchema = z.object({ ok: z.boolean() });
+type FnApi = {
+  handler: <T>(
+    impl: () => Promise<T> | T,
+  ) => (...args: unknown[]) => Promise<T>;
+  openapi: (op: unknown) => void;
+};
+
+export const fn = app.defineFunction({
+  functionName: 'hello_get',
+  eventType: 'rest',
+  httpContexts: ['public'],
+  method: 'get',
+  basePath: 'hello',
+  contentType: 'application/json',
+  eventSchema,
+  responseSchema,
+  callerModuleUrl: import.meta.url,
+  endpointsRootAbs: toPosixPath(join(APP_ROOT_ABS, 'functions', 'rest')),
+}) as unknown as FnApi;

package/templates/minimal/app/functions/rest/hello/get/openapi.ts

@@ -0,0 +1,23 @@
+import { fn, responseSchema } from './lambda';
+
+type FnOpenApiApi = {
+  openapi: (op: unknown) => void;
+};
+
+const reg = fn as unknown as FnOpenApiApi;
+
+reg.openapi({
+  summary: 'Hello',
+  description: 'Return a simple OK payload.',
+  responses: {
+    200: {
+      description: 'Ok',
+      content: {
+        'application/json': { schema: responseSchema },
+      },
+    },
+  },
+  tags: ['public'],
+});
+
+export {};

package/templates/minimal/serverless.ts

@@ -0,0 +1,34 @@
+import type { AWS } from '@serverless/typescript';
+
+import { app } from '@/app/config/app.config';
+/**
+ * Template note:
+ * - Templates do NOT commit generated register files under app/generated; they
+ *   are declared via ambient types (templates/minimal/types/registers.d.ts) so
+ *   TypeScript can typecheck without artifacts.
+ * - To ensure side effects still run (endpoint/serverless registration) and to
+ *   satisfy noUncheckedSideEffectImports, import register modules as namespaces
+ *   and reference them via `void`.
+ * - In real apps, `smoz init` seeds placeholders and `smoz register` rewrites
+ *   app/generated/register.*.ts at author time.
+ */
+import * as __register_functions from '@/app/generated/register.functions';
+import * as __register_serverless from '@/app/generated/register.serverless';
+void __register_functions;
+void __register_serverless;
+
+const config: AWS = {
+  service: '${param:SERVICE_NAME}',
+  frameworkVersion: '4',
+  stages: app.stages as NonNullable<AWS['stages']>,
+  provider: {
+    name: 'aws',
+    region: '${param:REGION}' as NonNullable<AWS['provider']['region']>,
+    runtime: 'nodejs22.x',
+    environment: app.environment as NonNullable<AWS['provider']['environment']>,
+    stage: '${opt:stage, "dev"}',
+  },
+  functions: app.buildAllServerlessFunctions() as NonNullable<AWS['functions']>,
+};
+
+export default config;

package/templates/minimal/tsconfig.json

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

package/templates/minimal/types/registers.d.ts

@@ -0,0 +1,11 @@
+// Ambient declarations to satisfy template typechecking without requiring
+// generated register files to exist on disk.
+declare module '@/app/generated/register.functions' {
+  export {};
+}
+declare module '@/app/generated/register.openapi' {
+  export {};
+}
+declare module '@/app/generated/register.serverless' {
+  export {};
+}

package/templates/project/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "singleQuote": true
+}