@better-openclaw/core 1.0.0

package/src/generate.test.ts

@@ -0,0 +1,349 @@
+import { describe, expect, it } from "vitest";
+import { parse } from "yaml";
+import { generate } from "./generate.js";
+
+describe("generate (end-to-end)", () => {
+	it("generates a minimal stack (redis only)", () => {
+		const result = generate({
+			projectName: "test-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		// Core files must be present
+		expect(result.files).toHaveProperty("docker-compose.yml");
+		expect(result.files).toHaveProperty(".env.example");
+		expect(result.files).toHaveProperty(".env");
+		expect(result.files).toHaveProperty("README.md");
+
+		// docker-compose.yml must be valid YAML
+		const composed = parse(result.files["docker-compose.yml"]!);
+		expect(composed).toHaveProperty("services");
+
+		// .env.example should reference REDIS_PASSWORD
+		expect(result.files[".env.example"]).toContain("REDIS_PASSWORD");
+
+		// README should mention the project name
+		expect(result.files["README.md"]).toContain("test-stack");
+
+		// At least one service resolved
+		expect(result.metadata.serviceCount).toBeGreaterThanOrEqual(1);
+	});
+
+	it("generates research-agent stack from skill pack", () => {
+		const result = generate({
+			projectName: "research-stack",
+			services: [],
+			skillPacks: ["research-agent"],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		// Skill SKILL.md files for each skill in the research-agent pack
+		expect(result.files).toHaveProperty("openclaw/workspace/skills/qdrant-memory/SKILL.md");
+		expect(result.files).toHaveProperty("openclaw/workspace/skills/searxng-search/SKILL.md");
+		expect(result.files).toHaveProperty("openclaw/workspace/skills/browserless-browse/SKILL.md");
+
+		// docker-compose.yml should contain the expected services
+		const composed = parse(result.files["docker-compose.yml"]!);
+		expect(composed.services).toHaveProperty("qdrant");
+		expect(composed.services).toHaveProperty("searxng");
+		expect(composed.services).toHaveProperty("browserless");
+	});
+
+	it("generates full preset stack", () => {
+		const fullServices = [
+			"redis",
+			"postgresql",
+			"qdrant",
+			"n8n",
+			"ffmpeg",
+			"remotion",
+			"minio",
+			"caddy",
+			"browserless",
+			"searxng",
+			"meilisearch",
+			"uptime-kuma",
+			"grafana",
+			"prometheus",
+			"ollama",
+			"whisper",
+			"gotify",
+		];
+
+		const result = generate({
+			projectName: "full-stack",
+			services: fullServices,
+			skillPacks: [
+				"video-creator",
+				"research-agent",
+				"social-media",
+				"dev-ops",
+				"knowledge-base",
+				"local-ai",
+			],
+			proxy: "caddy",
+			domain: "example.com",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		// Should have many files
+		const fileCount = Object.keys(result.files).length;
+		expect(fileCount).toBeGreaterThan(10);
+
+		// Should include the start script
+		expect(result.files).toHaveProperty("scripts/start.sh");
+
+		// Should not throw (it already didn't if we got here)
+		expect(result.metadata.serviceCount).toBeGreaterThan(5);
+	});
+
+	it("generates caddy config when proxy is caddy", () => {
+		const result = generate({
+			projectName: "caddy-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "caddy",
+			domain: "example.com",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		expect(result.files).toHaveProperty("caddy/Caddyfile");
+		expect(result.files["caddy/Caddyfile"]!.length).toBeGreaterThan(0);
+	});
+
+	it("generates prometheus config when monitoring enabled", () => {
+		const result = generate({
+			projectName: "monitored-stack",
+			services: [],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+			monitoring: true,
+		});
+
+		expect(result.files).toHaveProperty("prometheus/prometheus.yml");
+		// Verify it's valid YAML
+		const promConfig = parse(result.files["prometheus/prometheus.yml"]!);
+		expect(promConfig).toBeDefined();
+	});
+
+	it("generates La Suite Meet stack with all expected services", () => {
+		const lasuiteMeetServices = [
+			"postgresql",
+			"redis",
+			"livekit",
+			"lasuite-meet-backend",
+			"lasuite-meet-frontend",
+			"lasuite-meet-agents",
+		];
+		const result = generate({
+			projectName: "lasuite-meet-stack",
+			services: lasuiteMeetServices,
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		// Services may be split across main and profile compose files
+		const allServiceIds = new Set<string>();
+		for (const [filename, content] of Object.entries(result.files)) {
+			if (filename.endsWith(".yml") && content) {
+				const doc = parse(content);
+				if (doc?.services && typeof doc.services === "object") {
+					for (const id of Object.keys(doc.services)) {
+						allServiceIds.add(id);
+					}
+				}
+			}
+		}
+		for (const id of lasuiteMeetServices) {
+			expect(allServiceIds.has(id), `missing service ${id}`).toBe(true);
+		}
+		expect(result.metadata.serviceCount).toBe(lasuiteMeetServices.length);
+	});
+
+	it("generates bare-metal installer for Windows (install.ps1)", () => {
+		const result = generate({
+			projectName: "win-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "windows/amd64",
+			deployment: "local",
+			deploymentType: "bare-metal",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+		expect(result.files).toHaveProperty("install.ps1");
+		expect(result.files["install.ps1"]).toContain("docker compose");
+		expect(result.files["install.ps1"]).toContain("PowerShell");
+	});
+
+	it("generates bare-metal installer for Linux/macOS (install.sh)", () => {
+		const result = generate({
+			projectName: "linux-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			deploymentType: "bare-metal",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+		expect(result.files).toHaveProperty("install.sh");
+		expect(result.files["install.sh"]).toContain("docker");
+		expect(result.files["install.sh"]).toContain("compose");
+	});
+
+	it("bare-metal with redis on Linux: native script, compose excludes redis, gateway has extra_hosts", () => {
+		const result = generate({
+			projectName: "bare-metal-redis",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			deploymentType: "bare-metal",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		// Native install script for Linux
+		expect(result.files).toHaveProperty("native/install-linux.sh");
+		expect(result.files["native/install-linux.sh"]).toContain("redis");
+
+		// Docker compose must NOT include redis (native); only gateway/openclaw
+		const composed = parse(result.files["docker-compose.yml"]!);
+		expect(composed.services).not.toHaveProperty("redis");
+		expect(composed.services).toHaveProperty("openclaw-gateway");
+
+		// Gateway must have extra_hosts for host.docker.internal
+		const gateway = composed.services["openclaw-gateway"];
+		expect(gateway).toBeDefined();
+		expect(gateway.extra_hosts).toBeDefined();
+		expect(
+			(gateway.extra_hosts as string[]).some(
+				(h: string) => h.includes("host.docker.internal") && h.includes("host-gateway"),
+			),
+		).toBe(true);
+
+		// .env should set REDIS_HOST to host.docker.internal for gateway to reach native Redis
+		expect(result.files[".env"]).toContain("REDIS_HOST=host.docker.internal");
+	});
+
+	it("throws on conflicting services", () => {
+		expect(() =>
+			generate({
+				projectName: "conflict-stack",
+				services: ["redis", "valkey"],
+				skillPacks: [],
+				proxy: "none",
+				gpu: false,
+				platform: "linux/amd64",
+				deployment: "local",
+				generateSecrets: true,
+				openclawVersion: "latest",
+			}),
+		).toThrow();
+	});
+
+	it("generates scripts directory", () => {
+		const result = generate({
+			projectName: "scripts-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		const expectedScripts = [
+			"scripts/start.sh",
+			"scripts/stop.sh",
+			"scripts/update.sh",
+			"scripts/backup.sh",
+			"scripts/status.sh",
+		];
+
+		for (const script of expectedScripts) {
+			expect(result.files).toHaveProperty(script);
+			expect(result.files[script]!.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("all generated .env.example vars have comments", () => {
+		const result = generate({
+			projectName: "env-comments-stack",
+			services: ["redis", "qdrant", "n8n"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+		});
+
+		const envExample = result.files[".env.example"]!;
+		const lines = envExample.split("\n");
+
+		// Walk through lines: every non-empty, non-comment KEY=VALUE line should
+		// have a preceding comment line (starting with #).
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i]!.trim();
+			if (line === "" || line.startsWith("#")) continue;
+
+			// This line looks like KEY=VALUE
+			if (line.includes("=")) {
+				// There must be a comment somewhere before it (look backwards for a # line)
+				let foundComment = false;
+				for (let j = i - 1; j >= 0; j--) {
+					const prev = lines[j]!.trim();
+					if (prev === "") continue; // skip blank lines
+					if (prev.startsWith("#")) {
+						foundComment = true;
+						break;
+					}
+					// Hit another non-comment, non-empty line — no comment found
+					break;
+				}
+				expect(foundComment).toBe(true);
+			}
+		}
+	});
+});

package/src/generate.ts

@@ -0,0 +1,259 @@
+import {
+	partitionBareMetal,
+	platformToNativePlatform,
+	resolvedWithOnlyServices,
+} from "./bare-metal-partition.js";
+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 { generateGrafanaConfig, generateGrafanaDashboard } from "./generators/grafana.js";
+import { generateN8nWorkflows } from "./generators/n8n-workflows.js";
+import { generateNativeInstallScripts } from "./generators/native-services.js";
+import { generatePostgresInit } from "./generators/postgres-init.js";
+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 { resolve } from "./resolver.js";
+import type {
+	GeneratedFiles,
+	GenerationInput,
+	GenerationResult,
+	Platform,
+	ResolverInput,
+} from "./types.js";
+import { validate } from "./validator.js";
+
+/** Resolver/compose only support linux image platforms; normalize for bare-metal (windows/macos). */
+function getComposePlatform(platform: Platform): "linux/amd64" | "linux/arm64" {
+	if (platform === "linux/amd64" || platform === "linux/arm64") return platform;
+	return "linux/amd64";
+}
+
+/**
+ * Main orchestration function: takes generation input, resolves dependencies,
+ * generates all files, validates, and returns the complete file tree.
+ */
+export function generate(input: GenerationInput): GenerationResult {
+	const composePlatform = getComposePlatform(input.platform);
+
+	// 1. Resolve dependencies
+	const resolverInput: ResolverInput = {
+		services: input.services,
+		skillPacks: input.skillPacks,
+		proxy: input.proxy,
+		gpu: input.gpu,
+		platform: composePlatform,
+		monitoring: input.monitoring,
+	};
+	const resolved = resolve(resolverInput);
+
+	if (!resolved.isValid) {
+		throw new Error(
+			`Invalid stack configuration: ${resolved.errors.map((e) => e.message).join("; ")}`,
+		);
+	}
+
+	const isBareMetal = input.deploymentType === "bare-metal";
+	let resolvedForCompose = resolved;
+	let nativeIds = new Set<string>();
+	let nativeServices: typeof resolved.services = [];
+	let dockerOnlyServices: typeof resolved.services = [];
+
+	if (isBareMetal) {
+		const partition = partitionBareMetal(resolved, input.platform);
+		nativeServices = partition.nativeServices;
+		dockerOnlyServices = partition.dockerOnlyServices;
+		nativeIds = partition.nativeIds;
+		if (nativeServices.length > 0) {
+			resolvedForCompose = resolvedWithOnlyServices(resolved, dockerOnlyServices);
+		}
+	}
+
+	// 2. Generate Docker Compose YAML (multi-file)
+	const composeOptions = {
+		projectName: input.projectName,
+		proxy: input.proxy,
+		domain: input.domain,
+		gpu: input.gpu,
+		platform: composePlatform,
+		deployment: input.deployment,
+		openclawVersion: input.openclawVersion,
+		bareMetalNativeHost: isBareMetal && nativeIds.size > 0,
+	};
+	const composeResult = composeMultiFile(resolvedForCompose, composeOptions);
+
+	// 3. Validate (using the base docker-compose.yml)
+	const validation = validate(resolvedForCompose, composeResult.files["docker-compose.yml"] ?? "", {
+		domain: input.domain,
+		generateSecrets: input.generateSecrets,
+	});
+	if (!validation.valid) {
+		throw new Error(`Validation failed: ${validation.errors.map((e) => e.message).join("; ")}`);
+	}
+
+	// 4. Generate all files
+	const files: GeneratedFiles = {};
+
+	// Docker Compose (multi-file output)
+	for (const [filename, content] of Object.entries(composeResult.files)) {
+		files[filename] = content;
+	}
+
+	// Environment files (when bare-metal with native services, host vars use host.docker.internal)
+	const envFiles = generateEnvFiles(resolved, {
+		generateSecrets: input.generateSecrets,
+		domain: input.domain,
+		openclawVersion: input.openclawVersion,
+		nativeServiceIds: isBareMetal ? nativeIds : undefined,
+	});
+	files[".env.example"] = envFiles.envExample;
+	files[".env"] = envFiles.env;
+
+	// .gitignore
+	files[".gitignore"] = [
+		".env",
+		".env.local",
+		".env.*.local",
+		"*.log",
+		"docker-compose.override.yml",
+	].join("\n");
+
+	// Skills
+	const skillFiles = generateSkillFiles(resolved);
+	for (const [path, content] of Object.entries(skillFiles)) {
+		files[path] = content;
+	}
+
+	// README
+	files["README.md"] = generateReadme(resolved, {
+		projectName: input.projectName,
+		domain: input.domain,
+		proxy: input.proxy,
+		deploymentType: input.deploymentType,
+		hasNativeServices: isBareMetal && nativeServices.length > 0,
+	});
+
+	// Scripts
+	const scripts = generateScripts();
+	for (const [path, content] of Object.entries(scripts)) {
+		files[path] = content;
+	}
+
+	// n8n workflows
+	const n8nWorkflows = generateN8nWorkflows(resolved);
+	for (const [path, content] of Object.entries(n8nWorkflows)) {
+		files[path] = content;
+	}
+
+	// PostgreSQL init script (creates per-service databases and users)
+	const postgresInit = generatePostgresInit(resolved);
+	if (postgresInit) {
+		files["postgres/init-databases.sh"] = postgresInit;
+	}
+
+	// Caddy config
+	if (input.proxy === "caddy" && input.domain) {
+		files["caddy/Caddyfile"] = generateCaddyfile(resolved, input.domain);
+	}
+
+	// Prometheus config
+	const hasPrometheus = resolved.services.some((s) => s.definition.id === "prometheus");
+	if (hasPrometheus) {
+		files["prometheus/prometheus.yml"] = generatePrometheusConfig(resolved);
+	}
+
+	// Grafana config
+	const hasGrafana = resolved.services.some((s) => s.definition.id === "grafana");
+	if (hasGrafana) {
+		const grafanaFiles = generateGrafanaConfig();
+		for (const [path, content] of Object.entries(grafanaFiles)) {
+			files[path] = content;
+		}
+		// Grafana dashboard
+		files["config/grafana/dashboards/openclaw-stack-overview.json"] = generateGrafanaDashboard();
+	}
+
+	// Docker Compose override (empty template)
+	files["docker-compose.override.yml"] = [
+		"# Local overrides for docker-compose.yml",
+		"# This file is gitignored — use it for personal port changes, extra volumes, etc.",
+		"services: {}",
+		"",
+	].join("\n");
+
+	// SERVICES.md documentation
+	files["docs/SERVICES.md"] = generateServicesDoc(resolved);
+
+	// Bare-metal: native install scripts + top-level installer
+	if (isBareMetal) {
+		if (nativeServices.length > 0) {
+			const nativePlatform = platformToNativePlatform(input.platform);
+			const nativeScripts = generateNativeInstallScripts({
+				nativeServices,
+				platform: nativePlatform,
+				projectName: input.projectName,
+			});
+			for (const [path, content] of Object.entries(nativeScripts)) {
+				files[path] = content;
+			}
+		}
+		const bareMetalFiles = generateBareMetalInstall({
+			platform: input.platform,
+			projectName: input.projectName,
+			hasNativeServices: nativeServices.length > 0,
+		});
+		for (const [path, content] of Object.entries(bareMetalFiles)) {
+			files[path] = content;
+		}
+	}
+
+	// 5. Calculate metadata
+	const skillCount = resolved.services.reduce((sum, s) => sum + s.definition.skills.length, 0);
+
+	return {
+		files,
+		metadata: {
+			serviceCount: resolved.services.length,
+			skillCount,
+			estimatedMemoryMB: resolved.estimatedMemoryMB,
+			generatedAt: new Date().toISOString(),
+		},
+	};
+}
+
+function generateServicesDoc(resolved: import("./types.js").ResolverOutput): string {
+	const lines: string[] = [
+		"# Service Reference",
+		"",
+		"This document describes all companion services in your OpenClaw stack.",
+		"",
+	];
+
+	for (const svc of resolved.services) {
+		const def = svc.definition;
+		lines.push(`## ${def.icon} ${def.name}`);
+		lines.push("");
+		lines.push(def.description);
+		lines.push("");
+		lines.push(`- **Image**: \`${def.image}:${def.imageTag}\``);
+		lines.push(`- **Category**: ${def.category}`);
+		lines.push(`- **Maturity**: ${def.maturity}`);
+		if (def.minMemoryMB) {
+			lines.push(`- **Min Memory**: ${def.minMemoryMB}MB`);
+		}
+		if (def.ports.length > 0) {
+			lines.push("- **Ports**:");
+			for (const p of def.ports) {
+				lines.push(
+					`  - \`${p.container}\` — ${p.description}${p.exposed ? "" : " (internal only)"}`,
+				);
+			}
+		}
+		lines.push(`- **Docs**: ${def.docsUrl}`);
+		lines.push("");
+	}
+
+	return lines.join("\n");
+}

package/src/generators/bare-metal-install.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { generateBareMetalInstall } from "./bare-metal-install.js";
+
+describe("generateBareMetalInstall", () => {
+	it("returns install.ps1 for windows/amd64", () => {
+		const result = generateBareMetalInstall({
+			platform: "windows/amd64",
+			projectName: "my-stack",
+		});
+		expect(result).toHaveProperty("install.ps1");
+		expect(Object.keys(result)).toHaveLength(1);
+		expect(result["install.ps1"]).toContain("docker compose");
+		expect(result["install.ps1"]).toContain("PowerShell");
+	});
+
+	it("returns install.sh for linux/amd64", () => {
+		const result = generateBareMetalInstall({
+			platform: "linux/amd64",
+			projectName: "my-stack",
+		});
+		expect(result).toHaveProperty("install.sh");
+		expect(Object.keys(result)).toHaveLength(1);
+		expect(result["install.sh"]).toContain("docker");
+		expect(result["install.sh"]).toContain("compose");
+	});
+
+	it("returns install.sh for linux/arm64", () => {
+		const result = generateBareMetalInstall({
+			platform: "linux/arm64",
+			projectName: "my-stack",
+		});
+		expect(result).toHaveProperty("install.sh");
+		expect(result["install.sh"]).toContain("docker");
+	});
+
+	it("returns install.sh for macos/amd64 and macos/arm64", () => {
+		for (const platform of ["macos/amd64", "macos/arm64"] as const) {
+			const result = generateBareMetalInstall({ platform, projectName: "my-stack" });
+			expect(result).toHaveProperty("install.sh");
+			expect(result["install.sh"]).toContain("Docker");
+		}
+	});
+});