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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Empire Builder Kit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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-go/infra/service.ts.template

@@ -0,0 +1,59 @@
+export interface Register<%= className %>ServiceArgs {
+  cluster: sst.aws.Cluster;
+  domain?: string | { name: string };
+  environment?: Record<string, string>;
+  link?: any[];
+  publicLoadBalancer?: boolean;
+}
+
+// Go service runs a static binary — no node/curl in the runtime image,
+// so the Docker HEALTHCHECK is omitted here and the load balancer's
+// target-group health check on `/health` gates traffic instead. Add a
+// HEALTHCHECK back in Dockerfile + pass `health` here explicitly if you
+// need task-level health visibility in ECS.
+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,
+    },
+    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-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/infra/service.ts.template

@@ -0,0 +1,68 @@
+export interface Register<%= className %>ServiceArgs {
+  cluster: sst.aws.Cluster;
+  domain?: string | { name: string };
+  environment?: Record<string, string>;
+  link?: any[];
+  publicLoadBalancer?: boolean;
+}
+
+// Python service uses `python -c` for the Docker HEALTHCHECK — the
+// runtime image already has python + stdlib `urllib.request`, so no
+// extra system package is needed. The load balancer's target-group
+// health check on `/health` still gates traffic independently.
+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',
+        'python -c "import urllib.request,sys;sys.exit(0 if urllib.request.urlopen(\'http://127.0.0.1:3000/health\',timeout=2).status<400 else 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-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/infra/service.ts.template

@@ -0,0 +1,59 @@
+export interface Register<%= className %>ServiceArgs {
+  cluster: sst.aws.Cluster;
+  domain?: string | { name: string };
+  environment?: Record<string, string>;
+  link?: any[];
+  publicLoadBalancer?: boolean;
+}
+
+// Rust service runs a native binary inside debian-slim — no node/curl in
+// the runtime image, so the Docker HEALTHCHECK is omitted here and the
+// load balancer's target-group health check on `/health` gates traffic
+// instead. Add a HEALTHCHECK back in Dockerfile + pass `health` here
+// explicitly if you need task-level health visibility in ECS.
+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,
+    },
+    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-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 };
+}