@forwardimpact/libmock 0.1.2

package/src/mock/infra.js

@@ -0,0 +1,297 @@
+/**
+ * Additional infrastructure mocks for services/products tests. Centralizes
+ * variants that consumers previously inlined.
+ */
+import { Writable } from "node:stream";
+
+/**
+ * A capturing `Writable` used as the mock `proc.stdout`/`stderr`. It retains
+ * the `chunks` accessor existing assertions read AND is a real `Writable`, so
+ * it accepts piped input (e.g. a `pipeline()` from a read stream).
+ */
+class CaptureWritable extends Writable {
+  constructor() {
+    super();
+    this.chunks = [];
+  }
+
+  /**
+   * @param {Buffer|string} chunk - The written chunk.
+   * @param {string} _encoding - Chunk encoding (unused).
+   * @param {Function} callback - Completion callback.
+   */
+  _write(chunk, _encoding, callback) {
+    this.chunks.push(String(chunk));
+    callback();
+  }
+}
+
+/**
+ * Creates a mock Supabase-style client with configurable table and storage
+ * behaviour. Covers the patterns found across products/map/test/activity/*.
+ *
+ * @param {object} [options]
+ * @param {Record<string, object>} [options.tables] - Map of table name to
+ *   override. Each override may expose `select`, `insert`, `upsert`, `delete`
+ *   as async functions. Unspecified methods return `{ data: [], error: null }`.
+ * @param {Record<string, string>} [options.files] - Files exposed via
+ *   `storage.from(...).list(prefix)` / `.download(path)`.
+ * @returns {object} Mock client and call-tracking arrays.
+ */
+export function createMockSupabaseClient({ tables = {}, files = {} } = {}) {
+  const calls = {
+    select: [],
+    insert: [],
+    upsert: [],
+    delete: [],
+    download: [],
+    list: [],
+  };
+
+  function record(kind, entry) {
+    calls[kind].push(entry);
+  }
+
+  return {
+    calls,
+    from(table) {
+      const override = tables[table] ?? {};
+      return {
+        async select(...args) {
+          record("select", { table, args });
+          if (override.select) return override.select(...args);
+          return { data: [], error: null };
+        },
+        async insert(rows, opts) {
+          record("insert", { table, rows, options: opts });
+          if (override.insert) return override.insert(rows, opts);
+          return { data: rows, error: null };
+        },
+        async upsert(rows, opts) {
+          record("upsert", {
+            table,
+            rows,
+            onConflict: opts?.onConflict,
+            options: opts,
+          });
+          if (override.upsert) return override.upsert(rows, opts);
+          return { data: rows, error: null };
+        },
+        async delete(...args) {
+          record("delete", { table, args });
+          if (override.delete) return override.delete(...args);
+          return { error: null };
+        },
+      };
+    },
+    storage: {
+      from() {
+        return {
+          async list(prefix) {
+            record("list", { prefix });
+            const names = Object.keys(files)
+              .filter((k) => k.startsWith(prefix))
+              .map((k) => ({
+                name: k.slice(prefix.length),
+                created_at: "z",
+              }));
+            return { data: names, error: null };
+          },
+          async download(path) {
+            record("download", { path });
+            const content = files[path];
+            if (content === undefined) {
+              return { data: null, error: { message: "not found" } };
+            }
+            return {
+              data: { text: async () => content },
+              error: null,
+            };
+          },
+        };
+      },
+    },
+  };
+}
+
+/**
+ * Creates Turtle parsing helpers bound to an injected n3 Parser. Keeps
+ * libmock free of an n3 dependency while allowing services to share the
+ * parseQuads / findAll / findOne idiom.
+ *
+ * @param {import("n3").Parser | Function} ParserOrInstance - n3 Parser class
+ *   or a pre-built parser instance.
+ * @param {object} [options]
+ * @param {string} [options.format="Turtle"] - Parser format.
+ * @returns {object} { parseQuads, findAll, findOne }
+ */
+export function createTurtleHelpers(
+  ParserOrInstance,
+  { format = "Turtle" } = {},
+) {
+  const isClass =
+    typeof ParserOrInstance === "function" &&
+    ParserOrInstance.prototype &&
+    typeof ParserOrInstance.prototype.parse === "function";
+  const parser = isClass ? new ParserOrInstance({ format }) : ParserOrInstance;
+
+  function parseQuads(turtle) {
+    return parser.parse(turtle);
+  }
+
+  function findAll(quads, { subject, predicate, object } = {}) {
+    return quads.filter(
+      (q) =>
+        (!subject || q.subject.value === subject) &&
+        (!predicate || q.predicate.value === predicate) &&
+        (!object || q.object.value === object),
+    );
+  }
+
+  function findOne(quads, pattern) {
+    return findAll(quads, pattern)[0];
+  }
+
+  return { parseQuads, findAll, findOne };
+}
+
+/**
+ * Build an `AsyncIterable<string>` over a fixed list of input chunks, used as
+ * the mock `proc.stdin`.
+ * @param {string[]} chunks - Lines/chunks the iterator yields in order.
+ * @returns {AsyncIterable<string>}
+ */
+export function createMockStdin(chunks = []) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const chunk of chunks) yield chunk;
+    },
+  };
+}
+
+/**
+ * Creates a mock `process`-like object matching the `Runtime.proc` surface:
+ * `cwd()`, `env`, `argv`, `stdin`, `stdout`/`stderr` (capturing `Writable`s),
+ * `exit(code)`, `kill(pid, signal)`, `pid`, `platform`, `on(event, handler)`,
+ * and a settable `exitCode`. Writes are captured on `stdout.chunks` /
+ * `stderr.chunks` (and the streams accept piped input); kill calls on `kills`;
+ * event handlers on `handlers` (fire them via `emit(event, ...args)` to
+ * simulate a signal).
+ *
+ * @param {object} [options]
+ * @param {Record<string, string>} [options.env] - Initial env map.
+ * @param {string} [options.cwd] - Working directory `cwd()` returns.
+ * @param {string[]} [options.argv] - The frozen `argv` array.
+ * @param {string[]} [options.stdin] - Chunks the `stdin` iterator yields.
+ * @param {(pid: number, signal: string|number) => any} [options.kill] - Optional
+ *   `kill` implementation (e.g. to model a liveness probe); calls are always
+ *   recorded on the returned `kills` array regardless.
+ * @param {number} [options.pid] - The fake's `pid` (default 1234).
+ * @param {string} [options.platform] - The fake's `platform` string
+ *   (default `"linux"`; set `"darwin"`/`"win32"` to exercise per-platform code).
+ * @returns {object}
+ */
+export function createMockProcess({
+  env = {},
+  cwd,
+  argv,
+  stdin,
+  kill,
+  pid = 1234,
+  platform = "linux",
+} = {}) {
+  const stdout = new CaptureWritable();
+  const stderr = new CaptureWritable();
+  const kills = [];
+  // Registered event handlers (e.g. "SIGTERM"/"SIGINT"); a test can fire them
+  // via `emit(event, ...args)` to simulate a signal without a real process.
+  const handlers = {};
+  return {
+    env: { ...env },
+    cwd: () => cwd ?? "/work",
+    argv: Object.freeze([...(argv ?? ["/usr/bin/node", "/tmp/test-bin.js"])]),
+    stdin: createMockStdin(stdin ?? []),
+    stdout,
+    stderr,
+    pid,
+    platform,
+    exitCode: 0,
+    exit(code = 0) {
+      this.exitCode = code;
+    },
+    kills,
+    kill(pid, signal) {
+      kills.push({ pid, signal });
+      return kill?.(pid, signal);
+    },
+    handlers,
+    on(event, handler) {
+      (handlers[event] ??= []).push(handler);
+    },
+    emit(event, ...args) {
+      for (const handler of handlers[event] ?? []) handler(...args);
+    },
+  };
+}
+
+/**
+ * Runs `fn` with `console.log`, `console.info`, and `console.warn` suppressed,
+ * returning whatever `fn` returns. Errors still propagate.
+ *
+ * @template T
+ * @param {() => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withSilentConsole(fn) {
+  const originals = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+  };
+  console.log = () => {};
+  console.info = () => {};
+  console.warn = () => {};
+  try {
+    return await fn();
+  } finally {
+    console.log = originals.log;
+    console.info = originals.info;
+    console.warn = originals.warn;
+  }
+}
+
+/**
+ * Creates a bag of async query stubs from a plain values object. A function
+ * value is passed through untouched; anything else becomes an async function
+ * returning that value. Collapses landmark-style `stubQueries` boilerplate.
+ *
+ * @param {Record<string, unknown>} values
+ * @returns {Record<string, Function>}
+ */
+export function createMockQueries(values = {}) {
+  const out = {};
+  for (const [key, val] of Object.entries(values)) {
+    out[key] = typeof val === "function" ? val : async () => val;
+  }
+  return out;
+}
+
+/**
+ * Creates a minimal mock S3 client that records command sends and returns a
+ * configurable response.
+ *
+ * @param {object} [options]
+ * @param {(command: object) => unknown} [options.sendFn] - Custom send handler.
+ * @returns {object} { client, sends }
+ */
+export function createMockS3Client({ sendFn } = {}) {
+  const sends = [];
+  return {
+    sends,
+    async send(command) {
+      sends.push(command);
+      if (sendFn) return sendFn(command);
+      return {};
+    },
+  };
+}

package/src/mock/logger.js

@@ -0,0 +1,42 @@
+import { spy } from "./spy.js";
+/**
+ * Creates a mock logger with call tracking
+ * @param {object} options - Logger options
+ * @param {boolean} options.captureOutput - Whether to capture log output
+ * @returns {object} Mock logger
+ */
+export function createMockLogger(options = {}) {
+  const logs = [];
+  const capture = options.captureOutput ?? false;
+
+  const createMethod = (level) =>
+    spy((appId, msg, attributes) => {
+      if (capture) {
+        logs.push({ level, appId, msg, attributes });
+      }
+    });
+
+  return {
+    logs,
+    debug: createMethod("debug"),
+    info: createMethod("info"),
+    warn: createMethod("warn"),
+    error: createMethod("error"),
+    exception: createMethod("exception"),
+  };
+}
+
+/**
+ * Creates a silent logger that does nothing
+ * @returns {object} Silent logger
+ */
+export function createSilentLogger() {
+  const noop = () => {};
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    exception: noop,
+  };
+}

package/src/mock/observer.js

@@ -0,0 +1,78 @@
+import { spy } from "./spy.js";
+/**
+ * Creates a mock observer factory
+ * @param {object} logger - Logger to use (optional)
+ * @returns {Function} Mock observer factory
+ */
+export function createMockObserverFn(logger = null) {
+  const mockLogger = logger || {
+    debug: spy(),
+    info: spy(),
+    error: spy(),
+  };
+
+  return () => ({
+    observeServerUnaryCall: async (_method, handler, call, callback) => {
+      return await handler(call, callback);
+    },
+    observeClientUnaryCall: async (_method, _request, fn) => {
+      return await fn();
+    },
+    observeClientStreamingCall: (_method, _request, fn) => {
+      return fn();
+    },
+    logger: () => mockLogger,
+  });
+}
+
+/**
+ * Creates a mock tracer
+ * @param {object} overrides - Method overrides
+ * @returns {object} Mock tracer
+ */
+export function createMockTracer(overrides = {}) {
+  return {
+    startSpan: spy((name, options = {}) => ({
+      span_id: `span-${Date.now()}`,
+      trace_id: `trace-${Date.now()}`,
+      name,
+      ...options,
+      addEvent: spy(),
+      setOk: spy(),
+      setError: spy(),
+      end: spy(async () => {}),
+    })),
+    startClientSpan: spy((_service, _method) => ({
+      span: {
+        span_id: `client-span-${Date.now()}`,
+        trace_id: `trace-${Date.now()}`,
+      },
+      metadata: { get: () => [], set: () => {} },
+    })),
+    startServerSpan: spy((_service, _method, _request, metadata) => ({
+      span_id: `server-span-${Date.now()}`,
+      trace_id: metadata?.get?.("x-trace-id")?.[0] || `trace-${Date.now()}`,
+    })),
+    getSpanContext: () => ({
+      run: (span, fn) => fn(),
+      getStore: () => null,
+    }),
+    endSpan: spy(),
+    recordError: spy(),
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock auth factory
+ * @param {object} options - Auth options
+ * @returns {Function} Mock auth factory
+ */
+export function createMockAuthFn(options = {}) {
+  const { isValid = true, serviceId = "test" } = options;
+
+  return () => ({
+    createClientInterceptor: () => () => {},
+    validateCall: () => ({ isValid, serviceId }),
+  });
+}

package/src/mock/resource-index.js

@@ -0,0 +1,95 @@
+import { common, tool } from "@forwardimpact/libtype";
+
+/**
+ * Creates a mock resource index with common test data
+ * @param {object} options - Setup options
+ * @returns {object} Mock resource index
+ */
+export function createMockResourceIndex(options = {}) {
+  const resources = new Map();
+
+  const index = {
+    resources,
+
+    async get(identifiers, _actor) {
+      if (!identifiers || identifiers.length === 0) return [];
+      return identifiers
+        .map((id) => {
+          const key = typeof id === "string" ? id : id.toString?.() || id.name;
+          return resources.get(key);
+        })
+        .filter(Boolean);
+    },
+
+    put(resource) {
+      const key = resource.id?.toString?.() || resource.id?.name;
+      if (key) resources.set(key, resource);
+    },
+
+    async has(id) {
+      const key = typeof id === "string" ? id : id.toString?.();
+      return resources.has(key);
+    },
+
+    /**
+     * Sets up default test resources
+     * @param {object} setupOptions - Setup options
+     * @param {string[]} [setupOptions.tools] - Tool names to seed
+     * @param {string} [setupOptions.conversationId] - Conversation ID
+     */
+    setupDefaults(setupOptions = {}) {
+      const { tools = [], conversationId = "test-conversation" } = setupOptions;
+
+      resources.set(
+        conversationId,
+        common.Conversation.fromObject({
+          id: { name: conversationId },
+        }),
+      );
+
+      for (const name of tools) {
+        resources.set(
+          `tool.ToolFunction.${name}`,
+          tool.ToolFunction.fromObject({
+            id: { name, tokens: 20 },
+            name,
+            description: `${name} tool`,
+          }),
+        );
+      }
+    },
+
+    /**
+     * Adds a message resource
+     * @param {object} msg - Message to add
+     */
+    addMessage(msg) {
+      const id =
+        msg.id?.type && msg.id?.toString
+          ? msg.id.toString()
+          : msg.id?.name || String(msg.id);
+      resources.set(id, msg);
+    },
+
+    /**
+     * Find resources by prefix
+     * @param {string} prefix - Prefix to search for
+     * @returns {Promise<string[]>} List of matching keys
+     */
+    async findByPrefix(prefix) {
+      const keys = [];
+      for (const key of resources.keys()) {
+        if (key.startsWith(prefix)) {
+          keys.push(key);
+        }
+      }
+      return keys;
+    },
+  };
+
+  if (options.tools || options.conversationId) {
+    index.setupDefaults(options);
+  }
+
+  return index;
+}

package/src/mock/service-callbacks.js

@@ -0,0 +1,39 @@
+/**
+ * Creates a mock service callbacks object for agent testing
+ * @param {object} overrides - Method overrides per service
+ * @returns {object} Service callbacks object
+ */
+export function createMockServiceCallbacks(overrides = {}) {
+  return {
+    memory: {
+      append: async () => ({}),
+      get: async () => ({
+        messages: [{ role: "system", content: "You are an assistant" }],
+        tools: [],
+      }),
+      ...overrides.memory,
+    },
+    llm: {
+      createCompletions: async () => ({
+        choices: [
+          {
+            message: {
+              role: "assistant",
+              content: "Test response",
+              tool_calls: [],
+            },
+          },
+        ],
+      }),
+      ...overrides.llm,
+    },
+    tool: {
+      call: async () => ({
+        role: "tool",
+        content: "Tool result",
+      }),
+      ...overrides.tool,
+    },
+    ...overrides,
+  };
+}

package/src/mock/services.js

@@ -0,0 +1,79 @@
+/**
+ * Mock service utilities for testing
+ */
+
+/**
+ * Creates a mock vector service
+ * @param {object} overrides - Properties to override in the mock
+ * @returns {object} Mock vector service
+ */
+export function mockVectorService(overrides = {}) {
+  return {
+    QueryItems: async (request, callback) => {
+      callback(null, { results: [], total: 0 });
+    },
+    close: () => {},
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock history service
+ * @param {object} overrides - Properties to override in the mock
+ * @returns {object} Mock history service
+ */
+export function mockHistoryService(overrides = {}) {
+  return {
+    GetHistory: async (request, callback) => {
+      callback(null, { messages: [] });
+    },
+    UpdateHistory: async (request, callback) => {
+      callback(null, {});
+    },
+    close: () => {},
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock LLM service
+ * @param {object} overrides - Properties to override in the mock
+ * @returns {object} Mock LLM service
+ */
+export function mockLlmService(overrides = {}) {
+  return {
+    CreateCompletions: async (request, callback) => {
+      callback(null, {
+        choices: [
+          {
+            index: 0,
+            message: { role: "assistant", content: "Test response" },
+            finish_reason: "stop",
+          },
+        ],
+      });
+    },
+    CreateEmbeddings: async (request, callback) => {
+      callback(null, {
+        data: [{ index: 0, embedding: [0.1, 0.2, 0.3] }],
+      });
+    },
+    close: () => {},
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a mock text service
+ * @param {object} overrides - Properties to override in the mock
+ * @returns {object} Mock text service
+ */
+export function mockTextService(overrides = {}) {
+  return {
+    GetChunks: async (request, callback) => {
+      callback(null, { chunks: {} });
+    },
+    close: () => {},
+    ...overrides,
+  };
+}

package/src/mock/spy.js

@@ -0,0 +1,44 @@
+/**
+ * Portable mock function helper. Replaces `mock.fn` from `node:test` so the
+ * test suite can run under either node:test or bun:test.
+ *
+ * Shape matches node:test's `mock.fn` to keep call-inspection sites
+ * (`fn.mock.calls[0].arguments`, `fn.mock.callCount()`, `fn.mock.resetCalls()`)
+ * unchanged across the codebase.
+ *
+ * @template T
+ * @param {(...args: any[]) => T} [impl] - Initial implementation.
+ * @returns {((...args: any[]) => T) & { mock: { calls: Array<{arguments: any[], result?: T, error?: unknown, this: unknown}>, callCount: () => number, resetCalls: () => void, mockImplementation: (newImpl: (...args: any[]) => T) => void } }}
+ */
+export function spy(impl) {
+  let _impl = impl;
+  const calls = [];
+  const fn = function (...args) {
+    const rec = { arguments: args, this: this };
+    if (!_impl) {
+      calls.push(rec);
+      return undefined;
+    }
+    try {
+      const result = _impl.apply(this, args);
+      rec.result = result;
+      calls.push(rec);
+      return result;
+    } catch (err) {
+      rec.error = err;
+      calls.push(rec);
+      throw err;
+    }
+  };
+  fn.mock = {
+    calls,
+    callCount: () => calls.length,
+    resetCalls: () => {
+      calls.length = 0;
+    },
+    mockImplementation: (newImpl) => {
+      _impl = newImpl;
+    },
+  };
+  return fn;
+}