clawchef 0.1.0

package/src/openclaw/provider.ts

@@ -0,0 +1,44 @@
+import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection, WorkspaceDef } from "../types.js";
+
+export type ResolvedWorkspaceDef = WorkspaceDef & { path: string };
+
+export interface EnsureVersionResult {
+  installedThisRun: boolean;
+}
+
+export interface OpenClawProvider {
+  ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+  factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
+  startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;
+  createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void>;
+  configureChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
+  loginChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void>;
+  materializeFile?(
+    config: OpenClawSection,
+    workspace: string,
+    filePath: string,
+    content: string,
+    overwrite: boolean | undefined,
+    dryRun: boolean,
+  ): Promise<void>;
+  createAgent(
+    config: OpenClawSection,
+    agent: AgentDef,
+    workspacePath: string,
+    dryRun: boolean,
+  ): Promise<void>;
+  installSkill(
+    config: OpenClawSection,
+    workspace: string,
+    agent: string,
+    skill: string,
+    dryRun: boolean,
+  ): Promise<void>;
+  sendMessage(
+    config: OpenClawSection,
+    conversation: ConversationDef,
+    content: string,
+    dryRun: boolean,
+  ): Promise<void>;
+  runAgent(config: OpenClawSection, conversation: ConversationDef, dryRun: boolean): Promise<string>;
+}

package/src/openclaw/remote-provider.ts

@@ -0,0 +1,264 @@
+import { ClawChefError } from "../errors.js";
+import type {
+  AgentDef,
+  ChannelDef,
+  ConversationDef,
+  OpenClawRemoteConfig,
+  OpenClawSection,
+} from "../types.js";
+import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
+
+interface StagedMessage {
+  content: string;
+}
+
+interface RemoteOperationRequest {
+  operation: string;
+  recipe_version: string;
+  payload?: Record<string, unknown>;
+}
+
+interface RemoteOperationResponse {
+  ok?: boolean;
+  message?: string;
+  output?: string;
+  installed_this_run?: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_OPERATION_PATH = "/v1/clawchef/operation";
+
+function parseResponseBody(raw: string): RemoteOperationResponse {
+  if (!raw.trim()) {
+    return {};
+  }
+  try {
+    return JSON.parse(raw) as RemoteOperationResponse;
+  } catch {
+    return { message: raw.trim() };
+  }
+}
+
+function buildHeaders(remote: OpenClawRemoteConfig): Record<string, string> {
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+  };
+
+  if (remote.api_key?.trim()) {
+    const headerName = remote.api_header?.trim() || "Authorization";
+    const scheme = remote.api_scheme === undefined ? "Bearer" : remote.api_scheme;
+    headers[headerName] = scheme ? `${scheme} ${remote.api_key}` : remote.api_key;
+  }
+
+  return headers;
+}
+
+function operationUrl(remote: OpenClawRemoteConfig): string {
+  const path = remote.operation_path?.trim() || DEFAULT_OPERATION_PATH;
+  return new URL(path, remote.base_url).toString();
+}
+
+function assertRemoteConfig(remote: Partial<OpenClawRemoteConfig>): OpenClawRemoteConfig {
+  const baseUrl = remote.base_url?.trim();
+  if (!baseUrl) {
+    throw new ClawChefError("--provider remote requires --remote-base-url (or CLAWCHEF_REMOTE_BASE_URL)");
+  }
+
+  try {
+    new URL(baseUrl);
+  } catch {
+    throw new ClawChefError(`Remote base URL is invalid: ${baseUrl}`);
+  }
+
+  return {
+    base_url: baseUrl,
+    api_key: remote.api_key,
+    api_header: remote.api_header,
+    api_scheme: remote.api_scheme,
+    timeout_ms: remote.timeout_ms,
+    operation_path: remote.operation_path,
+  };
+}
+
+export class RemoteOpenClawProvider implements OpenClawProvider {
+  private readonly stagedMessages = new Map<string, StagedMessage[]>();
+  private readonly remoteConfig: Partial<OpenClawRemoteConfig>;
+
+  constructor(remoteConfig: Partial<OpenClawRemoteConfig>) {
+    this.remoteConfig = remoteConfig;
+  }
+
+  private async perform(
+    config: OpenClawSection,
+    operation: string,
+    payload: Record<string, unknown> | undefined,
+    dryRun: boolean,
+  ): Promise<RemoteOperationResponse> {
+    if (dryRun) {
+      return { ok: true };
+    }
+
+    const remote = assertRemoteConfig(this.remoteConfig);
+    const timeoutMs = remote.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    const requestBody: RemoteOperationRequest = {
+      operation,
+      recipe_version: config.version,
+      payload,
+    };
+
+    try {
+      const response = await fetch(operationUrl(remote), {
+        method: "POST",
+        headers: buildHeaders(remote),
+        body: JSON.stringify(requestBody),
+        signal: controller.signal,
+      });
+      const raw = await response.text();
+      const parsed = parseResponseBody(raw);
+
+      if (!response.ok) {
+        throw new ClawChefError(
+          `Remote operation failed (${response.status}) for ${operation}: ${parsed.message ?? response.statusText}`,
+        );
+      }
+
+      if (parsed.ok === false) {
+        throw new ClawChefError(`Remote operation failed for ${operation}: ${parsed.message ?? "unknown error"}`);
+      }
+
+      return parsed;
+    } catch (err) {
+      if (err instanceof ClawChefError) {
+        throw err;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ClawChefError(`Remote operation failed for ${operation}: ${message}`);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult> {
+    const result = await this.perform(
+      config,
+      "ensure_version",
+      {
+        install: config.install,
+      },
+      dryRun,
+    );
+
+    return {
+      installedThisRun: Boolean(result.installed_this_run),
+    };
+  }
+
+  async factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void> {
+    await this.perform(config, "factory_reset", undefined, dryRun);
+  }
+
+  async startGateway(config: OpenClawSection, dryRun: boolean): Promise<void> {
+    await this.perform(config, "start_gateway", undefined, dryRun);
+  }
+
+  async createWorkspace(config: OpenClawSection, workspace: ResolvedWorkspaceDef, dryRun: boolean): Promise<void> {
+    await this.perform(config, "create_workspace", { workspace }, dryRun);
+  }
+
+  async configureChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void> {
+    await this.perform(config, "configure_channel", { channel }, dryRun);
+  }
+
+  async loginChannel(config: OpenClawSection, channel: ChannelDef, dryRun: boolean): Promise<void> {
+    await this.perform(config, "login_channel", { channel }, dryRun);
+  }
+
+  async materializeFile(
+    config: OpenClawSection,
+    workspace: string,
+    filePath: string,
+    content: string,
+    overwrite: boolean | undefined,
+    dryRun: boolean,
+  ): Promise<void> {
+    await this.perform(
+      config,
+      "materialize_file",
+      {
+        workspace,
+        path: filePath,
+        content,
+        overwrite,
+      },
+      dryRun,
+    );
+  }
+
+  async createAgent(
+    config: OpenClawSection,
+    agent: AgentDef,
+    workspacePath: string,
+    dryRun: boolean,
+  ): Promise<void> {
+    await this.perform(
+      config,
+      "create_agent",
+      {
+        agent,
+        workspace_path: workspacePath,
+      },
+      dryRun,
+    );
+  }
+
+  async installSkill(
+    config: OpenClawSection,
+    workspace: string,
+    agent: string,
+    skill: string,
+    dryRun: boolean,
+  ): Promise<void> {
+    await this.perform(
+      config,
+      "install_skill",
+      {
+        workspace,
+        agent,
+        skill,
+      },
+      dryRun,
+    );
+  }
+
+  async sendMessage(
+    _config: OpenClawSection,
+    conversation: ConversationDef,
+    content: string,
+    _dryRun: boolean,
+  ): Promise<void> {
+    const key = `${conversation.workspace}::${conversation.agent}`;
+    const staged = this.stagedMessages.get(key) ?? [];
+    staged.push({ content });
+    this.stagedMessages.set(key, staged);
+  }
+
+  async runAgent(config: OpenClawSection, conversation: ConversationDef, dryRun: boolean): Promise<string> {
+    const key = `${conversation.workspace}::${conversation.agent}`;
+    const staged = this.stagedMessages.get(key) ?? [];
+    const prompt = staged.map((m) => `user: ${m.content}`).join("\n");
+    const result = await this.perform(
+      config,
+      "run_agent",
+      {
+        workspace: conversation.workspace,
+        agent: conversation.agent,
+        prompt,
+      },
+      dryRun,
+    );
+    return result.output ?? result.message ?? "";
+  }
+}

package/src/orchestrator.ts

@@ -0,0 +1,271 @@
+import path from "node:path";
+import { homedir } from "node:os";
+import { mkdir, access, copyFile, writeFile, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { validateReply } from "./assertions.js";
+import { ClawChefError } from "./errors.js";
+import { Logger } from "./logger.js";
+import { createProvider } from "./openclaw/factory.js";
+import type { Recipe, RunOptions } from "./types.js";
+import type { RecipeOrigin } from "./recipe.js";
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function truncateForLog(text: string, maxLength = 500): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength)}... [truncated ${text.length - maxLength} chars]`;
+}
+
+function resolveWorkspacePath(recipeOrigin: RecipeOrigin, name: string, configuredPath?: string): string {
+  if (configuredPath?.trim()) {
+    if (path.isAbsolute(configuredPath)) {
+      return configuredPath;
+    }
+    if (recipeOrigin.kind === "local") {
+      return path.resolve(recipeOrigin.recipeDir, configuredPath);
+    }
+    return path.resolve(configuredPath);
+  }
+  return path.join(homedir(), ".openclaw", "workspaces", name);
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function resolveFileRef(recipeOrigin: RecipeOrigin, reference: string): { kind: "local" | "url"; value: string } {
+  if (isHttpUrl(reference)) {
+    return { kind: "url", value: reference };
+  }
+  if (path.isAbsolute(reference)) {
+    return { kind: "local", value: reference };
+  }
+  if (recipeOrigin.kind === "local") {
+    return { kind: "local", value: path.resolve(recipeOrigin.recipeDir, reference) };
+  }
+  return { kind: "url", value: new URL(reference, recipeOrigin.recipeUrl).toString() };
+}
+
+async function readTextFromRef(recipeOrigin: RecipeOrigin, reference: string): Promise<string> {
+  const resolved = resolveFileRef(recipeOrigin, reference);
+  if (resolved.kind === "local") {
+    return readFile(resolved.value, "utf8");
+  }
+  const response = await fetch(resolved.value);
+  if (!response.ok) {
+    throw new ClawChefError(`Failed to fetch file content from ${resolved.value}: HTTP ${response.status}`);
+  }
+  return response.text();
+}
+
+async function readBinaryFromRef(recipeOrigin: RecipeOrigin, reference: string): Promise<Buffer> {
+  const resolved = resolveFileRef(recipeOrigin, reference);
+  if (resolved.kind === "local") {
+    return readFile(resolved.value);
+  }
+  const response = await fetch(resolved.value);
+  if (!response.ok) {
+    throw new ClawChefError(`Failed to fetch file source from ${resolved.value}: HTTP ${response.status}`);
+  }
+  const bytes = await response.arrayBuffer();
+  return Buffer.from(bytes);
+}
+
+async function confirmFactoryReset(options: RunOptions): Promise<boolean> {
+  if (options.silent || options.dryRun) {
+    return true;
+  }
+  if (!input.isTTY) {
+    throw new ClawChefError("Reset confirmation requires an interactive terminal. Use --silent to skip prompt.");
+  }
+
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(
+      "This run will factory-reset existing OpenClaw state before execution. Continue? [y/N] ",
+    );
+    return ["y", "yes"].includes(answer.trim().toLowerCase());
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runRecipe(
+  recipe: Recipe,
+  recipeOrigin: RecipeOrigin,
+  options: RunOptions,
+  logger: Logger,
+): Promise<void> {
+  const provider = createProvider(options);
+  const remoteMode = options.provider === "remote";
+  const workspacePaths = new Map<string, string>();
+
+  logger.info(`Running recipe: ${recipe.name}`);
+  const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent);
+  logger.info(`OpenClaw version ready: ${recipe.openclaw.version}`);
+
+  if (versionResult.installedThisRun) {
+    logger.info("OpenClaw was installed in this run; skipping factory reset");
+  } else {
+    const confirmed = await confirmFactoryReset(options);
+    if (!confirmed) {
+      throw new ClawChefError("Aborted by user before factory reset");
+    }
+    await provider.factoryReset(recipe.openclaw, options.dryRun);
+    logger.info("Factory reset completed");
+  }
+
+  for (const ws of recipe.workspaces ?? []) {
+    const absPath = resolveWorkspacePath(recipeOrigin, ws.name, ws.path);
+    workspacePaths.set(ws.name, absPath);
+    if (!options.dryRun && !remoteMode) {
+      await mkdir(absPath, { recursive: true });
+    }
+    await provider.createWorkspace(recipe.openclaw, { ...ws, path: absPath }, options.dryRun);
+    logger.info(`Workspace created: ${ws.name}`);
+  }
+
+  for (const agent of recipe.agents ?? []) {
+    const workspacePath = workspacePaths.get(agent.workspace);
+    if (!workspacePath) {
+      throw new ClawChefError(`Agent references missing workspace: ${agent.workspace}`);
+    }
+    await provider.createAgent(recipe.openclaw, agent, workspacePath, options.dryRun);
+    logger.info(`Agent created: ${agent.workspace}/${agent.name}`);
+  }
+
+  for (const channel of recipe.channels ?? []) {
+    await provider.configureChannel(recipe.openclaw, channel, options.dryRun);
+    logger.info(`Channel configured: ${channel.channel}${channel.account ? `/${channel.account}` : ""}`);
+  }
+
+  for (const file of recipe.files ?? []) {
+    const wsPath = workspacePaths.get(file.workspace);
+    if (!wsPath) {
+      throw new ClawChefError(`File target workspace does not exist: ${file.workspace}`);
+    }
+
+    if (provider.materializeFile) {
+      let content = file.content;
+      if (content === undefined && file.content_from) {
+        if (!options.dryRun) {
+          content = await readTextFromRef(recipeOrigin, file.content_from);
+        } else {
+          const resolved = resolveFileRef(recipeOrigin, file.content_from);
+          content = `__dry_run_content_from__:${resolved.value}`;
+        }
+      }
+      if (content === undefined && file.source) {
+        if (!options.dryRun) {
+          content = await readTextFromRef(recipeOrigin, file.source);
+        } else {
+          const resolved = resolveFileRef(recipeOrigin, file.source);
+          content = `__dry_run_source__:${resolved.value}`;
+        }
+      }
+      if (content === undefined) {
+        throw new ClawChefError(`File ${file.path} requires content, content_from, or source`);
+      }
+
+      await provider.materializeFile(recipe.openclaw, file.workspace, file.path, content, file.overwrite, options.dryRun);
+      logger.info(`File materialized: ${file.workspace}/${file.path}`);
+      continue;
+    }
+
+    const target = path.resolve(wsPath, file.path);
+    const targetDir = path.dirname(target);
+
+    if (!options.dryRun) {
+      await mkdir(targetDir, { recursive: true });
+      const alreadyExists = await exists(target);
+      if (alreadyExists && file.overwrite === false) {
+        logger.warn(`Skipping existing file: ${target}`);
+      } else if (file.content !== undefined) {
+        await writeFile(target, file.content, "utf8");
+      } else if (file.content_from) {
+        const content = await readTextFromRef(recipeOrigin, file.content_from);
+        await writeFile(target, content, "utf8");
+      } else if (file.source) {
+        const resolved = resolveFileRef(recipeOrigin, file.source);
+        if (resolved.kind === "local") {
+          await copyFile(resolved.value, target);
+        } else {
+          const content = await readBinaryFromRef(recipeOrigin, file.source);
+          await writeFile(target, content);
+        }
+      }
+    }
+    logger.info(`File materialized: ${file.workspace}/${file.path}`);
+  }
+
+  for (const agent of recipe.agents ?? []) {
+    for (const skill of agent.skills ?? []) {
+      await provider.installSkill(recipe.openclaw, agent.workspace, agent.name, skill, options.dryRun);
+      logger.info(`Skill installed: ${agent.workspace}/${agent.name} -> ${skill}`);
+    }
+  }
+
+  for (const conv of recipe.conversations ?? []) {
+    for (const msg of conv.messages) {
+      await provider.sendMessage(recipe.openclaw, conv, msg.content, options.dryRun);
+
+      const shouldRun = conv.run ?? Boolean(msg.expect);
+      if (shouldRun) {
+        if (options.dryRun) {
+          logger.info(`dry-run: skipping execution and output assertions: ${conv.workspace}/${conv.agent}`);
+          continue;
+        }
+        const reply = await provider.runAgent(recipe.openclaw, conv, options.dryRun);
+        if (msg.expect) {
+          try {
+            validateReply(reply, msg.expect);
+            logger.info(`Output assertions passed: ${conv.workspace}/${conv.agent}`);
+          } catch (err) {
+            logger.warn(
+              `Assertion failed reply (truncated): ${truncateForLog(reply)}`,
+            );
+            throw err;
+          }
+        } else {
+          logger.info(`Agent executed: ${conv.workspace}/${conv.agent}`);
+        }
+        logger.debug(`Agent output: ${reply}`);
+      }
+    }
+    logger.info(`Preset messages sent: ${conv.workspace}/${conv.agent}`);
+  }
+
+  await provider.startGateway(recipe.openclaw, options.dryRun);
+  logger.info("Gateway started");
+
+  for (const channel of recipe.channels ?? []) {
+    if (!channel.login) {
+      continue;
+    }
+    if (!options.dryRun && !input.isTTY) {
+      throw new ClawChefError(
+        `Channel login for ${channel.channel} requires an interactive terminal session`,
+      );
+    }
+    await provider.loginChannel(recipe.openclaw, channel, options.dryRun);
+    logger.info(`Channel login completed: ${channel.channel}${channel.account ? `/${channel.account}` : ""}`);
+  }
+
+  logger.info("Recipe execution completed");
+}