clawchef 0.1.0

package/dist/schema.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+const paramDefSchema = z.object({
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+});
+const openClawCommandsSchema = z
+    .object({
+    use_version: z.string().optional(),
+    install_version: z.string().optional(),
+    uninstall_version: z.string().optional(),
+    factory_reset: z.string().optional(),
+    start_gateway: z.string().optional(),
+    enable_plugin: z.string().optional(),
+    login_channel: z.string().optional(),
+    create_workspace: z.string().optional(),
+    create_agent: z.string().optional(),
+    install_skill: z.string().optional(),
+    send_message: z.string().optional(),
+    run_agent: z.string().optional(),
+})
+    .strict();
+const openClawBootstrapSchema = z
+    .object({
+    non_interactive: z.boolean().optional(),
+    accept_risk: z.boolean().optional(),
+    mode: z.enum(["local", "remote"]).optional(),
+    flow: z.enum(["quickstart", "advanced", "manual"]).optional(),
+    auth_choice: z.string().optional(),
+    workspace: z.string().optional(),
+    reset: z.boolean().optional(),
+    skip_channels: z.boolean().optional(),
+    skip_skills: z.boolean().optional(),
+    skip_health: z.boolean().optional(),
+    skip_ui: z.boolean().optional(),
+    skip_daemon: z.boolean().optional(),
+    install_daemon: z.boolean().optional(),
+    openai_api_key: z.string().optional(),
+    anthropic_api_key: z.string().optional(),
+    openrouter_api_key: z.string().optional(),
+    xai_api_key: z.string().optional(),
+    gemini_api_key: z.string().optional(),
+    ai_gateway_api_key: z.string().optional(),
+    cloudflare_ai_gateway_api_key: z.string().optional(),
+    cloudflare_ai_gateway_account_id: z.string().optional(),
+    cloudflare_ai_gateway_gateway_id: z.string().optional(),
+    token: z.string().optional(),
+    token_provider: z.string().optional(),
+    token_profile_id: z.string().optional(),
+})
+    .strict();
+const openClawSchema = z
+    .object({
+    bin: z.string().optional(),
+    version: z.string(),
+    install: z.enum(["auto", "always", "never"]).optional(),
+    bootstrap: openClawBootstrapSchema.optional(),
+    commands: openClawCommandsSchema.optional(),
+})
+    .strict();
+const workspaceSchema = z
+    .object({
+    name: z.string().min(1),
+    path: z.string().min(1).optional(),
+})
+    .strict();
+const channelSchema = z
+    .object({
+    channel: z.string().min(1),
+    account: z.string().min(1).optional(),
+    login: z.boolean().optional(),
+    login_mode: z.enum(["interactive"]).optional(),
+    login_account: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    token: z.string().min(1).optional(),
+    token_file: z.string().min(1).optional(),
+    use_env: z.boolean().optional(),
+    bot_token: z.string().min(1).optional(),
+    access_token: z.string().min(1).optional(),
+    app_token: z.string().min(1).optional(),
+    webhook_url: z.string().min(1).optional(),
+    webhook_path: z.string().min(1).optional(),
+    signal_number: z.string().min(1).optional(),
+    password: z.string().min(1).optional(),
+    extra_flags: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+})
+    .strict();
+const agentSchema = z
+    .object({
+    workspace: z.string().min(1),
+    name: z.string().min(1),
+    model: z.string().optional(),
+    skills: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+const fileSchema = z
+    .object({
+    workspace: z.string().min(1),
+    path: z.string().min(1),
+    content: z.string().optional(),
+    content_from: z.string().min(1).optional(),
+    source: z.string().optional(),
+    overwrite: z.boolean().optional(),
+})
+    .strict()
+    .refine((v) => [v.content, v.content_from, v.source].filter((item) => item !== undefined).length === 1, {
+    message: "files[] requires exactly one of content, content_from, or source",
+});
+const conversationExpectSchema = z
+    .object({
+    contains: z.array(z.string()).optional(),
+    not_contains: z.array(z.string()).optional(),
+    regex: z.array(z.string()).optional(),
+    equals: z.string().optional(),
+})
+    .strict();
+const messageSchema = z
+    .object({
+    content: z.string(),
+    expect: conversationExpectSchema.optional(),
+})
+    .strict();
+const conversationSchema = z
+    .object({
+    workspace: z.string().min(1),
+    agent: z.string().min(1),
+    messages: z.array(messageSchema).min(1),
+    run: z.boolean().optional(),
+})
+    .strict();
+export const recipeSchema = z
+    .object({
+    version: z.string().min(1),
+    name: z.string().min(1),
+    params: z.record(z.string(), paramDefSchema).optional(),
+    openclaw: openClawSchema,
+    workspaces: z.array(workspaceSchema).optional(),
+    channels: z.array(channelSchema).optional(),
+    agents: z.array(agentSchema).optional(),
+    files: z.array(fileSchema).optional(),
+    conversations: z.array(conversationSchema).optional(),
+})
+    .strict();

package/dist/template.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveTemplate(value: string, vars: Record<string, string>, allowMissing: boolean): string;
+export declare function deepResolveTemplates<T>(input: T, vars: Record<string, string>, allowMissing: boolean): T;

package/dist/template.js

@@ -0,0 +1,30 @@
+import { ClawChefError } from "./errors.js";
+const TOKEN_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+export function resolveTemplate(value, vars, allowMissing) {
+    return value.replace(TOKEN_RE, (_, key) => {
+        if (Object.prototype.hasOwnProperty.call(vars, key)) {
+            return vars[key];
+        }
+        if (allowMissing) {
+            return `\${${key}}`;
+        }
+        throw new ClawChefError(`Missing parameter: ${key}`);
+    });
+}
+export function deepResolveTemplates(input, vars, allowMissing) {
+    if (typeof input === "string") {
+        return resolveTemplate(input, vars, allowMissing);
+    }
+    if (Array.isArray(input)) {
+        return input.map((v) => deepResolveTemplates(v, vars, allowMissing));
+    }
+    if (input && typeof input === "object") {
+        const obj = input;
+        const out = {};
+        for (const [key, value] of Object.entries(obj)) {
+            out[key] = deepResolveTemplates(value, vars, allowMissing);
+        }
+        return out;
+    }
+    return input;
+}

package/dist/types.d.ts

@@ -0,0 +1,136 @@
+export type InstallPolicy = "auto" | "always" | "never";
+export type OpenClawProvider = "command" | "mock" | "remote";
+export interface OpenClawRemoteConfig {
+    base_url: string;
+    api_key?: string;
+    api_header?: string;
+    api_scheme?: string;
+    timeout_ms?: number;
+    operation_path?: string;
+}
+export interface ParamDef {
+    default?: string;
+    required?: boolean;
+    description?: string;
+}
+export interface OpenClawCommandOverrides {
+    use_version?: string;
+    install_version?: string;
+    uninstall_version?: string;
+    factory_reset?: string;
+    start_gateway?: string;
+    enable_plugin?: string;
+    login_channel?: string;
+    create_workspace?: string;
+    create_agent?: string;
+    install_skill?: string;
+    send_message?: string;
+    run_agent?: string;
+}
+export interface OpenClawBootstrap {
+    non_interactive?: boolean;
+    accept_risk?: boolean;
+    mode?: "local" | "remote";
+    flow?: "quickstart" | "advanced" | "manual";
+    auth_choice?: string;
+    workspace?: string;
+    reset?: boolean;
+    skip_channels?: boolean;
+    skip_skills?: boolean;
+    skip_health?: boolean;
+    skip_ui?: boolean;
+    skip_daemon?: boolean;
+    install_daemon?: boolean;
+    openai_api_key?: string;
+    anthropic_api_key?: string;
+    openrouter_api_key?: string;
+    xai_api_key?: string;
+    gemini_api_key?: string;
+    ai_gateway_api_key?: string;
+    cloudflare_ai_gateway_api_key?: string;
+    cloudflare_ai_gateway_account_id?: string;
+    cloudflare_ai_gateway_gateway_id?: string;
+    token?: string;
+    token_provider?: string;
+    token_profile_id?: string;
+}
+export interface OpenClawSection {
+    bin?: string;
+    version: string;
+    install?: InstallPolicy;
+    bootstrap?: OpenClawBootstrap;
+    commands?: OpenClawCommandOverrides;
+}
+export interface WorkspaceDef {
+    name: string;
+    path?: string;
+}
+export interface ChannelDef {
+    channel: string;
+    account?: string;
+    login?: boolean;
+    login_mode?: "interactive";
+    login_account?: string;
+    name?: string;
+    token?: string;
+    token_file?: string;
+    use_env?: boolean;
+    bot_token?: string;
+    access_token?: string;
+    app_token?: string;
+    webhook_url?: string;
+    webhook_path?: string;
+    signal_number?: string;
+    password?: string;
+    extra_flags?: Record<string, string | number | boolean>;
+}
+export interface AgentDef {
+    workspace: string;
+    name: string;
+    model?: string;
+    skills?: string[];
+}
+export interface FileDef {
+    workspace: string;
+    path: string;
+    content?: string;
+    content_from?: string;
+    source?: string;
+    overwrite?: boolean;
+}
+export interface MessageDef {
+    content: string;
+    expect?: ConversationExpectDef;
+}
+export interface ConversationExpectDef {
+    contains?: string[];
+    not_contains?: string[];
+    regex?: string[];
+    equals?: string;
+}
+export interface ConversationDef {
+    workspace: string;
+    agent: string;
+    messages: MessageDef[];
+    run?: boolean;
+}
+export interface Recipe {
+    version: string;
+    name: string;
+    params?: Record<string, ParamDef>;
+    openclaw: OpenClawSection;
+    workspaces?: WorkspaceDef[];
+    channels?: ChannelDef[];
+    agents?: AgentDef[];
+    files?: FileDef[];
+    conversations?: ConversationDef[];
+}
+export interface RunOptions {
+    vars: Record<string, string>;
+    dryRun: boolean;
+    allowMissing: boolean;
+    verbose: boolean;
+    silent: boolean;
+    provider: OpenClawProvider;
+    remote: Partial<OpenClawRemoteConfig>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "clawchef",
+  "version": "0.1.0",
+  "description": "Recipe-driven OpenClaw environment orchestrator",
+  "type": "module",
+  "main": "dist/api.js",
+  "types": "dist/api.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    }
+  },
+  "bin": {
+    "clawchef": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.13",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/recipes/content-from-sample.yaml

@@ -0,0 +1,20 @@
+version: "1"
+name: "content-from-sample"
+
+openclaw:
+  version: "1.3.2"
+  install: "auto"
+
+workspaces:
+  - name: "content-from-demo"
+
+agents:
+  - workspace: "content-from-demo"
+    name: "planner"
+    model: "gpt-5.3-codex"
+
+files:
+  - workspace: "content-from-demo"
+    path: "README.md"
+    overwrite: true
+    content_from: "./snippets/readme-template.md"

package/recipes/openclaw-from-zero.yaml

@@ -0,0 +1,45 @@
+version: "1"
+name: "openclaw-from-zero"
+
+params:
+  project_name:
+    default: "from-zero-demo"
+  openclaw_version:
+    default: "2026.2.9"
+  openai_api_key:
+    required: true
+
+openclaw:
+  bin: "openclaw"
+  version: "${openclaw_version}"
+  install: "never"
+  bootstrap:
+    auth_choice: "openai-api-key"
+    openai_api_key: "${openai_api_key}"
+    mode: "local"
+    flow: "quickstart"
+    accept_risk: true
+    non_interactive: true
+    skip_channels: true
+    skip_skills: true
+    skip_health: true
+    skip_ui: true
+    skip_daemon: true
+
+workspaces:
+  - name: "${project_name}"
+
+agents:
+  - workspace: "${project_name}"
+    name: "chef-openai"
+    model: "openai/gpt-5.3-codex"
+
+conversations:
+  - workspace: "${project_name}"
+    agent: "chef-openai"
+    run: true
+    messages:
+      - content: "Say hello in one sentence."
+        expect:
+          contains:
+            - "hello"

package/recipes/openclaw-local.yaml

@@ -0,0 +1,65 @@
+version: "1"
+name: "openclaw-local-demo"
+
+params:
+  project_name:
+    default: "openclaw-local-demo"
+  openclaw_version:
+    default: "2026.2.9"
+  openai_api_key:
+    required: true
+  telegram_bot_token:
+    required: true
+  user_name:
+    required: true
+  agent_name:
+    required: true
+
+openclaw:
+  bin: "openclaw"
+  version: "${openclaw_version}"
+  install: "never"
+  bootstrap:
+    auth_choice: "openai-api-key"
+    openai_api_key: "${openai_api_key}"
+    mode: "local"
+    flow: "quickstart"
+    accept_risk: true
+    non_interactive: true
+    skip_channels: true
+    skip_skills: true
+    skip_health: true
+    skip_ui: true
+    skip_daemon: true
+
+workspaces:
+  - name: "${project_name}"
+
+agents:
+  - workspace: "${project_name}"
+    name: "chef-openai"
+    model: "openai/gpt-5.3-codex"
+
+files:
+  - workspace: "${project_name}"
+    path: "README.md"
+    overwrite: true
+    content: |
+      # ${project_name}
+      Generated by clawchef.
+
+channels:
+  - channel: "telegram"
+    token: "${telegram_bot_token}"
+    account: "default"
+    login: true
+
+conversations:
+  - workspace: "${project_name}"
+    agent: "chef-openai"
+    run: true
+    messages:
+      - content: "I'm ${user_name}, you're ${agent_name}."
+        expect:
+          contains:
+            - "${user_name}"

package/recipes/openclaw-remote-http.yaml

@@ -0,0 +1,38 @@
+version: "1"
+name: "openclaw-remote-http-demo"
+
+params:
+  project_name:
+    default: "remote-http-demo"
+  openclaw_version:
+    default: "2026.2.9"
+
+openclaw:
+  version: "${openclaw_version}"
+  install: "never"
+
+workspaces:
+  - name: "${project_name}"
+
+agents:
+  - workspace: "${project_name}"
+    name: "chef-openai"
+    model: "openai/gpt-5.3-codex"
+
+files:
+  - workspace: "${project_name}"
+    path: "README.md"
+    overwrite: true
+    content: |
+      # ${project_name}
+      Managed by clawchef remote HTTP provider.
+
+conversations:
+  - workspace: "${project_name}"
+    agent: "chef-openai"
+    run: true
+    messages:
+      - content: "Say hello in one sentence."
+        expect:
+          contains:
+            - "hello"

package/recipes/openclaw-telegram-mock.yaml

@@ -0,0 +1,22 @@
+version: "1"
+name: "openclaw-telegram-mock-channel"
+
+params:
+  openclaw_version:
+    default: "2026.2.9"
+  telegram_mock_api_key:
+    required: true
+
+openclaw:
+  bin: "openclaw"
+  version: "${openclaw_version}"
+  install: "never"
+
+channels:
+  - channel: "telegram-mock"
+    account: "testbot"
+    token: "${telegram_mock_api_key}"
+    extra_flags:
+      mock_bind: "127.0.0.1:18790"
+      mock_api_key: "${telegram_mock_api_key}"
+      mode: "webhook"

package/recipes/openclaw-telegram.yaml

@@ -0,0 +1,19 @@
+version: "1"
+name: "openclaw-telegram-channel"
+
+params:
+  openclaw_version:
+    default: "2026.2.9"
+  telegram_bot_token:
+    required: true
+
+openclaw:
+  bin: "openclaw"
+  version: "${openclaw_version}"
+  install: "never"
+
+channels:
+  - channel: "telegram"
+    token: "${telegram_bot_token}"
+    account: "default"
+    login: true

package/recipes/sample.yaml

@@ -0,0 +1,49 @@
+version: "1"
+name: "demo-run"
+
+params:
+  project_name:
+    default: "demo-app"
+  openclaw_version:
+    default: "1.3.2"
+  telegram_bot_token:
+    default: "mock-telegram-token"
+
+openclaw:
+  version: "${openclaw_version}"
+  install: "auto"
+
+workspaces:
+  - name: "${project_name}"
+
+channels:
+  - channel: "telegram"
+    token: "${telegram_bot_token}"
+    account: "default"
+
+agents:
+  - workspace: "${project_name}"
+    name: "planner"
+    model: "gpt-5.3-codex"
+    skills: ["repo-explore", "code-review"]
+
+files:
+  - workspace: "${project_name}"
+    path: "README.md"
+    overwrite: true
+    content: |
+      # ${project_name}
+      Generated by clawchef.
+
+conversations:
+  - workspace: "${project_name}"
+    agent: "planner"
+    run: true
+    messages:
+      - content: "You are a strict software planning assistant."
+      - content: "Please provide a 3-step plan."
+        expect:
+          contains:
+            - "mock-reply"
+          regex:
+            - "[Pp]lan"

package/recipes/snippets/readme-template.md

@@ -0,0 +1,3 @@
+# content-from-demo
+
+This content is loaded from a referenced file.

package/src/api.ts

@@ -0,0 +1,65 @@
+import YAML from "js-yaml";
+import { ClawChefError } from "./errors.js";
+import { importDotEnvFromCwd } from "./env.js";
+import { Logger } from "./logger.js";
+import { runRecipe } from "./orchestrator.js";
+import { loadRecipe, loadRecipeText } from "./recipe.js";
+import { recipeSchema } from "./schema.js";
+import type { OpenClawProvider, OpenClawRemoteConfig, RunOptions } from "./types.js";
+
+export interface CookOptions {
+  vars?: Record<string, string>;
+  dryRun?: boolean;
+  allowMissing?: boolean;
+  verbose?: boolean;
+  silent?: boolean;
+  provider?: OpenClawProvider;
+  remote?: Partial<OpenClawRemoteConfig>;
+  loadDotEnvFromCwd?: boolean;
+}
+
+function normalizeCookOptions(options: CookOptions): RunOptions {
+  return {
+    vars: options.vars ?? {},
+    dryRun: Boolean(options.dryRun),
+    allowMissing: Boolean(options.allowMissing),
+    verbose: Boolean(options.verbose),
+    silent: options.silent ?? true,
+    provider: options.provider ?? "command",
+    remote: options.remote ?? {},
+  };
+}
+
+export async function cook(recipeRef: string, options: CookOptions = {}): Promise<void> {
+  if (options.loadDotEnvFromCwd ?? true) {
+    importDotEnvFromCwd();
+  }
+
+  const runOptions = normalizeCookOptions(options);
+  const logger = new Logger(runOptions.verbose);
+  const loaded = await loadRecipe(recipeRef, runOptions);
+  try {
+    await runRecipe(loaded.recipe, loaded.origin, runOptions, logger);
+  } finally {
+    if (loaded.cleanup) {
+      await loaded.cleanup();
+    }
+  }
+}
+
+export async function validate(recipeRef: string): Promise<void> {
+  const loaded = await loadRecipeText(recipeRef);
+  try {
+    const raw = YAML.load(loaded.source);
+    const result = recipeSchema.safeParse(raw);
+    if (!result.success) {
+      throw new ClawChefError(`Validation failed: ${result.error.message}`);
+    }
+  } finally {
+    if (loaded.cleanup) {
+      await loaded.cleanup();
+    }
+  }
+}
+
+export type { OpenClawProvider, OpenClawRemoteConfig };