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

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-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/pyproject.toml.template

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

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

@@ -0,0 +1,26 @@
+"""<%= projectTitle %> — task runner for the <%= app %> app group."""
+
+import json
+import logging
+import os
+import sys
+
+logging.basicConfig(
+    stream=sys.stdout,
+    level=logging.INFO,
+    format="%(message)s",
+)
+logger = logging.getLogger("<%= projectName %>")
+
+
+def main():
+    trigger = os.environ.get("TASK_TRIGGER", "manual")
+    logger.info(json.dumps({"msg": "task started", "trigger": trigger, "task": "<%= projectName %>"}))
+
+    # Task logic goes here
+
+    logger.info(json.dumps({"msg": "task completed successfully"}))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,15 @@
+[package]
+name = "<%= projectName %>"
+version = "0.1.0"
+edition = "2021"
+
+[[bin]]
+name = "task"
+path = "src/main.rs"
+
+[dependencies]
+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/task/files-rust/Dockerfile.template

@@ -0,0 +1,11 @@
+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/task /usr/local/bin/task
+CMD ["task"]

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

@@ -0,0 +1,11 @@
+# <%= projectTitle %>
+
+Rust task for the `<%= app %>` app group.
+
+## Commands
+
+- `pnpm nx run <%= projectName %>:build` — compile release binary
+- `pnpm nx run <%= projectName %>:dev` — run locally
+- `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/task/files-rust/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-rust/src/main.rs.template

@@ -0,0 +1,12 @@
+use std::env;
+
+#[tokio::main]
+async fn main() {
+    tracing_subscriber::fmt().json().init();
+
+    let trigger = env::var("TASK_TRIGGER").unwrap_or_else(|_| "manual".to_string());
+    tracing::info!(trigger = %trigger, task = "<%= projectName %>", "task started");
+
+    // Task logic goes here
+    tracing::info!("task completed successfully");
+}

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

@@ -0,0 +1,25 @@
+# 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 TASK_NAME=<%= className %>Task
+
+COPY --from=build /workspace/dist/<%= projectRoot %>/ ./
+
+CMD ["node", "main.js"]

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

@@ -0,0 +1,24 @@
+# <%= projectTitle %>
+
+TypeScript-first backend container task for the `<%= appName %>` app group.
+
+## Purpose
+
+This package provides a first mergeable ECS-style task slice for scheduled, queue-driven, and ad hoc operational work without forcing a broader multi-language preset decision yet.
+
+## 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 batch and worker logic in `src/`
+- treat `src/main.ts` as the command entrypoint for local and container runs
+- prefer structured JSON logs so ECS, EventBridge, and CloudWatch parsing stay predictable
+- keep SST composition scaffolding in `infra/task.ts` so remote execution and local proxying use the same contract
+- treat this package as app-group-internal until a supported SDK or API contract is published

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

@@ -0,0 +1,18 @@
+# <%= projectTitle %> Architecture
+
+## Scope
+
+`<%= projectName %>` is the first TypeScript-first container task slice for `<%= appName %>`. It gives the app group a batch-oriented workload under `packages/<%= appName %>/apps/task` without introducing language-preset sprawl in the first milestone.
+
+## Runtime Shape
+
+- `src/main.ts` runs the task entrypoint and emits structured lifecycle logs
+- `src/task.ts` keeps config, result creation, and task behavior testable
+- `TASK_TRIGGER` provides a simple starting contract for schedule, queue, or manual execution context
+- `infra/task.ts` captures the recommended SST `Cluster` + `Task` composition seam and `sst dev` proxy command contract
+
+## Current Boundaries
+
+- keep scheduled, queue-driven, and ad hoc operational work 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 runtime code instantiate SST resources ad hoc

package/dist/generators/task/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/task.ts` passes the same command to SST via `dev.command` so `sst dev` can proxy remote task runs back to local code.
+- `TASK_NAME`, `TASK_VERSION`, and `TASK_TRIGGER` are the supported starter env overrides.
+
+## Infra Composition
+
+- import `register<%= className %>Task` from `apps/task/infra/task` 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
+- pass linked SST resources through `link` so runtime code can consume them through `Resource.*`
+- use `TASK_TRIGGER` as the starter trigger contract for local runs, EventBridge invocations, or task SDK calls
+
+## Deployment Defaults
+
+- image build context stays rooted at `packages/<%= appName %>/apps/task`
+- local dev runs the same command SST uses when proxying task executions
+- logging defaults to a one-month CloudWatch retention window until app-specific requirements are known

package/dist/generators/task/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 `TASK_NAME`, `TASK_VERSION`, or `TASK_TRIGGER` in the environment to override the defaults exposed by the starter task.
+
+`<%= projectName %>:dev` uses `@swc-node/register` so SST can proxy remote task invocations back to the same local command during `sst dev`.
+
+## Container Workflow
+
+- `pnpm nx run <%= projectName %>:docker-build`
+- image build runs the workspace install plus `pnpm nx run <%= projectName %>:build`
+- run the image with `docker run --rm -e TASK_TRIGGER=schedule <%= projectName %>` to exercise the starter command path
+- `infra/task.ts` keeps the SST `Task` image path, linked-resource surface, and local proxy command aligned
+
+## Next Steps
+
+- replace the starter task body with app-specific batch or worker logic
+- import `register<%= className %>Task` into the owning app group's `infra/` entrypoint when the workload is ready to deploy

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

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

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

@@ -0,0 +1,35 @@
+export interface Register<%= className %>TaskArgs {
+  cluster: sst.aws.Cluster;
+  environment?: Record<string, string>;
+  link?: any[];
+}
+
+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-typescript/package.json.template

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

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

@@ -0,0 +1,6 @@
+export {
+  createTaskResult,
+  formatLogEvent,
+  readTaskConfig,
+  runTask,
+} from './task.js';