@joshualelon/clawdbot-skill-flow 0.1.0

package/src/state/flow-store.ts

@@ -0,0 +1,158 @@
+/**
+ * Flow metadata storage with file locking for concurrent access
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import lockfile from "lockfile";
+import { promisify } from "node:util";
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import type { FlowMetadata } from "../types.js";
+import { FlowMetadataSchema } from "../validation.js";
+
+const lock = promisify(lockfile.lock);
+const unlock = promisify(lockfile.unlock);
+
+/**
+ * Get the flows directory path
+ */
+function getFlowsDir(api: ClawdbotPluginApi): string {
+  const stateDir = api.runtime.state.resolveStateDir();
+  return path.join(stateDir, "flows");
+}
+
+/**
+ * Get the flow directory path
+ */
+function getFlowDir(api: ClawdbotPluginApi, flowName: string): string {
+  return path.join(getFlowsDir(api), flowName);
+}
+
+/**
+ * Get the flow metadata file path
+ */
+function getFlowMetadataPath(
+  api: ClawdbotPluginApi,
+  flowName: string
+): string {
+  return path.join(getFlowDir(api, flowName), "metadata.json");
+}
+
+/**
+ * Load a flow by name
+ */
+export async function loadFlow(
+  api: ClawdbotPluginApi,
+  flowName: string
+): Promise<FlowMetadata | null> {
+  const metadataPath = getFlowMetadataPath(api, flowName);
+  const lockPath = `${metadataPath}.lock`;
+
+  try {
+    await lock(lockPath, { wait: 5000, retries: 3 });
+
+    try {
+      const content = await fs.readFile(metadataPath, "utf-8");
+      const data = JSON.parse(content);
+      return FlowMetadataSchema.parse(data);
+    } finally {
+      await unlock(lockPath);
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    api.logger.error(`Failed to load flow ${flowName}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Save a flow (atomic write with locking)
+ */
+export async function saveFlow(
+  api: ClawdbotPluginApi,
+  flow: FlowMetadata
+): Promise<void> {
+  const flowDir = getFlowDir(api, flow.name);
+  const metadataPath = getFlowMetadataPath(api, flow.name);
+  const lockPath = `${metadataPath}.lock`;
+  const tempPath = `${metadataPath}.tmp`;
+
+  // Validate flow metadata
+  FlowMetadataSchema.parse(flow);
+
+  try {
+    // Ensure flow directory exists
+    await fs.mkdir(flowDir, { recursive: true });
+
+    await lock(lockPath, { wait: 5000, retries: 3 });
+
+    try {
+      // Write to temp file
+      await fs.writeFile(tempPath, JSON.stringify(flow, null, 2), "utf-8");
+
+      // Atomic rename
+      await fs.rename(tempPath, metadataPath);
+    } finally {
+      await unlock(lockPath);
+
+      // Cleanup temp file if it still exists
+      try {
+        await fs.unlink(tempPath);
+      } catch {
+        // Ignore errors
+      }
+    }
+  } catch (error) {
+    api.logger.error(`Failed to save flow ${flow.name}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * List all flows
+ */
+export async function listFlows(
+  api: ClawdbotPluginApi
+): Promise<FlowMetadata[]> {
+  const flowsDir = getFlowsDir(api);
+
+  try {
+    await fs.mkdir(flowsDir, { recursive: true });
+    const entries = await fs.readdir(flowsDir, { withFileTypes: true });
+
+    const flows: FlowMetadata[] = [];
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const flow = await loadFlow(api, entry.name);
+        if (flow) {
+          flows.push(flow);
+        }
+      }
+    }
+
+    return flows;
+  } catch (error) {
+    api.logger.error("Failed to list flows:", error);
+    throw error;
+  }
+}
+
+/**
+ * Delete a flow
+ */
+export async function deleteFlow(
+  api: ClawdbotPluginApi,
+  flowName: string
+): Promise<void> {
+  const flowDir = getFlowDir(api, flowName);
+
+  try {
+    await fs.rm(flowDir, { recursive: true, force: true });
+  } catch (error) {
+    api.logger.error(`Failed to delete flow ${flowName}:`, error);
+    throw error;
+  }
+}

package/src/state/history-store.ts

@@ -0,0 +1,76 @@
+/**
+ * JSONL append-only history log for completed flows
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import type { FlowSession } from "../types.js";
+
+/**
+ * Get history file path for a flow
+ */
+function getHistoryPath(api: ClawdbotPluginApi, flowName: string): string {
+  const stateDir = api.runtime.state.resolveStateDir();
+  return path.join(stateDir, "flows", flowName, "history.jsonl");
+}
+
+/**
+ * Save completed flow session to history (fire-and-forget)
+ */
+export async function saveFlowHistory(
+  api: ClawdbotPluginApi,
+  session: FlowSession
+): Promise<void> {
+  const historyPath = getHistoryPath(api, session.flowName);
+
+  try {
+    // Ensure directory exists
+    await fs.mkdir(path.dirname(historyPath), { recursive: true });
+
+    // Create history entry
+    const entry = {
+      ...session,
+      completedAt: Date.now(),
+    };
+
+    // Append to JSONL file
+    const line = JSON.stringify(entry) + "\n";
+    await fs.appendFile(historyPath, line, "utf-8");
+  } catch (error) {
+    // Log error but don't throw (fire-and-forget)
+    api.logger.error(
+      `Failed to save history for flow ${session.flowName}:`,
+      error
+    );
+  }
+}
+
+/**
+ * Read history for a flow (for analytics/debugging)
+ * @public - For future analytics/debugging features
+ */
+export async function readFlowHistory(
+  api: ClawdbotPluginApi,
+  flowName: string
+): Promise<Array<FlowSession & { completedAt: number }>> {
+  const historyPath = getHistoryPath(api, flowName);
+
+  try {
+    const content = await fs.readFile(historyPath, "utf-8");
+    const lines = content.trim().split("\n");
+
+    return lines
+      .filter((line) => line.length > 0)
+      .map((line) => JSON.parse(line));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return [];
+    }
+    api.logger.error(
+      `Failed to read history for flow ${flowName}:`,
+      error
+    );
+    throw error;
+  }
+}

package/src/state/session-store.ts

@@ -0,0 +1,155 @@
+/**
+ * In-memory session storage with automatic timeout cleanup
+ */
+
+import type { FlowSession } from "../types.js";
+
+// Session timeout: 30 minutes
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+
+// Cleanup interval: 5 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000;
+
+// In-memory session store
+const sessions = new Map<string, FlowSession>();
+
+// Cleanup timer
+let cleanupTimer: NodeJS.Timeout | null = null;
+
+/**
+ * Generate session key
+ */
+export function getSessionKey(senderId: string, flowName: string): string {
+  return `${senderId}-${flowName}`;
+}
+
+/**
+ * Create a new session
+ */
+export function createSession(params: {
+  flowName: string;
+  currentStepId: string;
+  senderId: string;
+  channel: string;
+}): FlowSession {
+  const now = Date.now();
+  const session: FlowSession = {
+    ...params,
+    variables: {},
+    startedAt: now,
+    lastActivityAt: now,
+  };
+
+  const key = getSessionKey(params.senderId, params.flowName);
+  sessions.set(key, session);
+
+  // Start cleanup timer if not already running
+  if (!cleanupTimer) {
+    cleanupTimer = setInterval(cleanupExpiredSessions, CLEANUP_INTERVAL_MS);
+  }
+
+  return session;
+}
+
+/**
+ * Get session by key (returns null if expired)
+ */
+export function getSession(key: string): FlowSession | null {
+  const session = sessions.get(key);
+
+  if (!session) {
+    return null;
+  }
+
+  // Check if expired
+  const now = Date.now();
+  if (now - session.lastActivityAt > SESSION_TIMEOUT_MS) {
+    sessions.delete(key);
+    return null;
+  }
+
+  return session;
+}
+
+/**
+ * Update session (merges partial updates)
+ */
+export function updateSession(
+  key: string,
+  patch: Partial<FlowSession>
+): FlowSession | null {
+  const session = getSession(key);
+
+  if (!session) {
+    return null;
+  }
+
+  const updated: FlowSession = {
+    ...session,
+    ...patch,
+    lastActivityAt: Date.now(),
+    // Merge variables instead of replacing
+    variables: patch.variables
+      ? { ...session.variables, ...patch.variables }
+      : session.variables,
+  };
+
+  sessions.set(key, updated);
+  return updated;
+}
+
+/**
+ * Delete session
+ */
+export function deleteSession(key: string): void {
+  sessions.delete(key);
+
+  // Stop cleanup timer if no sessions remain
+  if (sessions.size === 0 && cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}
+
+/**
+ * Cleanup expired sessions
+ */
+function cleanupExpiredSessions(): void {
+  const now = Date.now();
+  const keysToDelete: string[] = [];
+
+  for (const [key, session] of sessions.entries()) {
+    if (now - session.lastActivityAt > SESSION_TIMEOUT_MS) {
+      keysToDelete.push(key);
+    }
+  }
+
+  for (const key of keysToDelete) {
+    sessions.delete(key);
+  }
+
+  // Stop timer if no sessions remain
+  if (sessions.size === 0 && cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}
+
+/**
+ * Get all active sessions (for debugging)
+ * @public - For debugging and monitoring
+ */
+export function getAllSessions(): FlowSession[] {
+  return Array.from(sessions.values());
+}
+
+/**
+ * Clear all sessions (for testing)
+ */
+export function clearAllSessions(): void {
+  sessions.clear();
+  if (cleanupTimer) {
+    clearInterval(cleanupTimer);
+    cleanupTimer = null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Core type definitions for skill-flow plugin
+ */
+
+export type ValidationType = "number" | "email" | "phone";
+
+export interface Button {
+  text: string;
+  value: string | number;
+  next?: string;
+}
+
+export interface FlowStep {
+  id: string;
+  message: string;
+  buttons?: Array<Button | string | number>;
+  next?: string;
+  capture?: string;
+  validate?: ValidationType;
+  condition?: {
+    variable: string;
+    equals?: string | number;
+    greaterThan?: number;
+    lessThan?: number;
+    contains?: string;
+    next: string;
+  };
+}
+
+export interface FlowMetadata {
+  name: string;
+  description: string;
+  version: string;
+  author?: string;
+  steps: FlowStep[];
+  triggers?: {
+    manual?: boolean;
+    cron?: string;
+    event?: string;
+  };
+}
+
+export interface FlowSession {
+  flowName: string;
+  currentStepId: string;
+  senderId: string;
+  channel: string;
+  variables: Record<string, string | number>;
+  startedAt: number;
+  lastActivityAt: number;
+}
+
+export interface TransitionResult {
+  nextStepId?: string;
+  variables: Record<string, string | number>;
+  complete: boolean;
+  error?: string;
+  message?: string;
+}
+
+export interface ReplyPayload {
+  text: string;
+  buttons?: Array<{
+    text: string;
+    callback_data: string;
+  }[]>;
+}

package/src/validation.ts

@@ -0,0 +1,119 @@
+/**
+ * Zod validation schemas for flow definitions
+ */
+
+import { z } from "zod";
+import type { Button } from "./types.js";
+
+// Validation type enum
+const ValidationTypeSchema = z.enum(["number", "email", "phone"]);
+
+// Button schema - can be string, number, or full object
+const ButtonValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.object({
+    text: z.string(),
+    value: z.union([z.string(), z.number()]),
+    next: z.string().optional(),
+  }),
+]);
+
+// Conditional branching schema
+const ConditionSchema = z.object({
+  variable: z.string(),
+  equals: z.union([z.string(), z.number()]).optional(),
+  greaterThan: z.number().optional(),
+  lessThan: z.number().optional(),
+  contains: z.string().optional(),
+  next: z.string(),
+});
+
+// Flow step schema
+const FlowStepSchema = z.object({
+  id: z.string(),
+  message: z.string(),
+  buttons: z.array(ButtonValueSchema).optional(),
+  next: z.string().optional(),
+  capture: z.string().optional(),
+  validate: ValidationTypeSchema.optional(),
+  condition: ConditionSchema.optional(),
+});
+
+// Trigger schema
+const TriggerSchema = z
+  .object({
+    manual: z.boolean().optional(),
+    cron: z.string().optional(),
+    event: z.string().optional(),
+  })
+  .optional();
+
+// Complete flow metadata schema
+export const FlowMetadataSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  version: z.string(),
+  author: z.string().optional(),
+  steps: z.array(FlowStepSchema).min(1),
+  triggers: TriggerSchema,
+});
+
+/**
+ * Normalize button input to Button object
+ */
+export function normalizeButton(
+  btn: string | number | Button,
+  _index: number
+): Button {
+  if (typeof btn === "string") {
+    return {
+      text: btn,
+      value: btn,
+    };
+  }
+  if (typeof btn === "number") {
+    return {
+      text: String(btn),
+      value: btn,
+    };
+  }
+  return btn;
+}
+
+/**
+ * Validate input based on validation type
+ */
+export function validateInput(
+  input: string,
+  validationType: "number" | "email" | "phone"
+): { valid: boolean; error?: string } {
+  switch (validationType) {
+    case "number": {
+      const num = Number(input);
+      if (isNaN(num)) {
+        return { valid: false, error: "Please enter a valid number" };
+      }
+      return { valid: true };
+    }
+    case "email": {
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      if (!emailRegex.test(input)) {
+        return { valid: false, error: "Please enter a valid email address" };
+      }
+      return { valid: true };
+    }
+    case "phone": {
+      const phoneRegex = /^\+?[\d\s()-]{10,}$/;
+      if (!phoneRegex.test(input)) {
+        return {
+          valid: false,
+          error: "Please enter a valid phone number",
+        };
+      }
+      return { valid: true };
+    }
+    default:
+      return { valid: true };
+  }
+}

package/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Type declarations for external modules without types
+ */
+
+declare module "lockfile" {
+  export function lock(
+    path: string,
+    opts: { wait?: number; retries?: number },
+    callback: (err: Error | null) => void
+  ): void;
+
+  export function unlock(path: string, callback: (err: Error | null) => void): void;
+}
+
+declare module "clawdbot/plugin-sdk" {
+  export interface ClawdbotPluginApi {
+    logger: {
+      info(...args: any[]): void;
+      error(...args: any[]): void;
+      warn(...args: any[]): void;
+      debug(...args: any[]): void;
+    };
+    runtime: {
+      state: {
+        resolveStateDir(): string;
+      };
+    };
+    registerCommand(config: {
+      name: string;
+      description: string;
+      acceptsArgs: boolean;
+      requireAuth: boolean;
+      handler: (args: any) => Promise<any>;
+    }): void;
+  }
+}