@moxxy/sdk 0.12.0 → 0.14.0

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/semver.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { compareSemver, parseSemverCore } from './semver.js';
+
+describe('compareSemver', () => {
+  it('orders by major, then minor, then patch', () => {
+    expect(compareSemver('1.0.0', '2.0.0')).toBeLessThan(0);
+    expect(compareSemver('1.2.0', '1.1.9')).toBeGreaterThan(0);
+    expect(compareSemver('1.1.2', '1.1.10')).toBeLessThan(0);
+    expect(compareSemver('3.4.5', '3.4.5')).toBe(0);
+  });
+
+  it('normalizes to -1 / 0 / 1', () => {
+    expect(compareSemver('0.0.1', '0.0.2')).toBe(-1);
+    expect(compareSemver('0.0.2', '0.0.1')).toBe(1);
+    expect(compareSemver('0.0.1', '0.0.1')).toBe(0);
+  });
+
+  it('ignores prerelease/build suffixes (bare-tag precedence)', () => {
+    expect(compareSemver('1.0.0-rc.1', '1.0.0')).toBe(0);
+    expect(compareSemver('1.0.0+build2', '1.0.0')).toBe(0);
+    expect(compareSemver('1.0.0', '1.0.0+build9')).toBe(0);
+  });
+
+  it('treats missing/garbage segments as 0', () => {
+    expect(compareSemver('1', '1.0.0')).toBe(0);
+    expect(compareSemver('1.2', '1.2.0')).toBe(0);
+    expect(compareSemver('vX.Y.Z', '0.0.0')).toBe(0);
+  });
+
+  it('sorts ascending with a deterministic call-site tie-break', () => {
+    const tags = ['1.2.0', '1.10.0', '1.2.0+b', '1.1.0'];
+    const sorted = [...tags].sort((a, b) => compareSemver(a, b) || a.localeCompare(b));
+    expect(sorted).toEqual(['1.1.0', '1.2.0', '1.2.0+b', '1.10.0']);
+  });
+});
+
+describe('parseSemverCore', () => {
+  it('extracts the numeric core', () => {
+    expect(parseSemverCore('12.3.45-rc.1')).toEqual([12, 3, 45]);
+    expect(parseSemverCore('0.0.0')).toEqual([0, 0, 0]);
+    expect(parseSemverCore('7')).toEqual([7, 0, 0]);
+  });
+});

package/src/semver.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal numeric `major.minor.patch` comparison. Any prerelease/build suffix
+ * (`-rc.1`, `+build2`) is ignored — moxxy release tags are bare `x.y.z`, so this
+ * is the precedence the update/check and release paths actually need, without
+ * pulling in a full semver dependency.
+ *
+ * Returns a negative number if `a < b`, positive if `a > b`, `0` if the numeric
+ * cores are equal. **When ordering a list where two entries can share a core**
+ * (e.g. build-metadata variants), add an explicit, deterministic tie-break at
+ * the call site — `Array.prototype.sort` is not guaranteed stable across all
+ * inputs, so a `0` here would leave their relative order unspecified.
+ */
+export function compareSemver(a: string, b: string): number {
+  const pa = parseSemverCore(a);
+  const pb = parseSemverCore(b);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Parse the leading `major.minor.patch` of a version/tag into a 3-tuple. */
+export function parseSemverCore(s: string): [number, number, number] {
+  const parts = (s.split('-')[0] ?? '').split('.').map((n) => Number.parseInt(n, 10) || 0);
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}

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>();
+  });
+});

package/src/view-renderer.test.ts

@@ -3,11 +3,38 @@ import {
   VIEW_PRIMITIVES,
   VIEW_COMPONENTS,
   DEFAULT_VIEW_TAGS,
+  countNodes,
+  isSafeViewUrl,
   defineViewRenderer,
   defineTunnelProvider,
+  type ViewNode,
   type ViewTagSpec,
 } from './index.js';
 
+describe('countNodes', () => {
+  const text = (value: string): ViewNode => ({ kind: 'text', value });
+  const el = (tag: string, children: ViewNode[] = []): ViewNode => ({
+    kind: 'element',
+    tag,
+    props: {},
+    children,
+  });
+
+  it('counts a single text node as 1', () => {
+    expect(countNodes(text('hi'))).toBe(1);
+  });
+
+  it('counts an element plus its descendants', () => {
+    const tree = el('col', [el('row', [text('a'), text('b')]), text('c')]);
+    // col + row + a + b + c = 5
+    expect(countNodes(tree)).toBe(5);
+  });
+
+  it('counts a leaf element as 1', () => {
+    expect(countNodes(el('hr'))).toBe(1);
+  });
+});
+
 describe('view vocabulary integrity', () => {
   const all = DEFAULT_VIEW_TAGS;
 
@@ -88,3 +115,33 @@ describe('define factories freeze their specs', () => {
     expect(Object.isFrozen(def)).toBe(true);
   });
 });
+
+describe('isSafeViewUrl', () => {
+  it('rejects javascript/vbscript/data-text schemes', () => {
+    expect(isSafeViewUrl('javascript:alert(1)', 'href')).toBe(false);
+    expect(isSafeViewUrl('vbscript:msgbox', 'href')).toBe(false);
+    expect(isSafeViewUrl('data:text/html,<x>', 'src')).toBe(false);
+  });
+
+  it('rejects schemes split by whitespace/control chars (audit u72-1)', () => {
+    // a browser strips tab/newline/CR before scheme resolution, so these
+    // collapse to javascript: on click; the gate must normalize the same way
+    expect(isSafeViewUrl('java\tscript:alert(1)', 'href')).toBe(false);
+    expect(isSafeViewUrl('java\nscript:alert(1)', 'href')).toBe(false);
+    expect(isSafeViewUrl('java\rscript:alert(1)', 'href')).toBe(false);
+    expect(isSafeViewUrl('\u0000javascript:alert(1)', 'href')).toBe(false);
+    expect(isSafeViewUrl('  javascript:alert(1)', 'href')).toBe(false);
+  });
+
+  it('allows safe schemes + relative + data-image src', () => {
+    expect(isSafeViewUrl('https://example.com/x', 'href')).toBe(true);
+    expect(isSafeViewUrl('http://example.com', 'href')).toBe(true);
+    expect(isSafeViewUrl('mailto:a@b.com', 'href')).toBe(true);
+    expect(isSafeViewUrl('tel:+1555', 'href')).toBe(true);
+    expect(isSafeViewUrl('/relative/path', 'href')).toBe(true);
+    expect(isSafeViewUrl('#frag', 'href')).toBe(true);
+    expect(isSafeViewUrl('  https://example.com  ', 'href')).toBe(true);
+    expect(isSafeViewUrl('data:image/png;base64,AAAA', 'src')).toBe(true);
+    expect(isSafeViewUrl('data:image/png;base64,AAAA', 'href')).toBe(false);
+  });
+});

package/src/view-renderer.ts

@@ -108,7 +108,14 @@ export interface ViewRendererDef {
  * parties, so a `javascript:` link is click-XSS on a shared surface.
  */
 export function isSafeViewUrl(url: string, attr: string): boolean {
-  const u = url.trim().toLowerCase();
+  // Strip ALL ASCII whitespace + C0 control chars (U+0000–U+0020) anywhere in
+  // the URL before the scheme check — the HTML URL parser removes tab/newline/CR
+  // before resolving the scheme, so `java\tscript:` would otherwise pass this
+  // gate and then execute as `javascript:` on click (audit u72-1). The frontend
+  // copy in @moxxy/plugin-channel-web/src/frontend/url-safety.ts is a verbatim
+  // lockstep duplicate (the browser bundle can't import this root) — keep both
+  // in sync.
+  const u = url.replace(/[\u0000-\u0020]/g, '').toLowerCase();
   if (u.startsWith('javascript:') || u.startsWith('vbscript:')) return false;
   if (u.startsWith('data:')) return attr === 'src' && u.startsWith('data:image/');
   if (/^[a-z][a-z0-9+.-]*:/.test(u)) return /^(https?:|mailto:|tel:)/.test(u);
@@ -176,3 +183,13 @@ export const VIEW_COMPONENTS: ReadonlyArray<ViewTagSpec> = [
 
 /** The default renderer's full allow-list (primitives + components). */
 export const DEFAULT_VIEW_TAGS: ReadonlyArray<ViewTagSpec> = [...VIEW_PRIMITIVES, ...VIEW_COMPONENTS];
+
+/**
+ * Count element + text nodes in a view tree (the `nodeCount` a `present_view`
+ * tool reports). Single source of truth: core's parser and the plugin-view tool
+ * both import this rather than re-implementing the recursion.
+ */
+export function countNodes(node: ViewNode): number {
+  if (node.kind === 'text') return 1;
+  return 1 + node.children.reduce((sum, child) => sum + countNodes(child), 0);
+}