@karmaniverous/smoz 0.1.2

package/templates/project/README.md

@@ -0,0 +1,85 @@
+# 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
+
+## 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/project/eslint.config.ts

@@ -0,0 +1,47 @@
+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';
+
+const tsconfigRootDir = dirname(fileURLToPath(import.meta.url));
+
+export default [
+  {
+    ignores: [
+      '.serverless/**',
+      '.tsbuild/**',
+      'coverage/**',
+      'dist/**',
+      'docs/**',
+      'node_modules/**',
+    ],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.strictTypeChecked,
+  prettierConfig,
+  {
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        project: ['./tsconfig.json'],
+        tsconfigRootDir,
+      },
+    },
+    plugins: {
+      prettier: prettierPlugin,
+      'simple-import-sort': simpleImportSortPlugin,
+    },
+    rules: {
+      'prettier/prettier': 'error',
+      '@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/project/tsconfig.base.json

@@ -0,0 +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
+  }
+}

package/templates/project/tsconfig.json

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

package/templates/project/typedoc.json

@@ -0,0 +1,14 @@
+{
+  "entryPoints": ["./src"],
+  "entryPointStrategy": "expand",
+  "exclude": ["**/*.test.ts", "**/*.d.ts", "**/generated/**"],
+  "excludeInternal": false,
+  "out": "./docs/",
+  "searchInComments": true,
+  "searchInDocuments": true,
+  "highlightLanguages": ["bash", "console", "json", "typescript"],
+  "navigation": {
+    "excludeReferences": true
+  },
+  "projectDocuments": []
+}

package/templates/project/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    exclude: ['**/node_modules/**', '**/dist/**', '**/.tsbuild/**'],
+  },
+});