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

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/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-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';

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

@@ -0,0 +1,45 @@
+import { formatLogEvent, readTaskConfig, runTask, type TaskInput } from './task.js';
+
+function readTaskInput(env: NodeJS.ProcessEnv = process.env): TaskInput {
+  const trigger = env.TASK_TRIGGER?.trim();
+
+  return {
+    trigger: trigger && trigger.length > 0 ? trigger : 'manual',
+  };
+}
+
+async function main() {
+  const config = readTaskConfig();
+  const input = readTaskInput();
+
+  console.log(
+    formatLogEvent(config, 'task.started', {
+      trigger: input.trigger,
+    })
+  );
+
+  const result = await runTask(config, input);
+
+  console.log(
+    formatLogEvent(config, 'task.completed', {
+      status: result.status,
+      trigger: result.trigger,
+    })
+  );
+
+  console.log(JSON.stringify(result));
+}
+
+void main().catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : 'Unknown task failure';
+
+  console.error(
+    JSON.stringify({
+      level: 'error',
+      message: 'task.failed',
+      error: message,
+    })
+  );
+
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { createTaskResult, formatLogEvent, readTaskConfig, runTask } from './task.js';
+
+describe('task helpers', () => {
+  it('falls back to task defaults', () => {
+    expect(readTaskConfig({})).toEqual({
+      taskName: '<%= className %>Task',
+      version: '0.0.1',
+    });
+  });
+
+  it('builds a stable task result', () => {
+    expect(
+      createTaskResult(
+        {
+          taskName: '<%= className %>Task',
+          version: '1.2.3',
+        },
+        { trigger: 'schedule' }
+      )
+    ).toEqual({
+      status: 'ok',
+      task: '<%= className %>Task',
+      trigger: 'schedule',
+      version: '1.2.3',
+    });
+  });
+
+  it('formats structured log output', () => {
+    expect(
+      formatLogEvent(
+        {
+          taskName: '<%= className %>Task',
+          version: '1.2.3',
+        },
+        'task.started',
+        { trigger: 'manual' }
+      )
+    ).toBe(
+      JSON.stringify({
+        level: 'info',
+        message: 'task.started',
+        task: '<%= className %>Task',
+        version: '1.2.3',
+        trigger: 'manual',
+      })
+    );
+  });
+
+  it('runs the starter task', async () => {
+    await expect(
+      runTask(
+        {
+          taskName: '<%= className %>Task',
+          version: '1.2.3',
+        },
+        { trigger: 'queue' }
+      )
+    ).resolves.toEqual({
+      status: 'ok',
+      task: '<%= className %>Task',
+      trigger: 'queue',
+      version: '1.2.3',
+    });
+  });
+});

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

@@ -0,0 +1,71 @@
+export interface TaskConfig {
+  taskName: string;
+  version: string;
+}
+
+export interface TaskInput {
+  trigger: string;
+}
+
+export interface TaskResult {
+  status: 'ok';
+  task: string;
+  trigger: string;
+  version: string;
+}
+
+export interface LogContext {
+  [key: string]: string | number | boolean | null;
+}
+
+const DEFAULT_TASK_NAME = '<%= className %>Task';
+const DEFAULT_TASK_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 readTaskConfig(env: NodeJS.ProcessEnv = process.env): TaskConfig {
+  return {
+    taskName: readOptionalEnv(env, 'TASK_NAME', DEFAULT_TASK_NAME),
+    version: readOptionalEnv(env, 'TASK_VERSION', DEFAULT_TASK_VERSION),
+  };
+}
+
+export function createTaskResult(
+  config: TaskConfig,
+  input: TaskInput
+): TaskResult {
+  return {
+    status: 'ok',
+    task: config.taskName,
+    trigger: input.trigger,
+    version: config.version,
+  };
+}
+
+export async function runTask(
+  config: TaskConfig,
+  input: TaskInput
+): Promise<TaskResult> {
+  return createTaskResult(config, input);
+}
+
+export function formatLogEvent(
+  config: TaskConfig,
+  message: string,
+  context: LogContext = {}
+): string {
+  return JSON.stringify({
+    level: 'info',
+    message,
+    task: config.taskName,
+    version: config.version,
+    ...context,
+  });
+}

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

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "tsBuildInfoFile": "./dist/tsconfig.app.tsbuildinfo"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.spec.ts"]
+}

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

@@ -0,0 +1,19 @@
+{
+  "extends": "<%= offsetFromRoot %>tsconfig.base.json",
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "ES2022",
+    "types": ["node", "vitest/globals"]
+  },
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "noEmit": true,
+    "tsBuildInfoFile": "./dist/tsconfig.spec.tsbuildinfo"
+  },
+  "include": ["src/**/*.spec.ts", "src/**/*.test.ts"]
+}

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

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: true,
+    include: ['src/**/*.spec.ts'],
+  },
+});

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

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

package/dist/generators/task/schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "Task",
+  "title": "Generate an EBK container task",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Name for the task within the app group.",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "What name should the task have?"
+    },
+    "app": {
+      "type": "string",
+      "description": "Owning Empire Builder Kit app-group name.",
+      "x-prompt": "Which app group should receive the task?"
+    },
+    "language": {
+      "type": "string",
+      "description": "Programming language for the task.",
+      "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/task/task.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../src/generators/task/task.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,IAAI,EACL,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AA+M/C,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,mBAAmB,iBA6C3E;AAED,eAAe,aAAa,CAAC"}