@better-openclaw/core 1.0.0

package/src/resolver.ts

@@ -0,0 +1,282 @@
+import { getServiceById } from "./services/registry.js";
+import { getSkillPackById } from "./skills/registry.js";
+import type {
+	AddedDependency,
+	ResolvedService,
+	ResolverError,
+	ResolverInput,
+	ResolverOutput,
+	ServiceDefinition,
+	Warning,
+} from "./types.js";
+
+/**
+ * Resolves user selections into a complete, valid service list.
+ *
+ * Algorithm:
+ * 1. Expand skill pack requirements into service list
+ * 2. Resolve transitive `requires` dependencies (iterate until stable)
+ * 3. Detect `conflictsWith` violations
+ * 4. Check platform compatibility and GPU requirements
+ * 5. Estimate total memory (sum minMemoryMB)
+ * 6. Deduplicate
+ * 7. Topological sort by dependency graph, alphabetical for ties
+ *
+ * Deterministic: same input -> same output, always.
+ */
+export function resolve(input: ResolverInput): ResolverOutput {
+	const addedDependencies: AddedDependency[] = [];
+	const warnings: Warning[] = [];
+	const errors: ResolverError[] = [];
+
+	// Track all service IDs needed
+	const serviceIds = new Set<string>(input.services);
+	const serviceAddedBy = new Map<string, ResolvedService["addedBy"]>();
+
+	// Mark user-selected services
+	for (const id of input.services) {
+		serviceAddedBy.set(id, "user");
+	}
+
+	// 1. Expand skill pack requirements
+	for (const packId of input.skillPacks) {
+		const pack = getSkillPackById(packId);
+		if (!pack) {
+			errors.push({
+				type: "unknown_skill_pack",
+				message: `Unknown skill pack: "${packId}"`,
+			});
+			continue;
+		}
+		for (const requiredService of pack.requiredServices) {
+			if (!serviceIds.has(requiredService)) {
+				serviceIds.add(requiredService);
+				serviceAddedBy.set(requiredService, "skill-pack");
+				addedDependencies.push({
+					service: requiredService,
+					reason: `Required by skill pack: ${pack.name}`,
+				});
+			}
+		}
+	}
+
+	// Add proxy if specified
+	if (input.proxy && input.proxy !== "none") {
+		if (!serviceIds.has(input.proxy)) {
+			serviceIds.add(input.proxy);
+			serviceAddedBy.set(input.proxy, "proxy");
+			addedDependencies.push({
+				service: input.proxy,
+				reason: `Selected as reverse proxy`,
+			});
+		}
+	}
+
+	// Add monitoring stack if requested
+	if (input.monitoring) {
+		const monitoringServices = ["uptime-kuma", "grafana", "prometheus"];
+		for (const svc of monitoringServices) {
+			if (!serviceIds.has(svc)) {
+				serviceIds.add(svc);
+				serviceAddedBy.set(svc, "monitoring");
+				addedDependencies.push({
+					service: svc,
+					reason: "Included with monitoring stack",
+				});
+			}
+		}
+	}
+
+	// Validate all service IDs exist
+	const unknownIds: string[] = [];
+	for (const id of serviceIds) {
+		if (!getServiceById(id)) {
+			unknownIds.push(id);
+		}
+	}
+	if (unknownIds.length > 0) {
+		for (const id of unknownIds) {
+			errors.push({
+				type: "unknown_service",
+				message: `Unknown service: "${id}"`,
+			});
+			serviceIds.delete(id);
+		}
+	}
+
+	// 2. Resolve transitive dependencies (iterate until stable)
+	let changed = true;
+	const maxIterations = 50; // safety bound
+	let iteration = 0;
+	while (changed && iteration < maxIterations) {
+		changed = false;
+		iteration++;
+		for (const id of [...serviceIds]) {
+			const def = getServiceById(id);
+			if (!def) continue;
+			for (const reqId of def.requires) {
+				if (!serviceIds.has(reqId)) {
+					serviceIds.add(reqId);
+					serviceAddedBy.set(reqId, "dependency");
+					addedDependencies.push({
+						service: reqId,
+						reason: `Required by ${def.name}`,
+					});
+					changed = true;
+				}
+			}
+		}
+	}
+
+	// 3. Detect conflicts
+	const resolvedDefs: ServiceDefinition[] = [];
+	for (const id of serviceIds) {
+		const def = getServiceById(id);
+		if (def) resolvedDefs.push(def);
+	}
+
+	for (let i = 0; i < resolvedDefs.length; i++) {
+		for (let j = i + 1; j < resolvedDefs.length; j++) {
+			const a = resolvedDefs[i]!;
+			const b = resolvedDefs[j]!;
+			if (a.conflictsWith.includes(b.id) || b.conflictsWith.includes(a.id)) {
+				errors.push({
+					type: "conflict",
+					message: `${a.name} and ${b.name} cannot be used together`,
+				});
+			}
+		}
+	}
+
+	// 4. Check platform compatibility
+	if (input.platform) {
+		for (const def of resolvedDefs) {
+			if (def.platforms && def.platforms.length > 0 && !def.platforms.includes(input.platform)) {
+				warnings.push({
+					type: "platform",
+					message: `${def.name} may not be compatible with ${input.platform}. Supported: ${def.platforms.join(", ")}`,
+				});
+			}
+		}
+	}
+
+	// Check GPU requirements
+	const gpuServices = resolvedDefs.filter((d) => d.gpuRequired);
+	if (gpuServices.length > 0 && !input.gpu) {
+		for (const svc of gpuServices) {
+			warnings.push({
+				type: "gpu",
+				message: `${svc.name} requires GPU passthrough. Enable --gpu flag for optimal performance.`,
+			});
+		}
+	}
+
+	// 5. Estimate total memory
+	let estimatedMemoryMB = 512; // Base for OpenClaw itself
+	for (const def of resolvedDefs) {
+		estimatedMemoryMB += def.minMemoryMB ?? 128;
+	}
+
+	// Memory warnings
+	if (estimatedMemoryMB > 8192) {
+		warnings.push({
+			type: "memory",
+			message: `Estimated ${(estimatedMemoryMB / 1024).toFixed(1)}GB RAM required. Ensure your server has sufficient resources.`,
+		});
+	} else if (estimatedMemoryMB > 4096) {
+		warnings.push({
+			type: "memory",
+			message: `Estimated ${(estimatedMemoryMB / 1024).toFixed(1)}GB RAM required. A server with at least 8GB RAM is recommended.`,
+		});
+	} else if (estimatedMemoryMB > 2048) {
+		warnings.push({
+			type: "memory",
+			message: `Estimated ${(estimatedMemoryMB / 1024).toFixed(1)}GB RAM required.`,
+		});
+	}
+
+	// 7. Topological sort by dependency graph
+	const sorted = topologicalSort(resolvedDefs);
+
+	// Build final resolved services list
+	const services: ResolvedService[] = sorted.map((def) => ({
+		definition: def,
+		addedBy: serviceAddedBy.get(def.id) ?? "user",
+	}));
+
+	const isValid = errors.length === 0;
+
+	return {
+		services,
+		addedDependencies,
+		removedConflicts: [],
+		warnings,
+		errors,
+		isValid,
+		estimatedMemoryMB,
+	};
+}
+
+/**
+ * Topological sort using Kahn's algorithm.
+ * Ties broken alphabetically by service ID for determinism.
+ */
+function topologicalSort(definitions: ServiceDefinition[]): ServiceDefinition[] {
+	const idSet = new Set(definitions.map((d) => d.id));
+	const graph = new Map<string, string[]>(); // id -> list of IDs that depend on it
+	const inDegree = new Map<string, number>();
+
+	// Initialize
+	for (const def of definitions) {
+		graph.set(def.id, []);
+		inDegree.set(def.id, 0);
+	}
+
+	// Build edges: if A requires B, then B -> A (B must come before A)
+	for (const def of definitions) {
+		for (const reqId of [...def.requires, ...def.dependsOn]) {
+			if (idSet.has(reqId)) {
+				graph.get(reqId)?.push(def.id);
+				inDegree.set(def.id, (inDegree.get(def.id) ?? 0) + 1);
+			}
+		}
+	}
+
+	// Kahn's algorithm with alphabetical tie-breaking
+	const queue: string[] = [];
+	for (const [id, deg] of inDegree) {
+		if (deg === 0) queue.push(id);
+	}
+	queue.sort(); // alphabetical for determinism
+
+	const sorted: ServiceDefinition[] = [];
+	const defMap = new Map(definitions.map((d) => [d.id, d]));
+
+	while (queue.length > 0) {
+		const id = queue.shift()!;
+		const def = defMap.get(id);
+		if (def) sorted.push(def);
+
+		const neighbors = graph.get(id) ?? [];
+		const newReady: string[] = [];
+		for (const neighbor of neighbors) {
+			const deg = (inDegree.get(neighbor) ?? 0) - 1;
+			inDegree.set(neighbor, deg);
+			if (deg === 0) newReady.push(neighbor);
+		}
+		// Sort newly ready nodes alphabetically and add to queue in order
+		newReady.sort();
+		queue.push(...newReady);
+	}
+
+	// If not all nodes are in sorted, there's a cycle
+	if (sorted.length < definitions.length) {
+		// Return what we have plus remaining (cycle detected but we still produce output)
+		const sortedIds = new Set(sorted.map((d) => d.id));
+		const remaining = definitions.filter((d) => !sortedIds.has(d.id));
+		remaining.sort((a, b) => a.id.localeCompare(b.id));
+		sorted.push(...remaining);
+	}
+
+	return sorted;
+}

package/src/schema.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it } from "vitest";
+import {
+	EnvVariableSchema,
+	GenerationInputSchema,
+	HealthCheckSchema,
+	PortMappingSchema,
+	PresetSchema,
+	ServiceCategorySchema,
+	ServiceDefinitionSchema,
+	SkillPackSchema,
+	VolumeMappingSchema,
+} from "./schema.js";
+
+describe("ServiceCategorySchema", () => {
+	it("accepts valid categories", () => {
+		expect(ServiceCategorySchema.parse("automation")).toBe("automation");
+		expect(ServiceCategorySchema.parse("vector-db")).toBe("vector-db");
+		expect(ServiceCategorySchema.parse("ai")).toBe("ai");
+	});
+
+	it("rejects invalid categories", () => {
+		expect(() => ServiceCategorySchema.parse("invalid")).toThrow();
+		expect(() => ServiceCategorySchema.parse("")).toThrow();
+	});
+});
+
+describe("PortMappingSchema", () => {
+	it("accepts valid port mapping", () => {
+		const result = PortMappingSchema.parse({
+			host: 6379,
+			container: 6379,
+			description: "Redis port",
+			exposed: true,
+		});
+		expect(result.host).toBe(6379);
+	});
+
+	it("defaults exposed to true", () => {
+		const result = PortMappingSchema.parse({
+			host: 6379,
+			container: 6379,
+			description: "Redis port",
+		});
+		expect(result.exposed).toBe(true);
+	});
+
+	it("rejects invalid port numbers", () => {
+		expect(() =>
+			PortMappingSchema.parse({
+				host: 0,
+				container: 6379,
+				description: "bad",
+			}),
+		).toThrow();
+		expect(() =>
+			PortMappingSchema.parse({
+				host: 70000,
+				container: 6379,
+				description: "bad",
+			}),
+		).toThrow();
+	});
+});
+
+describe("VolumeMappingSchema", () => {
+	it("accepts valid volume mapping", () => {
+		const result = VolumeMappingSchema.parse({
+			name: "redis-data",
+			containerPath: "/data",
+			description: "Redis persistent data",
+		});
+		expect(result.name).toBe("redis-data");
+	});
+
+	it("rejects empty name", () => {
+		expect(() =>
+			VolumeMappingSchema.parse({
+				name: "",
+				containerPath: "/data",
+				description: "bad",
+			}),
+		).toThrow();
+	});
+});
+
+describe("EnvVariableSchema", () => {
+	it("accepts valid env variable", () => {
+		const result = EnvVariableSchema.parse({
+			key: "REDIS_PASSWORD",
+			defaultValue: "changeme",
+			secret: true,
+			description: "Redis password",
+			required: true,
+		});
+		expect(result.secret).toBe(true);
+	});
+
+	it("defaults secret to false", () => {
+		const result = EnvVariableSchema.parse({
+			key: "REDIS_HOST",
+			defaultValue: "redis",
+			description: "Redis host",
+		});
+		expect(result.secret).toBe(false);
+		expect(result.required).toBe(true);
+	});
+});
+
+describe("HealthCheckSchema", () => {
+	it("accepts valid healthcheck with defaults", () => {
+		const result = HealthCheckSchema.parse({
+			test: "redis-cli ping",
+		});
+		expect(result.interval).toBe("30s");
+		expect(result.timeout).toBe("10s");
+		expect(result.retries).toBe(3);
+	});
+});
+
+describe("GenerationInputSchema", () => {
+	it("accepts valid generation input", () => {
+		const result = GenerationInputSchema.parse({
+			projectName: "my-openclaw-stack",
+			services: ["redis", "qdrant"],
+			skillPacks: ["research-agent"],
+			proxy: "caddy",
+			domain: "openclaw.example.com",
+		});
+		expect(result.projectName).toBe("my-openclaw-stack");
+		expect(result.gpu).toBe(false);
+	});
+
+	it("rejects invalid project names", () => {
+		expect(() => GenerationInputSchema.parse({ projectName: "-bad-name" })).toThrow();
+		expect(() => GenerationInputSchema.parse({ projectName: "Bad Name" })).toThrow();
+		expect(() => GenerationInputSchema.parse({ projectName: "has spaces" })).toThrow();
+	});
+
+	it("accepts single-char project name", () => {
+		const result = GenerationInputSchema.parse({ projectName: "a" });
+		expect(result.projectName).toBe("a");
+	});
+
+	it("applies defaults", () => {
+		const result = GenerationInputSchema.parse({ projectName: "test" });
+		expect(result.services).toEqual([]);
+		expect(result.skillPacks).toEqual([]);
+		expect(result.proxy).toBe("none");
+		expect(result.gpu).toBe(false);
+		expect(result.platform).toBe("linux/amd64");
+		expect(result.deployment).toBe("local");
+		expect(result.deploymentType).toBe("docker");
+		expect(result.generateSecrets).toBe(true);
+		expect(result.openclawVersion).toBe("latest");
+	});
+
+	it("accepts deploymentType bare-metal and extended platform", () => {
+		const result = GenerationInputSchema.parse({
+			projectName: "my-stack",
+			services: ["redis"],
+			deploymentType: "bare-metal",
+			platform: "windows/amd64",
+		});
+		expect(result.deploymentType).toBe("bare-metal");
+		expect(result.platform).toBe("windows/amd64");
+	});
+
+	it("accepts platform macos/arm64", () => {
+		const result = GenerationInputSchema.parse({
+			projectName: "my-stack",
+			platform: "macos/arm64",
+		});
+		expect(result.platform).toBe("macos/arm64");
+	});
+});
+
+describe("ServiceDefinitionSchema", () => {
+	const validDef = {
+		id: "redis",
+		name: "Redis",
+		description: "In-memory data store",
+		category: "database",
+		icon: "🔴",
+		image: "redis",
+		imageTag: "7-alpine",
+		ports: [{ host: 6379, container: 6379, description: "Redis port", exposed: true }],
+		volumes: [{ name: "redis-data", containerPath: "/data", description: "Data" }],
+		environment: [],
+		restartPolicy: "unless-stopped",
+		networks: ["openclaw-network"],
+		skills: [],
+		openclawEnvVars: [],
+		docsUrl: "https://redis.io/docs",
+		tags: ["cache", "database"],
+		maturity: "stable",
+	};
+
+	it("accepts valid service definition", () => {
+		const result = ServiceDefinitionSchema.parse(validDef);
+		expect(result.id).toBe("redis");
+	});
+
+	it("rejects invalid id format", () => {
+		expect(() => ServiceDefinitionSchema.parse({ ...validDef, id: "Bad_Id" })).toThrow();
+	});
+
+	it("defaults arrays and booleans correctly", () => {
+		const minimal = {
+			id: "test",
+			name: "Test",
+			description: "Test service",
+			category: "database",
+			icon: "🧪",
+			image: "test",
+			imageTag: "latest",
+			docsUrl: "https://example.com",
+		};
+		const result = ServiceDefinitionSchema.parse(minimal);
+		expect(result.ports).toEqual([]);
+		expect(result.volumes).toEqual([]);
+		expect(result.requires).toEqual([]);
+		expect(result.conflictsWith).toEqual([]);
+		expect(result.gpuRequired).toBe(false);
+	});
+
+	it("accepts optional mandatory field and defaults to false when omitted", () => {
+		const withMandatory = { ...validDef, mandatory: true };
+		const result = ServiceDefinitionSchema.parse(withMandatory);
+		expect(result.mandatory).toBe(true);
+	});
+
+	it("omitting mandatory leaves it undefined or false (schema default false)", () => {
+		const result = ServiceDefinitionSchema.parse(validDef);
+		expect(result.mandatory !== true).toBe(true); // false or undefined both mean not mandatory
+	});
+
+	it("accepts nativeSupported and nativeRecipes for bare-metal", () => {
+		const withNative = {
+			...validDef,
+			nativeSupported: true,
+			nativeRecipes: [
+				{
+					platform: "linux",
+					installSteps: ["apt-get install -y redis-server"],
+					startCommand: "systemctl start redis-server",
+					stopCommand: "systemctl stop redis-server",
+					systemdUnit: "redis-server",
+				},
+			],
+		};
+		const result = ServiceDefinitionSchema.parse(withNative);
+		expect(result.nativeSupported).toBe(true);
+		expect(result.nativeRecipes).toHaveLength(1);
+		expect(result.nativeRecipes![0].platform).toBe("linux");
+		expect(result.nativeRecipes![0].startCommand).toBe("systemctl start redis-server");
+	});
+});
+
+describe("SkillPackSchema", () => {
+	it("accepts valid skill pack", () => {
+		const result = SkillPackSchema.parse({
+			id: "research-agent",
+			name: "Research Agent",
+			description: "Research agent pack",
+			requiredServices: ["qdrant", "searxng", "browserless"],
+			skills: ["qdrant-memory", "searxng-search", "browserless-browse"],
+		});
+		expect(result.requiredServices).toHaveLength(3);
+	});
+
+	it("rejects empty required services", () => {
+		expect(() =>
+			SkillPackSchema.parse({
+				id: "empty",
+				name: "Empty",
+				description: "Bad",
+				requiredServices: [],
+				skills: [],
+			}),
+		).toThrow();
+	});
+});
+
+describe("PresetSchema", () => {
+	it("accepts valid preset", () => {
+		const result = PresetSchema.parse({
+			id: "minimal",
+			name: "Minimal",
+			description: "OpenClaw + Redis",
+			services: ["redis"],
+			estimatedMemoryMB: 1024,
+		});
+		expect(result.skillPacks).toEqual([]);
+	});
+});