@moxxy/sdk 0.13.0 → 0.14.0

package/src/json-file-store.test.ts

@@ -0,0 +1,207 @@
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { createJsonFileStore } from './json-file-store.js';
+
+interface Item {
+  id: string;
+  n: number;
+}
+
+const itemSchema = z.object({ id: z.string(), n: z.number() });
+const fileSchema = z.object({ version: z.literal(1), items: z.array(itemSchema) });
+
+/** A `load` that mirrors the scheduler policy: corrupt/invalid -> empty. */
+function lenientLoad(raw: string | null): Item[] {
+  if (raw === null) return [];
+  try {
+    const parsed = fileSchema.safeParse(JSON.parse(raw));
+    return parsed.success ? [...parsed.data.items] : [];
+  } catch {
+    return [];
+  }
+}
+
+describe('createJsonFileStore', () => {
+  let dir: string;
+  let file: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-jfs-'));
+    file = join(dir, 'sub', 'store.json');
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  function store() {
+    return createJsonFileStore<Item>({ file, load: lenientLoad });
+  }
+
+  it('returns an empty list when the file is missing (ENOENT)', async () => {
+    expect(await store().read()).toEqual([]);
+  });
+
+  it('persists { version: 1, items } pretty-printed and creates parent dirs', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const raw = await readFile(file, 'utf8');
+    expect(JSON.parse(raw)).toEqual({ version: 1, items: [{ id: 'a', n: 1 }] });
+    // pretty-printed with 2-space indent
+    expect(raw).toContain('\n  "version": 1');
+    // a fresh instance reads the persisted state back
+    expect(await store().read()).toEqual([{ id: 'a', n: 1 }]);
+  });
+
+  it('get() finds by id and returns null for misses', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }, { id: 'b', n: 2 }]);
+    expect(await s.get('b')).toEqual({ id: 'b', n: 2 });
+    expect(await s.get('zzz')).toBeNull();
+  });
+
+  it('read() and the mutator each get a fresh copy (caller cannot mutate cache)', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+
+    // Mutating the array returned by read() must not affect the store.
+    const snap = await s.read();
+    snap.push({ id: 'evil', n: 99 });
+    expect(await s.read()).toEqual([{ id: 'a', n: 1 }]);
+
+    // The mutator receives a fresh slice; pushing into it then returning a
+    // DIFFERENT array means the push is discarded (proves it's a copy, not the
+    // live cache).
+    await s.mutate((items) => {
+      items.push({ id: 'discarded', n: -1 });
+      return [{ id: 'a', n: 2 }];
+    });
+    expect(await s.read()).toEqual([{ id: 'a', n: 2 }]);
+  });
+
+  it('serializes concurrent mutate() calls so neither clobbers the other', async () => {
+    const s = store();
+    // Fire many overlapping appends. Without the mutex these read the same
+    // baseline and the last write wins, dropping entries.
+    await Promise.all(
+      Array.from({ length: 25 }, (_, i) =>
+        s.mutate((items) => [...items, { id: `k${i}`, n: i }]),
+      ),
+    );
+    const all = await s.read();
+    expect(all).toHaveLength(25);
+    expect(new Set(all.map((x) => x.id)).size).toBe(25);
+    // The on-disk file agrees (every write landed atomically).
+    const onDisk = JSON.parse(await readFile(file, 'utf8')) as { items: Item[] };
+    expect(onDisk.items).toHaveLength(25);
+  });
+
+  it('leaves the prior file intact when serializing the new state throws', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const before = await readFile(file, 'utf8');
+
+    // A value JSON.stringify cannot serialize (BigInt) makes the persist throw
+    // before any bytes hit disk; the previously-persisted file must survive.
+    await expect(
+      s.mutate(() => [{ id: 'bad', n: 1n as unknown as number }]),
+    ).rejects.toThrow();
+
+    expect(await readFile(file, 'utf8')).toBe(before);
+    const leftovers = (await readdir(join(dir, 'sub'))).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+  });
+
+  it('leaves the prior file intact when the atomic rename fails mid-write', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const before = await readFile(file, 'utf8');
+
+    // Replace the parent dir's write path: make the TARGET a directory so the
+    // temp-file rename throws. We can't do that to `file` itself without losing
+    // the prior copy, so use a sibling store whose target is a directory and
+    // assert no temp file is orphaned. The original store's file is untouched.
+    const sib = join(dir, 'sub', 'sibling');
+    await mkdir(sib, { recursive: true });
+    const s2 = createJsonFileStore<Item>({ file: sib, load: lenientLoad });
+    await expect(s2.mutate((items) => [...items, { id: 'x', n: 1 }])).rejects.toThrow();
+
+    // No orphaned temp files, and the unrelated prior file is intact.
+    const leftovers = (await readdir(join(dir, 'sub'))).filter((n) => n.includes('.tmp'));
+    expect(leftovers).toEqual([]);
+    expect(await readFile(file, 'utf8')).toBe(before);
+  });
+
+  it('lenient load resets a corrupt file to empty (scheduler policy)', async () => {
+    await mkdir(join(dir, 'sub'), { recursive: true });
+    await writeFile(file, '{ not json', 'utf8');
+    const s = store();
+    expect(await s.read()).toEqual([]);
+    // The bad file is left in place until the next write.
+    expect(await readFile(file, 'utf8')).toBe('{ not json');
+  });
+
+  it('lenient load resets a schema-mismatched file to empty', async () => {
+    await mkdir(join(dir, 'sub'), { recursive: true });
+    await writeFile(file, JSON.stringify({ version: 99, items: [] }), 'utf8');
+    expect(await store().read()).toEqual([]);
+  });
+
+  it('onReadError lets a store refuse to operate on a non-ENOENT read error', async () => {
+    // Point the store at a directory so readFile throws EISDIR (not ENOENT).
+    const asDir = join(dir, 'as-dir');
+    await mkdir(asDir, { recursive: true });
+    const s = createJsonFileStore<Item>({
+      file: asDir,
+      load: lenientLoad,
+      onReadError: (err) => {
+        throw new Error(`refusing: ${(err as NodeJS.ErrnoException).code}`);
+      },
+    });
+    await expect(s.read()).rejects.toThrow(/refusing:/);
+  });
+
+  it('re-throws a non-ENOENT read error by default (no onReadError)', async () => {
+    const asDir = join(dir, 'as-dir2');
+    await mkdir(asDir, { recursive: true });
+    const s = createJsonFileStore<Item>({ file: asDir, load: lenientLoad });
+    await expect(s.read()).rejects.toThrow();
+  });
+
+  it('honors a custom itemsKey, fileFields, stringify and writeOptions', async () => {
+    const f = join(dir, 'custom.json');
+    const s = createJsonFileStore<Item>({
+      file: f,
+      itemsKey: 'rows',
+      fileFields: {},
+      stringify: (obj) => JSON.stringify(obj) + '\n',
+      writeOptions: { mode: 0o600 },
+      load: (raw) => {
+        if (raw === null) return [];
+        const obj = JSON.parse(raw) as { rows: Item[] };
+        return obj.rows;
+      },
+    });
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    const raw = await readFile(f, 'utf8');
+    // versionless, name-key `rows`, compact, trailing newline
+    expect(raw).toBe('{"rows":[{"id":"a","n":1}]}\n');
+    const { stat } = await import('node:fs/promises');
+    expect((await stat(f)).mode & 0o777).toBe(0o600);
+  });
+
+  it('invalidate() forces a re-read from disk', async () => {
+    const s = store();
+    await s.mutate((items) => [...items, { id: 'a', n: 1 }]);
+    // Write a second entry directly to disk behind the store's back.
+    await writeFile(file, JSON.stringify({ version: 1, items: [{ id: 'b', n: 2 }] }), 'utf8');
+    // Stale cache still shows the first entry…
+    expect(await s.read()).toEqual([{ id: 'a', n: 1 }]);
+    s.invalidate();
+    // …until invalidated.
+    expect(await s.read()).toEqual([{ id: 'b', n: 2 }]);
+  });
+});

package/src/json-file-store.ts

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises';
+import { createMutex, type Mutex } from './mutex.js';
+import { writeFileAtomic, type WriteFileAtomicOptions } from './fs-utils.js';
+
+/**
+ * Generic whole-file JSON collection store: the single home for the repeated
+ * "id-collection" persistence skeleton (invariant #5). It owns the in-memory
+ * cache, the per-instance write mutex, the read-modify-write `.slice()` copy,
+ * and the crash-atomic whole-file write via {@link writeFileAtomic} — so each
+ * domain store (scheduler, webhooks, …) no longer re-derives that atomicity
+ * by hand and can't silently regress it (forget the mutex, forget the copy,
+ * hand-roll a non-unique tmp).
+ *
+ * The store persists `{ [itemsKey]: T[], ...extraFileFields }` — by default
+ * `{ version: 1, items: [...] }`. The shape and key are configurable so a
+ * domain store keeps its exact on-disk format.
+ *
+ * Parsing/validation and corruption policy stay with the caller via
+ * {@link JsonFileStoreOptions.load}: it receives the raw file contents (or
+ * `null` when the file is absent) and returns the validated item array. This
+ * keeps each store's bespoke corrupt handling (silent reset vs. quarantine
+ * aside) byte-for-byte unchanged while centralizing the atomicity invariant.
+ *
+ * SDK-internal-dep-free: uses only node builtins + the SDK's own
+ * {@link createMutex} / {@link writeFileAtomic}.
+ */
+export interface JsonFileStoreOptions<T extends { id: string }> {
+  /** Absolute path to the JSON file. */
+  readonly file: string;
+  /**
+   * Parse + validate the file contents into the item array. Called once per
+   * load with the raw UTF-8 string, or `null` when the file does not exist
+   * (ENOENT). Owns all corruption policy (quarantine, silent reset, throw).
+   * Any non-ENOENT read error is surfaced through {@link onReadError} first.
+   */
+  readonly load: (raw: string | null) => T[] | Promise<T[]>;
+  /**
+   * Called when reading the file fails with a non-ENOENT error (permissions,
+   * I/O, …). Return an item array to recover, or throw to refuse to operate
+   * (the safe direction when the file may hold the only copy of secrets).
+   * Defaults to re-throwing the original error.
+   */
+  readonly onReadError?: (err: unknown) => T[] | Promise<T[]>;
+  /**
+   * Property name the items array is stored under. Default `'items'`.
+   * (scheduler uses `'schedules'`, webhooks `'triggers'`.)
+   */
+  readonly itemsKey?: string;
+  /**
+   * Extra top-level fields written alongside the items. Default
+   * `{ version: 1 }`. Pass `{}` for a versionless file.
+   */
+  readonly fileFields?: Record<string, unknown>;
+  /**
+   * How the persisted object is serialized. Default: pretty 2-space JSON
+   * (matches the scheduler/webhooks format). Receives the full file object.
+   */
+  readonly stringify?: (fileObject: Record<string, unknown>) => string;
+  /** Atomic-write options forwarded to {@link writeFileAtomic} (e.g. `mode`). */
+  readonly writeOptions?: WriteFileAtomicOptions;
+}
+
+/**
+ * The collection store handle. Domain stores compose this and add their own
+ * id/createdAt minting and bespoke methods on top of {@link mutate}.
+ */
+export interface JsonFileStore<T extends { id: string }> {
+  /** Loaded snapshot (a fresh shallow copy; safe to mutate by the caller). */
+  read(): Promise<T[]>;
+  /** Find a single item by id, or `null`. */
+  get(id: string): Promise<T | null>;
+  /**
+   * Read-modify-write under the write mutex. The mutator receives a fresh
+   * shallow copy of the current items; whatever it returns becomes the new
+   * state and is persisted atomically before {@link mutate} resolves.
+   */
+  mutate(fn: (items: T[]) => T[] | Promise<T[]>): Promise<void>;
+  /** Drop the cache so the next access re-reads from disk. */
+  invalidate(): void;
+}
+
+const prettyJson = (value: Record<string, unknown>): string => JSON.stringify(value, null, 2);
+
+export function createJsonFileStore<T extends { id: string }>(
+  opts: JsonFileStoreOptions<T>,
+): JsonFileStore<T> {
+  const {
+    file,
+    load,
+    onReadError,
+    itemsKey = 'items',
+    fileFields = { version: 1 },
+    stringify = prettyJson,
+    writeOptions,
+  } = opts;
+
+  let cache: T[] | null = null;
+  const mutex: Mutex = createMutex();
+
+  async function ensureLoaded(): Promise<void> {
+    if (cache) return;
+    let raw: string | null;
+    try {
+      raw = await readFile(file, 'utf8');
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        raw = null;
+      } else if (onReadError) {
+        cache = await onReadError(err);
+        return;
+      } else {
+        throw err;
+      }
+    }
+    cache = await load(raw);
+  }
+
+  async function persist(items: T[]): Promise<void> {
+    const payload = stringify({ ...fileFields, [itemsKey]: items });
+    await writeFileAtomic(file, payload, writeOptions ?? {});
+  }
+
+  return {
+    async read(): Promise<T[]> {
+      await ensureLoaded();
+      return cache!.slice();
+    },
+    async get(id: string): Promise<T | null> {
+      await ensureLoaded();
+      return cache!.find((item) => item.id === id) ?? null;
+    },
+    async mutate(fn): Promise<void> {
+      await mutex.run(async () => {
+        await ensureLoaded();
+        const updated = await fn(cache!.slice());
+        cache = updated;
+        await persist(updated);
+      });
+    },
+    invalidate(): void {
+      cache = null;
+    },
+  };
+}

package/src/mode.ts

@@ -64,6 +64,16 @@ export interface ElisionSettings {
 export interface ModeContext {
   readonly sessionId: SessionId;
   readonly turnId: TurnId;
+  /**
+   * The session's working directory and environment, mirrored from
+   * {@link AppContext}. Threaded into the `dispatchToolCall` hook context so
+   * `onToolCall` hooks that gate on cwd/env (path-based policy/security hooks)
+   * see the real per-session values rather than empty placeholders. Tools
+   * themselves get cwd via the tool registry's default; this carries the same
+   * truth to the hook layer so the two never disagree.
+   */
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
   readonly model: string;
   readonly systemPrompt?: string;
   readonly provider: LLMProvider;

package/src/tool-dispatch.ts

@@ -26,9 +26,12 @@ export async function* dispatchToolCall(
   try {
     const verdict = await ctx.hooks.dispatchToolCall({
       sessionId: ctx.sessionId,
-      cwd: '',
+      // Hand the hook the session's real cwd/env (mirrored onto ModeContext by
+      // run-turn / the subagent runtime). Previously hardcoded '' / {}, which
+      // silently defeated path-based onToolCall policy/security hooks.
+      cwd: ctx.cwd,
       log: ctx.log,
-      env: {},
+      env: ctx.env,
       turnId: ctx.turnId,
       iteration,
       call: { callId: asToolCallId(t.id), name: t.name, input: t.input },

package/src/types.test-d.ts

@@ -2,9 +2,11 @@ import { describe, expectTypeOf, it } from 'vitest';
 import type {
   MoxxyEvent,
   MoxxyEventOfType,
+  PluginRegisteredEvent,
   ToolCallRequestedEvent,
   UserPromptEvent,
 } from './events.js';
+import type { PluginKind } from './plugin.js';
 
 describe('event union narrowing', () => {
   it('MoxxyEventOfType narrows correctly', () => {
@@ -27,3 +29,14 @@ describe('event union narrowing', () => {
     expectTypeOf(handle).returns.toEqualTypeOf<string | null>();
   });
 });
+
+describe('PluginRegisteredEvent.kind stays in sync with PluginKind', () => {
+  it('the inlined kind union equals PluginKind member-for-member', () => {
+    // events.ts inlines the kind union (to avoid an events↔plugin value cycle)
+    // with a "keep in sync with PluginKind" note. This bidirectional equality
+    // fails the build the moment PluginKind grows a member the inlined union
+    // lacks (or vice versa) — exactly the drift the note was meant to prevent.
+    type RegisteredKind = PluginRegisteredEvent['kind'][number];
+    expectTypeOf<RegisteredKind>().toEqualTypeOf<PluginKind>();
+  });
+});