@better-openclaw/core 1.0.16 → 1.0.18

package/src/generators/stack-manifest.ts

@@ -0,0 +1,127 @@
+/**
+ * Stack manifest generator — produces a JSON manifest describing the
+ * chosen services, skills, and configuration for a generated stack.
+ *
+ * This manifest is consumed by Mission Control to render dynamic
+ * services/skills pages for managing the deployed stack.
+ */
+
+import type { GenerationInput, ResolverOutput } from "../types.js";
+
+export interface StackManifestService {
+	id: string;
+	name: string;
+	category: string;
+	icon: string;
+	image: string;
+	imageTag: string;
+	ports: { container: number; host?: number; exposed: boolean; description: string }[];
+	docsUrl: string;
+	addedBy: string;
+	dependencyOf?: string;
+}
+
+export interface StackManifestSkill {
+	id: string;
+	name: string;
+	path: string;
+	serviceIds: string[];
+}
+
+export interface StackManifest {
+	formatVersion: string;
+	generatedAt: string;
+	projectName: string;
+	deployment?: string;
+	deploymentType?: string;
+	platform?: string;
+	proxy?: string;
+	domain?: string;
+	services: StackManifestService[];
+	skills: StackManifestSkill[];
+	metadata: {
+		serviceCount: number;
+		skillCount: number;
+		estimatedMemoryMB: number;
+	};
+}
+
+/**
+ * Generate stack-manifest.json from resolved output and generation input.
+ * Returns a single-file record: { "stack-manifest.json": string }.
+ */
+export function generateStackManifest(
+	resolved: ResolverOutput,
+	input: GenerationInput,
+): Record<string, string> {
+	// Build a lookup of dependency chains: serviceId → requiredBy
+	const depMap = new Map<string, string>();
+	for (const dep of resolved.addedDependencies) {
+		const depId = dep.serviceId ?? dep.service;
+		if (dep.requiredBy) {
+			depMap.set(depId, dep.requiredBy);
+		}
+	}
+
+	const services: StackManifestService[] = resolved.services.map((svc) => {
+		const def = svc.definition;
+		return {
+			id: def.id,
+			name: def.name,
+			category: def.category,
+			icon: def.icon,
+			image: def.image,
+			imageTag: def.imageTag,
+			ports: def.ports.map((p) => ({
+				container: p.container,
+				host: p.host,
+				exposed: p.exposed,
+				description: p.description,
+			})),
+			docsUrl: def.docsUrl,
+			addedBy: svc.addedBy,
+			...(svc.addedBy !== "user" && depMap.has(def.id) ? { dependencyOf: depMap.get(def.id) } : {}),
+		};
+	});
+
+	// Collect skills from service definitions (SkillBinding has skillId, not name)
+	const skills: StackManifestSkill[] = [];
+	const seenSkillIds = new Set<string>();
+	for (const svc of resolved.services) {
+		for (const skill of svc.definition.skills) {
+			const skillKey = `${svc.definition.id}-${skill.skillId}`;
+			if (seenSkillIds.has(skillKey)) continue;
+			seenSkillIds.add(skillKey);
+			skills.push({
+				id: skillKey,
+				name: skill.skillId,
+				path: `openclaw/skills/${skill.skillId}.md`,
+				serviceIds: [svc.definition.id],
+			});
+		}
+	}
+
+	const skillCount = skills.length;
+
+	const manifest: StackManifest = {
+		formatVersion: "1",
+		generatedAt: new Date().toISOString(),
+		projectName: input.projectName,
+		deployment: input.deployment,
+		deploymentType: input.deploymentType,
+		platform: input.platform,
+		proxy: input.proxy,
+		domain: input.domain,
+		services,
+		skills,
+		metadata: {
+			serviceCount: resolved.services.length,
+			skillCount,
+			estimatedMemoryMB: resolved.estimatedMemoryMB,
+		},
+	};
+
+	return {
+		"stack-manifest.json": JSON.stringify(manifest, null, 2),
+	};
+}

package/src/index.ts

@@ -8,6 +8,21 @@ export {
 } from "./bare-metal-partition.js";
 export type { ComposeResult } from "./composer.js";
 export { compose, composeMultiFile } from "./composer.js";
+// ─── PaaS Deployers ─────────────────────────────────────────────────────────
+export type {
+	DeployInput as PaasDeployInput,
+	DeployResult as PaasDeployResult,
+	DeployStep as PaasDeployStep,
+	DeployTarget as PaasDeployTarget,
+	PaasDeployer,
+} from "./deployers/index.js";
+export {
+	CoolifyDeployer,
+	DokployDeployer,
+	deployerRegistry,
+	getAvailableDeployers,
+	getDeployer,
+} from "./deployers/index.js";
 // ─── Errors ─────────────────────────────────────────────────────────────────
 export { StackConfigError, ValidationError } from "./errors.js";
 export { generate, generateServicesDoc } from "./generate.js";
@@ -22,8 +37,17 @@ export { generatePrometheusConfig } from "./generators/prometheus.js";
 export { generateReadme } from "./generators/readme.js";
 export { generateScripts } from "./generators/scripts.js";
 export { generateSkillFiles } from "./generators/skills.js";
+export type {
+	StackManifest,
+	StackManifestService,
+	StackManifestSkill,
+} from "./generators/stack-manifest.js";
+export { generateStackManifest } from "./generators/stack-manifest.js";
 // ─── Config Migrations ──────────────────────────────────────────────────────
 export { CURRENT_CONFIG_VERSION, migrateConfig, needsMigration } from "./migrations.js";
+// ─── Port Scanner ───────────────────────────────────────────────────────────
+export type { PortConflict } from "./port-scanner.js";
+export { formatPortConflicts, scanPortConflicts } from "./port-scanner.js";
 // ─── Presets ────────────────────────────────────────────────────────────────
 export { getAllPresets, getPresetById, presetRegistry } from "./presets/registry.js";
 export { resolve } from "./resolver.js";
@@ -34,6 +58,7 @@ export {
 	DeploymentTargetSchema,
 	DeploymentTypeSchema,
 	DeploySchema,
+	DeployTargetSchema,
 	EnvVariableSchema,
 	ErrorSchema,
 	GenerationInputSchema,
@@ -41,6 +66,8 @@ export {
 	MaturitySchema,
 	NativePlatformSchema,
 	NativeRecipeSchema,
+	OpenclawImageVariantSchema,
+	OpenclawInstallMethodSchema,
 	OutputFormatSchema,
 	PlatformSchema,
 	PortMappingSchema,
@@ -90,6 +117,7 @@ export type {
 	Deploy,
 	DeploymentTarget,
 	DeploymentType,
+	DeployTarget,
 	EnvVariable,
 	GeneratedFiles,
 	GenerationInput,
@@ -100,6 +128,8 @@ export type {
 	Maturity,
 	NativePlatform,
 	NativeRecipe,
+	OpenclawImageVariant,
+	OpenclawInstallMethod,
 	OutputFormat,
 	Platform,
 	PortMapping,

package/src/port-scanner.ts

@@ -0,0 +1,189 @@
+import type { ServiceDefinition } from "./types.js";
+
+/**
+ * Scans system for ports in use and suggests alternatives for conflicts
+ */
+export interface PortConflict {
+	port: number;
+	serviceId: string;
+	description: string;
+	suggestedPort: number;
+}
+
+/**
+ * Check if a port is available using a two-phase approach:
+ * 1. TCP connect — detects if something is already listening
+ * 2. Bind check — detects OS-reserved/excluded port ranges (e.g. Hyper-V on Windows)
+ *
+ * The connect-only approach misses Windows excluded port ranges because
+ * ECONNREFUSED (nothing listening) looks the same as "available" even though
+ * Docker's bind() will fail on those reserved ranges.
+ */
+async function isPortAvailable(port: number): Promise<boolean> {
+	try {
+		const net = await import("node:net");
+
+		// Phase 1: TCP connect check — is something actively listening?
+		const isListening = await new Promise<boolean>((resolve) => {
+			const socket = new net.Socket();
+			let resolved = false;
+
+			const cleanup = () => {
+				if (!resolved) {
+					resolved = true;
+					socket.removeAllListeners();
+					socket.destroy();
+				}
+			};
+
+			socket.once("connect", () => {
+				cleanup();
+				resolve(true);
+			});
+
+			socket.once("error", () => {
+				cleanup();
+				resolve(false);
+			});
+
+			socket.setTimeout(500);
+			socket.once("timeout", () => {
+				cleanup();
+				resolve(false);
+			});
+
+			socket.connect(port, "127.0.0.1");
+		});
+
+		if (isListening) return false; // Port is in use
+
+		// Phase 2: Bind check — catches OS-reserved/excluded port ranges
+		// On Windows, Hyper-V/WSL reserve dynamic port ranges that TCP connect
+		// cannot detect. Attempting to bind reveals these reservations.
+		const canBind = await new Promise<boolean>((resolve) => {
+			const server = net.createServer();
+
+			server.once("error", (err: NodeJS.ErrnoException) => {
+				// EACCES / EADDRINUSE / EPERM = port is reserved or in use
+				resolve(false);
+			});
+
+			server.listen(port, "0.0.0.0", () => {
+				// Successfully bound — port is truly available
+				server.close(() => resolve(true));
+			});
+		});
+
+		return canBind;
+	} catch (error) {
+		console.warn(`Port scanner error for port ${port}:`, error);
+		return true; // Failsafe: assume available
+	}
+}
+
+/**
+ * Find next available port starting from a base port.
+ * Also skips ports already claimed by other services in this generation.
+ */
+async function findNextAvailablePort(
+	startPort: number,
+	claimedPorts: Set<number>,
+	maxAttempts = 100,
+): Promise<number> {
+	for (let i = 0; i < maxAttempts; i++) {
+		const port = startPort + i;
+		if (port > 65535) break;
+		if (claimedPorts.has(port)) continue;
+		if (await isPortAvailable(port)) {
+			return port;
+		}
+	}
+	// Fallback: return a high random port
+	return 50000 + Math.floor(Math.random() * 10000);
+}
+
+/**
+ * Scan for port conflicts and suggest alternatives.
+ *
+ * Detects two types of conflicts:
+ * 1. Host conflicts — port is already in use or reserved by the OS
+ * 2. Inter-service conflicts — multiple selected services claim the same host port
+ */
+export async function scanPortConflicts(
+	services: ServiceDefinition[],
+): Promise<Map<string, Map<number, number>>> {
+	const portReassignments = new Map<string, Map<number, number>>();
+
+	// Track which host ports are already claimed by services in this stack.
+	// First service to claim a port wins; subsequent services get reassigned.
+	const claimedPorts = new Map<number, string>(); // port → serviceId that claimed it
+
+	for (const service of services) {
+		if (!service.ports || service.ports.length === 0) continue;
+
+		const serviceReassignments = new Map<number, number>();
+
+		for (const portDef of service.ports) {
+			if (!portDef.exposed) continue;
+
+			const port = portDef.host;
+
+			// Check inter-service conflict first
+			const claimedBy = claimedPorts.get(port);
+			if (claimedBy && claimedBy !== service.id) {
+				// Another service already claimed this port — must reassign
+				const newPort = await findNextAvailablePort(port + 1000, new Set(claimedPorts.keys()));
+				serviceReassignments.set(port, newPort);
+				claimedPorts.set(newPort, service.id);
+				continue;
+			}
+
+			// Check host availability (TCP connect + bind check)
+			const isAvailable = await isPortAvailable(port);
+
+			if (!isAvailable) {
+				const newPort = await findNextAvailablePort(port + 1000, new Set(claimedPorts.keys()));
+				serviceReassignments.set(port, newPort);
+				claimedPorts.set(newPort, service.id);
+			} else {
+				// Port is available and not claimed — claim it
+				claimedPorts.set(port, service.id);
+			}
+		}
+
+		if (serviceReassignments.size > 0) {
+			portReassignments.set(service.id, serviceReassignments);
+		}
+	}
+
+	return portReassignments;
+}
+
+/**
+ * Get conflicts in a user-friendly format
+ */
+export function formatPortConflicts(
+	services: ServiceDefinition[],
+	reassignments: Map<string, Map<number, number>>,
+): PortConflict[] {
+	const conflicts: PortConflict[] = [];
+
+	for (const service of services) {
+		const serviceReassignments = reassignments.get(service.id);
+		if (!serviceReassignments) continue;
+
+		for (const portDef of service.ports || []) {
+			const newPort = serviceReassignments.get(portDef.host);
+			if (newPort) {
+				conflicts.push({
+					port: portDef.host,
+					serviceId: service.id,
+					description: portDef.description || `${service.name} port`,
+					suggestedPort: newPort,
+				});
+			}
+		}
+	}
+
+	return conflicts;
+}

package/src/presets/presets.test.ts

@@ -0,0 +1,73 @@
+import * as yaml from "yaml";
+import { generate } from "../generate.js";
+import { getAllPresets, getPresetById } from "../presets/registry.js";
+import { resolve } from "../resolver.js";
+
+const allPresets = getAllPresets();
+
+describe("preset smoke tests", () => {
+	it("all presets are defined", () => {
+		expect(allPresets.length).toBeGreaterThanOrEqual(5);
+	});
+
+	it("all preset IDs are unique", () => {
+		const ids = allPresets.map((p) => p.id);
+		const uniqueIds = new Set(ids);
+		expect(uniqueIds.size).toBe(ids.length);
+	});
+
+	for (const preset of allPresets) {
+		it(`getPresetById returns correct preset for "${preset.id}"`, () => {
+			const found = getPresetById(preset.id);
+			expect(found).toBeDefined();
+			expect(found!.id).toBe(preset.id);
+			expect(found!.name).toBe(preset.name);
+			expect(found!.services).toEqual(preset.services);
+			expect(found!.skillPacks).toEqual(preset.skillPacks);
+		});
+	}
+
+	for (const preset of allPresets) {
+		it(`preset "${preset.id}" generates valid configuration`, () => {
+			const result = generate({
+				projectName: "test-project",
+				services: preset.services,
+				skillPacks: preset.skillPacks,
+				aiProviders: [],
+				gsdRuntimes: [],
+				proxy: "none",
+				gpu: false,
+				platform: "linux/amd64",
+				deployment: "local",
+				deploymentType: "docker",
+				generateSecrets: false,
+				openclawVersion: "latest",
+				monitoring: false,
+			});
+
+			expect(result.files["docker-compose.yml"]).toBeDefined();
+			expect(result.files[".env.example"]).toBeDefined();
+			expect(result.metadata.serviceCount).toBeGreaterThan(0);
+
+			const composeContent = result.files["docker-compose.yml"]!;
+			const parsed = yaml.parse(composeContent);
+			expect(parsed).toBeDefined();
+			expect(parsed.services).toBeDefined();
+		});
+	}
+
+	for (const preset of allPresets) {
+		it(`preset "${preset.id}" resolves without errors`, () => {
+			const result = resolve({
+				services: preset.services,
+				skillPacks: preset.skillPacks,
+				proxy: "none",
+				gpu: false,
+				platform: "linux/amd64",
+				monitoring: false,
+			});
+
+			expect(result.isValid).toBe(true);
+		});
+	}
+});

package/src/presets/registry.test.ts

@@ -18,6 +18,9 @@ describe("preset registry", () => {
 			"lasuite-meet-backend",
 			"lasuite-meet-frontend",
 			"lasuite-meet-agents",
+			"whisper",
+			"ollama",
+			"caddy",
 		]);
 		expect(preset!.skillPacks).toEqual([]);
 		expect(preset!.estimatedMemoryMB).toBe(2048);

package/src/presets/registry.ts

@@ -5,7 +5,7 @@ const presets: Preset[] = [
 		id: "minimal",
 		name: "Minimal",
 		description: "OpenClaw + Redis for caching and session management",
-		services: ["redis"],
+		services: ["redis", "caddy"],
 		skillPacks: [],
 		estimatedMemoryMB: 1024,
 	},
@@ -13,7 +13,7 @@ const presets: Preset[] = [
 		id: "creator",
 		name: "Creator",
 		description: "Full media creation stack with FFmpeg, Remotion, and MinIO storage",
-		services: ["ffmpeg", "remotion", "minio", "redis"],
+		services: ["ffmpeg", "remotion", "minio", "redis", "caddy"],
 		skillPacks: ["video-creator"],
 		estimatedMemoryMB: 2048,
 	},
@@ -21,7 +21,7 @@ const presets: Preset[] = [
 		id: "researcher",
 		name: "Researcher",
 		description: "Research agent with vector search, web scraping, and meta search",
-		services: ["qdrant", "searxng", "browserless", "redis"],
+		services: ["qdrant", "searxng", "browserless", "redis", "caddy", "postgresql"],
 		skillPacks: ["research-agent"],
 		estimatedMemoryMB: 2560,
 	},
@@ -29,7 +29,7 @@ const presets: Preset[] = [
 		id: "devops",
 		name: "DevOps",
 		description: "Full monitoring and automation stack with n8n, Grafana, and Uptime Kuma",
-		services: ["n8n", "postgresql", "redis", "uptime-kuma", "grafana", "prometheus"],
+		services: ["n8n", "postgresql", "redis", "uptime-kuma", "grafana", "prometheus", "caddy"],
 		skillPacks: ["dev-ops"],
 		estimatedMemoryMB: 3072,
 	},
@@ -70,7 +70,7 @@ const presets: Preset[] = [
 		id: "content-creator",
 		name: "Content Creator",
 		description: "Social media scheduling with Postiz, media processing, and analytics",
-		services: ["postiz", "ffmpeg", "minio", "redis", "postgresql", "umami"],
+		services: ["postiz", "ffmpeg", "minio", "redis", "postgresql", "umami", "caddy"],
 		skillPacks: ["content-creator"],
 		estimatedMemoryMB: 2048,
 	},
@@ -78,7 +78,27 @@ const presets: Preset[] = [
 		id: "ai-playground",
 		name: "AI Playground",
 		description: "Local AI stack with Ollama, Open WebUI, LiteLLM gateway, and document chat",
-		services: ["ollama", "open-webui", "litellm", "anything-llm", "redis"],
+		services: ["ollama", "open-webui", "litellm", "anything-llm", "redis", "caddy"],
+		skillPacks: ["ai-playground"],
+		estimatedMemoryMB: 4096,
+	},
+	{
+		id: "ai-powerhouse",
+		name: "AI Powerhouse",
+		description: "Local AI stack with Ollama, Open WebUI, LiteLLM gateway, and document chat",
+		services: [
+			"ollama",
+			"redis",
+			"qdrant",
+			"minio",
+			"litellm",
+			"anything-llm",
+			"n8n",
+			"postgresql",
+			"caddy",
+			"open-webui",
+			"searxng",
+		],
 		skillPacks: ["ai-playground"],
 		estimatedMemoryMB: 4096,
 	},
@@ -86,7 +106,7 @@ const presets: Preset[] = [
 		id: "coding-team",
 		name: "Coding Team",
 		description: "AI development environment with coding agents, Git, and browser IDE",
-		services: ["claude-code", "opencode", "gitea", "code-server", "redis"],
+		services: ["claude-code", "opencode", "gitea", "code-server", "redis", "caddy"],
 		skillPacks: ["coding-team"],
 		estimatedMemoryMB: 2560,
 	},
@@ -101,6 +121,9 @@ const presets: Preset[] = [
 			"lasuite-meet-backend",
 			"lasuite-meet-frontend",
 			"lasuite-meet-agents",
+			"whisper",
+			"ollama",
+			"caddy",
 		],
 		skillPacks: [],
 		estimatedMemoryMB: 2048,

package/src/resolver.ts

@@ -132,6 +132,8 @@ export function resolve(input: ResolverInput): ResolverOutput {
 					serviceAddedBy.set(reqId, "dependency");
 					addedDependencies.push({
 						service: reqId,
+						serviceId: reqId,
+						requiredBy: def.name,
 						reason: `Required by ${def.name}`,
 					});
 					changed = true;

package/src/schema.ts

@@ -38,7 +38,7 @@ export const PlatformSchema = z.enum([
 /** Platform for Docker image arch only (used by resolver/compose). */
 export const ComposePlatformSchema = z.enum(["linux/amd64", "linux/arm64"]);
 
-export const DeploymentTypeSchema = z.enum(["docker", "bare-metal"]);
+export const DeploymentTypeSchema = z.enum(["docker", "bare-metal", "local"]);
 
 export const RestartPolicySchema = z.enum(["unless-stopped", "always", "on-failure", "no"]);
 
@@ -48,6 +48,12 @@ export const DeploymentTargetSchema = z.enum(["local", "vps", "homelab", "clawex
 
 export const OutputFormatSchema = z.enum(["directory", "tar", "zip"]);
 
+export const OpenclawImageVariantSchema = z.enum(["official", "coolify", "alpine"]);
+
+export const OpenclawInstallMethodSchema = z.enum(["docker", "direct"]);
+
+export const DeployTargetSchema = z.enum(["local", "cloud-init"]);
+
 export const AiProviderSchema = z.enum([
 	"openai",
 	"anthropic",
@@ -59,6 +65,7 @@ export const AiProviderSchema = z.enum([
 	"mistral",
 	"together",
 	"ollama",
+	"ollama-cloud",
 	"lmstudio",
 	"vllm",
 ]);
@@ -233,6 +240,11 @@ export const GenerationInputSchema = z.object({
 	aiProviders: z.array(AiProviderSchema).default([]),
 	gsdRuntimes: z.array(GsdRuntimeSchema).default([]),
 	proxy: ProxyTypeSchema.default("none"),
+	proxyHttpPort: z.number().int().min(1).max(65535).optional(),
+	proxyHttpsPort: z.number().int().min(1).max(65535).optional(),
+	portOverrides: z
+		.record(z.string(), z.record(z.string(), z.number().int().min(1).max(65535)))
+		.optional(),
 	domain: z.string().optional(),
 	gpu: z.boolean().default(false),
 	platform: PlatformSchema.default("linux/amd64"),
@@ -241,6 +253,10 @@ export const GenerationInputSchema = z.object({
 	generateSecrets: z.boolean().default(true),
 	openclawVersion: z.string().default("latest"),
 	monitoring: z.boolean().default(false),
+	openclawImage: OpenclawImageVariantSchema.default("official"),
+	openclawInstallMethod: OpenclawInstallMethodSchema.default("docker"),
+	deployTarget: DeployTargetSchema.default("local"),
+	hardened: z.boolean().default(true),
 });
 
 // ─── Resolver Output ────────────────────────────────────────────────────────
@@ -252,6 +268,8 @@ export const ResolvedServiceSchema = z.object({
 
 export const AddedDependencySchema = z.object({
 	service: z.string(),
+	serviceId: z.string().optional(),
+	requiredBy: z.string().optional(),
 	reason: z.string(),
 });
 
@@ -282,6 +300,11 @@ export const ResolverOutputSchema = z.object({
 export const ComposeOptionsSchema = z.object({
 	projectName: z.string(),
 	proxy: ProxyTypeSchema.default("none"),
+	proxyHttpPort: z.number().int().min(1).max(65535).optional(),
+	proxyHttpsPort: z.number().int().min(1).max(65535).optional(),
+	portOverrides: z
+		.record(z.string(), z.record(z.string(), z.number().int().min(1).max(65535)))
+		.optional(),
 	domain: z.string().optional(),
 	gpu: z.boolean().default(false),
 	platform: PlatformSchema.default("linux/amd64"),
@@ -289,6 +312,12 @@ export const ComposeOptionsSchema = z.object({
 	openclawVersion: z.string().default("latest"),
 	/** When true, gateway gets extra_hosts so it can reach host-run (native) services. */
 	bareMetalNativeHost: z.boolean().optional(),
+	/** OpenClaw Docker image variant: official, coolify, or alpine. */
+	openclawImage: OpenclawImageVariantSchema.default("official"),
+	/** Whether to apply security hardening (cap_drop, no-new-privileges, etc.) */
+	hardened: z.boolean().default(true),
+	/** How to install OpenClaw itself: docker (in container) or direct (host install). */
+	openclawInstallMethod: OpenclawInstallMethodSchema.default("docker"),
 });
 
 // ─── API Request/Response ───────────────────────────────────────────────────

package/src/services/definitions/anything-llm.ts

@@ -9,10 +9,10 @@ export const anythingLlmDefinition: ServiceDefinition = {
 	icon: "📖",
 
 	image: "mintplexlabs/anythingllm",
-	imageTag: "latest",
+	imageTag: "1.3.0",
 	ports: [
 		{
-			host: 3100,
+			host: 3115,
 			container: 3001,
 			description: "AnythingLLM interface",
 			exposed: true,

package/src/services/definitions/appflowy.ts

@@ -9,7 +9,7 @@ export const appflowyDefinition: ServiceDefinition = {
 	icon: "🍃",
 
 	image: "appflowyio/appflowy-cloud",
-	imageTag: "latest",
+	imageTag: "0.11.1",
 	ports: [
 		{
 			host: 8087,