@fkws/klonk 0.0.4

package/dist/index.js

@@ -0,0 +1,429 @@
+// src/prototypes/Playlist.ts
+class Playlist {
+  machines;
+  finalizer;
+  constructor(machines = [], finalizer) {
+    this.machines = machines;
+    this.finalizer = finalizer;
+  }
+  addTask(task, builder) {
+    const machine = { task, builder };
+    const newMachines = [...this.machines, machine];
+    return new Playlist(newMachines, this.finalizer);
+  }
+  finally(finalizer) {
+    this.finalizer = finalizer;
+    return this;
+  }
+  async run(source) {
+    const outputs = {};
+    for (const machine of this.machines) {
+      const input = machine.builder(source, outputs);
+      const isValid = await machine.task.validateInput(input);
+      if (!isValid) {
+        throw new Error(`Input validation failed for task '${machine.task.ident}'`);
+      }
+      const result = await machine.task.run(input);
+      outputs[machine.task.ident] = result;
+    }
+    if (this.finalizer) {
+      await this.finalizer(source, outputs);
+    }
+    return outputs;
+  }
+}
+
+// src/prototypes/Workflow.ts
+class Workflow {
+  playlist;
+  triggers;
+  constructor(triggers, playlist) {
+    this.triggers = triggers;
+    this.playlist = playlist;
+  }
+  addTrigger(trigger) {
+    const newTriggers = [...this.triggers, trigger];
+    const newPlaylist = this.playlist;
+    return new Workflow(newTriggers, newPlaylist);
+  }
+  setPlaylist(builder) {
+    const initialPlaylist = new Playlist;
+    const finalPlaylist = builder(initialPlaylist);
+    return new Workflow(this.triggers, finalPlaylist);
+  }
+  async start({ interval = 5000, callback } = {}) {
+    if (!this.playlist) {
+      throw new Error("Cannot start a workflow without a playlist.");
+    }
+    for (const trigger of this.triggers) {
+      await trigger.start();
+    }
+    const runTick = async () => {
+      for (const trigger of this.triggers) {
+        const event = trigger.poll();
+        if (event) {
+          try {
+            const outputs = await this.playlist.run(event);
+            if (callback) {
+              callback(event, outputs);
+            }
+          } catch (error) {
+            console.error(`[Workflow] Error during playlist execution for trigger '${event.triggerIdent}':`, error);
+          }
+        }
+      }
+      setTimeout(runTick, interval);
+    };
+    runTick();
+  }
+  static create() {
+    return new Workflow([], null);
+  }
+}
+// src/prototypes/Task.ts
+class Task {
+  ident;
+  constructor(ident) {
+    this.ident = ident;
+  }
+}
+// src/prototypes/Trigger.ts
+class EventQueue {
+  size;
+  queue = [];
+  constructor(size) {
+    this.size = size;
+  }
+  push(item) {
+    if (this.queue.length + 1 > this.size) {
+      this.queue.shift();
+    }
+    this.queue.push(item);
+  }
+  shift() {
+    return this.queue.shift();
+  }
+  get length() {
+    return this.queue.length;
+  }
+}
+
+class Trigger {
+  ident;
+  queue;
+  constructor(ident, queueSize = 50) {
+    this.ident = ident;
+    this.queue = new EventQueue(queueSize);
+  }
+  pushEvent(data) {
+    this.queue.push({
+      triggerIdent: this.ident,
+      data
+    });
+  }
+  poll() {
+    const event = this.queue.shift();
+    return event ?? null;
+  }
+}
+// src/prototypes/Machine.ts
+import pino from "pino";
+import { randomUUID } from "crypto";
+var glogger = null;
+
+class StateNode {
+  transitions;
+  playlist;
+  timeToNextTick;
+  ident;
+  tempTransitions;
+  retry;
+  maxRetries;
+  constructor(transitions, playlist) {
+    this.transitions = transitions;
+    this.playlist = playlist;
+    this.timeToNextTick = 1000;
+    this.ident = "";
+    this.retry = 1000;
+    this.maxRetries = false;
+  }
+  static create() {
+    return new StateNode([], new Playlist);
+  }
+  addTransition({ to, condition, weight }) {
+    if (!this.tempTransitions) {
+      this.tempTransitions = [];
+    }
+    this.tempTransitions?.push({ to, condition, weight });
+    return this;
+  }
+  setPlaylist(arg) {
+    if (typeof arg === "function") {
+      const initial = new Playlist;
+      const finalPlaylist = arg(initial);
+      this.playlist = finalPlaylist;
+      return this;
+    }
+    this.playlist = arg;
+    return this;
+  }
+  preventRetry() {
+    this.retry = false;
+    return this;
+  }
+  retryDelayMs(delayMs) {
+    this.retry = delayMs;
+    return this;
+  }
+  retryLimit(maxRetries) {
+    this.maxRetries = maxRetries;
+    return this;
+  }
+  setIdent(ident) {
+    this.ident = ident;
+    return this;
+  }
+  getByIdent(ident, visited = []) {
+    if (this.ident === ident) {
+      return this;
+    }
+    if (visited.includes(this.ident)) {
+      return null;
+    }
+    visited.push(this.ident);
+    if (this.transitions) {
+      for (const transition of this.transitions) {
+        const found = transition.to?.getByIdent(ident, visited);
+        if (found)
+          return found;
+      }
+    }
+    return null;
+  }
+  async next(data) {
+    const logger = glogger?.child({ path: "StateNode.next", state: this.ident });
+    logger?.info({ phase: "start" }, "Evaluating next state");
+    const sorted = [...this.transitions || []].map((t, i) => ({ t, i })).sort((a, b) => (b.t.weight ?? 0) - (a.t.weight ?? 0) || a.i - b.i);
+    for (const { t } of sorted) {
+      try {
+        if (await t.condition(data)) {
+          logger?.info({ phase: "end", nextState: t.to?.ident }, "Condition met, transitioning");
+          return t.to;
+        }
+      } catch (err) {
+        logger?.error({ phase: "error", error: err }, "Transition condition failed");
+      }
+    }
+    logger?.info({ phase: "end", nextState: null }, "No condition met, no transition");
+    return null;
+  }
+}
+
+class Machine {
+  initialState = null;
+  statesToCreate = [];
+  currentState = null;
+  finalized = false;
+  logger;
+  ident;
+  getAllStates() {
+    const logger = glogger?.child({ path: "machine.getAllStates" });
+    logger?.info({ phase: "start" }, "Gathering all states...");
+    if (!this.initialState)
+      return [];
+    const visited = new Set;
+    const result = [];
+    const stack = [this.initialState];
+    while (stack.length > 0) {
+      const node = stack.pop();
+      if (!node.ident || visited.has(node.ident))
+        continue;
+      visited.add(node.ident);
+      result.push(node);
+      for (const tr of node.transitions || []) {
+        if (tr.to && tr.to.ident && !visited.has(tr.to.ident)) {
+          stack.push(tr.to);
+        }
+      }
+    }
+    logger?.info({ phase: "end" }, "States gathered");
+    return result;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  static create() {
+    return new Machine;
+  }
+  finalize({
+    verbose,
+    ident
+  } = {}) {
+    const logger = glogger?.child({ path: "machine.finalize", instance: this.ident });
+    if (!this.initialState || this.statesToCreate.length === 0) {
+      logger?.error({ phase: "error" }, "Finalization failed: no initial state or states to create");
+      throw new Error("Cannot finalize a machine without an initial state or states to create.");
+    }
+    if (ident) {
+      this.ident = ident;
+    } else {
+      this.ident = randomUUID();
+    }
+    if (verbose)
+      glogger = pino();
+    logger?.info("Logging enabled.");
+    logger?.info({ phase: "start" }, `Finalizing machine ${this.ident}...`);
+    const registry = new Map;
+    logger?.info({ phase: "progress" }, `Building state registry...`);
+    for (const s of this.statesToCreate) {
+      if (!s.ident) {
+        logger?.error({ phase: "error" }, "Finalization failed: state missing ident");
+        throw new Error("State missing ident.");
+      }
+      if (registry.has(s.ident)) {
+        logger?.error({ phase: "error", state: s.ident }, "Finalization failed: duplicate state ident");
+        throw new Error(`Duplicate state ident '${s.ident}'.`);
+      }
+      registry.set(s.ident, s);
+    }
+    logger?.info({ phase: "progress", count: registry.size }, `State registry built.`);
+    logger?.info({ phase: "progress" }, `Resolving transitions...`);
+    for (const state of this.statesToCreate) {
+      state.transitions = [];
+      for (const tr of state.tempTransitions || []) {
+        const toNode = registry.get(tr.to);
+        if (!toNode) {
+          logger?.error({ phase: "error", from: state.ident, to: tr.to }, "Finalization failed: target state not found");
+          throw new Error(`State '${tr.to}' not found.`);
+        }
+        state.transitions.push({ to: toNode, condition: tr.condition, weight: tr.weight });
+      }
+      state.tempTransitions = undefined;
+    }
+    logger?.info({ phase: "progress" }, `Transitions resolved.`);
+    this.statesToCreate = [];
+    this.finalized = true;
+    logger?.info({ phase: "end" }, `Machine ${this.ident} finalized.`);
+    return this;
+  }
+  addState(state, options = {}) {
+    const logger = glogger?.child({ path: "machine.addState", instance: this.ident });
+    logger?.info({ phase: "start", state: state.ident, isInitial: !!options.initial }, "Adding state");
+    this.statesToCreate.push(state);
+    if (options.initial) {
+      this.initialState = state;
+    }
+    logger?.info({ phase: "end", state: state.ident }, "State added");
+    return this;
+  }
+  async start(stateData, options) {
+    const logger = glogger?.child({ path: "machine.start", instance: this.ident });
+    logger?.info({ phase: "start" }, "Starting machine...");
+    if (!this.finalized) {
+      logger?.error({ phase: "error" }, "Machine not finalized");
+      throw new Error("Cannot start a machine that is not finalized.");
+    }
+    if (!this.initialState) {
+      logger?.error({ phase: "error" }, "No initial state");
+      throw new Error("Cannot start a machine without an initial state.");
+    }
+    const interval = options?.interval ?? 1000;
+    logger?.info({ phase: "progress", interval }, "Machine interval set");
+    if (!this.currentState) {
+      this.currentState = this.initialState;
+      logger?.info({ phase: "progress", state: this.currentState.ident }, "Set initial state. Running playlist.");
+      await this.currentState.playlist.run(stateData);
+      logger?.info({ phase: "progress", state: this.currentState.ident }, "Initial playlist run complete.");
+    }
+    const tick = async () => {
+      const tickLogger = logger?.child({ path: "machine.tick" });
+      tickLogger?.info({ phase: "start", state: this.currentState.ident }, "Tick.");
+      const next = await this.currentState.next(stateData);
+      if (next) {
+        tickLogger?.info({ phase: "progress", from: this.currentState.ident, to: next.ident }, "Transitioning state.");
+        this.currentState = next;
+        await this.currentState.playlist.run(stateData);
+        tickLogger?.info({ phase: "progress", state: this.currentState.ident }, "Playlist run complete.");
+      } else {
+        tickLogger?.info({ phase: "progress", state: this.currentState.ident }, "No next state.");
+      }
+      setTimeout(tick, interval);
+    };
+    tick();
+    logger?.info({ phase: "end" }, "Machine started, tick loop initiated.");
+  }
+  async run(stateData) {
+    const logger = glogger?.child({ path: "machine.run", instance: this.ident });
+    logger?.info({ phase: "start" }, "Running machine...");
+    if (!this.finalized) {
+      logger?.error({ phase: "error" }, "Machine not finalized");
+      throw new Error("Cannot run a machine that is not finalized.");
+    }
+    if (!this.initialState) {
+      logger?.error({ phase: "error" }, "No initial state");
+      throw new Error("Cannot run a machine without an initial state.");
+    }
+    const allStates = this.getAllStates();
+    const visitedIdents = new Set;
+    let current = this.initialState;
+    logger?.info({ phase: "progress", state: current.ident }, "Set initial state. Running playlist.");
+    await current.playlist.run(stateData);
+    visitedIdents.add(current.ident);
+    while (true) {
+      if (!current.transitions || current.transitions.length === 0) {
+        logger?.info({ phase: "end", state: current.ident }, "Reached leaf node, run complete.");
+        return stateData;
+      }
+      let next = await current.next(stateData);
+      if (!next) {
+        const retryDelay = current.retry;
+        if (!retryDelay) {
+          logger?.info({ phase: "end", state: current.ident }, "No next state and retries disabled, run complete.");
+          return stateData;
+        }
+        let retries = 0;
+        logger?.info({ phase: "progress", state: current.ident, retryDelay }, "No next state, beginning retry logic.");
+        while (!next) {
+          if (current.maxRetries && retries >= current.maxRetries) {
+            logger?.warn({ phase: "end", state: current.ident, retries }, "Retry limit exhausted, run complete.");
+            return stateData;
+          }
+          await this.sleep(retryDelay);
+          logger?.info({ phase: "progress", state: current.ident, attempt: retries + 1 }, "Retrying to find next state.");
+          next = await current.next(stateData);
+          if (next) {
+            logger?.info({ phase: "progress", state: current.ident, nextState: next.ident }, "Retry successful.");
+            break;
+          }
+          retries++;
+        }
+        if (!next) {
+          logger?.info({ phase: "end" }, "No next state after retries, run complete.");
+          return stateData;
+        }
+      }
+      if (next === this.initialState) {
+        logger?.info({ phase: "end" }, "Next state is initial state, run complete.");
+        return stateData;
+      }
+      logger?.info({ phase: "progress", from: current.ident, to: next.ident }, "Transitioning state.");
+      current = next;
+      await current.playlist.run(stateData);
+      if (current.ident)
+        visitedIdents.add(current.ident);
+      if (visitedIdents.size >= allStates.length) {
+        logger?.info({ phase: "end" }, "All reachable states visited, run complete.");
+        return stateData;
+      }
+    }
+    return stateData;
+  }
+}
+export {
+  Workflow,
+  Trigger,
+  Task,
+  StateNode,
+  Playlist,
+  Machine
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@fkws/klonk",
+  "version": "0.0.4",
+  "description": "A lightweight, extensible workflow automation engine for Node.js and Bun",
+  "bin": {
+    "klonk": "./dist/cli.js"
+  },
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "bun index.ts",
+    "build": "bunx rimraf dist && bunup",
+    "prepublishOnly": "bun run build",
+    "release": "bun scripts/release.js",
+    "release:patch": "bun scripts/release.js patch",
+    "release:minor": "bun scripts/release.js minor",
+    "release:major": "bun scripts/release.js major"
+  },
+  "keywords": [
+    "workflow",
+    "automation",
+    "zapier",
+    "notion",
+    "openai"
+  ],
+  "author": "FKWS (https://klonk.dev)",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/express": "^5.0.1",
+    "@types/node": "latest",
+    "bunup": "^0.6.2",
+    "tavily": "^1.0.2"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "cli-highlight": "^2.1.11",
+    "commander": "^13.1.0",
+    "express": "^5.1.0",
+    "json-to-zod": "^1.1.2",
+    "pino": "^10.1.0"
+  }
+}