@opengroundplan/core 0.1.1

package/templates/architectures/serverless/files/scripts/check-handler-boundaries.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// Fails when one handler imports another, when a shared layer imports a handler, or when
+// application code reaches into the IaC entry point.
+// Zero dependencies on purpose: the bases disagree on linter (ESLint vs Biome), so this
+// check has to work without editing whichever config the base already owns.
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** The only place these paths are written. Environment overrides them per repo. */
+const defaults = {
+  functionsDir: 'src/functions',
+  layersDir: 'src/layers',
+  infraDir: 'infra',
+  extensions: '.ts,.tsx,.mts,.cts,.js,.jsx,.mjs,.cjs',
+};
+
+const functionsDir = toPosix(process.env.FUNCTIONS_DIR || defaults.functionsDir);
+const layersDir = toPosix(process.env.LAYERS_DIR || defaults.layersDir);
+const infraDir = toPosix(process.env.INFRA_DIR || defaults.infraDir);
+const extensions = new Set((process.env.HANDLER_EXTENSIONS || defaults.extensions).split(','));
+
+/** Last segment of each root, as it appears inside alias imports like `@/functions/x`. */
+const functionsSegment = lastSegment(functionsDir);
+const infraSegment = lastSegment(infraDir);
+
+const SPECIFIER_PATTERNS = [
+  /\bfrom\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\bimport\s+['"]([^'"]+)['"]/g,
+];
+
+function toPosix(value) {
+  return value.split(path.sep).join('/');
+}
+
+function lastSegment(dir) {
+  return dir.split('/').filter(Boolean).at(-1);
+}
+
+async function listFiles(dir) {
+  const found = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+
+  for (const entry of entries) {
+    const child = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) found.push(...(await listFiles(child)));
+    else if (extensions.has(path.extname(entry.name))) found.push(child);
+  }
+  return found;
+}
+
+function specifiersIn(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return found;
+}
+
+/** The function a repo-root-relative path belongs to, or null when it is outside the root. */
+function functionOfPath(posixPath) {
+  const prefix = `${functionsDir}/`;
+  if (!posixPath.startsWith(prefix)) return null;
+  return posixPath.slice(prefix.length).split('/')[0] || null;
+}
+
+/** Alias and package specifiers carry no repo path, so match on the `functions/<name>` segment. */
+function functionOfSpecifier(specifier) {
+  const parts = toPosix(specifier).split('/');
+  const at = parts.lastIndexOf(functionsSegment);
+  return at >= 0 && at < parts.length - 1 ? parts[at + 1] : null;
+}
+
+function resolveRelative(specifier, fromFile) {
+  return path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+}
+
+function targetFunction(specifier, fromFile) {
+  if (!specifier.startsWith('.')) return functionOfSpecifier(specifier);
+  return functionOfPath(resolveRelative(specifier, fromFile));
+}
+
+function reachesInfra(specifier, fromFile) {
+  if (specifier.startsWith('.')) {
+    return resolveRelative(specifier, fromFile).startsWith(`${infraDir}/`);
+  }
+  return toPosix(specifier).split('/').includes(infraSegment);
+}
+
+/** Same message for a handler and for a layer — the reason is identical. */
+function infraViolation(file, specifier) {
+  return `${file}: imports ${infraDir}/ via "${specifier}" — deployment shape is not runtime input`;
+}
+
+async function findViolations() {
+  const violations = [];
+
+  for (const file of await listFiles(functionsDir)) {
+    const owner = functionOfPath(file);
+    if (owner === null) continue;
+
+    for (const specifier of specifiersIn(await readFile(file, 'utf8'))) {
+      const target = targetFunction(specifier, file);
+      if (target !== null && target !== owner) {
+        violations.push(
+          `${file}: handler "${owner}" imports handler "${target}" via "${specifier}" — ` +
+            `move the shared part to ${layersDir}/, or invoke it as an event`,
+        );
+      }
+      if (reachesInfra(specifier, file)) violations.push(infraViolation(file, specifier));
+    }
+  }
+
+  for (const file of await listFiles(layersDir)) {
+    for (const specifier of specifiersIn(await readFile(file, 'utf8'))) {
+      const target = targetFunction(specifier, file);
+      if (target !== null) {
+        violations.push(
+          `${file}: shared layer imports handler "${target}" via "${specifier}" — ` +
+            `that inverts the dependency`,
+        );
+      }
+      if (reachesInfra(specifier, file)) violations.push(infraViolation(file, specifier));
+    }
+  }
+
+  return violations;
+}
+
+const violations = await findViolations();
+if (violations.length > 0) {
+  console.error(`Handler boundary violations (${violations.length}):`);
+  for (const violation of violations) console.error(`  ${violation}`);
+  process.exit(1);
+}
+
+console.log(`Handler boundaries hold: ${functionsDir} has no cross-handler imports.`);

package/templates/architectures/serverless/files/scripts/invoke-local.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env tsx
+// Local invocation harness: runs one handler in-process against a saved event.
+// No cloud account, no container, no deploy — the fast loop serverless otherwise loses.
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** The only place these paths are written. Environment overrides them per repo. */
+const defaults = {
+  functionsRoot: 'src/functions',
+  eventsRoot: 'events',
+  entry: 'handler.ts',
+  exportName: 'handler',
+};
+
+const functionsRoot = process.env.FUNCTIONS_ROOT ?? defaults.functionsRoot;
+const eventsRoot = process.env.EVENTS_ROOT ?? defaults.eventsRoot;
+const entry = process.env.HANDLER_ENTRY ?? defaults.entry;
+const exportName = process.env.HANDLER_EXPORT ?? defaults.exportName;
+
+async function main(): Promise<number> {
+  const [name, eventName = name] = process.argv.slice(2);
+  if (!name) {
+    console.error('usage: tsx scripts/invoke-local.ts <function> [event]');
+    return 2;
+  }
+
+  const event: unknown = JSON.parse(await readFile(join(eventsRoot, `${eventName}.json`), 'utf8'));
+  const modulePath = resolve(functionsRoot, name, entry);
+  const loaded = (await import(pathToFileURL(modulePath).href)) as Record<string, unknown>;
+
+  const fn = loaded[exportName];
+  if (typeof fn !== 'function') {
+    console.error(`${modulePath} does not export "${exportName}"`);
+    return 1;
+  }
+
+  // Enough context for a handler that logs a request id — deliberately not a runtime emulator.
+  const context = {
+    awsRequestId: randomUUID(),
+    functionName: name,
+    getRemainingTimeInMillis: () => Number.MAX_SAFE_INTEGER,
+  };
+
+  const result: unknown = await (fn as (e: unknown, c: unknown) => unknown)(event, context);
+  console.log(JSON.stringify(result, null, 2));
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: unknown) => {
+    console.error(error);
+    process.exit(1);
+  },
+);

package/templates/architectures/serverless/files/scripts/invoke_local.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Local invocation harness: runs one handler in-process against a saved event.
+
+No cloud account, no container, no deploy — the fast loop serverless otherwise loses.
+`sam local invoke` is the higher-fidelity option when the packaging itself is in question.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+from types import SimpleNamespace
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+# The only place these defaults are written. Environment overrides them per repo.
+DEFAULTS = {
+    "source_root": "src",
+    "package": "{{ solutionName | snake }}",
+    "events_root": "events",
+    "export": "handler",
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Invoke one handler against a saved event.")
+    parser.add_argument("function", help="function name in kebab-case, e.g. {{ firstHandler | kebab }}")
+    parser.add_argument("event", nargs="?", help="event file stem; defaults to the function name")
+    args = parser.parse_args()
+
+    source_root = REPO_ROOT / os.environ.get("SOURCE_ROOT", DEFAULTS["source_root"])
+    package = os.environ.get("FUNCTIONS_PACKAGE", DEFAULTS["package"])
+    events_root = REPO_ROOT / os.environ.get("EVENTS_ROOT", DEFAULTS["events_root"])
+    export = os.environ.get("HANDLER_EXPORT", DEFAULTS["export"])
+
+    event_path = events_root / f"{args.event or args.function}.json"
+    if not event_path.is_file():
+        print(f"no event file at {event_path}", file=sys.stderr)
+        return 2
+    event = json.loads(event_path.read_text(encoding="utf-8"))
+
+    sys.path.insert(0, str(source_root))
+    module_name = f"{package}.functions.{args.function.replace('-', '_')}.handler"
+    fn = getattr(importlib.import_module(module_name), export, None)
+    if not callable(fn):
+        print(f"{module_name} does not export '{export}'", file=sys.stderr)
+        return 1
+
+    # Enough context for a handler that logs a request id — deliberately not a runtime emulator.
+    context = SimpleNamespace(aws_request_id=str(uuid.uuid4()), function_name=args.function)
+    print(json.dumps(fn(event, context), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/architectures/serverless/files/src/__solutionName.snake__/functions/__firstHandler.snake__/__init__.py

@@ -0,0 +1 @@
+"""The {{ firstHandler | kebab }} function. Everything this function needs lives in this package."""

package/templates/architectures/serverless/files/src/__solutionName.snake__/functions/__firstHandler.snake__/handler.py

@@ -0,0 +1,27 @@
+"""Entry point named in template.yaml. May import the shared layers, never another handler."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from {{ solutionName | snake }}.layers.config import config
+from {{ solutionName | snake }}.layers.observability import get_logger
+
+log = get_logger(__name__)
+
+
+def handler(event: Any, context: Any) -> dict[str, Any]:
+    log.info("invoked", extra={"fields": {"handler": "{{ firstHandler | kebab }}"}})
+
+    return {
+        "statusCode": 200,
+        "headers": {"content-type": "application/json"},
+        "body": json.dumps(
+            {
+                "service": config.service_name,
+                "stage": config.stage,
+                "receivedEvent": event is not None,
+            }
+        ),
+    }

package/templates/architectures/serverless/files/src/__solutionName.snake__/functions/__init__.py

@@ -0,0 +1,4 @@
+"""One package per deployed function. A handler never imports a sibling handler.
+
+Enforced by the `handlers-are-independent` contract in .importlinter.
+"""

package/templates/architectures/serverless/files/src/__solutionName.snake__/layers/__init__.py

@@ -0,0 +1,5 @@
+"""Shared layers: code every function may import, that imports no function in return.
+
+Each module here is a candidate for its own Lambda Layer once it grows a dependency the
+handlers do not all need.
+"""

package/templates/architectures/serverless/files/src/__solutionName.snake__/layers/config.py

@@ -0,0 +1,45 @@
+"""Shared layer: every runtime tunable, resolved once with one typed default each.
+
+A handler that reads os.environ directly re-hardcodes config where nobody audits it.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_LOG_LEVELS = frozenset({"DEBUG", "INFO", "WARNING", "ERROR"})
+
+
+@dataclass(frozen=True)
+class Config:
+    service_name: str
+    stage: str
+    log_level: str
+    request_timeout_ms: int
+
+
+def _int(raw: str | None, fallback: int) -> int:
+    try:
+        parsed = int(raw) if raw else fallback
+    except ValueError:
+        return fallback
+    return parsed if parsed > 0 else fallback
+
+
+def _level(raw: str | None, fallback: str) -> str:
+    candidate = (raw or "").upper()
+    return candidate if candidate in _LOG_LEVELS else fallback
+
+
+def load() -> Config:
+    return Config(
+        service_name=os.environ.get("SERVICE_NAME", "{{ solutionName | kebab }}"),
+        stage=os.environ.get("STAGE", "dev"),
+        log_level=_level(os.environ.get("LOG_LEVEL"), "INFO"),
+        request_timeout_ms=_int(os.environ.get("REQUEST_TIMEOUT_MS"), 3000),
+    )
+
+
+# Loaded at import so the cost lands in the cold start, not in every invocation.
+config = load()

package/templates/architectures/serverless/files/src/__solutionName.snake__/layers/observability.py

@@ -0,0 +1,35 @@
+"""Shared layer: structured JSON lines, the only log shape a platform can index per invocation."""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+
+from {{ solutionName | snake }}.layers.config import config
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "level": record.levelname.lower(),
+            "message": record.getMessage(),
+            "logger": record.name,
+            "service": config.service_name,
+            "stage": config.stage,
+        }
+        # `extra=` fields ride along as a dict so the line stays one flat JSON object.
+        payload.update(getattr(record, "fields", {}))
+        return json.dumps(payload)
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(JsonFormatter())
+        logger.addHandler(handler)
+        # The managed runtime installs its own root handler; do not log every line twice.
+        logger.propagate = False
+    logger.setLevel(config.log_level)
+    return logger

package/templates/architectures/serverless/files/src/functions/__firstHandler.kebab__/handler.ts

@@ -0,0 +1,26 @@
+// One folder per deployed function. This file may import src/layers/**, never another handler.
+import { config } from '../../layers/config/index.js';
+import { createLogger } from '../../layers/observability/index.js';
+
+const log = createLogger({ handler: '{{ firstHandler | kebab }}' });
+
+export interface HttpResult {
+  statusCode: number;
+  headers: Record<string, string>;
+  body: string;
+}
+
+// The event shape belongs to the trigger, not to this repo — narrow it where you use it.
+export const handler = async (event: unknown): Promise<HttpResult> => {
+  log.info('invoked');
+
+  return {
+    statusCode: 200,
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      service: config.serviceName,
+      stage: config.stage,
+      receivedEvent: event !== undefined && event !== null,
+    }),
+  };
+};

package/templates/architectures/serverless/files/src/layers/config/index.ts

@@ -0,0 +1,31 @@
+// Shared layer: every runtime tunable a handler may read, resolved once with one typed default.
+// A handler that reads process.env directly re-hardcodes config in a place nobody audits.
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface AppConfig {
+  readonly serviceName: string;
+  readonly stage: string;
+  readonly logLevel: LogLevel;
+  readonly requestTimeoutMs: number;
+}
+
+const LOG_LEVELS: readonly LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+function toInt(raw: string | undefined, fallback: number): number {
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function toLogLevel(raw: string | undefined, fallback: LogLevel): LogLevel {
+  const candidate = raw?.toLowerCase() as LogLevel | undefined;
+  return candidate && LOG_LEVELS.includes(candidate) ? candidate : fallback;
+}
+
+// Read at module load so the cost lands in the cold start, not in every invocation.
+export const config: AppConfig = {
+  serviceName: process.env.SERVICE_NAME ?? '{{ solutionName | kebab }}',
+  stage: process.env.STAGE ?? 'dev',
+  logLevel: toLogLevel(process.env.LOG_LEVEL, 'info'),
+  requestTimeoutMs: toInt(process.env.REQUEST_TIMEOUT_MS, 3000),
+};

package/templates/architectures/serverless/files/src/layers/observability/index.ts

@@ -0,0 +1,38 @@
+// Shared layer: structured JSON lines, the only log shape a platform can index per invocation.
+import { config, type LogLevel } from '../config/index.js';
+
+const ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 };
+
+export type Fields = Record<string, unknown>;
+
+export interface Logger {
+  debug(message: string, fields?: Fields): void;
+  info(message: string, fields?: Fields): void;
+  warn(message: string, fields?: Fields): void;
+  error(message: string, fields?: Fields): void;
+}
+
+/** `bound` carries per-invocation context (request id, handler name) into every line. */
+export function createLogger(bound: Fields = {}): Logger {
+  const threshold = ORDER[config.logLevel];
+
+  const emit = (level: LogLevel, message: string, fields: Fields = {}): void => {
+    if (ORDER[level] < threshold) return;
+    const line = JSON.stringify({
+      level,
+      message,
+      service: config.serviceName,
+      stage: config.stage,
+      ...bound,
+      ...fields,
+    });
+    process.stdout.write(`${line}\n`);
+  };
+
+  return {
+    debug: (message, fields) => emit('debug', message, fields),
+    info: (message, fields) => emit('info', message, fields),
+    warn: (message, fields) => emit('warn', message, fields),
+    error: (message, fields) => emit('error', message, fields),
+  };
+}

package/templates/architectures/serverless/files/src/requirements.txt

@@ -0,0 +1,3 @@
+# `sam build` resolves function dependencies from here, but the lock file stays the source
+# of truth. Regenerate, never hand-edit:
+#   uv export --no-dev --no-emit-project --format requirements-txt > src/requirements.txt

package/templates/architectures/serverless/files/template.yaml

@@ -0,0 +1,48 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+Description: >-
+  {{ solutionName | title }} — IaC entry point. Every deployed resource is declared here;
+  nothing is created by hand in a console.
+
+Parameters:
+  Stage:
+    Type: String
+    Default: dev
+    Description: Deployment stage carried into every function's environment.
+  LogLevel:
+    Type: String
+    Default: INFO
+    AllowedValues: [DEBUG, INFO, WARNING, ERROR]
+
+# The single place per-function defaults are set. Override inside a function only with a reason.
+Globals:
+  Function:
+    Runtime: {{ pythonRuntime }}
+    Architectures: [arm64]
+    Timeout: 10
+    MemorySize: 512
+    Environment:
+      Variables:
+        SERVICE_NAME: {{ solutionName | kebab }}
+        STAGE: !Ref Stage
+        LOG_LEVEL: !Ref LogLevel
+
+Resources:
+  # One resource per handler package. Adding a function is a new package plus a block here —
+  # never a change inside another function.
+  {{ firstHandler | pascal }}Function:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: src/
+      Handler: {{ solutionName | snake }}.functions.{{ firstHandler | snake }}.handler.handler
+      Events:
+        Http:
+          Type: HttpApi
+          Properties:
+            Path: /{{ firstHandler | kebab }}
+            Method: GET
+
+Outputs:
+  ApiBaseUrl:
+    Description: Base URL of the generated HTTP API.
+    Value: !Sub 'https://${ServerlessHttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}'

package/templates/architectures/serverless/files/tests/architecture/test_handler_boundaries.py

@@ -0,0 +1,32 @@
+"""The one rule of this architecture, enforced instead of documented.
+
+Runs the same contracts as `lint-imports`, so CI fails whether it invokes the linter
+directly or just runs the test suite.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_handler_import_contracts_hold() -> None:
+    linter = shutil.which("lint-imports")
+    if linter is None:
+        # Skipping would mean the boundary is unenforced and nobody notices.
+        pytest.fail("import-linter is declared in the dev group but not installed. Run: uv sync")
+
+    # Fixed argv, no shell.
+    result = subprocess.run(
+        [linter],
+        cwd=REPO_ROOT,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr