@empire-builder-kit/containers 0.0.1-alpha.10

package/dist/generators/service/files-typescript/package.json.template

@@ -0,0 +1,7 @@
+{
+  "name": "@<%= appName %>/service",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/main.js"
+}

package/dist/generators/service/files-typescript/src/index.ts.template

@@ -0,0 +1,2 @@
+export { createHealthResponse, formatLogEvent, readServiceConfig } from './service.js';
+export type { HealthResponse, LogContext, ServiceConfig } from './service.js';

package/dist/generators/service/files-typescript/src/main.ts.template

@@ -0,0 +1,60 @@
+import { createServer } from 'node:http';
+import { createLogger, createRequestContext } from '@empire-builder-kit/runtime';
+import {
+  createHealthResponse,
+  readServiceConfig,
+} from './service.js';
+
+function readPort(env: NodeJS.ProcessEnv = process.env): number {
+  const value = env.PORT?.trim();
+
+  if (!value) {
+    return 3000;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid PORT value: ${value}`);
+  }
+
+  return parsed;
+}
+
+const config = readServiceConfig();
+const port = readPort();
+const logger = createLogger({ app: '<%= app %>', source: '<%= projectName %>' });
+
+const server = createServer((request, response) => {
+  const method = request.method ?? 'GET';
+  const url = request.url ?? '/';
+  const ctx = createRequestContext({
+    app: '<%= app %>',
+    operation: `${method} ${url}`,
+    stage: process.env.SST_STAGE ?? process.env.EBK_STAGE ?? 'development',
+  });
+
+  logger.info('request received', {
+    correlationId: ctx.correlationId,
+    method,
+    path: url,
+  });
+
+  if (method === 'GET' && url === '/health') {
+    response.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+    response.end(JSON.stringify(createHealthResponse(config)));
+    return;
+  }
+
+  response.writeHead(404, { 'content-type': 'application/json; charset=utf-8' });
+  response.end(
+    JSON.stringify({
+      error: 'Not Found',
+      path: url,
+    })
+  );
+});
+
+server.listen(port, () => {
+  logger.info('service listening', { port });
+});

package/dist/generators/service/files-typescript/src/service.spec.ts.template

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createHealthResponse,
+  formatLogEvent,
+  readServiceConfig,
+} from './service.js';
+
+describe('service helpers', () => {
+  it('falls back to service defaults', () => {
+    expect(readServiceConfig({})).toEqual({
+      serviceName: '<%= className %>Service',
+      version: '0.0.1',
+    });
+  });
+
+  it('builds a stable health payload', () => {
+    expect(
+      createHealthResponse({
+        serviceName: '<%= className %>Service',
+        version: '1.2.3',
+      })
+    ).toEqual({
+      service: '<%= className %>Service',
+      status: 'ok',
+      version: '1.2.3',
+    });
+  });
+
+  it('formats structured log output', () => {
+    expect(
+      formatLogEvent(
+        {
+          serviceName: '<%= className %>Service',
+          version: '1.2.3',
+        },
+        'service.started',
+        { port: 3000 }
+      )
+    ).toBe(
+      JSON.stringify({
+        level: 'info',
+        message: 'service.started',
+        service: '<%= className %>Service',
+        version: '1.2.3',
+        port: 3000,
+      })
+    );
+  });
+});

package/dist/generators/service/files-typescript/src/service.ts.template

@@ -0,0 +1,57 @@
+export interface ServiceConfig {
+  serviceName: string;
+  version: string;
+}
+
+export interface HealthResponse {
+  service: string;
+  status: 'ok';
+  version: string;
+}
+
+export interface LogContext {
+  [key: string]: string | number | boolean | null;
+}
+
+const DEFAULT_SERVICE_NAME = '<%= className %>Service';
+const DEFAULT_SERVICE_VERSION = '0.0.1';
+
+function readOptionalEnv(
+  env: NodeJS.ProcessEnv,
+  key: string,
+  fallback: string
+): string {
+  const value = env[key]?.trim();
+  return value && value.length > 0 ? value : fallback;
+}
+
+export function readServiceConfig(
+  env: NodeJS.ProcessEnv = process.env
+): ServiceConfig {
+  return {
+    serviceName: readOptionalEnv(env, 'SERVICE_NAME', DEFAULT_SERVICE_NAME),
+    version: readOptionalEnv(env, 'SERVICE_VERSION', DEFAULT_SERVICE_VERSION),
+  };
+}
+
+export function createHealthResponse(config: ServiceConfig): HealthResponse {
+  return {
+    service: config.serviceName,
+    status: 'ok',
+    version: config.version,
+  };
+}
+
+export function formatLogEvent(
+  config: ServiceConfig,
+  message: string,
+  context: LogContext = {}
+): string {
+  return JSON.stringify({
+    level: 'info',
+    message,
+    service: config.serviceName,
+    version: config.version,
+    ...context,
+  });
+}

package/dist/generators/service/files-typescript/tsconfig.app.json.template

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "<%= offsetFromRoot %>dist/<%= projectRoot %>",
+    "declaration": false,
+    "declarationMap": false,
+    "emitDeclarationOnly": false
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts"]
+}

package/dist/generators/service/files-typescript/tsconfig.json.template

@@ -0,0 +1,7 @@
+{
+  "extends": "<%= offsetFromRoot %>tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "vitest.config.mts"]
+}

package/dist/generators/service/files-typescript/tsconfig.spec.json.template

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.spec.ts", "src/**/*.test.ts", "vitest.config.mts"]
+}

package/dist/generators/service/files-typescript/vitest.config.mts.template

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  root: __dirname,
+  cacheDir: '<%= offsetFromRoot %>node_modules/.vite/<%= projectRoot %>',
+  test: {
+    name: '<%= projectName %>',
+    watch: false,
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.ts'],
+    reporters: ['default'],
+    coverage: {
+      provider: 'v8',
+      reportsDirectory: './test-output/vitest/coverage',
+    },
+  },
+});

package/dist/generators/service/schema.d.ts

@@ -0,0 +1,8 @@
+export interface ServiceGeneratorSchema {
+  name: string;
+  app: string;
+  language?: 'typescript' | 'rust' | 'go' | 'python';
+  directory?: string;
+  skipFormat?: boolean;
+  tags?: string;
+}

package/dist/generators/service/schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "Service",
+  "title": "Generate an EBK container service",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Name for the service within the app group.",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "What name should the service have?"
+    },
+    "app": {
+      "type": "string",
+      "description": "Owning Empire Builder Kit app-group name.",
+      "x-prompt": "Which app group should receive the service?"
+    },
+    "language": {
+      "type": "string",
+      "description": "Programming language for the service.",
+      "enum": ["typescript", "rust", "go", "python"],
+      "default": "typescript"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Base directory for app groups.",
+      "default": "packages"
+    },
+    "tags": {
+      "type": "string",
+      "description": "Comma-separated additional tags to apply to the project."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files.",
+      "default": false
+    }
+  },
+  "required": ["name", "app"]
+}

package/dist/generators/service/service.d.ts

@@ -0,0 +1,5 @@
+import { Tree } from '@nx/devkit';
+import { ServiceGeneratorSchema } from './schema';
+export declare function serviceGenerator(tree: Tree, options: ServiceGeneratorSchema): Promise<void>;
+export default serviceGenerator;
+//# sourceMappingURL=service.d.ts.map

package/dist/generators/service/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/generators/service/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,IAAI,EACL,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA+MlD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,sBAAsB,iBA8ChC;AAED,eAAe,gBAAgB,CAAC"}

package/dist/generators/service/service.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceGenerator = serviceGenerator;
+const tslib_1 = require("tslib");
+const devkit_1 = require("@nx/devkit");
+const path = tslib_1.__importStar(require("node:path"));
+function runtimeForLanguage(language) {
+    switch (language) {
+        case 'typescript':
+            return 'node';
+        case 'rust':
+            return 'native';
+        case 'go':
+            return 'native';
+        case 'python':
+            return 'python';
+    }
+}
+function targetsForLanguage(language, projectRoot, projectName, outputPath) {
+    const cwd = projectRoot;
+    switch (language) {
+        case 'typescript':
+            return {
+                build: {
+                    executor: 'nx:run-commands',
+                    outputs: [`{workspaceRoot}/${outputPath}`],
+                    options: { cwd, command: 'tsc -p tsconfig.app.json' },
+                },
+                lint: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'eslint .' },
+                },
+                typecheck: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'tsc --noEmit -p tsconfig.json' },
+                },
+                test: {
+                    executor: 'nx:run-commands',
+                    options: {
+                        cwd,
+                        command: 'vitest run --config vitest.config.mts',
+                    },
+                },
+                dev: {
+                    executor: 'nx:run-commands',
+                    options: {
+                        cwd,
+                        command: 'node --watch --enable-source-maps --import @swc-node/register/esm-register src/main.ts',
+                    },
+                },
+                'docker-build': {
+                    executor: 'nx:run-commands',
+                    options: {
+                        command: `docker build --tag ${projectName} ${projectRoot}`,
+                    },
+                },
+            };
+        case 'rust':
+            return {
+                build: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'cargo build --release' },
+                },
+                lint: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'cargo clippy -- -D warnings' },
+                },
+                test: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'cargo test' },
+                },
+                dev: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'cargo watch -x run' },
+                },
+                'docker-build': {
+                    executor: 'nx:run-commands',
+                    options: {
+                        command: `docker build --tag ${projectName} ${projectRoot}`,
+                    },
+                },
+            };
+        case 'go':
+            return {
+                build: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'go build -o bin/service ./cmd/...' },
+                },
+                lint: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'golangci-lint run' },
+                },
+                typecheck: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'go vet ./...' },
+                },
+                test: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'go test ./...' },
+                },
+                dev: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'go run ./cmd/...' },
+                },
+                'docker-build': {
+                    executor: 'nx:run-commands',
+                    options: {
+                        command: `docker build --tag ${projectName} ${projectRoot}`,
+                    },
+                },
+            };
+        case 'python':
+            return {
+                lint: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'ruff check .' },
+                },
+                typecheck: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'mypy src/' },
+                },
+                test: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'pytest' },
+                },
+                dev: {
+                    executor: 'nx:run-commands',
+                    options: { cwd, command: 'uvicorn src.main:app --reload' },
+                },
+                'docker-build': {
+                    executor: 'nx:run-commands',
+                    options: {
+                        command: `docker build --tag ${projectName} ${projectRoot}`,
+                    },
+                },
+            };
+    }
+}
+function normalizeOptions(options) {
+    const appNames = (0, devkit_1.names)(options.app);
+    const serviceNames = (0, devkit_1.names)(options.name);
+    const language = options.language ?? 'typescript';
+    const directory = (options.directory ?? 'packages').replace(/\\/g, '/');
+    const projectRoot = (0, devkit_1.joinPathFragments)(directory, appNames.fileName, 'apps', 'service', serviceNames.fileName);
+    const userTags = options.tags
+        ?.split(',')
+        .map((tag) => tag.trim())
+        .filter(Boolean) ?? [];
+    return {
+        app: appNames.fileName,
+        appName: appNames.fileName,
+        className: appNames.className,
+        directory,
+        language,
+        name: serviceNames.fileName,
+        offsetFromRoot: (0, devkit_1.offsetFromRoot)(projectRoot),
+        outputPath: (0, devkit_1.joinPathFragments)('dist', projectRoot),
+        projectName: `${appNames.fileName}-service-${serviceNames.fileName}`,
+        projectRoot,
+        projectTitle: `${appNames.className} Service ${serviceNames.className}`,
+        skipFormat: options.skipFormat,
+        tags: [
+            `scope:${appNames.fileName}`,
+            'layer:app',
+            'type:service',
+            `runtime:${runtimeForLanguage(language)}`,
+            'deploy:container',
+            'visibility:internal',
+            ...userTags,
+        ],
+    };
+}
+async function serviceGenerator(tree, options) {
+    const normalized = normalizeOptions(options);
+    const appRoot = (0, devkit_1.joinPathFragments)(normalized.directory, normalized.appName);
+    if (!tree.exists(appRoot)) {
+        throw new Error(`App group "${normalized.app}" does not exist at "${appRoot}". Generate the app group first.`);
+    }
+    if (tree.exists((0, devkit_1.joinPathFragments)(normalized.projectRoot, 'project.json')) ||
+        tree.exists((0, devkit_1.joinPathFragments)(normalized.projectRoot, 'package.json'))) {
+        throw new Error(`Service "${normalized.name}" already exists at "${normalized.projectRoot}".`);
+    }
+    (0, devkit_1.addProjectConfiguration)(tree, normalized.projectName, {
+        root: normalized.projectRoot,
+        projectType: 'application',
+        sourceRoot: `${normalized.projectRoot}/src`,
+        tags: normalized.tags,
+        targets: targetsForLanguage(normalized.language, normalized.projectRoot, normalized.projectName, normalized.outputPath),
+    });
+    (0, devkit_1.generateFiles)(tree, path.join(__dirname, `files-${normalized.language}`), normalized.projectRoot, {
+        ...normalized,
+        tmpl: '',
+    });
+    if (!normalized.skipFormat) {
+        await (0, devkit_1.formatFiles)(tree);
+    }
+}
+exports.default = serviceGenerator;

package/dist/generators/task/files-go/Dockerfile.template

@@ -0,0 +1,10 @@
+FROM golang:1-bookworm AS builder
+WORKDIR /app
+COPY go.mod go.sum* ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o /task ./cmd/...
+
+FROM gcr.io/distroless/static-debian12
+COPY --from=builder /task /task
+CMD ["/task"]

package/dist/generators/task/files-go/README.md.template

@@ -0,0 +1,11 @@
+# <%= projectTitle %>
+
+Go task for the `<%= app %>` app group.
+
+## Commands
+
+- `pnpm nx run <%= projectName %>:build` — compile binary
+- `pnpm nx run <%= projectName %>:dev` — run locally
+- `pnpm nx run <%= projectName %>:test` — run tests
+- `pnpm nx run <%= projectName %>:lint` — run golangci-lint
+- `pnpm nx run <%= projectName %>:docker-build` — build container image

package/dist/generators/task/files-go/cmd/main.go.template

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"log/slog"
+	"os"
+)
+
+func main() {
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	slog.SetDefault(logger)
+
+	trigger := os.Getenv("TASK_TRIGGER")
+	if trigger == "" {
+		trigger = "manual"
+	}
+
+	slog.Info("task started", "trigger", trigger, "task", "<%= projectName %>")
+
+	// Task logic goes here
+
+	slog.Info("task completed successfully")
+}

package/dist/generators/task/files-go/docs/contracts.md.template

@@ -0,0 +1,9 @@
+# <%= projectTitle %> Contracts
+
+## Input
+
+- `TASK_TRIGGER` env var controls the task trigger type (default: `manual`)
+
+## Local Development
+
+- `pnpm nx run <%= projectName %>:dev`

package/dist/generators/task/files-go/go.mod.template

@@ -0,0 +1,3 @@
+module github.com/org/<%= projectName %>
+
+go 1.22

package/dist/generators/task/files-go/infra/task.ts.template

@@ -0,0 +1,38 @@
+export interface Register<%= className %>TaskArgs {
+  cluster: sst.aws.Cluster;
+  environment?: Record<string, string>;
+  link?: any[];
+}
+
+// ECS task (not a long-running service) — runs once per trigger, no health
+// endpoint required. Runtime-agnostic SST wrapper; the Dockerfile decides
+// whether the workload is Rust, Go, Python, or Node.
+export function register<%= className %>Task({
+  cluster,
+  environment = {},
+  link = [],
+}: Register<%= className %>TaskArgs) {
+  const task = new sst.aws.Task('<%= projectName %>', {
+    cluster,
+    image: {
+      context: './apps/task/<%= name %>',
+      dockerfile: 'Dockerfile',
+    },
+    dev: {
+      command: 'pnpm nx run <%= projectName %>:dev',
+      directory: '../../..',
+    },
+    environment: {
+      TASK_NAME: '<%= className %>Task',
+      TASK_VERSION: '0.0.1',
+      TASK_TRIGGER: 'manual',
+      ...environment,
+    },
+    link,
+    logging: {
+      retention: '1 month',
+    },
+  });
+
+  return { task };
+}

package/dist/generators/task/files-python/Dockerfile.template

@@ -0,0 +1,10 @@
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY pyproject.toml ./
+RUN pip install --no-cache-dir .
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY src/ src/
+CMD ["python", "src/main.py"]

package/dist/generators/task/files-python/README.md.template

@@ -0,0 +1,11 @@
+# <%= projectTitle %>
+
+Python task for the `<%= app %>` app group.
+
+## Commands
+
+- `pnpm nx run <%= projectName %>:dev` — run locally
+- `pnpm nx run <%= projectName %>:test` — run pytest
+- `pnpm nx run <%= projectName %>:lint` — run ruff
+- `pnpm nx run <%= projectName %>:typecheck` — run mypy
+- `pnpm nx run <%= projectName %>:docker-build` — build container image

package/dist/generators/task/files-python/docs/contracts.md.template

@@ -0,0 +1,9 @@
+# <%= projectTitle %> Contracts
+
+## Input
+
+- `TASK_TRIGGER` env var controls the task trigger type (default: `manual`)
+
+## Local Development
+
+- `pnpm nx run <%= projectName %>:dev`

package/dist/generators/task/files-python/infra/task.ts.template

@@ -0,0 +1,38 @@
+export interface Register<%= className %>TaskArgs {
+  cluster: sst.aws.Cluster;
+  environment?: Record<string, string>;
+  link?: any[];
+}
+
+// ECS task (not a long-running service) — runs once per trigger, no health
+// endpoint required. Runtime-agnostic SST wrapper; the Dockerfile decides
+// whether the workload is Rust, Go, Python, or Node.
+export function register<%= className %>Task({
+  cluster,
+  environment = {},
+  link = [],
+}: Register<%= className %>TaskArgs) {
+  const task = new sst.aws.Task('<%= projectName %>', {
+    cluster,
+    image: {
+      context: './apps/task/<%= name %>',
+      dockerfile: 'Dockerfile',
+    },
+    dev: {
+      command: 'pnpm nx run <%= projectName %>:dev',
+      directory: '../../..',
+    },
+    environment: {
+      TASK_NAME: '<%= className %>Task',
+      TASK_VERSION: '0.0.1',
+      TASK_TRIGGER: 'manual',
+      ...environment,
+    },
+    link,
+    logging: {
+      retention: '1 month',
+    },
+  });
+
+  return { task };
+}