@jiggai/kitchen 0.1.12 → 0.2.0

package/src/lib/workflows/readdir.ts

@@ -0,0 +1,23 @@
+import fs from "node:fs/promises";
+
+/** Reads dir with optional suffix filter and reverse sort. Returns { ok, dir, files } or { ok, dir, files: [] } on ENOENT. */
+export async function readdirFiles(
+  dir: string,
+  suffix: string,
+  reverse = false
+): Promise<{ ok: true; dir: string; files: string[] }> {
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    let files = entries
+      .filter((e) => e.isFile() && e.name.endsWith(suffix))
+      .map((e) => e.name)
+      .sort();
+    if (reverse) files = files.reverse();
+    return { ok: true as const, dir, files };
+  } catch (err: unknown) {
+    if (err && typeof err === "object" && (err as { code?: unknown }).code === "ENOENT") {
+      return { ok: true as const, dir, files: [] as string[] };
+    }
+    throw err;
+  }
+}

package/src/lib/workflows/runs-storage.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getTeamWorkspaceDir } from "@/lib/paths";
+import { readdirFiles } from "@/lib/workflows/readdir";
+import { assertSafeWorkflowId } from "@/lib/workflows/storage";
+import type { WorkflowRunFileV1 } from "@/lib/workflows/runs-types";
+
+const RUNS_DIR = path.join("shared-context", "workflow-runs");
+
+export function assertSafeRunId(runId: string) {
+  const id = String(runId ?? "").trim();
+  if (!id) throw new Error("run id is required");
+  if (!/^[a-z0-9][a-z0-9-]{0,80}$/.test(id)) {
+    throw new Error("Invalid run id. Use lowercase letters, numbers, and dashes (max 81 chars).");
+  }
+  return id;
+}
+
+export async function getWorkflowRunsDir(teamId: string, workflowId: string) {
+  const wfId = assertSafeWorkflowId(workflowId);
+  const teamDir = await getTeamWorkspaceDir(teamId);
+  return path.join(teamDir, RUNS_DIR, wfId);
+}
+
+export function workflowRunFileName(runId: string) {
+  return `${runId}.run.json`;
+}
+
+export async function listWorkflowRuns(teamId: string, workflowId: string) {
+  const dir = await getWorkflowRunsDir(teamId, workflowId);
+  return readdirFiles(dir, ".run.json", true);
+}
+
+export async function readWorkflowRun(teamId: string, workflowId: string, runId: string) {
+  const wfId = assertSafeWorkflowId(workflowId);
+  const rId = assertSafeRunId(runId);
+  const dir = await getWorkflowRunsDir(teamId, wfId);
+  const p = path.join(dir, workflowRunFileName(rId));
+  const raw = await fs.readFile(p, "utf8");
+  const parsed = JSON.parse(raw) as WorkflowRunFileV1;
+  return { ok: true as const, path: p, run: parsed };
+}
+
+export async function writeWorkflowRun(teamId: string, workflowId: string, run: WorkflowRunFileV1) {
+  const wfId = assertSafeWorkflowId(workflowId);
+  const rId = assertSafeRunId(run.id);
+  const dir = await getWorkflowRunsDir(teamId, wfId);
+  await fs.mkdir(dir, { recursive: true });
+  const p = path.join(dir, workflowRunFileName(rId));
+  const toWrite: WorkflowRunFileV1 = {
+    ...run,
+    schema: "clawkitchen.workflow-run.v1",
+    id: rId,
+    workflowId: wfId,
+    teamId,
+  };
+  await fs.writeFile(p, JSON.stringify(toWrite, null, 2) + "\n", "utf8");
+  return { ok: true as const, path: p };
+}

package/src/lib/workflows/runs-types.ts

@@ -0,0 +1,42 @@
+export type WorkflowRunNodeResultV1 = {
+  nodeId: string;
+  status: "pending" | "running" | "waiting" | "success" | "error" | "skipped";
+  startedAt?: string;
+  endedAt?: string;
+  output?: unknown;
+  error?: { message: string; stack?: string } | string;
+};
+
+export type WorkflowRunApprovalV1 = {
+  nodeId: string;
+  state: "pending" | "approved" | "changes_requested" | "canceled";
+  requestedAt?: string;
+  decidedAt?: string;
+  /** Freeform notes from the approver (optional) */
+  note?: string;
+  /** Who made the decision (MVP: typically "ClawKitchen UI" or channel metadata) */
+  decidedBy?: string;
+  /** Outbound delivery metadata for the approval request (best-effort) */
+  outbound?: {
+    provider: string;
+    target: string;
+    sentAt?: string;
+    attemptedAt?: string;
+    error?: string;
+  };
+};
+
+export type WorkflowRunFileV1 = {
+  schema: "clawkitchen.workflow-run.v1";
+  id: string;
+  workflowId: string;
+  teamId?: string;
+  startedAt: string;
+  endedAt?: string;
+  status: "running" | "waiting_for_approval" | "success" | "error" | "canceled";
+  /** Optional high-level summary */
+  summary?: string;
+  nodes?: WorkflowRunNodeResultV1[];
+  approval?: WorkflowRunApprovalV1;
+  meta?: Record<string, unknown>;
+};

package/src/lib/workflows/storage.ts

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getTeamWorkspaceDir } from "@/lib/paths";
+import { readdirFiles } from "@/lib/workflows/readdir";
+import type { WorkflowFileV1 } from "@/lib/workflows/types";
+
+const WORKFLOWS_DIR = path.join("shared-context", "workflows");
+
+export function workflowFileName(workflowId: string) {
+  return `${workflowId}.workflow.json`;
+}
+
+export function assertSafeWorkflowId(workflowId: string) {
+  const id = String(workflowId ?? "").trim();
+  if (!id) throw new Error("workflow id is required");
+  if (!/^[a-z0-9][a-z0-9-]{0,62}$/.test(id)) {
+    throw new Error(
+      "Invalid workflow id. Use lowercase letters, numbers, and dashes (max 63 chars), e.g. marketing-cadence-v1"
+    );
+  }
+  return id;
+}
+
+export async function getTeamWorkflowsDir(teamId: string) {
+  const teamDir = await getTeamWorkspaceDir(teamId);
+  return path.join(teamDir, WORKFLOWS_DIR);
+}
+
+export async function listWorkflows(teamId: string) {
+  const dir = await getTeamWorkflowsDir(teamId);
+  return readdirFiles(dir, ".workflow.json");
+}
+
+export async function readWorkflow(teamId: string, workflowId: string) {
+  const id = assertSafeWorkflowId(workflowId);
+  const dir = await getTeamWorkflowsDir(teamId);
+  const p = path.join(dir, workflowFileName(id));
+  const raw = await fs.readFile(p, "utf8");
+  const parsed = JSON.parse(raw) as WorkflowFileV1;
+  return { ok: true as const, path: p, workflow: parsed };
+}
+
+export async function writeWorkflow(teamId: string, workflow: WorkflowFileV1) {
+  const id = assertSafeWorkflowId(workflow.id);
+  const dir = await getTeamWorkflowsDir(teamId);
+  await fs.mkdir(dir, { recursive: true });
+  const p = path.join(dir, workflowFileName(id));
+  const toWrite: WorkflowFileV1 = {
+    ...workflow,
+    schema: "clawkitchen.workflow.v1",
+    id,
+  };
+  await fs.writeFile(p, JSON.stringify(toWrite, null, 2) + "\n", "utf8");
+  return { ok: true as const, path: p };
+}
+
+export async function deleteWorkflow(teamId: string, workflowId: string) {
+  const id = assertSafeWorkflowId(workflowId);
+  const dir = await getTeamWorkflowsDir(teamId);
+  const p = path.join(dir, workflowFileName(id));
+  try {
+    await fs.unlink(p);
+  } catch (err: unknown) {
+    if (err && typeof err === "object" && (err as { code?: unknown }).code === "ENOENT") {
+      return { ok: true as const, path: p, existed: false as const };
+    }
+    throw err;
+  }
+  return { ok: true as const, path: p, existed: true as const };
+}

package/src/lib/workflows/templates/index.ts

@@ -0,0 +1 @@
+export { marketingCadenceWorkflowV1 } from "@/lib/workflows/templates/marketing-cadence-v1";

package/src/lib/workflows/templates/marketing-cadence-v1.ts

@@ -0,0 +1,142 @@
+import type { WorkflowFileV1 } from "@/lib/workflows/types";
+
+export function marketingCadenceWorkflowV1(opts?: { id?: string; approvalProvider?: string; approvalTarget?: string }): WorkflowFileV1 {
+  const id = String(opts?.id ?? "marketing-cadence-v1").trim() || "marketing-cadence-v1";
+  const approvalProvider = String(opts?.approvalProvider ?? "telegram").trim() || "telegram";
+  const approvalTarget = String(opts?.approvalTarget ?? "").trim();
+
+  return {
+    schema: "clawkitchen.workflow.v1",
+    id,
+    name: "Marketing Cadence (v1)",
+    version: 1,
+    timezone: "America/New_York",
+    triggers: [
+      {
+        kind: "cron",
+        id: "t-weekdays-9",
+        name: "Weekdays 09:00",
+        enabled: true,
+        expr: "0 9 * * 1-5",
+        tz: "America/New_York",
+      },
+    ],
+    meta: {
+      templateId: "marketing-cadence-v1",
+      approvalProvider,
+      approvalTarget,
+      writeback: {
+        postLogPath: "shared-context/marketing/POST_LOG.md",
+        learningsJsonlPath: "shared-context/memory/marketing_learnings.jsonl",
+      },
+      platforms: ["x", "instagram", "tiktok", "youtube"],
+    },
+    nodes: [
+      { id: "start", type: "start", name: "Start", x: 60, y: 120, config: {} },
+      {
+        id: "research",
+        type: "llm",
+        name: "Research + idea",
+        x: 300,
+        y: 80,
+        config: {
+          agentId: "marketing-research",
+          promptTemplate:
+            "Do competitive + trend research. Produce: 5 angles + supporting bullets. Output JSON: {angles:[...], sources:[...]}" as string,
+        },
+      },
+      {
+        id: "draft_assets",
+        type: "llm",
+        name: "Draft platform assets",
+        x: 560,
+        y: 80,
+        config: {
+          agentId: "marketing-writer",
+          promptTemplate:
+            "Using the research output, draft platform-specific variants for X/Instagram/TikTok/YouTube. Output JSON: {platforms:{x:{hook,body},instagram:{hook,body,assetNotes},tiktok:{hook,script,assetNotes},youtube:{hook,script,assetNotes}}}" as string,
+        },
+      },
+      {
+        id: "qc_brand",
+        type: "llm",
+        name: "QC / brand consistency",
+        x: 820,
+        y: 80,
+        config: {
+          agentId: "brand-qc",
+          promptTemplate:
+            "Review drafts for consistency. Apply corrections. Ensure: mention ClawRecipes before OpenClaw; no posting without approval. Output JSON: {platforms:{...}, notes:[...]}" as string,
+        },
+      },
+      {
+        id: "approval",
+        type: "human_approval",
+        name: "Human approval",
+        x: 1080,
+        y: 80,
+        config: {
+          provider: approvalProvider,
+          target: approvalTarget || "(set in UI)",
+          messageTemplate:
+            "{{workflow.name}} — Approval needed\nRun: {{run.id}}\n\n{{packet.note}}" as string,
+        },
+      },
+      {
+        id: "post_to_platforms",
+        type: "tool",
+        name: "Post (after approval)",
+        x: 1340,
+        y: 80,
+        config: {
+          tool: "marketing.post_all",
+          args: {
+            platforms: ["x", "instagram", "tiktok", "youtube"],
+            draftsFromNode: "qc_brand",
+          },
+        },
+      },
+      {
+        id: "write_post_log",
+        type: "tool",
+        name: "Append POST_LOG.md",
+        x: 1600,
+        y: 60,
+        config: {
+          tool: "fs.append",
+          args: {
+            path: "shared-context/marketing/POST_LOG.md",
+            content: "- {{date}} {{platforms}} posted. Run={{run.id}}\\n" as string,
+          },
+        },
+      },
+      {
+        id: "write_learnings",
+        type: "tool",
+        name: "Append marketing_learnings.jsonl",
+        x: 1600,
+        y: 140,
+        config: {
+          tool: "fs.append",
+          args: {
+            path: "shared-context/memory/marketing_learnings.jsonl",
+            content:
+              "{\"ts\":\"{{date}}\",\"runId\":\"{{run.id}}\",\"notes\":{{qc_brand.notes_json}}}\\n" as string,
+          },
+        },
+      },
+      { id: "end", type: "end", name: "End", x: 1860, y: 120, config: {} },
+    ],
+    edges: [
+      { id: "e-start-research", from: "start", to: "research" },
+      { id: "e-research-draft", from: "research", to: "draft_assets" },
+      { id: "e-draft-qc", from: "draft_assets", to: "qc_brand" },
+      { id: "e-qc-approval", from: "qc_brand", to: "approval" },
+      { id: "e-approval-post", from: "approval", to: "post_to_platforms" },
+      { id: "e-post-log", from: "post_to_platforms", to: "write_post_log" },
+      { id: "e-post-learnings", from: "post_to_platforms", to: "write_learnings" },
+      { id: "e-log-end", from: "write_post_log", to: "end" },
+      { id: "e-learnings-end", from: "write_learnings", to: "end" },
+    ],
+  };
+}

package/src/lib/workflows/types.ts

@@ -0,0 +1,48 @@
+export type WorkflowTriggerCronV1 = {
+  kind: "cron";
+  id: string;
+  name?: string;
+  enabled?: boolean;
+  /** Standard 5-field cron expression */
+  expr: string;
+  /** IANA timezone, e.g. America/New_York */
+  tz?: string;
+};
+
+export type WorkflowNodeV1 = {
+  id: string;
+  type:
+    | "start"
+    | "end"
+    | "llm"
+    | "tool"
+    | "condition"
+    | "delay"
+    | "human_approval";
+  name?: string;
+  /** UI layout hints (optional) */
+  x?: number;
+  y?: number;
+  /** Node-type-specific config */
+  config?: Record<string, unknown>;
+};
+
+export type WorkflowEdgeV1 = {
+  id: string;
+  from: string;
+  to: string;
+  /** Optional edge label/condition */
+  label?: string;
+};
+
+export type WorkflowFileV1 = {
+  schema: "clawkitchen.workflow.v1";
+  id: string;
+  name: string;
+  version?: number;
+  timezone?: string;
+  triggers?: WorkflowTriggerCronV1[];
+  nodes: WorkflowNodeV1[];
+  edges: WorkflowEdgeV1[];
+  meta?: Record<string, unknown>;
+};

package/src/lib/workflows/validate.ts

@@ -0,0 +1,92 @@
+import type { WorkflowEdgeV1, WorkflowFileV1, WorkflowNodeV1, WorkflowTriggerCronV1 } from "@/lib/workflows/types";
+
+export type WorkflowValidationResult = {
+  errors: string[];
+  warnings: string[];
+};
+
+function isFiveFieldCron(expr: string) {
+  const parts = String(expr || "")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  return parts.length === 5;
+}
+
+function uniqCount(values: string[]) {
+  const set = new Set<string>();
+  for (const v of values) set.add(v);
+  return set.size;
+}
+
+export function validateWorkflowFileV1(wf: WorkflowFileV1): WorkflowValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (wf.schema !== "clawkitchen.workflow.v1") errors.push(`schema must be clawkitchen.workflow.v1 (got ${String(wf.schema)})`);
+  if (!String(wf.id || "").trim()) errors.push("id is required");
+  if (!String(wf.name || "").trim()) errors.push("name is required");
+
+  const nodes: WorkflowNodeV1[] = Array.isArray(wf.nodes) ? wf.nodes : [];
+  const edges: WorkflowEdgeV1[] = Array.isArray(wf.edges) ? wf.edges : [];
+  const triggers: WorkflowTriggerCronV1[] = Array.isArray(wf.triggers) ? wf.triggers : [];
+
+  const nodeIds = nodes.map((n) => String(n?.id ?? "").trim()).filter(Boolean);
+  if (nodeIds.length !== nodes.length) errors.push("all nodes must have a non-empty id");
+  if (uniqCount(nodeIds) !== nodeIds.length) errors.push("node ids must be unique");
+
+  const edgeIds = edges.map((e) => String(e?.id ?? "").trim()).filter(Boolean);
+  if (edgeIds.length !== edges.length) errors.push("all edges must have a non-empty id");
+  if (uniqCount(edgeIds) !== edgeIds.length) errors.push("edge ids must be unique");
+
+  const nodeIdSet = new Set(nodeIds);
+  for (const e of edges) {
+    const from = String(e?.from ?? "").trim();
+    const to = String(e?.to ?? "").trim();
+    if (!from || !to) {
+      errors.push(`edge ${String(e?.id ?? "(missing id)")} must have from/to`);
+      continue;
+    }
+    if (!nodeIdSet.has(from)) errors.push(`edge ${String(e.id)} references missing from node: ${from}`);
+    if (!nodeIdSet.has(to)) errors.push(`edge ${String(e.id)} references missing to node: ${to}`);
+  }
+
+  const starts = nodes.filter((n) => n.type === "start");
+  const ends = nodes.filter((n) => n.type === "end");
+  if (!starts.length) warnings.push("no start node found");
+  if (starts.length > 1) warnings.push("multiple start nodes found (MVP supports this, but execution semantics may be ambiguous)");
+  if (!ends.length) warnings.push("no end node found");
+
+  for (const t of triggers) {
+    if (t.kind === "cron") {
+      if (!String(t.id || "").trim()) errors.push("cron trigger missing id");
+      if (!String(t.expr || "").trim()) errors.push(`cron trigger ${String(t.id || "(missing id)")} missing expr`);
+      else if (!isFiveFieldCron(t.expr)) warnings.push(`cron trigger ${String(t.id)} expr is not 5-field: ${String(t.expr)}`);
+      const tz = t.tz ? String(t.tz).trim() : "";
+      // NOTE: We commonly use "UTC" as a default, and it is widely accepted even though it isn't in the
+      // classic Region/City IANA format. Treat it as valid to avoid noisy validation warnings.
+      if (tz && tz !== "UTC" && !tz.includes("/")) {
+        warnings.push(`cron trigger ${String(t.id)} tz doesn't look like an IANA timezone: ${String(t.tz)}`);
+      }
+    }
+  }
+
+  // Human approval node sanity checks (MVP)
+  const meta = wf.meta && typeof wf.meta === "object" && !Array.isArray(wf.meta) ? (wf.meta as Record<string, unknown>) : {};
+  const defaultTarget = String(meta.approvalTarget ?? "").trim();
+  for (const n of nodes) {
+    if (n.type !== "human_approval") continue;
+    const cfg = n.config && typeof n.config === "object" && !Array.isArray(n.config) ? (n.config as Record<string, unknown>) : {};
+    const target = String(cfg.target ?? cfg.chatId ?? "").trim();
+    const provider = String(cfg.provider ?? cfg.channel ?? "").trim();
+
+    if (!target && !defaultTarget) {
+      warnings.push(`human_approval node ${String(n.id)} has no target (set node.config.target or workflow.meta.approvalTarget)`);
+    }
+    if (target && !provider && !String(meta.approvalProvider ?? "").trim()) {
+      warnings.push(`human_approval node ${String(n.id)} has a target but no provider (set node.config.provider or workflow.meta.approvalProvider)`);
+    }
+  }
+
+  return { errors, warnings };
+}