@better-openclaw/core 1.0.8 → 1.0.9

package/dist/version-manager.test.mjs

@@ -0,0 +1,102 @@
+import { n as describe, r as it, t as globalExpect } from "./vi.2VT5v0um-Qk6MgAnK.mjs";
+import { getAllServices, getServiceById } from "./services/registry.mjs";
+import { resolve } from "./resolver.mjs";
+import { checkCompatibility, getImageReference, getImageTag, pinImageTags } from "./version-manager.mjs";
+
+//#region src/version-manager.test.ts
+describe("getImageTag", () => {
+	it("returns the tag for a known service", () => {
+		const tag = getImageTag("redis");
+		globalExpect(tag).toBeDefined();
+		globalExpect(typeof tag).toBe("string");
+	});
+	it("returns undefined for an unknown service", () => {
+		globalExpect(getImageTag("nonexistent-service-xyz")).toBeUndefined();
+	});
+});
+describe("getImageReference", () => {
+	it("returns image:tag for a known service", () => {
+		const ref = getImageReference("redis");
+		globalExpect(ref).toBeDefined();
+		globalExpect(ref).toContain(":");
+		globalExpect(ref).toMatch(/^.+:.+$/);
+	});
+	it("returns undefined for an unknown service", () => {
+		globalExpect(getImageReference("nonexistent-service-xyz")).toBeUndefined();
+	});
+});
+describe("pinImageTags", () => {
+	it("pins image tags from the registry for all services", () => {
+		const resolved = resolve({
+			services: ["redis", "postgresql"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64"
+		});
+		const pinned = pinImageTags(resolved);
+		globalExpect(pinned.services).toHaveLength(resolved.services.length);
+		for (const svc of pinned.services) {
+			globalExpect(svc.definition.imageTag).toBeDefined();
+			globalExpect(typeof svc.definition.imageTag).toBe("string");
+			globalExpect(svc.definition.imageTag.length).toBeGreaterThan(0);
+		}
+	});
+	it("does not mutate the original resolved output", () => {
+		const resolved = resolve({
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64"
+		});
+		const originalTag = resolved.services[0]?.definition.imageTag;
+		pinImageTags(resolved);
+		globalExpect(resolved.services[0]?.definition.imageTag).toBe(originalTag);
+	});
+	it("preserves non-tag properties", () => {
+		const resolved = resolve({
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64"
+		});
+		const pinned = pinImageTags(resolved);
+		globalExpect(pinned.services[0]?.definition.id).toBe("redis");
+		globalExpect(pinned.services[0]?.definition.name).toBe("Redis");
+		globalExpect(pinned.estimatedMemoryMB).toBe(resolved.estimatedMemoryMB);
+	});
+});
+describe("checkCompatibility", () => {
+	it("warns when Redis and Valkey are both selected", () => {
+		const all = getAllServices();
+		const redis = all.find((s) => s.id === "redis");
+		const valkey = all.find((s) => s.id === "valkey");
+		if (redis && valkey) globalExpect(checkCompatibility([redis, valkey]).some((w) => w.message.includes("Redis") && w.message.includes("Valkey"))).toBe(true);
+	});
+	it("warns when Caddy and Traefik are both selected", () => {
+		const all = getAllServices();
+		const caddy = all.find((s) => s.id === "caddy");
+		const traefik = all.find((s) => s.id === "traefik");
+		if (caddy && traefik) globalExpect(checkCompatibility([caddy, traefik]).some((w) => w.message.includes("Caddy") && w.message.includes("Traefik"))).toBe(true);
+	});
+	it("warns about multiple vector databases", () => {
+		const all = getAllServices();
+		const qdrant = all.find((s) => s.id === "qdrant");
+		const chromadb = all.find((s) => s.id === "chromadb");
+		if (qdrant && chromadb) globalExpect(checkCompatibility([qdrant, chromadb]).some((w) => w.message.includes("vector database"))).toBe(true);
+	});
+	it("warns about GPU services", () => {
+		const gpuService = getAllServices().find((s) => s.gpuRequired);
+		if (gpuService) globalExpect(checkCompatibility([gpuService]).some((w) => w.message.includes("GPU"))).toBe(true);
+	});
+	it("returns no warnings for a single non-conflicting service", () => {
+		const redis = getServiceById("redis");
+		if (redis) globalExpect(checkCompatibility([redis]).filter((w) => w.type === "compatibility" && !w.message.includes("GPU"))).toHaveLength(0);
+	});
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=version-manager.test.mjs.map

package/dist/version-manager.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-manager.test.mjs","names":[],"sources":["../src/version-manager.test.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\";\nimport { resolve } from \"./resolver.js\";\nimport { getAllServices, getServiceById } from \"./services/registry.js\";\nimport { checkCompatibility, getImageReference, getImageTag, pinImageTags } from \"./version-manager.js\";\n\ndescribe(\"getImageTag\", () => {\n\tit(\"returns the tag for a known service\", () => {\n\t\tconst tag = getImageTag(\"redis\");\n\t\texpect(tag).toBeDefined();\n\t\texpect(typeof tag).toBe(\"string\");\n\t});\n\n\tit(\"returns undefined for an unknown service\", () => {\n\t\texpect(getImageTag(\"nonexistent-service-xyz\")).toBeUndefined();\n\t});\n});\n\ndescribe(\"getImageReference\", () => {\n\tit(\"returns image:tag for a known service\", () => {\n\t\tconst ref = getImageReference(\"redis\");\n\t\texpect(ref).toBeDefined();\n\t\texpect(ref).toContain(\":\");\n\t\texpect(ref).toMatch(/^.+:.+$/);\n\t});\n\n\tit(\"returns undefined for an unknown service\", () => {\n\t\texpect(getImageReference(\"nonexistent-service-xyz\")).toBeUndefined();\n\t});\n});\n\ndescribe(\"pinImageTags\", () => {\n\tit(\"pins image tags from the registry for all services\", () => {\n\t\tconst resolved = resolve({\n\t\t\tservices: [\"redis\", \"postgresql\"],\n\t\t\tskillPacks: [],\n\t\t\tproxy: \"none\",\n\t\t\tgpu: false,\n\t\t\tplatform: \"linux/amd64\",\n\t\t});\n\n\t\tconst pinned = pinImageTags(resolved);\n\n\t\texpect(pinned.services).toHaveLength(resolved.services.length);\n\n\t\tfor (const svc of pinned.services) {\n\t\t\texpect(svc.definition.imageTag).toBeDefined();\n\t\t\texpect(typeof svc.definition.imageTag).toBe(\"string\");\n\t\t\texpect(svc.definition.imageTag.length).toBeGreaterThan(0);\n\t\t}\n\t});\n\n\tit(\"does not mutate the original resolved output\", () => {\n\t\tconst resolved = resolve({\n\t\t\tservices: [\"redis\"],\n\t\t\tskillPacks: [],\n\t\t\tproxy: \"none\",\n\t\t\tgpu: false,\n\t\t\tplatform: \"linux/amd64\",\n\t\t});\n\n\t\tconst originalTag = resolved.services[0]?.definition.imageTag;\n\t\tpinImageTags(resolved);\n\n\t\texpect(resolved.services[0]?.definition.imageTag).toBe(originalTag);\n\t});\n\n\tit(\"preserves non-tag properties\", () => {\n\t\tconst resolved = resolve({\n\t\t\tservices: [\"redis\"],\n\t\t\tskillPacks: [],\n\t\t\tproxy: \"none\",\n\t\t\tgpu: false,\n\t\t\tplatform: \"linux/amd64\",\n\t\t});\n\n\t\tconst pinned = pinImageTags(resolved);\n\t\texpect(pinned.services[0]?.definition.id).toBe(\"redis\");\n\t\texpect(pinned.services[0]?.definition.name).toBe(\"Redis\");\n\t\texpect(pinned.estimatedMemoryMB).toBe(resolved.estimatedMemoryMB);\n\t});\n});\n\ndescribe(\"checkCompatibility\", () => {\n\tit(\"warns when Redis and Valkey are both selected\", () => {\n\t\tconst all = getAllServices();\n\t\tconst redis = all.find((s) => s.id === \"redis\");\n\t\tconst valkey = all.find((s) => s.id === \"valkey\");\n\n\t\tif (redis && valkey) {\n\t\t\tconst warnings = checkCompatibility([redis, valkey]);\n\t\t\texpect(warnings.some((w) => w.message.includes(\"Redis\") && w.message.includes(\"Valkey\"))).toBe(true);\n\t\t}\n\t});\n\n\tit(\"warns when Caddy and Traefik are both selected\", () => {\n\t\tconst all = getAllServices();\n\t\tconst caddy = all.find((s) => s.id === \"caddy\");\n\t\tconst traefik = all.find((s) => s.id === \"traefik\");\n\n\t\tif (caddy && traefik) {\n\t\t\tconst warnings = checkCompatibility([caddy, traefik]);\n\t\t\texpect(warnings.some((w) => w.message.includes(\"Caddy\") && w.message.includes(\"Traefik\"))).toBe(true);\n\t\t}\n\t});\n\n\tit(\"warns about multiple vector databases\", () => {\n\t\tconst all = getAllServices();\n\t\tconst qdrant = all.find((s) => s.id === \"qdrant\");\n\t\tconst chromadb = all.find((s) => s.id === \"chromadb\");\n\n\t\tif (qdrant && chromadb) {\n\t\t\tconst warnings = checkCompatibility([qdrant, chromadb]);\n\t\t\texpect(warnings.some((w) => w.message.includes(\"vector database\"))).toBe(true);\n\t\t}\n\t});\n\n\tit(\"warns about GPU services\", () => {\n\t\tconst all = getAllServices();\n\t\tconst gpuService = all.find((s) => s.gpuRequired);\n\n\t\tif (gpuService) {\n\t\t\tconst warnings = checkCompatibility([gpuService]);\n\t\t\texpect(warnings.some((w) => w.message.includes(\"GPU\"))).toBe(true);\n\t\t}\n\t});\n\n\tit(\"returns no warnings for a single non-conflicting service\", () => {\n\t\tconst redis = getServiceById(\"redis\");\n\t\tif (redis) {\n\t\t\tconst warnings = checkCompatibility([redis]);\n\t\t\texpect(warnings.filter((w) => w.type === \"compatibility\" && !w.message.includes(\"GPU\"))).toHaveLength(0);\n\t\t}\n\t});\n});\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-openclaw/core",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "private": false,
   "description": "Core logic for better-openclaw: schemas, service registry, resolver, composer, validators and more",
   "packageManager": "pnpm@9.15.4",

package/src/__snapshots__/composer.snapshot.test.ts.snap

@@ -164,6 +164,8 @@ exports[`compose snapshot tests > devops preset (n8n + postgresql + redis + moni
       N8N_HOST: n8n
       N8N_PORT: "5678"
       N8N_WEBHOOK_URL: http://n8n:5678/
+      GRAFANA_HOST: grafana
+      GRAFANA_PORT: "3000"
     volumes:
       - \${OPENCLAW_CONFIG_DIR:-./openclaw/config}:/home/node/.openclaw
       - \${OPENCLAW_WORKSPACE_DIR:-./openclaw/workspace}:/home/node/.openclaw/workspace
@@ -382,6 +384,8 @@ exports[`compose snapshot tests > full preset (many services) 1`] = `
       BROWSERLESS_HOST: browserless
       BROWSERLESS_PORT: "3000"
       BROWSERLESS_TOKEN: \${BROWSERLESS_TOKEN}
+      CADDY_HOST: caddy
+      CADDY_HTTP_PORT: "80"
       FFMPEG_SHARED_DIR: /home/node/.openclaw/workspace/media
       GOTIFY_HOST: gotify
       GOTIFY_PORT: "8080"
@@ -410,6 +414,8 @@ exports[`compose snapshot tests > full preset (many services) 1`] = `
       N8N_HOST: n8n
       N8N_PORT: "5678"
       N8N_WEBHOOK_URL: http://n8n:5678/
+      GRAFANA_HOST: grafana
+      GRAFANA_PORT: "3000"
     volumes:
       - \${OPENCLAW_CONFIG_DIR:-./openclaw/config}:/home/node/.openclaw
       - \${OPENCLAW_WORKSPACE_DIR:-./openclaw/workspace}:/home/node/.openclaw/workspace
@@ -433,7 +439,7 @@ exports[`compose snapshot tests > full preset (many services) 1`] = `
       browserless:
         condition: service_healthy
       caddy:
-        condition: service_started
+        condition: service_healthy
       meilisearch:
         condition: service_healthy
       minio:
@@ -474,6 +480,14 @@ exports[`compose snapshot tests > full preset (many services) 1`] = `
     volumes:
       - caddy-data:/data
       - caddy-config:/config
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - wget -q --spider http://localhost:80 || exit 1
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s
     restart: unless-stopped
     networks:
       - openclaw-network

package/src/bare-metal-partition.ts

@@ -7,6 +7,7 @@ export function platformToNativePlatform(platform: Platform): NativePlatform {
 	if (platform.startsWith("linux/")) return "linux";
 	if (platform.startsWith("windows/")) return "windows";
 	if (platform.startsWith("macos/")) return "macos";
+	console.warn(`Unknown platform prefix in "${platform}", defaulting to linux`);
 	return "linux";
 }
 

package/src/composer.ts

@@ -100,6 +100,12 @@ function buildGatewayServices(
 		],
 	};
 
+	// Traefik labels for the gateway
+	const gwTraefikLabels = options.traefikLabels?.get("openclaw-gateway");
+	if (gwTraefikLabels) {
+		gateway.labels = gwTraefikLabels;
+	}
+
 	if (options.bareMetalNativeHost) {
 		gateway.extra_hosts = ["host.docker.internal:host-gateway"];
 	}
@@ -198,7 +204,22 @@ function buildCompanionService(
 
 	if (def.command) svc.command = def.command;
 	if (def.entrypoint) svc.entrypoint = def.entrypoint;
-	if (def.labels && Object.keys(def.labels).length > 0) svc.labels = def.labels;
+
+	// Labels: merge static definition labels with dynamic Traefik labels
+	const mergedLabels: Record<string, string> = {};
+	if (def.labels) Object.assign(mergedLabels, def.labels);
+	const traefikLabels = options.traefikLabels?.get(def.id);
+	if (traefikLabels) Object.assign(mergedLabels, traefikLabels);
+	if (Object.keys(mergedLabels).length > 0) svc.labels = mergedLabels;
+
+	// Traefik: bind-mount static config and Docker socket
+	if (def.id === "traefik" && options.traefikLabels) {
+		if (!svc.volumes) svc.volumes = [];
+		(svc.volumes as string[]).push(
+			"./traefik/traefik.yml:/etc/traefik/traefik.yml:ro",
+			"/var/run/docker.sock:/var/run/docker.sock:ro",
+		);
+	}
 
 	let deploy: Record<string, unknown> | undefined;
 	if (def.deploy) {

package/src/errors.ts

@@ -0,0 +1,23 @@
+/**
+ * Typed error classes for stack generation.
+ */
+
+/** Thrown when the resolved stack configuration is invalid (e.g. conflicts). */
+export class StackConfigError extends Error {
+	readonly code = "STACK_CONFIG_ERROR" as const;
+
+	constructor(message: string) {
+		super(message);
+		this.name = "StackConfigError";
+	}
+}
+
+/** Thrown when post-generation validation fails. */
+export class ValidationError extends Error {
+	readonly code = "VALIDATION_ERROR" as const;
+
+	constructor(message: string) {
+		super(message);
+		this.name = "ValidationError";
+	}
+}

package/src/generate.ts

@@ -7,6 +7,7 @@ import { composeMultiFile } from "./composer.js";
 import { generateBareMetalInstall } from "./generators/bare-metal-install.js";
 import { generateCaddyfile } from "./generators/caddy.js";
 import { generateEnvFiles } from "./generators/env.js";
+import { generateTraefikConfig } from "./generators/traefik.js";
 import { generateGrafanaConfig, generateGrafanaDashboard } from "./generators/grafana.js";
 import { generateN8nWorkflows } from "./generators/n8n-workflows.js";
 import { generateNativeInstallScripts } from "./generators/native-services.js";
@@ -15,6 +16,7 @@ import { generatePrometheusConfig } from "./generators/prometheus.js";
 import { generateReadme } from "./generators/readme.js";
 import { generateScripts } from "./generators/scripts.js";
 import { generateSkillFiles } from "./generators/skills.js";
+import { migrateConfig } from "./migrations.js";
 import { resolve } from "./resolver.js";
 import type {
 	GeneratedFiles,
@@ -23,6 +25,7 @@ import type {
 	Platform,
 	ResolverInput,
 } from "./types.js";
+import { StackConfigError, ValidationError } from "./errors.js";
 import { validate } from "./validator.js";
 
 /** Resolver/compose only support linux image platforms; normalize for bare-metal (windows/macos). */
@@ -35,7 +38,10 @@ function getComposePlatform(platform: Platform): "linux/amd64" | "linux/arm64" {
  * Main orchestration function: takes generation input, resolves dependencies,
  * generates all files, validates, and returns the complete file tree.
  */
-export function generate(input: GenerationInput): GenerationResult {
+export function generate(rawInput: GenerationInput): GenerationResult {
+	// Apply config migrations if needed
+	const input = migrateConfig(rawInput as Record<string, unknown>) as GenerationInput;
+
 	const composePlatform = getComposePlatform(input.platform);
 
 	// 1. Resolve dependencies
@@ -50,7 +56,7 @@ export function generate(input: GenerationInput): GenerationResult {
 	const resolved = resolve(resolverInput);
 
 	if (!resolved.isValid) {
-		throw new Error(
+		throw new StackConfigError(
 			`Invalid stack configuration: ${resolved.errors.map((e) => e.message).join("; ")}`,
 		);
 	}
@@ -72,6 +78,12 @@ export function generate(input: GenerationInput): GenerationResult {
 	}
 
 	// 2. Generate Docker Compose YAML (multi-file)
+	// Compute Traefik labels before composing (labels get injected into docker-compose services)
+	let traefikOutput: ReturnType<typeof generateTraefikConfig> | undefined;
+	if (input.proxy === "traefik" && input.domain) {
+		traefikOutput = generateTraefikConfig(resolvedForCompose, input.domain);
+	}
+
 	const composeOptions = {
 		projectName: input.projectName,
 		proxy: input.proxy,
@@ -81,6 +93,7 @@ export function generate(input: GenerationInput): GenerationResult {
 		deployment: input.deployment,
 		openclawVersion: input.openclawVersion,
 		bareMetalNativeHost: isBareMetal && nativeIds.size > 0,
+		traefikLabels: traefikOutput?.serviceLabels,
 	};
 	const composeResult = composeMultiFile(resolvedForCompose, composeOptions);
 
@@ -90,7 +103,7 @@ export function generate(input: GenerationInput): GenerationResult {
 		generateSecrets: input.generateSecrets,
 	});
 	if (!validation.valid) {
-		throw new Error(`Validation failed: ${validation.errors.map((e) => e.message).join("; ")}`);
+		throw new ValidationError(`Validation failed: ${validation.errors.map((e) => e.message).join("; ")}`);
 	}
 
 	// 4. Generate all files
@@ -158,6 +171,11 @@ export function generate(input: GenerationInput): GenerationResult {
 		files["caddy/Caddyfile"] = generateCaddyfile(resolved, input.domain);
 	}
 
+	// Traefik config (labels are already injected via composeOptions.traefikLabels)
+	if (traefikOutput) {
+		files["traefik/traefik.yml"] = traefikOutput.staticConfig;
+	}
+
 	// Prometheus config
 	const hasPrometheus = resolved.services.some((s) => s.definition.id === "prometheus");
 	if (hasPrometheus) {
@@ -223,7 +241,7 @@ export function generate(input: GenerationInput): GenerationResult {
 	};
 }
 
-function generateServicesDoc(resolved: import("./types.js").ResolverOutput): string {
+export function generateServicesDoc(resolved: import("./types.js").ResolverOutput): string {
 	const lines: string[] = [
 		"# Service Reference",
 		"",

package/src/generators/traefik.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { generateTraefikConfig } from "./traefik.js";
+import type { ResolverOutput } from "../types.js";
+import { resolve } from "../resolver.js";
+
+function resolveWith(services: string[]): ResolverOutput {
+	return resolve({ services, skillPacks: [], proxy: "traefik", gpu: false });
+}
+
+describe("generateTraefikConfig", () => {
+	const domain = "example.com";
+
+	it("generates static config with domain email and entrypoints", () => {
+		const resolved = resolveWith(["redis"]);
+		const { staticConfig } = generateTraefikConfig(resolved, domain);
+
+		expect(staticConfig).toContain("admin@example.com");
+		expect(staticConfig).toContain('address: ":80"');
+		expect(staticConfig).toContain('address: ":443"');
+		expect(staticConfig).toContain("exposedByDefault: false");
+		expect(staticConfig).toContain("openclaw-network");
+	});
+
+	it("generates labels for services with exposed ports", () => {
+		const resolved = resolveWith(["redis"]);
+		const { serviceLabels } = generateTraefikConfig(resolved, domain);
+
+		const redisLabels = serviceLabels.get("redis");
+		expect(redisLabels).toBeDefined();
+		expect(redisLabels!["traefik.enable"]).toBe("true");
+		expect(redisLabels!["traefik.http.routers.redis.rule"]).toBe(
+			"Host(`redis.example.com`)",
+		);
+		expect(redisLabels!["traefik.http.routers.redis.entrypoints"]).toBe("websecure");
+		expect(redisLabels!["traefik.http.routers.redis.tls.certresolver"]).toBe("letsencrypt");
+		expect(redisLabels!["traefik.http.services.redis.loadbalancer.server.port"]).toBe("6379");
+	});
+
+	it("generates HTTP to HTTPS redirect labels", () => {
+		const resolved = resolveWith(["redis"]);
+		const { serviceLabels } = generateTraefikConfig(resolved, domain);
+
+		const redisLabels = serviceLabels.get("redis")!;
+		expect(redisLabels["traefik.http.routers.redis-http.entrypoints"]).toBe("web");
+		expect(redisLabels["traefik.http.routers.redis-http.middlewares"]).toBe(
+			"redirect-to-https",
+		);
+	});
+
+	it("assigns root domain to gateway", () => {
+		const resolved = resolveWith(["redis"]);
+		const { serviceLabels } = generateTraefikConfig(resolved, domain);
+
+		const gwLabels = serviceLabels.get("openclaw-gateway");
+		expect(gwLabels).toBeDefined();
+		expect(gwLabels!["traefik.http.routers.gateway.rule"]).toBe(
+			"Host(`example.com`)",
+		);
+		expect(gwLabels!["traefik.http.services.gateway.loadbalancer.server.port"]).toBe("18789");
+	});
+
+	it("adds global redirect middleware on traefik service", () => {
+		const resolved = resolveWith(["redis"]);
+		const { serviceLabels } = generateTraefikConfig(resolved, domain);
+
+		const traefikLabels = serviceLabels.get("traefik");
+		expect(traefikLabels).toBeDefined();
+		expect(
+			traefikLabels!["traefik.http.middlewares.redirect-to-https.redirectscheme.scheme"],
+		).toBe("https");
+		expect(
+			traefikLabels!["traefik.http.middlewares.redirect-to-https.redirectscheme.permanent"],
+		).toBe("true");
+	});
+
+	it("skips proxy services and services without exposed ports", () => {
+		const resolved = resolveWith(["redis", "ffmpeg"]);
+		const { serviceLabels } = generateTraefikConfig(resolved, domain);
+
+		// ffmpeg has no exposed ports
+		expect(serviceLabels.has("ffmpeg")).toBe(false);
+		// traefik itself is handled separately (not as a regular service)
+		expect(serviceLabels.get("traefik")!["traefik.http.routers.traefik.rule"]).toBeUndefined();
+	});
+
+	it("sanitizes service names with hyphens in router names", () => {
+		const resolved = resolveWith(["open-webui"]);
+		const { serviceLabels } = generateTraefikConfig(resolved, domain);
+
+		const labels = serviceLabels.get("open-webui");
+		expect(labels).toBeDefined();
+		// Router name has hyphens removed
+		expect(labels!["traefik.http.routers.openwebui.rule"]).toBe(
+			"Host(`open-webui.example.com`)",
+		);
+	});
+});

package/src/generators/traefik.ts

@@ -0,0 +1,104 @@
+import type { ResolverOutput } from "../types.js";
+
+export interface TraefikGeneratorOutput {
+	staticConfig: string;
+	serviceLabels: Map<string, Record<string, string>>;
+}
+
+/**
+ * Generates Traefik configuration: a static config YAML file and per-service
+ * Docker labels for automatic service discovery and reverse proxy routing.
+ *
+ * @param resolved - The resolved service configuration
+ * @param domain - The main domain for routing (e.g. "example.com")
+ * @returns Static config content and a map of serviceId → Docker labels
+ */
+export function generateTraefikConfig(
+	resolved: ResolverOutput,
+	domain: string,
+): TraefikGeneratorOutput {
+	const staticConfig = generateStaticConfig(domain);
+	const serviceLabels = new Map<string, Record<string, string>>();
+
+	// Per-service labels for exposed ports
+	for (const { definition } of resolved.services) {
+		if (definition.id === "traefik" || definition.id === "caddy") continue;
+
+		const exposedPorts = definition.ports.filter((p) => p.exposed);
+		if (exposedPorts.length === 0) continue;
+
+		const primaryPort = exposedPorts[0]!;
+		const routerName = definition.id.replace(/-/g, "");
+
+		const labels: Record<string, string> = {
+			"traefik.enable": "true",
+			// HTTPS router
+			[`traefik.http.routers.${routerName}.rule`]: `Host(\`${definition.id}.${domain}\`)`,
+			[`traefik.http.routers.${routerName}.entrypoints`]: "websecure",
+			[`traefik.http.routers.${routerName}.tls.certresolver`]: "letsencrypt",
+			[`traefik.http.services.${routerName}.loadbalancer.server.port`]: String(
+				primaryPort.container,
+			),
+			// HTTP → HTTPS redirect
+			[`traefik.http.routers.${routerName}-http.rule`]: `Host(\`${definition.id}.${domain}\`)`,
+			[`traefik.http.routers.${routerName}-http.entrypoints`]: "web",
+			[`traefik.http.routers.${routerName}-http.middlewares`]: "redirect-to-https",
+		};
+
+		serviceLabels.set(definition.id, labels);
+	}
+
+	// Gateway gets the root domain
+	serviceLabels.set("openclaw-gateway", {
+		"traefik.enable": "true",
+		"traefik.http.routers.gateway.rule": `Host(\`${domain}\`)`,
+		"traefik.http.routers.gateway.entrypoints": "websecure",
+		"traefik.http.routers.gateway.tls.certresolver": "letsencrypt",
+		"traefik.http.services.gateway.loadbalancer.server.port": "18789",
+		"traefik.http.routers.gateway-http.rule": `Host(\`${domain}\`)`,
+		"traefik.http.routers.gateway-http.entrypoints": "web",
+		"traefik.http.routers.gateway-http.middlewares": "redirect-to-https",
+	});
+
+	// Global redirect middleware on the Traefik service itself
+	serviceLabels.set("traefik", {
+		"traefik.enable": "true",
+		"traefik.http.middlewares.redirect-to-https.redirectscheme.scheme": "https",
+		"traefik.http.middlewares.redirect-to-https.redirectscheme.permanent": "true",
+	});
+
+	return { staticConfig, serviceLabels };
+}
+
+function generateStaticConfig(domain: string): string {
+	return `# Traefik Static Configuration — Auto-generated by OpenClaw
+# Domain: ${domain}
+
+api:
+  dashboard: true
+  insecure: true
+
+entryPoints:
+  web:
+    address: ":80"
+  websecure:
+    address: ":443"
+
+providers:
+  docker:
+    endpoint: "unix:///var/run/docker.sock"
+    exposedByDefault: false
+    network: openclaw-network
+
+certificatesResolvers:
+  letsencrypt:
+    acme:
+      email: admin@${domain}
+      storage: /letsencrypt/acme.json
+      httpChallenge:
+        entryPoint: web
+
+log:
+  level: INFO
+`;
+}

package/src/index.ts

@@ -8,7 +8,7 @@ export {
 } from "./bare-metal-partition.js";
 export type { ComposeResult } from "./composer.js";
 export { compose, composeMultiFile } from "./composer.js";
-export { generate } from "./generate.js";
+export { generate, generateServicesDoc } from "./generate.js";
 export { generateCaddyfile } from "./generators/caddy.js";
 export type { EnvVarGroup } from "./generators/env.js";
 export { generateEnvFiles, getStructuredEnvVars } from "./generators/env.js";
@@ -109,6 +109,12 @@ export type {
 export { SERVICE_CATEGORIES } from "./types.js";
 export { validate } from "./validator.js";
 
+// ─── Config Migrations ──────────────────────────────────────────────────────
+export { migrateConfig, needsMigration, CURRENT_CONFIG_VERSION } from "./migrations.js";
+
+// ─── Errors ─────────────────────────────────────────────────────────────────
+export { StackConfigError, ValidationError } from "./errors.js";
+
 // ─── Version Manager ────────────────────────────────────────────────────────
 export {
 	checkCompatibility,

package/src/migrations.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { migrateConfig, needsMigration, CURRENT_CONFIG_VERSION } from "./migrations.js";
+
+describe("config migrations", () => {
+	it("migrates v1 config to current version", () => {
+		const v1 = { projectName: "test", services: ["redis"], skillPacks: [] };
+		const result = migrateConfig(v1);
+		expect(result.configVersion).toBe(CURRENT_CONFIG_VERSION);
+		expect(result.deploymentType).toBe("docker");
+	});
+
+	it("preserves existing deploymentType during migration", () => {
+		const v1 = { configVersion: 1, deploymentType: "bare-metal" };
+		const result = migrateConfig(v1);
+		expect(result.deploymentType).toBe("bare-metal");
+	});
+
+	it("passes through current version unchanged", () => {
+		const current = { configVersion: CURRENT_CONFIG_VERSION, projectName: "test" };
+		const result = migrateConfig(current);
+		expect(result).toEqual(current);
+	});
+
+	it("needsMigration returns true for old configs", () => {
+		expect(needsMigration({ configVersion: 1 })).toBe(true);
+		expect(needsMigration({})).toBe(true); // no version = v1
+	});
+
+	it("needsMigration returns false for current configs", () => {
+		expect(needsMigration({ configVersion: CURRENT_CONFIG_VERSION })).toBe(false);
+	});
+
+	it("throws for unknown version with no migration path", () => {
+		expect(() => migrateConfig({ configVersion: 99 })).toThrow("No migration path");
+	});
+});

package/src/migrations.ts

@@ -0,0 +1,49 @@
+import type { GenerationInput } from "./types.js";
+
+export const CURRENT_CONFIG_VERSION = 2;
+
+type MigrationFn = (input: Record<string, unknown>) => Record<string, unknown>;
+
+const migrations: Record<number, MigrationFn> = {
+	// v1 → v2: ensure deploymentType field exists (defaulting to "docker")
+	1: (input) => ({
+		...input,
+		configVersion: 2,
+		deploymentType: (input.deploymentType as string) ?? "docker",
+	}),
+};
+
+/**
+ * Applies sequential migrations to bring a config from its current version
+ * to CURRENT_CONFIG_VERSION. Returns the config unchanged if already current.
+ */
+export function migrateConfig(input: Record<string, unknown>): Record<string, unknown> {
+	let version = (input.configVersion as number) ?? 1;
+
+	if (version > CURRENT_CONFIG_VERSION) {
+		throw new Error(
+			`No migration path from config version ${version}`,
+		);
+	}
+
+	let current = { ...input };
+
+	while (version < CURRENT_CONFIG_VERSION) {
+		const migrationFn = migrations[version];
+		if (!migrationFn) {
+			throw new Error(`No migration path from config version ${version}`);
+		}
+		current = migrationFn(current);
+		version++;
+	}
+
+	return current;
+}
+
+/**
+ * Returns true if the config needs migration to the current version.
+ */
+export function needsMigration(input: Record<string, unknown>): boolean {
+	const version = (input.configVersion as number) ?? 1;
+	return version < CURRENT_CONFIG_VERSION;
+}