@better-openclaw/core 1.0.26 → 1.0.30

package/src/frameworks/registry.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+	getAllFrameworks,
+	getCompanionFrameworks,
+	getFrameworkById,
+	getPrimaryFrameworks,
+} from "./registry.js";
+
+// Ensure all frameworks are auto-registered by importing the barrel
+import "./index.js";
+
+const EXPECTED_FRAMEWORK_IDS = [
+	"openclaw",
+	"copaw",
+	"nanoclaw",
+	"nanobot",
+	"zeroclaw",
+	"memu",
+	"claude-code",
+	"codex",
+];
+
+describe("framework registry", () => {
+	it("has all 8 frameworks registered", () => {
+		const all = getAllFrameworks();
+		expect(all.length).toBe(8);
+		const ids = all.map((fw) => fw.id);
+		for (const id of EXPECTED_FRAMEWORK_IDS) {
+			expect(ids).toContain(id);
+		}
+	});
+
+	it("returns undefined for unknown framework", () => {
+		expect(getFrameworkById("nonexistent")).toBeUndefined();
+	});
+
+	it("retrieves each framework by id", () => {
+		for (const id of EXPECTED_FRAMEWORK_IDS) {
+			const fw = getFrameworkById(id);
+			expect(fw).toBeDefined();
+			expect(fw!.id).toBe(id);
+			expect(fw!.name).toBeTruthy();
+			expect(fw!.icon).toBeTruthy();
+			expect(fw!.description).toBeTruthy();
+		}
+	});
+
+	it("all frameworks expose required methods", () => {
+		for (const fw of getAllFrameworks()) {
+			expect(typeof fw.buildGatewayService).toBe("function");
+			expect(typeof fw.generateConfig).toBe("function");
+			expect(typeof fw.getBaseEnvVars).toBe("function");
+			expect(typeof fw.getMandatoryServices).toBe("function");
+			expect(typeof fw.getRecommendedServices).toBe("function");
+			expect(typeof fw.getProviderEnvKeys).toBe("function");
+			expect(typeof fw.getEnvSectionName).toBe("function");
+		}
+	});
+
+	it("getPrimaryFrameworks returns only frameworks with canBePrimary", () => {
+		const primaries = getPrimaryFrameworks();
+		for (const fw of primaries) {
+			expect(fw.canBePrimary).toBe(true);
+		}
+		expect(primaries.length).toBeGreaterThanOrEqual(1);
+		// OpenClaw must always be a primary
+		expect(primaries.some((fw) => fw.id === "openclaw")).toBe(true);
+	});
+
+	it("getCompanionFrameworks returns only frameworks with canBeCompanion", () => {
+		const companions = getCompanionFrameworks();
+		for (const fw of companions) {
+			expect(fw.canBeCompanion).toBe(true);
+		}
+	});
+
+	it("openclaw has mandatory services (convex, mission-control, tailscale)", () => {
+		const openclaw = getFrameworkById("openclaw")!;
+		const mandatory = openclaw.getMandatoryServices();
+		expect(mandatory).toContain("convex");
+		expect(mandatory).toContain("mission-control");
+		expect(mandatory).toContain("tailscale");
+	});
+
+	it("memu has postgresql as mandatory service", () => {
+		const memu = getFrameworkById("memu")!;
+		expect(memu.getMandatoryServices()).toContain("postgresql");
+	});
+
+	it("non-openclaw frameworks do not require convex/mission-control/tailscale", () => {
+		for (const id of ["copaw", "nanoclaw", "nanobot", "zeroclaw", "claude-code", "codex"]) {
+			const fw = getFrameworkById(id)!;
+			const mandatory = fw.getMandatoryServices();
+			expect(mandatory).not.toContain("convex");
+			expect(mandatory).not.toContain("mission-control");
+			expect(mandatory).not.toContain("tailscale");
+		}
+	});
+
+	it("openclaw and copaw recommend clawrouter", () => {
+		const openclaw = getFrameworkById("openclaw")!;
+		expect(openclaw.getRecommendedServices()).toContain("clawrouter");
+
+		const copaw = getFrameworkById("copaw")!;
+		expect(copaw.getRecommendedServices()).toContain("clawrouter");
+	});
+
+	it("other frameworks do not recommend clawrouter", () => {
+		for (const id of ["nanoclaw", "nanobot", "zeroclaw", "claude-code", "codex"]) {
+			const fw = getFrameworkById(id)!;
+			expect(fw.getRecommendedServices()).not.toContain("clawrouter");
+		}
+	});
+
+	it("each framework has a unique network name", () => {
+		const names = getAllFrameworks().map((fw) => fw.networkName);
+		expect(new Set(names).size).toBe(names.length);
+	});
+
+	it("each framework provides env vars via getBaseEnvVars", () => {
+		for (const fw of getAllFrameworks()) {
+			const vars = fw.getBaseEnvVars({});
+			expect(Array.isArray(vars)).toBe(true);
+			// Each env var should have key and comment
+			for (const v of vars) {
+				expect(v.key).toBeTruthy();
+				expect(typeof v.comment).toBe("string");
+			}
+		}
+	});
+});

package/src/frameworks/registry.ts

@@ -0,0 +1,28 @@
+import type { AgentFrameworkDefinition, AgentFrameworkId } from "./types.js";
+
+const frameworkMap = new Map<AgentFrameworkId, AgentFrameworkDefinition>();
+
+/** Register a framework implementation. */
+export function registerFramework(fw: AgentFrameworkDefinition): void {
+	frameworkMap.set(fw.id, fw);
+}
+
+/** Get a framework by its ID. Returns undefined if not registered. */
+export function getFrameworkById(id: string): AgentFrameworkDefinition | undefined {
+	return frameworkMap.get(id as AgentFrameworkId);
+}
+
+/** Get all registered frameworks. */
+export function getAllFrameworks(): AgentFrameworkDefinition[] {
+	return [...frameworkMap.values()];
+}
+
+/** Get all frameworks that can be a primary orchestrator. */
+export function getPrimaryFrameworks(): AgentFrameworkDefinition[] {
+	return getAllFrameworks().filter((fw) => fw.canBePrimary);
+}
+
+/** Get all frameworks that can run as companions. */
+export function getCompanionFrameworks(): AgentFrameworkDefinition[] {
+	return getAllFrameworks().filter((fw) => fw.canBeCompanion);
+}

package/src/frameworks/types.ts

@@ -0,0 +1,146 @@
+import type { ResolverOutput } from "../types.js";
+
+// ─── Framework Identifiers ──────────────────────────────────────────────────
+
+export type AgentFrameworkId =
+	| "openclaw"
+	| "copaw"
+	| "nanoclaw"
+	| "nanobot"
+	| "zeroclaw"
+	| "memu"
+	| "claude-code"
+	| "codex";
+
+// ─── Gateway Build Types ────────────────────────────────────────────────────
+
+export interface GatewayBuildResult {
+	gatewayService: Record<string, unknown>;
+	cliService: Record<string, unknown> | null;
+	allVolumes: Set<string>;
+}
+
+export interface FrameworkComposeOptions {
+	projectName: string;
+	proxy: string;
+	proxyHttpPort?: number;
+	proxyHttpsPort?: number;
+	domain?: string;
+	gpu: boolean;
+	platform: string;
+	deployment: string;
+	frameworkVersion: string;
+	frameworkImageVariant: string;
+	bareMetalNativeHost?: boolean;
+	traefikLabels?: Map<string, Record<string, string>>;
+	hardened: boolean;
+	frameworkInstallMethod: string;
+}
+
+// ─── Env Line (for env file generation) ─────────────────────────────────────
+
+export interface EnvLine {
+	comment: string;
+	key: string;
+	exampleValue: string;
+	actualValue: string;
+}
+
+export interface FrameworkEnvOptions {
+	generateSecrets: boolean;
+	domain?: string;
+	frameworkVersion: string;
+	frameworkImageVariant: string;
+}
+
+// ─── Config Generation ──────────────────────────────────────────────────────
+
+export interface FrameworkConfigOptions {
+	deploymentType: string;
+	gatewayPort: number;
+	frameworkVersion: string;
+}
+
+export interface FrameworkConfigResult {
+	/** File path relative to project root (e.g. "openclaw/config/openclaw.json") */
+	path: string;
+	/** File content (JSON, YAML, TOML, etc.) */
+	content: string;
+}
+
+// ─── Agent Framework Definition ─────────────────────────────────────────────
+
+export interface AgentFrameworkDefinition {
+	/** Unique identifier, kebab-case. */
+	id: AgentFrameworkId;
+
+	/** Human-readable name. */
+	name: string;
+
+	/** Icon for UI display. */
+	icon: string;
+
+	/** Short description for CLI/Web UI selection. */
+	description: string;
+
+	/** Primary language/runtime of this framework. */
+	runtime: "node" | "python" | "rust" | "go";
+
+	/** Whether this framework can serve as the primary orchestrator (gateway). */
+	canBePrimary: boolean;
+
+	/** Whether this framework can run as a companion service alongside another primary. */
+	canBeCompanion: boolean;
+
+	/** Docker network name this framework uses (replaces hardcoded "openclaw-network"). */
+	networkName: string;
+
+	/** Map of image variant names to Docker image strings. */
+	imageVariants: Record<string, string>;
+
+	/** Default image variant key. */
+	defaultImageVariant: string;
+
+	/**
+	 * Build the gateway (primary orchestrator) service entry for docker-compose.
+	 * Returns null if this framework cannot be primary.
+	 */
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult;
+
+	/**
+	 * Build a companion container entry (when running alongside another primary).
+	 * Returns null if this framework cannot be a companion.
+	 */
+	buildCompanionService?(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+	): Record<string, unknown> | null;
+
+	/**
+	 * Generate the framework-specific config file (like openclaw.json).
+	 * Returns null if no config file is needed.
+	 */
+	generateConfig(
+		resolved: ResolverOutput,
+		options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null;
+
+	/** Framework-specific env vars to include in .env files. */
+	getBaseEnvVars(options: FrameworkEnvOptions): EnvLine[];
+
+	/** Service IDs that are mandatory when this framework is primary. */
+	getMandatoryServices(): string[];
+
+	/** Service IDs that are recommended when this framework is primary. */
+	getRecommendedServices(): string[];
+
+	/** AI provider API key env var names to inject into gateway environment. */
+	getProviderEnvKeys(): string[];
+
+	/** Section header name for .env file comments (e.g. "OpenClaw Core"). */
+	getEnvSectionName(): string;
+}

package/src/frameworks/zeroclaw.ts

@@ -0,0 +1,148 @@
+import type { ResolverOutput } from "../types.js";
+import type {
+	AgentFrameworkDefinition,
+	EnvLine,
+	FrameworkComposeOptions,
+	FrameworkConfigOptions,
+	FrameworkConfigResult,
+	FrameworkEnvOptions,
+	GatewayBuildResult,
+} from "./types.js";
+
+const IMAGE_VARIANTS: Record<string, string> = {
+	official: "ghcr.io/zeroclaw-labs/zeroclaw",
+};
+
+function getZeroclawImage(_variant: string, version: string): string {
+	const base = IMAGE_VARIANTS.official;
+	const tag = version !== "latest" ? version : "latest";
+	return `${base}:${tag}`;
+}
+
+const PROVIDER_ENV_KEYS = ["API_KEY", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "OPENROUTER_API_KEY"];
+
+export const zeroclawFramework: AgentFrameworkDefinition = {
+	id: "zeroclaw",
+	name: "ZeroClaw",
+	icon: "⚡",
+	description: "Rust-based 3.4MB agent binary with <10ms cold start",
+	runtime: "rust",
+	canBePrimary: true,
+	canBeCompanion: true,
+	networkName: "zeroclaw-network",
+	imageVariants: IMAGE_VARIANTS,
+	defaultImageVariant: "official",
+
+	buildGatewayService(
+		resolved: ResolverOutput,
+		options: FrameworkComposeOptions,
+		dependsOn?: Record<string, { condition: string }>,
+	): GatewayBuildResult {
+		const allVolumes = new Set<string>();
+		const defaultImage = getZeroclawImage(
+			options.frameworkImageVariant ?? "official",
+			options.frameworkVersion,
+		);
+
+		const gatewayEnv: Record<string, string> = {
+			API_KEY: "${API_KEY}",
+			PROVIDER: "${ZEROCLAW_PROVIDER:-openrouter}",
+			ZEROCLAW_GATEWAY_PORT: "${ZEROCLAW_GATEWAY_PORT:-42617}",
+			ZEROCLAW_ALLOW_PUBLIC_BIND: "true",
+		};
+
+		// Collect env vars from companion services
+		for (const { definition: def } of resolved.services) {
+			for (const env of def.openclawEnvVars) {
+				gatewayEnv[env.key] = env.secret ? `\${${env.key}}` : env.defaultValue;
+			}
+		}
+
+		const gateway: Record<string, unknown> = {
+			image: `\${ZEROCLAW_IMAGE:-${defaultImage}}`,
+			environment: gatewayEnv,
+			volumes: ["${ZEROCLAW_DATA_DIR:-./zeroclaw/data}:/zeroclaw-data"],
+			ports: ["${ZEROCLAW_HOST_PORT:-3000}:${ZEROCLAW_GATEWAY_PORT:-42617}"],
+			networks: [this.networkName],
+			restart: "unless-stopped",
+			deploy: {
+				resources: {
+					limits: { cpus: "2", memory: "2G" },
+					reservations: { cpus: "0.5", memory: "512M" },
+				},
+			},
+			healthcheck: {
+				test: ["CMD", "zeroclaw", "status"],
+				interval: "60s",
+				timeout: "10s",
+				retries: 3,
+				start_period: "10s",
+			},
+		};
+
+		if (dependsOn && Object.keys(dependsOn).length > 0) {
+			gateway.depends_on = dependsOn;
+		}
+
+		return { gatewayService: gateway, cliService: null, allVolumes };
+	},
+
+	generateConfig(
+		_resolved: ResolverOutput,
+		_options: FrameworkConfigOptions,
+	): FrameworkConfigResult | null {
+		// ZeroClaw uses config.toml; generated on first run or via env vars
+		return null;
+	},
+
+	getBaseEnvVars(_options: FrameworkEnvOptions): EnvLine[] {
+		return [
+			{
+				comment: "ZeroClaw Docker image override",
+				key: "ZEROCLAW_IMAGE",
+				exampleValue: "",
+				actualValue: "",
+			},
+			{
+				comment: "LLM provider name (openrouter, anthropic, openai, etc.)",
+				key: "ZEROCLAW_PROVIDER",
+				exampleValue: "openrouter",
+				actualValue: "openrouter",
+			},
+			{
+				comment: "Internal gateway port inside container",
+				key: "ZEROCLAW_GATEWAY_PORT",
+				exampleValue: "42617",
+				actualValue: "42617",
+			},
+			{
+				comment: "Host-facing port for ZeroClaw gateway",
+				key: "ZEROCLAW_HOST_PORT",
+				exampleValue: "3000",
+				actualValue: "3000",
+			},
+			{
+				comment: "Host path to ZeroClaw data directory",
+				key: "ZEROCLAW_DATA_DIR",
+				exampleValue: "./zeroclaw/data",
+				actualValue: "./zeroclaw/data",
+			},
+		];
+	},
+
+	getMandatoryServices(): string[] {
+		return [];
+	},
+
+	getRecommendedServices(): string[] {
+		return [];
+	},
+
+	getProviderEnvKeys(): string[] {
+		return [...PROVIDER_ENV_KEYS];
+	},
+
+	getEnvSectionName(): string {
+		return "ZeroClaw Core";
+	},
+};

package/src/generate.test.ts

@@ -128,7 +128,7 @@ describe("generate (end-to-end)", () => {
 		});
 
 		expect(result.files).toHaveProperty("caddy/Caddyfile");
-		expect(result.files["caddy/Caddyfile"]!.length).toBeGreaterThan(0);
+		expect(result.files["caddy/Caddyfile"]?.length).toBeGreaterThan(0);
 	});
 
 	it("generates prometheus config when monitoring enabled", () => {
@@ -303,10 +303,61 @@ describe("generate (end-to-end)", () => {
 
 		for (const script of expectedScripts) {
 			expect(result.files).toHaveProperty(script);
-			expect(result.files[script]!.length).toBeGreaterThan(0);
+			expect(result.files[script]?.length).toBeGreaterThan(0);
 		}
 	});
 
+	it("generates a stack with zeroclaw as primary framework", () => {
+		const result = generate({
+			projectName: "zeroclaw-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+			primaryFramework: "zeroclaw",
+		});
+
+		const composed = parse(result.files["docker-compose.yml"]!);
+
+		// Should have zeroclaw-gateway, not openclaw-gateway
+		expect(composed.services).toHaveProperty("zeroclaw-gateway");
+		expect(composed.services).not.toHaveProperty("openclaw-gateway");
+
+		// Should NOT have convex/mission-control/tailscale
+		expect(composed.services).not.toHaveProperty("convex");
+		expect(composed.services).not.toHaveProperty("mission-control");
+		expect(composed.services).not.toHaveProperty("tailscale");
+
+		// Network should be zeroclaw-network
+		expect(composed.networks).toHaveProperty("zeroclaw-network");
+	});
+
+	it("generates a stack with companion frameworks", () => {
+		const result = generate({
+			projectName: "multi-fw-stack",
+			services: ["redis"],
+			skillPacks: [],
+			proxy: "none",
+			gpu: false,
+			platform: "linux/amd64",
+			deployment: "local",
+			generateSecrets: true,
+			openclawVersion: "latest",
+			companionFrameworks: ["claude-code"],
+		});
+
+		const composed = parse(result.files["docker-compose.yml"]!);
+
+		// Primary OpenClaw gateway should be present
+		expect(composed.services).toHaveProperty("openclaw-gateway");
+		// Companion Claude Code should be present
+		expect(composed.services).toHaveProperty("claude-code-companion");
+	});
+
 	it("all generated .env.example vars have comments", () => {
 		const result = generate({
 			projectName: "env-comments-stack",
@@ -326,7 +377,7 @@ describe("generate (end-to-end)", () => {
 		// 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();
+			const line = lines[i]?.trim();
 			if (line === "" || line.startsWith("#")) continue;
 
 			// This line looks like KEY=VALUE
@@ -334,7 +385,7 @@ describe("generate (end-to-end)", () => {
 				// 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();
+					const prev = lines[j]?.trim();
 					if (prev === "") continue; // skip blank lines
 					if (prev.startsWith("#")) {
 						foundComment = true;