@oalo-ai/cli 0.0.0-stage → 0.1.1

package/src/envfile.js

@@ -0,0 +1,71 @@
+/**
+ * Read a `.env` file into `[{name, value}]`, the way dotenv does:
+ *
+ *   NAME=value            # a comment after a space
+ *   export NAME=value
+ *   NAME="double quoted, \n and \" work, and it may span lines"
+ *   NAME='single quoted, taken as is'
+ *
+ * Blank lines and lines starting with # are skipped. A later line wins over an
+ * earlier one with the same name. Throws on a line it can't read, naming it.
+ */
+export function parseDotenv(text) {
+  const out = new Map();
+  const lines = String(text).replace(/^\uFEFF/, "").split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!m) throw new Error(`line ${i + 1} isn't NAME=value: ${raw.slice(0, 60)}`);
+    const [, name] = m;
+    let rest = m[2];
+    let value;
+
+    if (rest.startsWith('"')) {
+      // May continue over the next lines until the closing quote.
+      let body = rest.slice(1);
+      const start = i;
+      while (!closes(body)) {
+        if (++i >= lines.length) throw new Error(`line ${start + 1}: ${name} opens a " that never closes`);
+        body += "\n" + lines[i];
+      }
+      const end = closingIndex(body);
+      value = body
+        .slice(0, end)
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/\\(["\\])/g, "$1");
+    } else if (rest.startsWith("'")) {
+      const end = rest.indexOf("'", 1);
+      if (end < 0) throw new Error(`line ${i + 1}: ${name} opens a ' that never closes`);
+      value = rest.slice(1, end);
+    } else {
+      value = rest.replace(/\s+#.*$/, "").trim();
+    }
+
+    out.set(name, value);
+  }
+
+  return [...out].map(([name, value]) => ({ name, value }));
+}
+
+function closingIndex(s) {
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") i++;
+    else if (s[i] === '"') return i;
+  }
+  return -1;
+}
+
+const closes = (s) => closingIndex(s) >= 0;
+
+/** `NAME=value` from the command line. The value may contain `=`. */
+export function parseAssignment(arg) {
+  const i = arg.indexOf("=");
+  if (i <= 0) return null;
+  return { name: arg.slice(0, i), value: arg.slice(i + 1) };
+}

package/src/events.js

@@ -0,0 +1,63 @@
+/**
+ * Shared event rendering for `oalo tail` and `oalo run --watch`. Both stream the
+ * same channel pushes, so they format them the same way from one place.
+ */
+
+// Phoenix's own frames. Not events, and showing them buries the signal.
+// Note replies arrive as `chan_reply_<ref>`, NOT `phx_reply`, so the prefix
+// test matters — without it every RPC answer shows up as an event.
+const INTERNAL = new Set(["phx_reply", "phx_close", "phx_error", "phx_join", "phx_leave"]);
+const isInternal = (event) => INTERNAL.has(event) || event.startsWith("chan_reply_");
+
+// High-frequency streaming chunks. A tail is for "what happened", not for
+// re-rendering an LLM token stream, so these need --all to appear.
+const NOISY = /(:chunk$|^response:|_chunk$)/;
+
+const COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (COLOR ? `\x1b[2m${s}\x1b[0m` : s);
+const bold = (s) => (COLOR ? `\x1b[1m${s}\x1b[0m` : s);
+
+function clock(at) {
+  const d = at ? new Date(at) : new Date();
+  return Number.isNaN(d.getTime()) ? new Date().toTimeString().slice(0, 8) : d.toTimeString().slice(0, 8);
+}
+
+/** One readable line per event. Falls back to compact JSON for unknown shapes. */
+function format(event, payload) {
+  const p = payload && typeof payload === "object" ? payload : {};
+
+  if (event === "activity:event") {
+    const who = p.actor?.username || p.actor?.user_id || "someone";
+    const what = [p.verb, p.object_type, p.object_name && `"${p.object_name}"`]
+      .filter(Boolean)
+      .join(" ");
+    return `${bold(who)} ${what || p.surface}${p.link ? dim(` ${p.link}`) : ""}`;
+  }
+
+  if (event === "jobs:update") {
+    const queues = Object.entries(p.by_queue || {})
+      .map(([q, n]) => `${q}=${n}`)
+      .join(" ");
+    return `running=${p.running ?? 0}${queues ? ` ${dim(queues)}` : ""}`;
+  }
+
+  if (event === "loop_run_status" || event === "loop_node_status") {
+    return [p.status, p.loop_name || p.loop_id, p.node_id && dim(p.node_id)].filter(Boolean).join(" ");
+  }
+
+  if (event === "team_chat:message") {
+    // The field is `content`; system announcements have a null user_id.
+    const who = p.username || (p.kind === "system" ? "system" : "?");
+    return `${bold(who)}: ${String(p.content ?? "").slice(0, 120)}`;
+  }
+
+  if (event === "build:updated" || event === "preview:building" || event === "preview:reload") {
+    return [p.status, p.slug, p.app_id].filter(Boolean).join(" ") || dim("(no detail)");
+  }
+
+  const json = JSON.stringify(p);
+  return json === "{}" ? dim("(no payload)") : json.length > 160 ? json.slice(0, 157) + "..." : json;
+}
+
+
+export { isInternal, NOISY, format, clock, dim, bold };

package/src/graphfiles.js

@@ -0,0 +1,273 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, unlinkSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+
+/**
+ * Flows and loops as files in the project, for `oalo pull` / `push` / `status`.
+ *
+ *   .oalo/flows/<bot public id>/<flow name>.json
+ *   .oalo/loops/<loop name>.json          (org loops)
+ *   .oalo/loops/apps/<app id>/<loop name>.json  (loops pinned to one app)
+ *   .oalo/tools/<tool name>.js + .json  a code tool: its JavaScript, and its
+ *                                      description, schemas and bookkeeping
+ *   .oalo/catalog/{flow,loop}.json     the node contract, refreshed on pull
+ *
+ * Each file separates WHAT YOU EDIT (`flow` / `loop`) from bookkeeping the CLI
+ * owns (`id`, `version`, `base_hash`). `base_hash` is the hash of the editable
+ * content as it was pulled, so "you changed this" (hash differs) can be told
+ * apart from "the server moved on" (remote version differs) without keeping a
+ * second copy of every graph. `version` goes back to the server as
+ * `base_version`, so a concurrent edit is refused instead of overwritten.
+ *
+ * The editable keys mirror what the save events accept. Read-only extras the
+ * server returns (stats, timestamps) are dropped, and the editor's own keys
+ * inside the graph (x/y, position, labels) are kept so the visual editor still
+ * lays a pushed graph out.
+ */
+
+export const ROOT = ".oalo";
+
+export const FLOW_FIELDS = [
+  "name",
+  "description",
+  "enabled",
+  "trigger",
+  "trigger_instructions",
+  "auto_start_on_open",
+  "max_cost_usd",
+  "graph",
+];
+
+export const LOOP_FIELDS = [
+  "description",
+  "enabled",
+  "cron",
+  "max_iterations",
+  "max_cost_usd",
+  "session_mode",
+  "provider",
+  "model",
+  "trigger_type",
+  "trigger_event",
+  "trigger_filter",
+  "entry",
+  "nodes",
+  "edges",
+];
+
+export const TOOL_FIELDS = ["description", "input_schema", "output_schema"];
+
+const ABOUT = {
+  tool: "The code is in the .js file next to this one (`source`); edit it, or `tool`, then `oalo push`. It is compiled when pushed, so code that doesn't build is refused. Leave id, version and base_hash alone.",
+  flow: "Edit `flow`, then `oalo lint` and `oalo push`. Leave id, version and base_hash alone. The node contract is .oalo/catalog/flow.json.",
+  loop: "Edit `loop`, then `oalo lint` and `oalo push`. The name is the loop's identity. Leave version, base_hash and trigger_base alone. The node contract is .oalo/catalog/loop.json. `triggers` is what starts the loop: add one as {type, event | cron | widget_id, filter?} (types and events: oalo_loop_triggers action=catalog), delete one to remove it, and push. Set a trigger's `enabled` to turn it on or off. `trigger_type`/`trigger_event` in `loop` are the old single trigger; prefer `triggers`.",
+};
+
+/** JSON with object keys sorted at every level, so equal content hashes equal. */
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .filter((k) => value[k] !== undefined)
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+export const hashOf = (content) => createHash("sha256").update(canonical(content)).digest("hex").slice(0, 16);
+
+/** A file-name-safe form of a flow or loop name (the real name stays inside). */
+export function slug(name) {
+  const s = String(name || "")
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return s || "unnamed";
+}
+
+const pick = (obj, keys) => Object.fromEntries(keys.filter((k) => k in (obj || {})).map((k) => [k, obj[k]]));
+
+export const flowPath = (bot, name, cwd = process.cwd()) => join(cwd, ROOT, "flows", bot, `${slug(name)}.json`);
+// Org loops are unique by name; a loop pinned to an app is unique within that
+// app, so it gets its own folder (an org loop and an app loop can share a name).
+export const loopPath = (name, appId = null, cwd = process.cwd()) =>
+  appId ? join(cwd, ROOT, "loops", "apps", slug(appId), `${slug(name)}.json`) : join(cwd, ROOT, "loops", `${slug(name)}.json`);
+export const catalogPath = (surface, cwd = process.cwd()) => join(cwd, ROOT, "catalog", `${surface}.json`);
+
+/** A flow as the server returned it -> the file we keep. */
+export function flowFile(remote, bot) {
+  const flow = pick(remote, FLOW_FIELDS);
+  return { $about: ABOUT.flow, kind: "flow", bot, id: remote.id, version: remote.version ?? null, base_hash: hashOf(flow), flow };
+}
+
+/**
+ * A loop entry as the server returned it -> the file we keep. With `triggers`
+ * (the loop's trigger list), the file carries them and the ids it saw
+ * (`trigger_base`), so a push removes only triggers deleted from the file, not
+ * ones a teammate added since.
+ */
+export function loopFile(remote, triggers) {
+  const loop = pick(remote, LOOP_FIELDS);
+  const file = {
+    $about: ABOUT.loop,
+    kind: "loop",
+    name: remote.name,
+    app_id: remote.app_id ?? null,
+    version: remote.version ?? null,
+    base_hash: null,
+    loop,
+  };
+  if (Array.isArray(triggers)) {
+    file.triggers = triggers.map(cleanTrigger);
+    file.trigger_base = file.triggers.map((t) => t.id).filter(Boolean);
+  }
+  file.base_hash = hashOf(content(file));
+  return file;
+}
+
+/** A trigger as listed, without empty keys. */
+export function cleanTrigger(t) {
+  return Object.fromEntries(Object.entries(t || {}).filter(([, v]) => v !== null && v !== undefined));
+}
+
+/** The keys that make two triggers the same trigger (not its id or on/off). */
+// An api trigger's contract (description, input, output) is part of it: a changed
+// contract is pushed as a changed trigger.
+export const triggerKey = (t) => canonical({ type: t.type, event: t.event ?? null, cron: t.cron ?? null, batch_size: t.batch_size ?? null, filter: t.filter ?? null, widget_id: t.widget_id ?? null, description: t.description ?? null, input: t.input ?? null, output: t.output ?? null });
+
+export const toolPaths = (name, cwd = process.cwd()) => {
+  const base = join(cwd, ROOT, "tools", slug(name));
+  return { meta: `${base}.json`, source: `${base}.js` };
+};
+
+/**
+ * A code tool as fn:source returned it -> {meta file, source text}. Its
+ * `version` is the server's source hash: tools have no version number, so the
+ * code itself is the concurrency token.
+ */
+export function toolFile(remote, bot = null) {
+  const tool = pick(remote, TOOL_FIELDS);
+  const source = remote.source_js || "";
+  return {
+    meta: {
+      $about: ABOUT.tool,
+      kind: "tool",
+      id: remote.id,
+      name: remote.name,
+      ...(bot ? { bot } : {}),
+      source: `${slug(remote.name)}.js`,
+      version: remote.source_hash ?? null,
+      // Trailing whitespace is ignored: the .js file always ends in a newline.
+      base_hash: hashOf({ ...tool, source: source.trimEnd() }),
+      tool,
+    },
+    source,
+  };
+}
+
+// A loop file without `triggers` (pulled before they were) hashes as before.
+export const content = (file) =>
+  file.kind === "flow"
+    ? file.flow
+    : file.kind === "loop"
+      ? Array.isArray(file.triggers)
+        ? { ...file.loop, __triggers: file.triggers.map(cleanTrigger) }
+        : file.loop
+      : { ...file.tool, source: (file._source ?? "").trimEnd() };
+
+/** Has the editable content changed since it was pulled (or is it new)? */
+export function locallyModified(file) {
+  if (file.version == null || !file.base_hash) return true;
+  return hashOf(content(file)) !== file.base_hash;
+}
+
+/**
+ * Where a local file stands against the remote copy.
+ *   new       never pushed (no version)
+ *   clean     same as the server
+ *   modified  edited locally; the server has not moved: push it
+ *   behind    unchanged locally; the server has a newer version: pull it
+ *   conflict  edited locally AND the server moved: merge by hand
+ *   gone      the server no longer has it
+ */
+export function standing(file, remote) {
+  const edited = locallyModified(file);
+  if (file.version == null) return remote ? "conflict" : "new";
+  if (!remote) return "gone";
+  const moved = remote.version !== file.version;
+  if (edited && moved) return "conflict";
+  if (edited) return "modified";
+  if (moved) return "behind";
+  return "clean";
+}
+
+export function readGraphFile(path) {
+  const file = JSON.parse(readFileSync(path, "utf8"));
+  if (!["flow", "loop", "tool"].includes(file.kind)) throw new Error(`${path}: not an oalo flow, loop or tool file (kind is ${JSON.stringify(file.kind)})`);
+  if (file.kind === "tool") {
+    if (!file.name || !file.tool) throw new Error(`${path}: a tool file needs \`name\` and \`tool\``);
+    const src = join(dirname(path), file.source || `${slug(file.name)}.js`);
+    if (!existsSync(src)) throw new Error(`${path}: its source file ${file.source} is missing`);
+    // Not written back: the .js file is the source of truth for the code.
+    Object.defineProperty(file, "_source", { value: readFileSync(src, "utf8"), enumerable: false });
+  }
+  if (file.kind === "flow" && (!file.bot || !file.flow)) throw new Error(`${path}: a flow file needs \`bot\` and \`flow\``);
+  if (file.kind === "loop" && (!file.name || !file.loop)) throw new Error(`${path}: a loop file needs \`name\` and \`loop\``);
+  return file;
+}
+
+export function writeToolFiles(name, { meta, source }, cwd = process.cwd()) {
+  const p = toolPaths(name, cwd);
+  writeGraphFile(p.meta, meta);
+  writeFileSync(p.source, source.endsWith("\n") ? source : source + "\n");
+  return p.meta;
+}
+
+export function writeGraphFile(path, file) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(file, null, 2) + "\n");
+}
+
+export function removeFile(path) {
+  if (existsSync(path)) unlinkSync(path);
+}
+
+// `<name>.server.json` is the server's copy saved by a conflicted push: a merge
+// aid, not a file to push.
+const isGraphFile = (f) => f.endsWith(".json") && !f.endsWith(".server.json");
+
+/** Every flow and loop file under .oalo/, as absolute paths. */
+export function listGraphFiles(cwd = process.cwd()) {
+  const out = [];
+  const flowsDir = join(cwd, ROOT, "flows");
+  const loopsDir = join(cwd, ROOT, "loops");
+  const toolsDir = join(cwd, ROOT, "tools");
+
+  if (existsSync(flowsDir)) {
+    for (const bot of readdirSync(flowsDir, { withFileTypes: true })) {
+      if (!bot.isDirectory()) continue;
+      for (const f of readdirSync(join(flowsDir, bot.name))) if (isGraphFile(f)) out.push(join(flowsDir, bot.name, f));
+    }
+  }
+  if (existsSync(loopsDir)) {
+    for (const e of readdirSync(loopsDir, { withFileTypes: true })) {
+      if (e.isFile() && isGraphFile(e.name)) out.push(join(loopsDir, e.name));
+      if (e.isDirectory() && e.name === "apps") {
+        for (const app of readdirSync(join(loopsDir, "apps"), { withFileTypes: true })) {
+          if (!app.isDirectory()) continue;
+          for (const f of readdirSync(join(loopsDir, "apps", app.name))) if (isGraphFile(f)) out.push(join(loopsDir, "apps", app.name, f));
+        }
+      }
+    }
+  }
+  if (existsSync(toolsDir)) {
+    for (const f of readdirSync(toolsDir)) if (isGraphFile(f)) out.push(join(toolsDir, f));
+  }
+  return out.sort();
+}
+
+export const rel = (path, cwd = process.cwd()) => relative(cwd, path);