@bendyline/gezel-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,231 @@
+// src/rpc.ts
+import { readFileSync, writeSync } from "fs";
+import { Socket } from "net";
+var DEFAULT_INIT = {
+  input: void 0,
+  runId: "",
+  projectId: "",
+  engagementMode: "off",
+  engagementFlags: { llmAllowed: false }
+};
+function readInitSync() {
+  if (process.env.GEZEL_SCRIPT_RUNTIME !== "1") {
+    return DEFAULT_INIT;
+  }
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf8");
+  } catch {
+    return DEFAULT_INIT;
+  }
+  if (!raw) return DEFAULT_INIT;
+  try {
+    return JSON.parse(raw.trim());
+  } catch {
+    return DEFAULT_INIT;
+  }
+}
+var RpcClient = class {
+  init;
+  nextId = 0;
+  pending = /* @__PURE__ */ new Map();
+  buffer = "";
+  started = false;
+  _socket = null;
+  constructor() {
+    this.init = readInitSync();
+  }
+  /**
+   * Lazy-create the read side. We use `net.Socket` for reads (it gives
+   * us proper 'data' / 'end' events on POSIX socketpairs and Windows
+   * named pipes) but **never** for writes — see `writeFrame` below.
+   */
+  get socket() {
+    if (!this._socket) {
+      this._socket = new Socket({ fd: 3, readable: true, writable: true });
+      this._socket.setEncoding("utf8");
+      this._socket.unref();
+    }
+    return this._socket;
+  }
+  updatePendingRef() {
+    if (!this._socket) return;
+    if (this.pending.size > 0) this._socket.ref();
+    else this._socket.unref();
+  }
+  ensureStarted() {
+    if (this.started) return;
+    this.started = true;
+    this.socket.on("data", (chunk) => {
+      this.buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      let newline = this.buffer.indexOf("\n");
+      while (newline >= 0) {
+        const line = this.buffer.slice(0, newline);
+        this.buffer = this.buffer.slice(newline + 1);
+        if (line.length > 0) {
+          this.handleMessage(line);
+        }
+        newline = this.buffer.indexOf("\n");
+      }
+    });
+    this.socket.on("error", (err) => {
+      for (const pending of this.pending.values()) {
+        pending.reject(err instanceof Error ? err : new Error(String(err)));
+      }
+      this.pending.clear();
+    });
+    this.socket.on("end", () => {
+      const err = new Error("script RPC channel closed before all requests completed");
+      for (const pending of this.pending.values()) {
+        pending.reject(err);
+      }
+      this.pending.clear();
+    });
+    this.updatePendingRef();
+  }
+  handleMessage(line) {
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (typeof parsed.id !== "number") return;
+    const pending = this.pending.get(parsed.id);
+    if (!pending) return;
+    this.pending.delete(parsed.id);
+    this.updatePendingRef();
+    if (parsed.error) {
+      const err = new Error(parsed.error.message);
+      err.code = parsed.error.code;
+      pending.reject(err);
+    } else {
+      pending.resolve(parsed.result);
+    }
+  }
+  async call(method, params) {
+    const id = ++this.nextId;
+    const req = { id, method };
+    if (params !== void 0) req.params = params;
+    const payload = `${JSON.stringify(req)}
+`;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      try {
+        writeFrame(payload);
+      } catch (err) {
+        this.pending.delete(id);
+        reject(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+      this.ensureStarted();
+      this.updatePendingRef();
+    });
+  }
+  notify(method, params) {
+    const msg = { method };
+    if (params !== void 0) msg.params = params;
+    writeFrame(`${JSON.stringify(msg)}
+`);
+  }
+};
+function writeFrame(payload) {
+  const buf = Buffer.from(payload, "utf8");
+  let offset = 0;
+  while (offset < buf.length) {
+    offset += writeSync(3, buf, offset, buf.length - offset);
+  }
+}
+
+// src/index.ts
+function defineScript(meta) {
+  return meta;
+}
+var rpc = new RpcClient();
+var outputStamped = false;
+var gezel = {
+  get input() {
+    return rpc.init.input ?? {};
+  },
+  output(value) {
+    if (outputStamped) {
+      throw new Error("gezel.output() called more than once \u2014 a script may only stamp one output");
+    }
+    outputStamped = true;
+    rpc.notify("script.output", { value });
+  },
+  log(...args) {
+    rpc.notify("script.log", { args });
+    process.stderr.write(
+      `${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`
+    );
+  },
+  fs: {
+    read: (path) => rpc.call("fs.read", { path }),
+    write: (path, content) => rpc.call("fs.write", { path, content }),
+    list: (path) => rpc.call("fs.list", { path }),
+    listAll: () => rpc.call("fs.listAll"),
+    stat: (path) => rpc.call("fs.stat", { path }),
+    rm: (path) => rpc.call("fs.rm", { path }),
+    mkdir: (path) => rpc.call("fs.mkdir", { path }),
+    rename: (from, to) => rpc.call("fs.rename", { from, to })
+  },
+  artifacts: {
+    read: (path) => rpc.call("artifact.read", { path }),
+    write: (path, content) => rpc.call("artifact.write", { path, content }),
+    list: (prefix) => rpc.call("artifact.list", { prefix }),
+    delete: (path) => rpc.call("artifact.delete", { path })
+  },
+  documents: {
+    read: (name) => rpc.call("document.read", { name }),
+    write: (name, content) => rpc.call("document.write", { name, content }),
+    list: () => rpc.call("document.list"),
+    delete: (name) => rpc.call("document.delete", { name })
+  },
+  task: {
+    get: (ref) => rpc.call("task.get", { ref }),
+    steps: (ref) => rpc.call("task.steps", { ref }),
+    currentStep: (ref) => rpc.call("task.currentStep", { ref }),
+    update: (ref, patch) => rpc.call("task.update", { ref, patch }),
+    advance: (ref, nextPhaseName) => rpc.call("task.advance", { ref, nextPhaseName }),
+    writeNotes: (ref, content, phaseId) => rpc.call("task.writeNotes", { ref, content, phaseId }),
+    appendNote: (ref, text, stepId) => rpc.call("task.appendNote", { ref, text, stepId }),
+    readNotes: (ref, phaseId) => rpc.call("task.readNotes", { ref, phaseId }),
+    deleteNote: (ref, noteId) => rpc.call("task.deleteNote", { ref, noteId }),
+    create: (req) => rpc.call("task.create", { req })
+  },
+  memory: {
+    search: (query) => rpc.call("memory.search", { query }),
+    save: (text, meta) => rpc.call("memory.save", { text, meta })
+  },
+  llm: {
+    oneShot: (prompt, opts) => rpc.call("llm.oneShot", { prompt, opts })
+  },
+  mcp: {
+    call: (tool, args) => rpc.call("mcp.call", { tool, args })
+  },
+  http: {
+    request: (url, opts) => rpc.call("http.request", {
+      url,
+      ...opts?.method ? { method: opts.method } : {},
+      ...opts?.body !== void 0 ? { body: opts.body } : {},
+      ...opts?.headers ? { headers: opts.headers } : {}
+    }),
+    authed: (url, opts) => rpc.call("http.authed", {
+      url,
+      credential: opts.credential,
+      ...opts.method ? { method: opts.method } : {},
+      ...opts.body !== void 0 ? { body: opts.body } : {},
+      ...opts.headers ? { headers: opts.headers } : {},
+      ...opts.authScheme ? { authScheme: opts.authScheme } : {}
+    })
+  },
+  script: {
+    run: (name, input) => rpc.call("script.run", { name, input })
+  }
+};
+export {
+  defineScript,
+  gezel
+};

package/dist/stores.d.ts

@@ -0,0 +1,188 @@
+/**
+ * `@bendyline/gezel-sdk/stores` — small persistent-store helpers for
+ * sandboxed scripts: an append-only event log with derived stats
+ * (`logStore`) and a record roster with staged status transitions
+ * (`rosterStore`).
+ *
+ * These are the shared "data that accrues" primitives project-type
+ * scripts wrap (a language trainer's practice log, a job hunt's
+ * application pipeline) so each type doesn't hand-roll its own JSON
+ * handling, streak math, and transition history.
+ *
+ * Like `./checks`, this entry takes its dependencies structurally
+ * (`StoreFs`, satisfied by `gezel.fs` or `gezel.artifacts`) instead of
+ * importing the main entry's stdin-initialized singleton — the bundle
+ * stays standalone for vendoring into sandbox scratch dirs.
+ *
+ * Persistence rules:
+ * - A failed read is treated as "no store yet" (the structural interface
+ *   can't distinguish missing from unreadable; `gezel.fs.read` throws on
+ *   both). The file is created lazily on the first write.
+ * - Corrupt JSON or an unknown `version` throws — user data is never
+ *   silently reset.
+ * - Files are written pretty-printed with a trailing newline so they stay
+ *   pleasant to `cat` and diff, per the files-all-the-way-down principle.
+ * - Calls are single read-modify-write; cross-run races are out of scope
+ *   for a single-user local tool.
+ *
+ * Scripts using these helpers on the workspace need
+ * `requires: ['workspace.read', 'workspace.write']`.
+ */
+interface StoreFs {
+    /** Read a file's text content. Expected to throw when the file is absent. */
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+}
+interface StoreOptions {
+    /** Injectable clock for deterministic tests. Defaults to the real time. */
+    now?: () => string;
+}
+interface LogEvent {
+    at: string;
+    kind: string;
+    note?: string;
+    data?: Record<string, unknown>;
+}
+interface LogStats {
+    total: number;
+    byKind: Record<string, number>;
+    /** Consecutive UTC days with events, ending at the latest event's day. */
+    streakDays: number;
+    /** Distinct UTC days with at least one event. */
+    daysActive: number;
+    firstAt: string | null;
+    lastAt: string | null;
+}
+interface LogStoreFile {
+    version: 1;
+    events: LogEvent[];
+}
+interface LogStore {
+    append(event: {
+        kind: string;
+        note?: string;
+        data?: Record<string, unknown>;
+        at?: string;
+    }): Promise<LogEvent>;
+    /**
+     * Events matching the filter, oldest first. `since` is an inclusive ISO
+     * lower bound on `at`; `limit` keeps the most recent N matches.
+     */
+    list(filter?: {
+        kind?: string;
+        since?: string;
+        limit?: number;
+    }): Promise<LogEvent[]>;
+    stats(): Promise<LogStats>;
+}
+declare function logStore(fs: StoreFs, path: string, opts?: StoreOptions): LogStore;
+interface RosterTransition {
+    at: string;
+    /** Null on the record's creation entry. `from === to` marks a note-only touch. */
+    from: string | null;
+    to: string;
+    note?: string;
+}
+interface RosterRecord {
+    id: string;
+    status: string;
+    fields: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    history: RosterTransition[];
+}
+interface RosterStoreFile {
+    version: 1;
+    stages: string[];
+    records: RosterRecord[];
+}
+interface RosterStore {
+    /** Add a record. Defaults: status = first stage; id = `<idPrefix>-<n>`. */
+    add(input?: {
+        id?: string;
+        status?: string;
+        fields?: Record<string, unknown>;
+        note?: string;
+    }): Promise<RosterRecord>;
+    get(id: string): Promise<RosterRecord | null>;
+    list(filter?: {
+        status?: string;
+    }): Promise<RosterRecord[]>;
+    /** Merge fields and/or record a note without changing status. */
+    update(id: string, patch: {
+        fields?: Record<string, unknown>;
+        note?: string;
+    }): Promise<RosterRecord>;
+    /** Move a record to another stage, appending to its history. */
+    transition(id: string, to: string, opts?: {
+        note?: string;
+    }): Promise<RosterRecord>;
+    /** Records per status; every declared stage present, zero-filled. */
+    counts(): Promise<Record<string, number>>;
+}
+interface RosterStoreOptions extends StoreOptions {
+    /** Stage vocabulary used to initialize a new store file. An existing file's own `stages` win. */
+    stages: [string, ...string[]];
+    /** Prefix for generated record ids. Defaults to `'rec'`. */
+    idPrefix?: string;
+}
+declare function rosterStore(fs: StoreFs, path: string, opts: RosterStoreOptions): RosterStore;
+interface LedgerEntry {
+    id: string;
+    at: string;
+    /** Always integer cents — float money drifts. */
+    amountCents: number;
+    kind: 'in' | 'out';
+    category: string;
+    note?: string;
+    data?: Record<string, unknown>;
+}
+interface LedgerBucket {
+    inCents: number;
+    outCents: number;
+    netCents: number;
+}
+interface LedgerTotals extends LedgerBucket {
+    count: number;
+    byCategory: Record<string, LedgerBucket>;
+    /** Keyed by UTC month, `YYYY-MM`. */
+    byMonth: Record<string, LedgerBucket>;
+}
+interface LedgerStoreFile {
+    version: 1;
+    currency: string;
+    entries: LedgerEntry[];
+}
+interface LedgerStore {
+    add(entry: {
+        amountCents: number;
+        kind: 'in' | 'out';
+        category: string;
+        note?: string;
+        at?: string;
+        data?: Record<string, unknown>;
+    }): Promise<LedgerEntry>;
+    /** Entries matching the filter, oldest first. `month` is `YYYY-MM` (UTC). */
+    list(filter?: {
+        kind?: 'in' | 'out';
+        category?: string;
+        month?: string;
+        limit?: number;
+    }): Promise<LedgerEntry[]>;
+    /** Rollups over the (optionally filtered) entries. */
+    totals(filter?: {
+        month?: string;
+        category?: string;
+    }): Promise<LedgerTotals>;
+}
+/**
+ * Money in/out with categories and monthly rollups — budgets, invoices,
+ * event budgets, pledge drives. Same persistence rules as the other
+ * stores; amounts are validated positive integers (the `kind` carries
+ * the sign).
+ */
+declare function ledgerStore(fs: StoreFs, path: string, opts?: StoreOptions & {
+    currency?: string;
+}): LedgerStore;
+
+export { type LedgerBucket, type LedgerEntry, type LedgerStore, type LedgerStoreFile, type LedgerTotals, type LogEvent, type LogStats, type LogStore, type LogStoreFile, type RosterRecord, type RosterStore, type RosterStoreFile, type RosterStoreOptions, type RosterTransition, type StoreFs, type StoreOptions, ledgerStore, logStore, rosterStore };

package/dist/stores.js

@@ -0,0 +1,287 @@
+// src/stores.ts
+function defaultNow() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function parseStoreFile(path, raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Store file ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}). Fix or remove the file; it will not be overwritten automatically.`
+    );
+  }
+  const version = parsed.version;
+  if (version !== 1) {
+    throw new Error(`Store file ${path} has unsupported version ${String(version)} (expected 1).`);
+  }
+  return parsed;
+}
+async function loadStoreFile(fs, path) {
+  let raw;
+  try {
+    raw = await fs.read(path);
+  } catch {
+    return null;
+  }
+  return parseStoreFile(path, raw);
+}
+async function saveStoreFile(fs, path, value) {
+  await fs.write(path, `${JSON.stringify(value, null, 2)}
+`);
+}
+function utcDay(iso) {
+  return iso.slice(0, 10);
+}
+function logStore(fs, path, opts = {}) {
+  const now = opts.now ?? defaultNow;
+  async function load() {
+    return await loadStoreFile(fs, path) ?? { version: 1, events: [] };
+  }
+  return {
+    async append(event) {
+      const file = await load();
+      const entry = {
+        at: event.at ?? now(),
+        kind: event.kind,
+        ...event.note !== void 0 ? { note: event.note } : {},
+        ...event.data !== void 0 ? { data: event.data } : {}
+      };
+      file.events.push(entry);
+      await saveStoreFile(fs, path, file);
+      return entry;
+    },
+    async list(filter = {}) {
+      const file = await load();
+      let events = file.events;
+      if (filter.kind !== void 0) events = events.filter((e) => e.kind === filter.kind);
+      if (filter.since !== void 0) events = events.filter((e) => e.at >= filter.since);
+      if (filter.limit !== void 0 && filter.limit >= 0 && events.length > filter.limit) {
+        events = events.slice(events.length - filter.limit);
+      }
+      return events;
+    },
+    async stats() {
+      const file = await load();
+      const byKind = {};
+      const days = /* @__PURE__ */ new Set();
+      let firstAt = null;
+      let lastAt = null;
+      for (const e of file.events) {
+        byKind[e.kind] = (byKind[e.kind] ?? 0) + 1;
+        days.add(utcDay(e.at));
+        if (firstAt === null || e.at < firstAt) firstAt = e.at;
+        if (lastAt === null || e.at > lastAt) lastAt = e.at;
+      }
+      let streakDays = 0;
+      if (lastAt !== null) {
+        let cursor = Date.parse(`${utcDay(lastAt)}T00:00:00Z`);
+        while (days.has(new Date(cursor).toISOString().slice(0, 10))) {
+          streakDays += 1;
+          cursor -= 24 * 60 * 60 * 1e3;
+        }
+      }
+      return {
+        total: file.events.length,
+        byKind,
+        streakDays,
+        daysActive: days.size,
+        firstAt,
+        lastAt
+      };
+    }
+  };
+}
+function rosterStore(fs, path, opts) {
+  const now = opts.now ?? defaultNow;
+  const idPrefix = opts.idPrefix ?? "rec";
+  async function load() {
+    return await loadStoreFile(fs, path) ?? {
+      version: 1,
+      stages: [...opts.stages],
+      records: []
+    };
+  }
+  function mustFind(file, id) {
+    const record = file.records.find((r) => r.id === id);
+    if (!record) {
+      throw new Error(
+        `No record '${id}' in ${path}. Known ids: ${file.records.map((r) => r.id).join(", ") || "(none)"}`
+      );
+    }
+    return record;
+  }
+  function assertStage(file, status) {
+    if (!file.stages.includes(status)) {
+      throw new Error(`Unknown stage '${status}' for ${path}. Stages: ${file.stages.join(", ")}`);
+    }
+  }
+  function nextId(file) {
+    let max = 0;
+    const pattern = new RegExp(`^${idPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-(\\d+)$`);
+    for (const r of file.records) {
+      const m = pattern.exec(r.id);
+      if (m) max = Math.max(max, Number(m[1]));
+    }
+    return `${idPrefix}-${max + 1}`;
+  }
+  return {
+    async add(input = {}) {
+      const file = await load();
+      const status = input.status ?? file.stages[0];
+      assertStage(file, status);
+      const id = input.id ?? nextId(file);
+      if (file.records.some((r) => r.id === id)) {
+        throw new Error(`Record '${id}' already exists in ${path}.`);
+      }
+      const at = now();
+      const record = {
+        id,
+        status,
+        fields: input.fields ?? {},
+        createdAt: at,
+        updatedAt: at,
+        history: [
+          { at, from: null, to: status, ...input.note !== void 0 ? { note: input.note } : {} }
+        ]
+      };
+      file.records.push(record);
+      await saveStoreFile(fs, path, file);
+      return record;
+    },
+    async get(id) {
+      const file = await load();
+      return file.records.find((r) => r.id === id) ?? null;
+    },
+    async list(filter = {}) {
+      const file = await load();
+      return filter.status === void 0 ? file.records : file.records.filter((r) => r.status === filter.status);
+    },
+    async update(id, patch) {
+      const file = await load();
+      const record = mustFind(file, id);
+      if (patch.fields) record.fields = { ...record.fields, ...patch.fields };
+      const at = now();
+      record.updatedAt = at;
+      if (patch.note !== void 0) {
+        record.history.push({ at, from: record.status, to: record.status, note: patch.note });
+      }
+      await saveStoreFile(fs, path, file);
+      return record;
+    },
+    async transition(id, to, transitionOpts = {}) {
+      const file = await load();
+      const record = mustFind(file, id);
+      assertStage(file, to);
+      const at = now();
+      record.history.push({
+        at,
+        from: record.status,
+        to,
+        ...transitionOpts.note !== void 0 ? { note: transitionOpts.note } : {}
+      });
+      record.status = to;
+      record.updatedAt = at;
+      await saveStoreFile(fs, path, file);
+      return record;
+    },
+    async counts() {
+      const file = await load();
+      const counts = {};
+      for (const stage of file.stages) counts[stage] = 0;
+      for (const r of file.records) counts[r.status] = (counts[r.status] ?? 0) + 1;
+      return counts;
+    }
+  };
+}
+function emptyBucket() {
+  return { inCents: 0, outCents: 0, netCents: 0 };
+}
+function addToBucket(bucket, entry) {
+  if (entry.kind === "in") bucket.inCents += entry.amountCents;
+  else bucket.outCents += entry.amountCents;
+  bucket.netCents = bucket.inCents - bucket.outCents;
+}
+function ledgerStore(fs, path, opts = {}) {
+  const now = opts.now ?? defaultNow;
+  async function load() {
+    return await loadStoreFile(fs, path) ?? {
+      version: 1,
+      currency: opts.currency ?? "USD",
+      entries: []
+    };
+  }
+  function nextId(file) {
+    let max = 0;
+    for (const e of file.entries) {
+      const m = /^ledger-(\d+)$/.exec(e.id);
+      if (m) max = Math.max(max, Number(m[1]));
+    }
+    return `ledger-${max + 1}`;
+  }
+  return {
+    async add(entry) {
+      if (!Number.isInteger(entry.amountCents) || entry.amountCents <= 0) {
+        throw new Error(
+          `amountCents must be a positive integer (got ${String(entry.amountCents)}); the 'kind' carries the sign.`
+        );
+      }
+      if (entry.kind !== "in" && entry.kind !== "out") {
+        throw new Error(`kind must be 'in' or 'out' (got '${String(entry.kind)}').`);
+      }
+      if (!entry.category || typeof entry.category !== "string") {
+        throw new Error("category is required.");
+      }
+      const file = await load();
+      const record = {
+        id: nextId(file),
+        at: entry.at ?? now(),
+        amountCents: entry.amountCents,
+        kind: entry.kind,
+        category: entry.category,
+        ...entry.note !== void 0 ? { note: entry.note } : {},
+        ...entry.data !== void 0 ? { data: entry.data } : {}
+      };
+      file.entries.push(record);
+      await saveStoreFile(fs, path, file);
+      return record;
+    },
+    async list(filter = {}) {
+      const file = await load();
+      let entries = file.entries;
+      if (filter.kind) entries = entries.filter((e) => e.kind === filter.kind);
+      if (filter.category) entries = entries.filter((e) => e.category === filter.category);
+      if (filter.month) entries = entries.filter((e) => e.at.slice(0, 7) === filter.month);
+      if (filter.limit !== void 0 && filter.limit >= 0 && entries.length > filter.limit) {
+        entries = entries.slice(entries.length - filter.limit);
+      }
+      return entries;
+    },
+    async totals(filter = {}) {
+      const file = await load();
+      let entries = file.entries;
+      if (filter.month) entries = entries.filter((e) => e.at.slice(0, 7) === filter.month);
+      if (filter.category) entries = entries.filter((e) => e.category === filter.category);
+      const totals = {
+        ...emptyBucket(),
+        count: entries.length,
+        byCategory: {},
+        byMonth: {}
+      };
+      for (const e of entries) {
+        addToBucket(totals, e);
+        totals.byCategory[e.category] ??= emptyBucket();
+        addToBucket(totals.byCategory[e.category], e);
+        const month = e.at.slice(0, 7);
+        totals.byMonth[month] ??= emptyBucket();
+        addToBucket(totals.byMonth[month], e);
+      }
+      return totals;
+    }
+  };
+}
+export {
+  ledgerStore,
+  logStore,
+  rosterStore
+};