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

package/README.md

@@ -0,0 +1,20 @@
+# @empire-builder-kit/containers
+
+Empire Builder Kit container workload generators.
+
+## Implemented Surface
+
+- `@empire-builder-kit/containers:service`: scaffold a TypeScript-first backend service at `packages/<app>/apps/service`
+- `@empire-builder-kit/containers:task`: scaffold a TypeScript-first backend task at `packages/<app>/apps/task`
+
+## Current Direction
+
+This milestone focuses on a mergeable TypeScript-first backend slice: a minimal HTTP service plus a batch-oriented task with shared container build conventions, Nx targets, Vitest coverage, app-local docs, and generated SST/ECS composition templates with a consistent local-dev command contract. Broader language presets can land in follow-on milestones.
+
+## Building
+
+Run `pnpm nx build @empire-builder-kit/containers` to build the library.
+
+## Running unit tests
+
+Run `pnpm nx test @empire-builder-kit/containers` to execute the unit tests via [Vitest](https://vitest.dev/).

package/dist/executors.json

@@ -0,0 +1,3 @@
+{
+  "executors": {}
+}

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

@@ -0,0 +1,11 @@
+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 /service ./cmd/...
+
+FROM gcr.io/distroless/static-debian12
+COPY --from=builder /service /service
+EXPOSE 3000
+CMD ["/service"]

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

@@ -0,0 +1,11 @@
+# <%= projectTitle %>
+
+Go service 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/service/files-go/cmd/main.go.template

@@ -0,0 +1,34 @@
+package main
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"os"
+)
+
+type healthResponse struct {
+	Status  string `json:"status"`
+	Service string `json:"service"`
+}
+
+func main() {
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	slog.SetDefault(logger)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /health", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(healthResponse{
+			Status:  "ok",
+			Service: "<%= projectName %>",
+		})
+	})
+
+	addr := ":3000"
+	slog.Info("listening", "addr", addr)
+	if err := http.ListenAndServe(addr, mux); err != nil {
+		slog.Error("server failed", "error", err)
+		os.Exit(1)
+	}
+}

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

@@ -0,0 +1,9 @@
+# <%= projectTitle %> Contracts
+
+## Health Endpoint
+
+- `GET /health` — returns `{ "status": "ok", "service": "<%= projectName %>" }`
+
+## Local Development
+
+- `pnpm nx run <%= projectName %>:dev`

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

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

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

@@ -0,0 +1,12 @@
+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 --from=builder /usr/local/bin /usr/local/bin
+COPY src/ src/
+EXPOSE 3000
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "3000"]

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

@@ -0,0 +1,11 @@
+# <%= projectTitle %>
+
+Python (FastAPI) service for the `<%= app %>` app group.
+
+## Commands
+
+- `pnpm nx run <%= projectName %>:dev` — run with auto-reload
+- `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/service/files-python/docs/contracts.md.template

@@ -0,0 +1,9 @@
+# <%= projectTitle %> Contracts
+
+## Health Endpoint
+
+- `GET /health` — returns `{ "status": "ok", "service": "<%= projectName %>" }`
+
+## Local Development
+
+- `pnpm nx run <%= projectName %>:dev`

package/dist/generators/service/files-python/pyproject.toml.template

@@ -0,0 +1,15 @@
+[project]
+name = "<%= projectName %>"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.34",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]

package/dist/generators/service/files-python/src/main.py.template

@@ -0,0 +1,20 @@
+"""<%= projectTitle %> — FastAPI service for the <%= app %> app group."""
+
+import logging
+import sys
+
+from fastapi import FastAPI
+
+logging.basicConfig(
+    stream=sys.stdout,
+    level=logging.INFO,
+    format="%(message)s",
+)
+logger = logging.getLogger("<%= projectName %>")
+
+app = FastAPI(title="<%= projectTitle %>")
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "service": "<%= projectName %>"}

package/dist/generators/service/files-rust/Cargo.toml.template

@@ -0,0 +1,16 @@
+[package]
+name = "<%= projectName %>"
+version = "0.1.0"
+edition = "2021"
+
+[[bin]]
+name = "service"
+path = "src/main.rs"
+
+[dependencies]
+axum = "0.8"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["json"] }

package/dist/generators/service/files-rust/Dockerfile.template

@@ -0,0 +1,12 @@
+FROM rust:1-bookworm AS builder
+WORKDIR /app
+COPY Cargo.toml Cargo.lock* ./
+RUN mkdir src && echo "fn main() {}" > src/main.rs && cargo build --release && rm -rf src
+COPY src/ src/
+RUN cargo build --release
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /app/target/release/service /usr/local/bin/service
+EXPOSE 3000
+CMD ["service"]

package/dist/generators/service/files-rust/README.md.template

@@ -0,0 +1,11 @@
+# <%= projectTitle %>
+
+Rust service for the `<%= app %>` app group.
+
+## Commands
+
+- `pnpm nx run <%= projectName %>:build` — compile release binary
+- `pnpm nx run <%= projectName %>:dev` — run with cargo-watch
+- `pnpm nx run <%= projectName %>:test` — run tests
+- `pnpm nx run <%= projectName %>:lint` — run clippy
+- `pnpm nx run <%= projectName %>:docker-build` — build container image

package/dist/generators/service/files-rust/docs/contracts.md.template

@@ -0,0 +1,9 @@
+# <%= projectTitle %> Contracts
+
+## Health Endpoint
+
+- `GET /health` — returns `{ "status": "ok", "service": "<%= projectName %>" }`
+
+## Local Development
+
+- `pnpm nx run <%= projectName %>:dev`

package/dist/generators/service/files-rust/src/main.rs.template

@@ -0,0 +1,29 @@
+use axum::{routing::get, Json, Router};
+use serde::Serialize;
+use std::net::SocketAddr;
+
+#[derive(Serialize)]
+struct HealthResponse {
+    status: &'static str,
+    service: &'static str,
+}
+
+async fn health() -> Json<HealthResponse> {
+    Json(HealthResponse {
+        status: "ok",
+        service: "<%= projectName %>",
+    })
+}
+
+#[tokio::main]
+async fn main() {
+    tracing_subscriber::fmt().json().init();
+
+    let app = Router::new().route("/health", get(health));
+
+    let addr = SocketAddr::from(([0, 0, 0, 0], 3000));
+    tracing::info!("listening on {}", addr);
+
+    let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
+    axum::serve(listener, app).await.unwrap();
+}

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

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1.7
+
+FROM node:22-bookworm-slim AS build
+WORKDIR /workspace
+
+ENV CI=true
+
+RUN corepack enable
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml nx.json tsconfig.base.json tsconfig.json eslint.config.mjs ./
+COPY packages ./packages
+COPY tools ./tools
+
+RUN pnpm install --frozen-lockfile
+RUN pnpm nx run <%= projectName %>:build
+
+FROM node:22-bookworm-slim AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV SERVICE_NAME=<%= className %>Service
+
+COPY --from=build /workspace/dist/<%= projectRoot %>/ ./
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s CMD node -e "fetch('http://127.0.0.1:' + (process.env.PORT || '3000') + '/health').then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))"
+
+CMD ["node", "main.js"]

package/dist/generators/service/files-typescript/README.md.template

@@ -0,0 +1,24 @@
+# <%= projectTitle %>
+
+TypeScript-first backend container service for the `<%= appName %>` app group.
+
+## Purpose
+
+This package provides a first mergeable ECS-style service slice with a health endpoint, structured log output, and container build conventions that fit the Empire Builder Kit app-group layout.
+
+## Nx Targets
+
+- `pnpm nx run <%= projectName %>:build`
+- `pnpm nx run <%= projectName %>:lint`
+- `pnpm nx run <%= projectName %>:typecheck`
+- `pnpm nx run <%= projectName %>:test`
+- `pnpm nx run <%= projectName %>:dev`
+- `pnpm nx run <%= projectName %>:docker-build`
+
+## Current Conventions
+
+- keep long-running backend code in `src/`
+- expose health behavior through `GET /health`
+- prefer structured JSON logs so ECS and CloudWatch parsing stay predictable
+- keep SST composition scaffolding in `infra/service.ts` so app-group infra can opt into the workload without rewriting the local-dev contract
+- treat this package as app-group-internal until a supported SDK or API contract is published

package/dist/generators/service/files-typescript/docs/architecture.md.template

@@ -0,0 +1,18 @@
+# <%= projectTitle %> Architecture
+
+## Scope
+
+`<%= projectName %>` is the first TypeScript-first container workload slice for `<%= appName %>`. It gives the app group a long-running backend process under `packages/<%= appName %>/apps/service` without introducing language-preset sprawl in the first milestone.
+
+## Runtime Shape
+
+- `src/main.ts` starts a small Node HTTP server
+- `src/service.ts` keeps config, health payloads, and structured log formatting testable
+- `GET /health` is the default readiness endpoint for local and container checks
+- `infra/service.ts` captures the recommended SST `Cluster` + `Service` composition seam, image path, service registry, and `sst dev` command contract
+
+## Current Boundaries
+
+- keep app-specific background processing and internal APIs here
+- publish cross-app contracts through the owning app group's SDK instead of importing internals directly
+- compose this workload into the owning app group's root `infra/` entrypoint instead of letting app code instantiate SST resources ad hoc

package/dist/generators/service/files-typescript/docs/contracts.md.template

@@ -0,0 +1,20 @@
+# <%= projectTitle %> Contracts
+
+## Local Development
+
+- `pnpm nx run <%= projectName %>:dev` is the canonical local command for this workload.
+- `infra/service.ts` passes the same command to SST via `dev.command` so `sst dev` and direct Nx usage stay aligned.
+- `PORT`, `SERVICE_NAME`, and `SERVICE_VERSION` are the supported starter env overrides.
+
+## Infra Composition
+
+- import `register<%= className %>Service` from `apps/service/infra/service` into the owning app group's root `infra/` entrypoint
+- provide an existing `sst.aws.Cluster` from app-group infrastructure instead of constructing a cluster inside runtime code
+- use the generated `GET /health` path as the default ECS and load balancer health contract
+- pass linked SST resources through `link` so runtime code can consume them through `Resource.*`
+
+## Deployment Defaults
+
+- image build context stays rooted at `packages/<%= appName %>/apps/service`
+- local dev assumes `http://127.0.0.1:3000`
+- load-balanced deployments default to forwarding `80/http` to `3000/http`

package/dist/generators/service/files-typescript/docs/operations.md.template

@@ -0,0 +1,24 @@
+# <%= projectTitle %> Operations
+
+## Local Verification
+
+- `pnpm nx run <%= projectName %>:build`
+- `pnpm nx run <%= projectName %>:test`
+- `pnpm nx run <%= projectName %>:dev`
+- `node dist/<%= projectRoot %>/main.js`
+
+Set `PORT`, `SERVICE_NAME`, or `SERVICE_VERSION` in the environment to override the defaults exposed by the starter service.
+
+`<%= projectName %>:dev` uses `@swc-node/register` so the same command can be handed to `sst dev` from `infra/service.ts` without introducing a second local entrypoint contract.
+
+## Container Workflow
+
+- `pnpm nx run <%= projectName %>:docker-build`
+- image build runs the workspace install plus `pnpm nx run <%= projectName %>:build`
+- the container exposes `GET /health` and ships with a matching Docker `HEALTHCHECK`
+- `infra/service.ts` wires the same health path into SST load balancer and ECS health checks for a mergeable default
+
+## Next Steps
+
+- replace the starter route handling with app-specific workload logic
+- import `register<%= className %>Service` into the owning app group's `infra/` entrypoint when the workload is ready to deploy

package/dist/generators/service/files-typescript/eslint.config.mjs.template

@@ -0,0 +1,3 @@
+import baseConfig from '<%= offsetFromRoot %>eslint.config.mjs';
+
+export default [...baseConfig];

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

@@ -0,0 +1,64 @@
+export interface Register<%= className %>ServiceArgs {
+  cluster: sst.aws.Cluster;
+  domain?: string | { name: string };
+  environment?: Record<string, string>;
+  link?: any[];
+  publicLoadBalancer?: boolean;
+}
+
+export function register<%= className %>Service({
+  cluster,
+  domain,
+  environment = {},
+  link = [],
+  publicLoadBalancer = false,
+}: Register<%= className %>ServiceArgs) {
+  const service = new sst.aws.Service('<%= projectName %>', {
+    cluster,
+    image: {
+      context: './apps/service/<%= name %>',
+      dockerfile: 'Dockerfile',
+    },
+    dev: {
+      command: 'pnpm nx run <%= projectName %>:dev',
+      directory: '../../..',
+      url: 'http://127.0.0.1:3000',
+    },
+    environment: {
+      PORT: '3000',
+      SERVICE_NAME: '<%= className %>Service',
+      SERVICE_VERSION: '0.0.1',
+      ...environment,
+    },
+    health: {
+      command: [
+        'CMD-SHELL',
+        'node -e "fetch(\'http://127.0.0.1:3000/health\').then((response) => process.exit(response.ok ? 0 : 1)).catch(() => process.exit(1))"',
+      ],
+      interval: '30 seconds',
+      timeout: '5 seconds',
+      retries: 3,
+      startPeriod: '10 seconds',
+    },
+    link,
+    logging: {
+      retention: '1 month',
+    },
+    serviceRegistry: {
+      port: 3000,
+    },
+    loadBalancer: {
+      public: publicLoadBalancer,
+      ...(domain ? { domain } : {}),
+      rules: [{ listen: '80/http', forward: '3000/http' }],
+      health: {
+        '3000/http': {
+          path: '/health',
+          successCodes: '200-399',
+        },
+      },
+    },
+  });
+
+  return { service };
+}

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 ?? 'dev',
+  });
+
+  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"]
+}