clawchef 0.1.1 → 0.1.3

package/README.md

@@ -14,10 +14,12 @@ Recipe-driven OpenClaw environment orchestrator.
 - Always runs factory reset first (with confirmation prompt unless `-s/--silent` is used).
 - If `openclaw` is missing, auto-installs the recipe version and skips factory reset.
 - Starts OpenClaw gateway service after each recipe execution.
-- Creates workspaces and agents (default workspace path: `~/.openclaw/workspaces/<workspace-name>`).
+- Creates workspaces and agents (default workspace path: `~/.openclaw/workspace-<workspace-name>`).
+- Supports workspace-level assets copy via `workspaces[].assets`.
 - Materializes files into target workspaces.
 - Installs skills.
 - Supports plugin preinstall via `openclaw.plugins[]` and runtime `--plugin` flags.
+- Supports preserving existing OpenClaw state via `--keep-openclaw-state` (skip factory reset).
 - Configures channels with `openclaw channels add`.
 - Supports interactive channel login at the end of execution (`channels[].login: true`) for channels that expose login.
 - Supports remote HTTP orchestration via runtime flags (`--provider remote`) when OpenClaw is reachable via API.
@@ -34,20 +36,20 @@ clawchef cook recipes/sample.yaml
 Run recipe from URL:
 
 ```bash
-clawchef cook https://example.com/recipes/sample.yaml --provider remote -s
+clawchef cook https://example.com/recipes/sample.yaml --provider remote
 ```
 
 Run recipe from archive (default `recipe.yaml`):
 
 ```bash
-clawchef cook ./bundle.tgz --provider mock -s
+clawchef cook ./bundle.tgz --provider mock
 ```
 
 Run specific recipe in directory or archive:
 
 ```bash
-clawchef cook ./recipes-pack:team/recipe-prod.yaml --provider remote -s
-clawchef cook https://example.com/recipes-pack.zip:team/recipe-prod.yaml --provider remote -s
+clawchef cook ./recipes-pack:team/recipe-prod.yaml --provider remote
+clawchef cook https://example.com/recipes-pack.zip:team/recipe-prod.yaml --provider remote
 ```
 
 Dev mode:
@@ -59,13 +61,13 @@ clawchef cook recipes/sample.yaml --verbose
 Run sample with mock provider:
 
 ```bash
-clawchef cook recipes/sample.yaml --provider mock -s
+clawchef cook recipes/sample.yaml --provider mock
 ```
 
 Run `content_from` sample:
 
 ```bash
-clawchef cook recipes/content-from-sample.yaml --provider mock -s
+clawchef cook recipes/content-from-sample.yaml --provider mock
 ```
 
 Skip reset confirmation prompt:
@@ -74,6 +76,15 @@ Skip reset confirmation prompt:
 clawchef cook recipes/sample.yaml -s
 ```
 
+Warning: `-s/--silent` suppresses the factory-reset confirmation and auto-chooses force reinstall on version mismatch.
+Use it only in CI/non-interactive flows where destructive reset behavior is expected.
+
+Keep existing OpenClaw state (skip reset and keep current version on mismatch):
+
+```bash
+clawchef cook recipes/sample.yaml --keep-openclaw-state
+```
+
 From-zero OpenClaw bootstrap (recommended):
 
 ```bash
@@ -83,19 +94,19 @@ CLAWCHEF_VAR_OPENAI_API_KEY=sk-... clawchef cook recipes/openclaw-from-zero.yaml
 Telegram channel setup only:
 
 ```bash
-CLAWCHEF_VAR_TELEGRAM_BOT_TOKEN=123456:abc... clawchef cook recipes/openclaw-telegram.yaml -s
+CLAWCHEF_VAR_TELEGRAM_BOT_TOKEN=123456:abc... clawchef cook recipes/openclaw-telegram.yaml
 ```
 
 Telegram mock channel setup (for tests):
 
 ```bash
-CLAWCHEF_VAR_TELEGRAM_MOCK_API_KEY=test-key clawchef cook recipes/openclaw-telegram-mock.yaml -s
+CLAWCHEF_VAR_TELEGRAM_MOCK_API_KEY=test-key clawchef cook recipes/openclaw-telegram-mock.yaml
 ```
 
 Install plugin only for this run:
 
 ```bash
-clawchef cook recipes/openclaw-telegram-mock.yaml --plugin openclaw-telegram-mock-channel -s
+clawchef cook recipes/openclaw-telegram-mock.yaml --plugin openclaw-telegram-mock-channel
 ```
 
 Remote HTTP orchestration:
@@ -103,7 +114,7 @@ Remote HTTP orchestration:
 ```bash
 CLAWCHEF_REMOTE_BASE_URL=https://remote-openclaw.example.com \
 CLAWCHEF_REMOTE_API_KEY=secret-token \
-clawchef cook recipes/openclaw-remote-http.yaml --provider remote -s --verbose
+clawchef cook recipes/openclaw-remote-http.yaml --provider remote --verbose
 ```
 
 Validate recipe structure only:
@@ -138,9 +149,9 @@ clawchef scaffold ./my-recipe-project --name meetingbot
 Scaffold output:
 
 - `package.json` with `telegram-api-mock-server` in `devDependencies`
-- `src/recipe.yaml` with `telegram-mock` channel and plugin preinstall
-- `src/<project-name>-assets/{AGENTS.md,IDENTITY.md,SOUL.md,TOOLS.md}`
-- `src/<project-name>-assets/scripts/scheduling.mjs`
+- `recipe.yaml` with `telegram-mock` channel, plugin preinstall, and `workspaces[].assets`
+- `assets/{AGENTS.md,IDENTITY.md,SOUL.md,TOOLS.md}`
+- `assets/scripts/scheduling.mjs`
 - `test/recipe-smoke.test.mjs`
 
 By default scaffold only writes files; it does not run `npm install`.
@@ -177,11 +188,14 @@ await scaffold("./my-recipe-project", {
 - `silent` (default: `true` in Node API)
 - `loadDotEnvFromCwd` (default: `true`)
 
+Node API `silent: true` has the same risk as CLI `-s`: no reset confirmation and force reinstall on version mismatch.
+Set `silent: false` when you want an interactive safety prompt.
+
 Notes:
 
 - `validate()` throws on invalid recipe.
 - `cook()` throws on runtime/configuration errors.
-- `scaffold()` creates `package.json`, `src/recipe.yaml`, `src/<project-name>-assets`, and `test/`.
+- `scaffold()` creates `package.json`, `recipe.yaml`, `assets/`, and `test/`.
 
 ## Variable precedence
 
@@ -243,7 +257,7 @@ Request payload format (POST):
   "payload": {
     "workspace": {
       "name": "demo",
-      "path": "/home/runner/.openclaw/workspaces/demo"
+      "path": "/home/runner/.openclaw/workspace-demo"
     }
   }
 }
@@ -356,54 +370,27 @@ Supported common fields:
 - optional: `account`, `name`, `token`, `token_file`, `use_env`, `bot_token`, `access_token`, `app_token`, `webhook_url`, `webhook_path`, `signal_number`, `password`, `login`, `login_mode`, `login_account`
 - advanced passthrough: `extra_flags` (`snake_case` keys become `--kebab-case` CLI flags)
 
-### Telegram mock channel (for recipe tests)
-
-Use `channel: "telegram-mock"` when you need to test Telegram-related recipe flows without connecting to the real Telegram network.
-
-`clawchef` treats `telegram-mock` like any other channel and passes mock-specific flags through `extra_flags`.
-
-Example:
-
-```yaml
-params:
-  telegram_mock_api_key:
-    required: true
-
-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"
-```
-
-Typical test setup:
-
-- Start OpenClaw with the telegram-mock plugin enabled.
-- Run `clawchef cook ...` to configure workspaces/agents/channels.
-- Use your external test program (HTTP API or Node.js SDK) to inject inbound mock messages and assert outbound events.
-
-Login fields:
-
-- `login: true` enables channel login step
-- `login_mode`: currently supports `interactive`
-- `login_account`: override account used for login (defaults to `account`)
-
-Security rules:
-
-- Do not inline secret values in `channels[]`.
-- Use `${var}` placeholders and inject values via `--var` / `CLAWCHEF_VAR_*`.
-
 ## Workspace path behavior
 
 - `workspaces[].path` is optional.
-- If omitted, clawchef uses `~/.openclaw/workspaces/<workspace-name>`.
+- If omitted, clawchef uses `~/.openclaw/workspace-<workspace-name>`.
+- `workspaces[].assets` is optional.
+- If `assets` is set, clawchef recursively copies files from that directory into the workspace root.
+- `assets` is resolved relative to the recipe file path (unless absolute path is given).
+- `files[]` runs after assets copy, so `files[]` can override copied asset files.
+- Direct URL recipes do not support `workspaces[].assets` (assets must resolve to a local directory).
 - If provided, relative paths are resolved from the recipe file directory.
 - For direct URL recipe files, relative workspace paths are resolved from the current working directory.
 - For directory/archive recipe references, relative workspace paths are resolved from the selected recipe file directory.
 
+Example:
+
+```yaml
+workspaces:
+  - name: "workspace-meeting"
+    assets: "./meetingbot-assets"
+```
+
 ## File content references
 
 In `files[]`, set exactly one of:

package/dist/api.js

@@ -15,6 +15,7 @@ function normalizeCookOptions(options) {
         allowMissing: Boolean(options.allowMissing),
         verbose: Boolean(options.verbose),
         silent: options.silent ?? true,
+        keepOpenClawState: false,
         provider: options.provider ?? "command",
         remote: options.remote ?? {},
     };

package/dist/cli.js

@@ -77,6 +77,7 @@ export function buildCli() {
         .option("--allow-missing", "Allow unresolved template variables", false)
         .option("--verbose", "Verbose logging", false)
         .option("-s, --silent", "Skip reset confirmation prompt", false)
+        .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
         .option("--provider <provider>", "Execution provider: command | remote | mock")
         .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p) => p.concat([v]), [])
         .option("--remote-base-url <url>", "Remote OpenClaw API base URL")
@@ -94,6 +95,7 @@ export function buildCli() {
             allowMissing: Boolean(opts.allowMissing),
             verbose: Boolean(opts.verbose),
             silent: Boolean(opts.silent),
+            keepOpenClawState: Boolean(opts.keepOpenclawState),
             provider,
             remote: {
                 base_url: opts.remoteBaseUrl ?? readEnv("CLAWCHEF_REMOTE_BASE_URL"),

package/dist/openclaw/command-provider.d.ts

@@ -2,7 +2,7 @@ import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class CommandOpenClawProvider implements OpenClawProvider {
     private readonly stagedMessages;
-    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/dist/openclaw/command-provider.js

@@ -221,7 +221,7 @@ function bootstrapRuntimeEnv(bootstrap) {
 }
 export class CommandOpenClawProvider {
     stagedMessages = new Map();
-    async ensureVersion(config, dryRun, silent) {
+    async ensureVersion(config, dryRun, silent, keepOpenClawState) {
         const bin = config.bin ?? "openclaw";
         const installPolicy = config.install ?? "auto";
         const useCmd = commandFor(config, "use_version", { bin, version: config.version });
@@ -272,6 +272,9 @@ export class CommandOpenClawProvider {
         if (installedThisRun) {
             throw new ClawChefError(`OpenClaw version mismatch after install: current ${currentVersion}, expected ${config.version}`);
         }
+        if (keepOpenClawState) {
+            return { installedThisRun: false };
+        }
         const choice = await chooseVersionMismatchAction(currentVersion, config.version, silent);
         if (choice === "ignore") {
             return { installedThisRun: false };

package/dist/openclaw/mock-provider.d.ts

@@ -2,7 +2,7 @@ import type { AgentDef, ChannelDef, ConversationDef, OpenClawSection } from "../
 import type { EnsureVersionResult, OpenClawProvider, ResolvedWorkspaceDef } from "./provider.js";
 export declare class MockOpenClawProvider implements OpenClawProvider {
     private state;
-    ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean, _keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     installPlugin(_config: OpenClawSection, _pluginSpec: string, _dryRun: boolean): Promise<void>;
     factoryReset(_config: OpenClawSection, _dryRun: boolean): Promise<void>;
     startGateway(_config: OpenClawSection, _dryRun: boolean): Promise<void>;

package/dist/openclaw/mock-provider.js

@@ -7,7 +7,7 @@ export class MockOpenClawProvider {
         skills: new Set(),
         messages: new Map(),
     };
-    async ensureVersion(config, _dryRun, _silent) {
+    async ensureVersion(config, _dryRun, _silent, _keepOpenClawState) {
         const policy = config.install ?? "auto";
         const installed = this.state.installedVersions.has(config.version);
         let installedThisRun = false;

package/dist/openclaw/provider.d.ts

@@ -6,7 +6,7 @@ export interface EnsureVersionResult {
     installedThisRun: boolean;
 }
 export interface OpenClawProvider {
-    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean, keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.d.ts

@@ -5,7 +5,7 @@ export declare class RemoteOpenClawProvider implements OpenClawProvider {
     private readonly remoteConfig;
     constructor(remoteConfig: Partial<OpenClawRemoteConfig>);
     private perform;
-    ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult>;
+    ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean, _keepOpenClawState: boolean): Promise<EnsureVersionResult>;
     installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
     factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
     startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/dist/openclaw/remote-provider.js

@@ -94,7 +94,7 @@ export class RemoteOpenClawProvider {
             clearTimeout(timeout);
         }
     }
-    async ensureVersion(config, dryRun, _silent) {
+    async ensureVersion(config, dryRun, _silent, _keepOpenClawState) {
         const result = await this.perform(config, "ensure_version", {
             install: config.install,
         }, dryRun);

package/dist/orchestrator.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { homedir } from "node:os";
-import { mkdir, access, copyFile, writeFile, readFile } from "node:fs/promises";
+import { mkdir, access, copyFile, writeFile, readFile, readdir, stat } 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";
@@ -32,7 +32,9 @@ function resolveWorkspacePath(recipeOrigin, name, configuredPath) {
         }
         return path.resolve(configuredPath);
     }
-    return path.join(homedir(), ".openclaw", "workspaces", name);
+    const trimmedName = name.trim() || name;
+    const workspaceName = trimmedName.startsWith("workspace-") ? trimmedName : `workspace-${trimmedName}`;
+    return path.join(homedir(), ".openclaw", workspaceName);
 }
 function isHttpUrl(value) {
     try {
@@ -78,6 +80,27 @@ async function readBinaryFromRef(recipeOrigin, reference) {
     const bytes = await response.arrayBuffer();
     return Buffer.from(bytes);
 }
+async function collectLocalAssetFiles(rootDir, relDir = "") {
+    const currentDir = relDir ? path.join(rootDir, relDir) : rootDir;
+    const entries = await readdir(currentDir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+        const nextRel = relDir ? path.join(relDir, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            out.push(...await collectLocalAssetFiles(rootDir, nextRel));
+            continue;
+        }
+        if (entry.isFile()) {
+            out.push({
+                absolutePath: path.join(rootDir, nextRel),
+                relativePath: nextRel,
+            });
+            continue;
+        }
+        throw new ClawChefError(`Unsupported entry in assets directory: ${path.join(rootDir, nextRel)}`);
+    }
+    return out;
+}
 async function confirmFactoryReset(options) {
     if (options.silent || options.dryRun) {
         return true;
@@ -99,11 +122,14 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
     const remoteMode = options.provider === "remote";
     const workspacePaths = new Map();
     logger.info(`Running recipe: ${recipe.name}`);
-    const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent);
+    const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent, options.keepOpenClawState);
     logger.info(`OpenClaw version ready: ${recipe.openclaw.version}`);
     if (versionResult.installedThisRun) {
         logger.info("OpenClaw was installed in this run; skipping factory reset");
     }
+    else if (options.keepOpenClawState) {
+        logger.info("Keeping existing OpenClaw state; skipping factory reset");
+    }
     else {
         const confirmed = await confirmFactoryReset(options);
         if (!confirmed) {
@@ -126,6 +152,39 @@ export async function runRecipe(recipe, recipeOrigin, options, logger) {
         }
         await provider.createWorkspace(recipe.openclaw, { ...ws, path: absPath }, options.dryRun);
         logger.info(`Workspace created: ${ws.name}`);
+        if (!ws.assets?.trim()) {
+            continue;
+        }
+        const resolvedAssets = resolveFileRef(recipeOrigin, ws.assets);
+        if (resolvedAssets.kind !== "local") {
+            throw new ClawChefError(`Workspace assets must resolve to a local directory: ${ws.assets}. Direct URL recipes cannot use workspaces[].assets.`);
+        }
+        let assetDirStat;
+        try {
+            assetDirStat = await stat(resolvedAssets.value);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new ClawChefError(`Workspace assets path is not accessible: ${resolvedAssets.value} (${message})`);
+        }
+        if (!assetDirStat.isDirectory()) {
+            throw new ClawChefError(`Workspace assets must be a directory: ${resolvedAssets.value}`);
+        }
+        const assetFiles = await collectLocalAssetFiles(resolvedAssets.value);
+        for (const assetFile of assetFiles) {
+            if (provider.materializeFile) {
+                const content = await readFile(assetFile.absolutePath, "utf8");
+                await provider.materializeFile(recipe.openclaw, ws.name, assetFile.relativePath, content, true, options.dryRun);
+            }
+            else {
+                const target = path.resolve(absPath, assetFile.relativePath);
+                if (!options.dryRun) {
+                    await mkdir(path.dirname(target), { recursive: true });
+                    await copyFile(assetFile.absolutePath, target);
+                }
+            }
+            logger.info(`Workspace asset copied: ${ws.name}/${assetFile.relativePath}`);
+        }
     }
     for (const agent of recipe.agents ?? []) {
         const workspacePath = workspacePaths.get(agent.workspace);

package/dist/recipe.js

@@ -125,6 +125,11 @@ function collectVars(recipe, cliVars) {
 }
 function semanticValidate(recipe) {
     const ws = new Set((recipe.workspaces ?? []).map((w) => w.name));
+    for (const workspace of recipe.workspaces ?? []) {
+        if (workspace.assets !== undefined && !workspace.assets.trim()) {
+            throw new ClawChefError(`Workspace ${workspace.name} has empty assets path`);
+        }
+    }
     for (const agent of recipe.agents ?? []) {
         if (!ws.has(agent.workspace)) {
             throw new ClawChefError(`Agent ${agent.name} references missing workspace: ${agent.workspace}`);

package/dist/scaffold.js

@@ -76,38 +76,13 @@ openclaw:
 
 workspaces:
   - name: "\${workspace_name}"
+    assets: "./assets"
 
 agents:
   - workspace: "\${workspace_name}"
     name: "\${agent_name}"
     model: "\${agent_model}"
 
-files:
-  - workspace: "\${workspace_name}"
-    path: "AGENTS.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/AGENTS.md"
-
-  - workspace: "\${workspace_name}"
-    path: "IDENTITY.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/IDENTITY.md"
-
-  - workspace: "\${workspace_name}"
-    path: "SOUL.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/SOUL.md"
-
-  - workspace: "\${workspace_name}"
-    path: "TOOLS.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/TOOLS.md"
-
-  - workspace: "\${workspace_name}"
-    path: "scripts/scheduling.mjs"
-    overwrite: true
-    content_from: "./${projectName}-assets/scripts/scheduling.mjs"
-
 channels:
   - channel: "telegram-mock"
     account: "default"
@@ -159,11 +134,17 @@ console.log("[scheduling] " + message);
 function makeRecipeSmokeTest() {
     return `import test from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { access } from "node:fs/promises";
 
+const testDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(testDir, "..");
+
 test("recipe scaffold files exist", async () => {
-  await access("src/recipe.yaml");
-  await access("package.json");
+  await access(path.join(projectRoot, "recipe.yaml"));
+  await access(path.join(projectRoot, "assets", "AGENTS.md"));
+  await access(path.join(projectRoot, "package.json"));
   assert.ok(true);
 });
 `;
@@ -174,16 +155,14 @@ export async function scaffoldProject(targetDirArg, options = {}) {
     const defaultName = path.basename(targetDir);
     const rawProjectName = options.projectName?.trim() || defaultName;
     const projectName = normalizeProjectName(rawProjectName);
-    const srcDir = path.join(targetDir, "src");
-    const assetsDir = path.join(srcDir, `${projectName}-assets`);
+    const assetsDir = path.join(targetDir, "assets");
     const assetsScriptsDir = path.join(assetsDir, "scripts");
     const testDir = path.join(targetDir, "test");
-    await mkdir(srcDir, { recursive: true });
     await mkdir(assetsDir, { recursive: true });
     await mkdir(assetsScriptsDir, { recursive: true });
     await mkdir(testDir, { recursive: true });
     await writeFile(path.join(targetDir, "package.json"), makePackageJson(projectName), "utf8");
-    await writeFile(path.join(srcDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
+    await writeFile(path.join(targetDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
     await writeFile(path.join(assetsDir, "AGENTS.md"), makeAgentsDoc(projectName), "utf8");
     await writeFile(path.join(assetsDir, "IDENTITY.md"), makeIdentityDoc(projectName), "utf8");
     await writeFile(path.join(assetsDir, "SOUL.md"), makeSoulDoc(), "utf8");

package/dist/schema.d.ts

@@ -240,12 +240,15 @@ export declare const recipeSchema: z.ZodObject<{
     workspaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         path: z.ZodOptional<z.ZodString>;
+        assets: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         name: string;
         path?: string | undefined;
+        assets?: string | undefined;
     }, {
         name: string;
         path?: string | undefined;
+        assets?: string | undefined;
     }>, "many">>;
     channels: z.ZodOptional<z.ZodArray<z.ZodObject<{
         channel: z.ZodString;
@@ -479,6 +482,7 @@ export declare const recipeSchema: z.ZodObject<{
     workspaces?: {
         name: string;
         path?: string | undefined;
+        assets?: string | undefined;
     }[] | undefined;
     channels?: {
         channel: string;
@@ -586,6 +590,7 @@ export declare const recipeSchema: z.ZodObject<{
     workspaces?: {
         name: string;
         path?: string | undefined;
+        assets?: string | undefined;
     }[] | undefined;
     channels?: {
         channel: string;

package/dist/schema.js

@@ -64,6 +64,7 @@ const workspaceSchema = z
     .object({
     name: z.string().min(1),
     path: z.string().min(1).optional(),
+    assets: z.string().min(1).optional(),
 })
     .strict();
 const channelSchema = z

package/dist/types.d.ts

@@ -66,6 +66,7 @@ export interface OpenClawSection {
 export interface WorkspaceDef {
     name: string;
     path?: string;
+    assets?: string;
 }
 export interface ChannelDef {
     channel: string;
@@ -134,6 +135,7 @@ export interface RunOptions {
     allowMissing: boolean;
     verbose: boolean;
     silent: boolean;
+    keepOpenClawState: boolean;
     provider: OpenClawProvider;
     remote: Partial<OpenClawRemoteConfig>;
 }

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "clawchef",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Recipe-driven OpenClaw environment orchestrator",
+  "homepage": "https://renorzr.github.io/clawchef",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/renorzr/clawchef.git"
+  },
+  "bugs": {
+    "url": "https://github.com/renorzr/clawchef/issues"
+  },
   "type": "module",
   "main": "dist/api.js",
   "types": "dist/api.d.ts",

package/src/api.ts

@@ -30,6 +30,7 @@ function normalizeCookOptions(options: CookOptions): RunOptions {
     allowMissing: Boolean(options.allowMissing),
     verbose: Boolean(options.verbose),
     silent: options.silent ?? true,
+    keepOpenClawState: false,
     provider: options.provider ?? "command",
     remote: options.remote ?? {},
   };

package/src/cli.ts

@@ -87,6 +87,7 @@ export function buildCli(): Command {
     .option("--allow-missing", "Allow unresolved template variables", false)
     .option("--verbose", "Verbose logging", false)
     .option("-s, --silent", "Skip reset confirmation prompt", false)
+    .option("--keep-openclaw-state", "Preserve existing OpenClaw state (skip factory reset)", false)
     .option("--provider <provider>", "Execution provider: command | remote | mock")
     .option("--plugin <npm-spec>", "Preinstall plugin package (repeatable)", (v, p: string[]) => p.concat([v]), [])
     .option("--remote-base-url <url>", "Remote OpenClaw API base URL")
@@ -104,6 +105,7 @@ export function buildCli(): Command {
         allowMissing: Boolean(opts.allowMissing),
         verbose: Boolean(opts.verbose),
         silent: Boolean(opts.silent),
+        keepOpenClawState: Boolean(opts.keepOpenclawState),
         provider,
         remote: {
           base_url: opts.remoteBaseUrl ?? readEnv("CLAWCHEF_REMOTE_BASE_URL"),

package/src/openclaw/command-provider.ts

@@ -273,7 +273,12 @@ function bootstrapRuntimeEnv(bootstrap: OpenClawBootstrap | undefined): Record<s
 export class CommandOpenClawProvider implements OpenClawProvider {
   private readonly stagedMessages = new Map<string, StagedMessage[]>();
 
-  async ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult> {
+  async ensureVersion(
+    config: OpenClawSection,
+    dryRun: boolean,
+    silent: boolean,
+    keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult> {
     const bin = config.bin ?? "openclaw";
     const installPolicy = config.install ?? "auto";
     const useCmd = commandFor(config, "use_version", { bin, version: config.version });
@@ -338,6 +343,10 @@ export class CommandOpenClawProvider implements OpenClawProvider {
       );
     }
 
+    if (keepOpenClawState) {
+      return { installedThisRun: false };
+    }
+
     const choice = await chooseVersionMismatchAction(currentVersion, config.version, silent);
 
     if (choice === "ignore") {

package/src/openclaw/mock-provider.ts

@@ -21,7 +21,12 @@ export class MockOpenClawProvider implements OpenClawProvider {
     messages: new Map(),
   };
 
-  async ensureVersion(config: OpenClawSection, _dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult> {
+  async ensureVersion(
+    config: OpenClawSection,
+    _dryRun: boolean,
+    _silent: boolean,
+    _keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult> {
     const policy = config.install ?? "auto";
     const installed = this.state.installedVersions.has(config.version);
     let installedThisRun = false;

package/src/openclaw/provider.ts

@@ -7,7 +7,12 @@ export interface EnsureVersionResult {
 }
 
 export interface OpenClawProvider {
-  ensureVersion(config: OpenClawSection, dryRun: boolean, silent: boolean): Promise<EnsureVersionResult>;
+  ensureVersion(
+    config: OpenClawSection,
+    dryRun: boolean,
+    silent: boolean,
+    keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult>;
   installPlugin(config: OpenClawSection, pluginSpec: string, dryRun: boolean): Promise<void>;
   factoryReset(config: OpenClawSection, dryRun: boolean): Promise<void>;
   startGateway(config: OpenClawSection, dryRun: boolean): Promise<void>;

package/src/openclaw/remote-provider.ts

@@ -141,7 +141,12 @@ export class RemoteOpenClawProvider implements OpenClawProvider {
     }
   }
 
-  async ensureVersion(config: OpenClawSection, dryRun: boolean, _silent: boolean): Promise<EnsureVersionResult> {
+  async ensureVersion(
+    config: OpenClawSection,
+    dryRun: boolean,
+    _silent: boolean,
+    _keepOpenClawState: boolean,
+  ): Promise<EnsureVersionResult> {
     const result = await this.perform(
       config,
       "ensure_version",

package/src/orchestrator.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { homedir } from "node:os";
-import { mkdir, access, copyFile, writeFile, readFile } from "node:fs/promises";
+import { mkdir, access, copyFile, writeFile, readFile, readdir, stat } 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";
@@ -37,7 +37,9 @@ function resolveWorkspacePath(recipeOrigin: RecipeOrigin, name: string, configur
     }
     return path.resolve(configuredPath);
   }
-  return path.join(homedir(), ".openclaw", "workspaces", name);
+  const trimmedName = name.trim() || name;
+  const workspaceName = trimmedName.startsWith("workspace-") ? trimmedName : `workspace-${trimmedName}`;
+  return path.join(homedir(), ".openclaw", workspaceName);
 }
 
 function isHttpUrl(value: string): boolean {
@@ -87,6 +89,35 @@ async function readBinaryFromRef(recipeOrigin: RecipeOrigin, reference: string):
   return Buffer.from(bytes);
 }
 
+interface LocalAssetFile {
+  absolutePath: string;
+  relativePath: string;
+}
+
+async function collectLocalAssetFiles(rootDir: string, relDir = ""): Promise<LocalAssetFile[]> {
+  const currentDir = relDir ? path.join(rootDir, relDir) : rootDir;
+  const entries = await readdir(currentDir, { withFileTypes: true });
+  const out: LocalAssetFile[] = [];
+
+  for (const entry of entries) {
+    const nextRel = relDir ? path.join(relDir, entry.name) : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...await collectLocalAssetFiles(rootDir, nextRel));
+      continue;
+    }
+    if (entry.isFile()) {
+      out.push({
+        absolutePath: path.join(rootDir, nextRel),
+        relativePath: nextRel,
+      });
+      continue;
+    }
+    throw new ClawChefError(`Unsupported entry in assets directory: ${path.join(rootDir, nextRel)}`);
+  }
+
+  return out;
+}
+
 async function confirmFactoryReset(options: RunOptions): Promise<boolean> {
   if (options.silent || options.dryRun) {
     return true;
@@ -117,11 +148,18 @@ export async function runRecipe(
   const workspacePaths = new Map<string, string>();
 
   logger.info(`Running recipe: ${recipe.name}`);
-  const versionResult = await provider.ensureVersion(recipe.openclaw, options.dryRun, options.silent);
+  const versionResult = await provider.ensureVersion(
+    recipe.openclaw,
+    options.dryRun,
+    options.silent,
+    options.keepOpenClawState,
+  );
   logger.info(`OpenClaw version ready: ${recipe.openclaw.version}`);
 
   if (versionResult.installedThisRun) {
     logger.info("OpenClaw was installed in this run; skipping factory reset");
+  } else if (options.keepOpenClawState) {
+    logger.info("Keeping existing OpenClaw state; skipping factory reset");
   } else {
     const confirmed = await confirmFactoryReset(options);
     if (!confirmed) {
@@ -146,6 +184,50 @@ export async function runRecipe(
     }
     await provider.createWorkspace(recipe.openclaw, { ...ws, path: absPath }, options.dryRun);
     logger.info(`Workspace created: ${ws.name}`);
+
+    if (!ws.assets?.trim()) {
+      continue;
+    }
+
+    const resolvedAssets = resolveFileRef(recipeOrigin, ws.assets);
+    if (resolvedAssets.kind !== "local") {
+      throw new ClawChefError(
+        `Workspace assets must resolve to a local directory: ${ws.assets}. Direct URL recipes cannot use workspaces[].assets.`,
+      );
+    }
+
+    let assetDirStat;
+    try {
+      assetDirStat = await stat(resolvedAssets.value);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ClawChefError(`Workspace assets path is not accessible: ${resolvedAssets.value} (${message})`);
+    }
+    if (!assetDirStat.isDirectory()) {
+      throw new ClawChefError(`Workspace assets must be a directory: ${resolvedAssets.value}`);
+    }
+
+    const assetFiles = await collectLocalAssetFiles(resolvedAssets.value);
+    for (const assetFile of assetFiles) {
+      if (provider.materializeFile) {
+        const content = await readFile(assetFile.absolutePath, "utf8");
+        await provider.materializeFile(
+          recipe.openclaw,
+          ws.name,
+          assetFile.relativePath,
+          content,
+          true,
+          options.dryRun,
+        );
+      } else {
+        const target = path.resolve(absPath, assetFile.relativePath);
+        if (!options.dryRun) {
+          await mkdir(path.dirname(target), { recursive: true });
+          await copyFile(assetFile.absolutePath, target);
+        }
+      }
+      logger.info(`Workspace asset copied: ${ws.name}/${assetFile.relativePath}`);
+    }
   }
 
   for (const agent of recipe.agents ?? []) {

package/src/recipe.ts

@@ -169,6 +169,11 @@ function collectVars(recipe: Recipe, cliVars: Record<string, string>): Record<st
 
 function semanticValidate(recipe: Recipe): void {
   const ws = new Set((recipe.workspaces ?? []).map((w) => w.name));
+  for (const workspace of recipe.workspaces ?? []) {
+    if (workspace.assets !== undefined && !workspace.assets.trim()) {
+      throw new ClawChefError(`Workspace ${workspace.name} has empty assets path`);
+    }
+  }
   for (const agent of recipe.agents ?? []) {
     if (!ws.has(agent.workspace)) {
       throw new ClawChefError(`Agent ${agent.name} references missing workspace: ${agent.workspace}`);

package/src/scaffold.ts

@@ -89,38 +89,13 @@ openclaw:
 
 workspaces:
   - name: "\${workspace_name}"
+    assets: "./assets"
 
 agents:
   - workspace: "\${workspace_name}"
     name: "\${agent_name}"
     model: "\${agent_model}"
 
-files:
-  - workspace: "\${workspace_name}"
-    path: "AGENTS.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/AGENTS.md"
-
-  - workspace: "\${workspace_name}"
-    path: "IDENTITY.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/IDENTITY.md"
-
-  - workspace: "\${workspace_name}"
-    path: "SOUL.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/SOUL.md"
-
-  - workspace: "\${workspace_name}"
-    path: "TOOLS.md"
-    overwrite: true
-    content_from: "./${projectName}-assets/TOOLS.md"
-
-  - workspace: "\${workspace_name}"
-    path: "scripts/scheduling.mjs"
-    overwrite: true
-    content_from: "./${projectName}-assets/scripts/scheduling.mjs"
-
 channels:
   - channel: "telegram-mock"
     account: "default"
@@ -178,11 +153,17 @@ console.log("[scheduling] " + message);
 function makeRecipeSmokeTest(): string {
   return `import test from "node:test";
 import assert from "node:assert/strict";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { access } from "node:fs/promises";
 
+const testDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(testDir, "..");
+
 test("recipe scaffold files exist", async () => {
-  await access("src/recipe.yaml");
-  await access("package.json");
+  await access(path.join(projectRoot, "recipe.yaml"));
+  await access(path.join(projectRoot, "assets", "AGENTS.md"));
+  await access(path.join(projectRoot, "package.json"));
   assert.ok(true);
 });
 `;
@@ -196,18 +177,16 @@ export async function scaffoldProject(targetDirArg?: string, options: ScaffoldOp
   const rawProjectName = options.projectName?.trim() || defaultName;
   const projectName = normalizeProjectName(rawProjectName);
 
-  const srcDir = path.join(targetDir, "src");
-  const assetsDir = path.join(srcDir, `${projectName}-assets`);
+  const assetsDir = path.join(targetDir, "assets");
   const assetsScriptsDir = path.join(assetsDir, "scripts");
   const testDir = path.join(targetDir, "test");
 
-  await mkdir(srcDir, { recursive: true });
   await mkdir(assetsDir, { recursive: true });
   await mkdir(assetsScriptsDir, { recursive: true });
   await mkdir(testDir, { recursive: true });
 
   await writeFile(path.join(targetDir, "package.json"), makePackageJson(projectName), "utf8");
-  await writeFile(path.join(srcDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
+  await writeFile(path.join(targetDir, "recipe.yaml"), makeRecipeYaml(projectName), "utf8");
   await writeFile(path.join(assetsDir, "AGENTS.md"), makeAgentsDoc(projectName), "utf8");
   await writeFile(path.join(assetsDir, "IDENTITY.md"), makeIdentityDoc(projectName), "utf8");
   await writeFile(path.join(assetsDir, "SOUL.md"), makeSoulDoc(), "utf8");

package/src/schema.ts

@@ -69,6 +69,7 @@ const workspaceSchema = z
   .object({
     name: z.string().min(1),
     path: z.string().min(1).optional(),
+    assets: z.string().min(1).optional(),
   })
   .strict();
 

package/src/types.ts

@@ -72,6 +72,7 @@ export interface OpenClawSection {
 export interface WorkspaceDef {
   name: string;
   path?: string;
+  assets?: string;
 }
 
 export interface ChannelDef {
@@ -148,6 +149,7 @@ export interface RunOptions {
   allowMissing: boolean;
   verbose: boolean;
   silent: boolean;
+  keepOpenClawState: boolean;
   provider: OpenClawProvider;
   remote: Partial<OpenClawRemoteConfig>;
 }