@clawcipes/recipes 0.1.2 → 0.1.4

package/README.md

@@ -4,6 +4,8 @@
   <img src="./clawcipes_cook.jpg" alt="Clawcipes logo" width="240" />
 </p>
 
+> **Experimental:** We’re in active development. Installing should not have any negative impacts, but it’s always good to be safe and copy your `~/.openclaw` folder to a backup.
+
 Clawcipes is an OpenClaw plugin that provides **CLI-first recipes** for scaffolding specialist agents and teams from Markdown.
 
 If you like durable workflows: Clawcipes is built around a **file-first team workspace** (inbox/backlog/in-progress/done) that plays nicely with git.

package/index.ts

@@ -180,6 +180,20 @@ type AgentConfigSnippet = {
   tools?: { profile?: string; allow?: string[]; deny?: string[] };
 };
 
+type BindingMatch = {
+  channel: string;
+  accountId?: string;
+  // OpenClaw config schema uses: dm | group | channel
+  peer?: { kind: "dm" | "group" | "channel"; id: string };
+  guildId?: string;
+  teamId?: string;
+};
+
+type BindingSnippet = {
+  agentId: string;
+  match: BindingMatch;
+};
+
 function upsertAgentInConfig(cfgObj: any, snippet: AgentConfigSnippet) {
   if (!cfgObj.agents) cfgObj.agents = {};
   if (!Array.isArray(cfgObj.agents.list)) cfgObj.agents.list = [];
@@ -242,6 +256,43 @@ function ensureMainFirstInAgentsList(cfgObj: any, api: OpenClawPluginApi) {
   list.unshift(main);
 }
 
+function stableStringify(x: any) {
+  const seen = new WeakSet();
+  const sortObj = (v: any): any => {
+    if (v && typeof v === "object") {
+      if (seen.has(v)) return "[Circular]";
+      seen.add(v);
+      if (Array.isArray(v)) return v.map(sortObj);
+      const out: any = {};
+      for (const k of Object.keys(v).sort()) out[k] = sortObj(v[k]);
+      return out;
+    }
+    return v;
+  };
+  return JSON.stringify(sortObj(x));
+}
+
+function upsertBindingInConfig(cfgObj: any, binding: BindingSnippet) {
+  if (!Array.isArray(cfgObj.bindings)) cfgObj.bindings = [];
+  const list: any[] = cfgObj.bindings;
+
+  const sig = stableStringify({ agentId: binding.agentId, match: binding.match });
+  const idx = list.findIndex((b) => stableStringify({ agentId: b?.agentId, match: b?.match }) === sig);
+
+  if (idx >= 0) {
+    // Update in place (preserve ordering)
+    list[idx] = { ...list[idx], ...binding };
+    return { changed: false, note: "already-present" as const };
+  }
+
+  // Most-specific-first: if a peer match is specified, insert at front so it wins.
+  // Otherwise append.
+  if (binding.match?.peer) list.unshift(binding);
+  else list.push(binding);
+
+  return { changed: true, note: "added" as const };
+}
+
 async function applyAgentSnippetsToOpenClawConfig(api: OpenClawPluginApi, snippets: AgentConfigSnippet[]) {
   // Load the latest config from disk (not the snapshot in api.config).
   const current = (api.runtime as any).config?.loadConfig?.();
@@ -262,16 +313,37 @@ async function applyAgentSnippetsToOpenClawConfig(api: OpenClawPluginApi, snippe
   return { updatedAgents: snippets.map((s) => s.id) };
 }
 
-async function scaffoldAgentFromRecipe(api: OpenClawPluginApi, recipe: RecipeFrontmatter, opts: {
-  agentId: string;
-  agentName?: string;
-  update?: boolean;
-  vars?: Record<string, string>;
-}) {
-  const cfg = getCfg(api);
+async function applyBindingSnippetsToOpenClawConfig(api: OpenClawPluginApi, snippets: BindingSnippet[]) {
+  const current = (api.runtime as any).config?.loadConfig?.();
+  if (!current) throw new Error("Failed to load config via api.runtime.config.loadConfig()");
+  const cfgObj = (current.cfg ?? current) as any;
 
-  const agentDir = workspacePath(api, cfg.workspaceAgentsDir, opts.agentId);
-  await ensureDir(agentDir);
+  const results: any[] = [];
+  for (const s of snippets) {
+    results.push({ ...s, result: upsertBindingInConfig(cfgObj, s) });
+  }
+
+  await (api.runtime as any).config?.writeConfigFile?.(cfgObj);
+  return { updatedBindings: results };
+}
+
+async function scaffoldAgentFromRecipe(
+  api: OpenClawPluginApi,
+  recipe: RecipeFrontmatter,
+  opts: {
+    agentId: string;
+    agentName?: string;
+    update?: boolean;
+    vars?: Record<string, string>;
+
+    // Where to write the scaffolded files (may be a shared team workspace role folder)
+    filesRootDir: string;
+
+    // What to set in agents.list[].workspace (may be shared team workspace root)
+    workspaceRootDir: string;
+  },
+) {
+  await ensureDir(opts.filesRootDir);
 
   const templates = recipe.templates ?? {};
   const files = recipe.files ?? [];
@@ -282,7 +354,7 @@ async function scaffoldAgentFromRecipe(api: OpenClawPluginApi, recipe: RecipeFro
     const raw = templates[f.template];
     if (typeof raw !== "string") throw new Error(`Missing template: ${f.template}`);
     const rendered = renderTemplate(raw, vars);
-    const target = path.join(agentDir, f.path);
+    const target = path.join(opts.filesRootDir, f.path);
     const mode = opts.update ? (f.mode ?? "overwrite") : (f.mode ?? "createOnly");
     const r = await writeFileSafely(target, rendered, mode);
     fileResults.push({ path: target, wrote: r.wrote, reason: r.reason });
@@ -290,13 +362,14 @@ async function scaffoldAgentFromRecipe(api: OpenClawPluginApi, recipe: RecipeFro
 
   const configSnippet: AgentConfigSnippet = {
     id: opts.agentId,
-    workspace: agentDir,
+    workspace: opts.workspaceRootDir,
     identity: { name: opts.agentName ?? recipe.name ?? opts.agentId },
     tools: recipe.tools ?? {},
   };
 
   return {
-    agentDir,
+    filesRootDir: opts.filesRootDir,
+    workspaceRootDir: opts.workspaceRootDir,
     fileResults,
     next: {
       configSnippet,
@@ -393,6 +466,194 @@ const recipesPlugin = {
             console.log(JSON.stringify(out, null, 2));
           });
 
+        cmd
+          .command("bind")
+          .description("Add/update a multi-agent routing binding (writes openclaw.json bindings[])")
+          .requiredOption("--agent-id <agentId>", "Target agent id")
+          .requiredOption("--channel <channel>", "Channel name (telegram|whatsapp|discord|slack|...) ")
+          .option("--account-id <accountId>", "Channel accountId (if applicable)")
+          .option("--peer-kind <kind>", "Peer kind (dm|group|channel) (aliases: direct->dm)")
+          .option("--peer-id <id>", "Peer id (DM number/id, group id, or channel id)")
+          .option("--guild-id <guildId>", "Discord guildId")
+          .option("--team-id <teamId>", "Slack teamId")
+          .option("--match <json>", "Full match object as JSON/JSON5 (overrides flags)")
+          .action(async (options: any) => {
+            const agentId = String(options.agentId);
+            let match: BindingMatch;
+
+            if (options.match) {
+              match = JSON5.parse(String(options.match)) as BindingMatch;
+            } else {
+              match = {
+                channel: String(options.channel),
+              };
+              if (options.accountId) match.accountId = String(options.accountId);
+              if (options.guildId) match.guildId = String(options.guildId);
+              if (options.teamId) match.teamId = String(options.teamId);
+
+              if (options.peerKind || options.peerId) {
+                if (!options.peerKind || !options.peerId) {
+                  throw new Error("--peer-kind and --peer-id must be provided together");
+                }
+                let kind = String(options.peerKind);
+                // Back-compat alias
+                if (kind === "direct") kind = "dm";
+                if (kind !== "dm" && kind !== "group" && kind !== "channel") {
+                  throw new Error("--peer-kind must be dm|group|channel (or direct as alias for dm)");
+                }
+                match.peer = { kind, id: String(options.peerId) };
+              }
+            }
+
+            if (!match?.channel) throw new Error("match.channel is required");
+
+            const res = await applyBindingSnippetsToOpenClawConfig(api, [{ agentId, match }]);
+            console.log(JSON.stringify(res, null, 2));
+            console.error("Binding written. Restart gateway if required for changes to take effect.");
+          });
+
+        cmd
+          .command("bindings")
+          .description("Show current bindings from openclaw config")
+          .action(async () => {
+            const current = (api.runtime as any).config?.loadConfig?.();
+            if (!current) throw new Error("Failed to load config via api.runtime.config.loadConfig()");
+            const cfgObj = (current.cfg ?? current) as any;
+            console.log(JSON.stringify(cfgObj.bindings ?? [], null, 2));
+          });
+
+        cmd
+          .command("migrate-team")
+          .description("Migrate a legacy team scaffold into the new workspace-<teamId> layout")
+          .requiredOption("--team-id <teamId>", "Team id (must end with -team)")
+          .option("--mode <mode>", "move|copy", "move")
+          .option("--dry-run", "Print the plan without writing anything", false)
+          .option("--overwrite", "Allow merging into an existing destination (dangerous)", false)
+          .action(async (options: any) => {
+            const teamId = String(options.teamId);
+            if (!teamId.endsWith("-team")) throw new Error("teamId must end with -team");
+
+            const mode = String(options.mode ?? "move");
+            if (mode !== "move" && mode !== "copy") throw new Error("--mode must be move|copy");
+
+            const baseWorkspace = api.config.agents?.defaults?.workspace;
+            if (!baseWorkspace) throw new Error("agents.defaults.workspace is not set in config");
+
+            const legacyTeamDir = path.resolve(baseWorkspace, "teams", teamId);
+            const legacyAgentsDir = path.resolve(baseWorkspace, "agents");
+
+            const destTeamDir = path.resolve(baseWorkspace, "..", `workspace-${teamId}`);
+            const destRolesDir = path.join(destTeamDir, "roles");
+
+            const exists = async (p: string) => fileExists(p);
+
+            // Build migration plan
+            const plan: any = {
+              teamId,
+              mode,
+              legacy: { teamDir: legacyTeamDir, agentsDir: legacyAgentsDir },
+              dest: { teamDir: destTeamDir, rolesDir: destRolesDir },
+              steps: [] as any[],
+              agentIds: [] as string[],
+            };
+
+            const legacyTeamExists = await exists(legacyTeamDir);
+            if (!legacyTeamExists) {
+              throw new Error(`Legacy team directory not found: ${legacyTeamDir}`);
+            }
+
+            const destExists = await exists(destTeamDir);
+            if (destExists && !options.overwrite) {
+              throw new Error(`Destination already exists: ${destTeamDir} (re-run with --overwrite to merge)`);
+            }
+
+            // 1) Move/copy team shared workspace
+            plan.steps.push({ kind: "teamDir", from: legacyTeamDir, to: destTeamDir });
+
+            // 2) Move/copy each role agent directory into roles/<role>/
+            const legacyAgentsExist = await exists(legacyAgentsDir);
+            let legacyAgentFolders: string[] = [];
+            if (legacyAgentsExist) {
+              legacyAgentFolders = (await fs.readdir(legacyAgentsDir)).filter((x) => x.startsWith(`${teamId}-`));
+            }
+
+            for (const folder of legacyAgentFolders) {
+              const agentId = folder;
+              const role = folder.slice((teamId + "-").length);
+              const from = path.join(legacyAgentsDir, folder);
+              const to = path.join(destRolesDir, role);
+              plan.agentIds.push(agentId);
+              plan.steps.push({ kind: "roleDir", agentId, role, from, to });
+            }
+
+            const dryRun = !!options.dryRun;
+            if (dryRun) {
+              console.log(JSON.stringify({ ok: true, dryRun: true, plan }, null, 2));
+              return;
+            }
+
+            // Helpers
+            const copyDirRecursive = async (src: string, dst: string) => {
+              await ensureDir(dst);
+              const entries = await fs.readdir(src, { withFileTypes: true });
+              for (const ent of entries) {
+                const s = path.join(src, ent.name);
+                const d = path.join(dst, ent.name);
+                if (ent.isDirectory()) await copyDirRecursive(s, d);
+                else if (ent.isSymbolicLink()) {
+                  const link = await fs.readlink(s);
+                  await fs.symlink(link, d);
+                } else {
+                  await ensureDir(path.dirname(d));
+                  await fs.copyFile(s, d);
+                }
+              }
+            };
+
+            const removeDirRecursive = async (p: string) => {
+              // node 25 supports fs.rm
+              await fs.rm(p, { recursive: true, force: true });
+            };
+
+            const moveDir = async (src: string, dst: string) => {
+              await ensureDir(path.dirname(dst));
+              try {
+                await fs.rename(src, dst);
+              } catch {
+                // cross-device or existing: fallback to copy+remove
+                await copyDirRecursive(src, dst);
+                await removeDirRecursive(src);
+              }
+            };
+
+            // Execute plan
+            if (mode === "copy") {
+              await copyDirRecursive(legacyTeamDir, destTeamDir);
+            } else {
+              await moveDir(legacyTeamDir, destTeamDir);
+            }
+
+            // Ensure roles dir exists
+            await ensureDir(destRolesDir);
+
+            for (const step of plan.steps.filter((s: any) => s.kind === "roleDir")) {
+              if (!(await exists(step.from))) continue;
+              if (mode === "copy") await copyDirRecursive(step.from, step.to);
+              else await moveDir(step.from, step.to);
+            }
+
+            // Update config: set each team agent's workspace to destTeamDir (shared)
+            const agentSnippets: AgentConfigSnippet[] = plan.agentIds.map((agentId: string) => ({
+              id: agentId,
+              workspace: destTeamDir,
+            }));
+            if (agentSnippets.length) {
+              await applyAgentSnippetsToOpenClawConfig(api, agentSnippets);
+            }
+
+            console.log(JSON.stringify({ ok: true, migrated: teamId, destTeamDir, agentIds: plan.agentIds }, null, 2));
+          });
+
         cmd
           .command("install")
           .description("Install a ClawHub skill into this OpenClaw workspace (confirmation-gated)")
@@ -509,7 +770,8 @@ const recipesPlugin = {
             if (!workspaceRoot) throw new Error("agents.defaults.workspace is not set in config");
 
             const teamId = String(options.teamId);
-            const teamDir = workspacePath(api, cfg.workspaceTeamsDir, teamId);
+            // Team workspace root (shared by all role agents): ~/.openclaw/workspace-<teamId>
+            const teamDir = path.resolve(workspaceRoot, "..", `workspace-${teamId}`);
 
             const inboxDir = path.join(teamDir, "inbox");
             const backlogDir = path.join(teamDir, "work", "backlog");
@@ -658,10 +920,16 @@ const recipesPlugin = {
               return;
             }
 
+            const baseWorkspace = api.config.agents?.defaults?.workspace ?? "~/.openclaw/workspace";
+            // Put standalone agent workspaces alongside the default workspace (same parent dir).
+            const resolvedWorkspaceRoot = path.resolve(baseWorkspace, "..", `workspace-${options.agentId}`);
+
             const result = await scaffoldAgentFromRecipe(api, recipe, {
               agentId: options.agentId,
               agentName: options.name,
               update: !!options.overwrite,
+              filesRootDir: resolvedWorkspaceRoot,
+              workspaceRootDir: resolvedWorkspaceRoot,
               vars: {
                 agentId: options.agentId,
                 agentName: options.name ?? recipe.name ?? options.agentId,
@@ -702,8 +970,15 @@ const recipesPlugin = {
               return;
             }
 
-            const teamDir = workspacePath(api, cfg.workspaceTeamsDir, teamId);
+            const baseWorkspace = api.config.agents?.defaults?.workspace;
+            if (!baseWorkspace) throw new Error("agents.defaults.workspace is not set in config");
+
+            // Team workspace root (shared by all role agents): ~/.openclaw/workspace-<teamId>
+            const teamDir = path.resolve(baseWorkspace, "..", `workspace-${teamId}`);
             await ensureDir(teamDir);
+
+            const rolesDir = path.join(teamDir, "roles");
+            await ensureDir(rolesDir);
             const notesDir = path.join(teamDir, "notes");
             const workDir = path.join(teamDir, "work");
             const backlogDir = path.join(workDir, "backlog");
@@ -761,16 +1036,22 @@ const recipesPlugin = {
                 tools: a.tools ?? recipe.tools,
               };
 
+              const roleDir = path.join(rolesDir, role);
               const r = await scaffoldAgentFromRecipe(api, scopedRecipe, {
                 agentId,
                 agentName,
                 update: !!options.overwrite,
+                // Write role-specific files under roles/<role>/
+                filesRootDir: roleDir,
+                // But set the agent workspace root to the shared team workspace
+                workspaceRootDir: teamDir,
                 vars: {
                   teamId,
                   teamDir,
                   role,
                   agentId,
                   agentName,
+                  roleDir,
                 },
               });
               results.push({ role, agentId, ...r });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawcipes/recipes",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Clawcipes recipes plugin for OpenClaw (markdown recipes -> scaffold agents/teams)",
   "main": "index.ts",
   "type": "commonjs",