@moxxy/plugin-self-update 0.26.0

package/src/deps.ts

@@ -0,0 +1,84 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import type { SessionId, ToolContext, TurnId } from '@moxxy/sdk';
+import type { RegistrySnapshot } from './transaction.js';
+import { detectCoreInstall, type CoreInstallInfo } from './core-update.js';
+
+export const PLUGIN_ID = '@moxxy/plugin-self-update';
+
+export interface SkipInfo {
+  readonly pluginName: string;
+  readonly packageName?: string;
+  readonly message: string;
+}
+
+export interface SelfUpdateEmit {
+  readonly subtype: string;
+  readonly payload: unknown;
+  readonly sessionId: SessionId;
+  readonly turnId: TurnId;
+}
+
+export interface SelfUpdateDeps {
+  /** Base user dir, normally `~/.moxxy`. Overridable for tests. */
+  readonly moxxyDir: string;
+  /** Hot-reload the plugin host (rescans user plugin dirs). */
+  readonly reload: () => Promise<void>;
+  /** Unload a plugin by name so a modified version re-imports fresh on reload. */
+  readonly unload: (name: string) => Promise<void>;
+  /** Current registered contribution names per kind. */
+  readonly snapshot: () => RegistrySnapshot;
+  /** Plugins the host failed to load (so we can surface a load error). */
+  readonly skipped: () => ReadonlyArray<SkipInfo>;
+  /** Append a `plugin_event` audit record. Best-effort. */
+  readonly emit: (e: SelfUpdateEmit) => Promise<void>;
+  /** How many terminal transactions to keep on GC. Default 5. */
+  readonly maxTxnRetained?: number;
+  /** Tier-2 core-patching config. Omit or set enabled:false to hide core tools. */
+  readonly coreUpdate?: {
+    /** Enable the Tier-2 core-update tools. Default true. */
+    readonly enabled?: boolean;
+    /** Module URL used to resolve the live @moxxy/core install. Default import.meta.url. */
+    readonly fromUrl?: string;
+    /** Override the git repository URL (else read from @moxxy/core package.json). */
+    readonly repoUrlOverride?: string;
+  };
+}
+
+export async function readJsonName(dir: string): Promise<string | undefined> {
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(dir, 'package.json'), 'utf8')) as {
+      name?: string;
+    };
+    return pkg.name;
+  } catch {
+    return undefined;
+  }
+}
+
+export function findSkip(
+  skipped: ReadonlyArray<SkipInfo>,
+  names: ReadonlyArray<string>,
+): SkipInfo | undefined {
+  const want = new Set(names.filter(Boolean));
+  return skipped.find((s) => want.has(s.pluginName) || (s.packageName ? want.has(s.packageName) : false));
+}
+
+export async function emitSafe(
+  deps: SelfUpdateDeps,
+  ctx: ToolContext,
+  subtype: string,
+  payload: unknown,
+): Promise<void> {
+  await deps
+    .emit({ subtype, payload, sessionId: ctx.sessionId, turnId: ctx.turnId })
+    .catch(() => undefined);
+}
+
+/**
+ * The fromUrl default is provided by the caller — `detectCoreInstall` resolves
+ * the live `@moxxy/core` install relative to that module URL.
+ */
+export function resolveCoreInstall(deps: SelfUpdateDeps, fromUrlDefault: string): CoreInstallInfo | null {
+  return detectCoreInstall(deps.coreUpdate?.fromUrl ?? fromUrlDefault);
+}

package/src/discovery.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { selfUpdatePlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves pluginHost + registrySnapshot +
+ * the writable appendEvent + its config options from the service registry in
+ * onInit, instead of the host SelfUpdateDeps closure.
+ */
+describe('selfUpdatePlugin (discovery-loadable)', () => {
+  it('exposes the self_update tools + an onInit hook', () => {
+    const names = selfUpdatePlugin.tools?.map((t) => t.name) ?? [];
+    expect(names).toContain('self_update_classify');
+    expect(names).toContain('self_update_begin');
+    expect(typeof selfUpdatePlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves pluginHost/registrySnapshot/appendEvent/getPluginOptions', () => {
+    const get = vi.fn((name: string) => {
+      switch (name) {
+        case 'pluginHost':
+          return { reload: async () => {}, unload: async () => {}, listSkipped: () => [] };
+        case 'registrySnapshot':
+          return () => ({});
+        case 'appendEvent':
+          return async () => {};
+        case 'getPluginOptions':
+          return () => ({});
+        default:
+          return undefined;
+      }
+    });
+    const services = { get, register: () => {}, require: () => undefined, has: () => true } as unknown as ServiceRegistry;
+    selfUpdatePlugin.hooks!.onInit!({ services } as never);
+    expect(get).toHaveBeenCalledWith('pluginHost');
+    expect(get).toHaveBeenCalledWith('registrySnapshot');
+    expect(get).toHaveBeenCalledWith('appendEvent');
+    expect(get).toHaveBeenCalledWith('getPluginOptions');
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,299 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+import { asSessionId, asTurnId, type ToolContext, type ToolDef } from '@moxxy/sdk';
+import { buildSelfUpdatePlugin, type SelfUpdateDeps, type SkipInfo } from './index.js';
+import { readJournal } from './transaction.js';
+import { writeCoreJournal } from './core-update.js';
+
+const tempDirs: string[] = [];
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((d) => fs.rm(d, { recursive: true, force: true })));
+});
+
+/**
+ * In-memory stand-in for the plugin host: a reload rescans the on-disk plugin
+ * dirs and registers a `<name>_tool` for each loadable entry, or records a skip
+ * for one whose entry contains the marker `BROKEN`.
+ */
+class FakeHost {
+  tools = new Set<string>();
+  skips: SkipInfo[] = [];
+  reloads = 0;
+  constructor(readonly moxxyDir: string) {}
+
+  reload = async (): Promise<void> => {
+    this.reloads++;
+    this.tools = new Set();
+    this.skips = [];
+    const pluginsDir = path.join(this.moxxyDir, 'plugins');
+    const names = await fs.readdir(pluginsDir).catch(() => [] as string[]);
+    for (const name of names) {
+      const content = await fs
+        .readFile(path.join(pluginsDir, name, 'index.mjs'), 'utf8')
+        .catch(() => null);
+      if (content == null) continue;
+      if (content.includes('BROKEN')) this.skips.push({ pluginName: name, message: 'SyntaxError: broken entry' });
+      else this.tools.add(`${name}_tool`);
+    }
+  };
+
+  unload = async (name: string): Promise<void> => {
+    this.tools.delete(`${name}_tool`);
+    this.skips = this.skips.filter((s) => s.pluginName !== name);
+  };
+
+  deps(): SelfUpdateDeps {
+    return {
+      moxxyDir: this.moxxyDir,
+      reload: this.reload,
+      unload: this.unload,
+      snapshot: () => ({
+        tools: [...this.tools],
+        agents: [],
+        providers: [],
+        modes: [],
+        compactors: [],
+        channels: [],
+      }),
+      skipped: () => this.skips,
+      emit: async () => undefined,
+    };
+  }
+}
+
+function makeCtx(): ToolContext {
+  return {
+    sessionId: asSessionId('s'),
+    turnId: asTurnId('t'),
+    callId: 't:0' as never,
+    cwd: '/tmp',
+    signal: new AbortController().signal,
+    log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+    logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+  } as unknown as ToolContext;
+}
+
+async function makeMoxxyDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'moxxy-su-int-'));
+  tempDirs.push(dir);
+  await fs.mkdir(path.join(dir, 'plugins'), { recursive: true });
+  return dir;
+}
+
+function tools(deps: SelfUpdateDeps): Record<string, ToolDef> {
+  const plugin = buildSelfUpdatePlugin(deps);
+  const out: Record<string, ToolDef> = {};
+  for (const t of plugin.tools ?? []) out[t.name] = t;
+  return out;
+}
+
+async function writePlugin(moxxy: string, name: string, content: string): Promise<void> {
+  const dir = path.join(moxxy, 'plugins', name);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(path.join(dir, 'index.mjs'), content, 'utf8');
+}
+
+describe('self-update happy path', () => {
+  it('begins, verifies a new plugin, and applies', async () => {
+    const moxxy = await makeMoxxyDir();
+    const host = new FakeHost(moxxy);
+    const t = tools(host.deps());
+    const ctx = makeCtx();
+
+    const begun = (await t.self_update_begin!.handler({ kind: 'plugin', name: 'greeter' }, ctx)) as {
+      txnId: string;
+      existedBefore: boolean;
+    };
+    expect(begun.existedBefore).toBe(false);
+
+    await writePlugin(moxxy, 'greeter', 'export default { name: "greeter" };\n');
+
+    const verified = (await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx)) as {
+      ok: boolean;
+      registered: Record<string, string[]>;
+    };
+    expect(verified.ok).toBe(true);
+    expect(verified.registered.tools).toEqual(['greeter_tool']);
+
+    await t.self_update_apply!.handler({ txnId: begun.txnId }, ctx);
+    expect((await readJournal(moxxy, begun.txnId)).state).toBe('committed');
+  });
+});
+
+describe('failed build / load auto-rollback + escalation', () => {
+  it('fails a broken new plugin, leaves files for retry, escalates after 2 cycles', async () => {
+    const moxxy = await makeMoxxyDir();
+    const host = new FakeHost(moxxy);
+    const t = tools(host.deps());
+    const ctx = makeCtx();
+
+    const begun = (await t.self_update_begin!.handler({ kind: 'plugin', name: 'oops' }, ctx)) as {
+      txnId: string;
+    };
+    await writePlugin(moxxy, 'oops', 'BROKEN syntax (((\n');
+
+    const first = (await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx)) as {
+      ok: boolean;
+      escalate: boolean;
+    };
+    expect(first.ok).toBe(false);
+    expect(first.escalate).toBe(false);
+    // New artifact is left in place so the model can fix it and retry.
+    await expect(fs.access(path.join(moxxy, 'plugins', 'oops'))).resolves.toBeUndefined();
+
+    const second = (await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx)) as { ok: boolean };
+    expect(second.ok).toBe(false);
+
+    // Third call hits the cap → escalate + clean up.
+    const third = (await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx)) as {
+      ok: boolean;
+      escalate: boolean;
+    };
+    expect(third.escalate).toBe(true);
+    expect((await readJournal(moxxy, begun.txnId)).state).toBe('escalated');
+    await expect(fs.access(path.join(moxxy, 'plugins', 'oops'))).rejects.toBeTruthy();
+  });
+
+  it('does not restore + reload twice on the capping MODIFY cycle', async () => {
+    // u106-5: when a MODIFY verify both fails AND hits the attempt cap, the
+    // snapshot restore + plugin reload must run ONCE, not be repeated by
+    // escalate().
+    const moxxy = await makeMoxxyDir();
+    const host = new FakeHost(moxxy);
+    const t = tools(host.deps());
+    const ctx = makeCtx();
+
+    await writePlugin(moxxy, 'mod', 'export default { name: "mod" };\n');
+    const begun = (await t.self_update_begin!.handler({ kind: 'plugin', name: 'mod' }, ctx)) as {
+      txnId: string;
+      existedBefore: boolean;
+    };
+    expect(begun.existedBefore).toBe(true);
+
+    // Break it, then verify three times. Each failure restores the good entry,
+    // so subsequent verifies still re-break it first.
+    const breakAndVerify = async (): Promise<number> => {
+      await writePlugin(moxxy, 'mod', 'BROKEN now\n');
+      const before = host.reloads;
+      await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx);
+      return host.reloads - before;
+    };
+
+    // Cycle 1 (below the cap) reloads twice: once for the load-check inside
+    // verifyPlugin, once for the snapshot restore on failure.
+    expect(await breakAndVerify()).toBe(2);
+    // Cycle 2 records the 2nd failure → hits the cap → escalates. Pre-fix this
+    // ran THREE reloads (load-check + verify-restore + escalate-restore);
+    // post-fix escalate() skips its restore (journal marked rolled_back), so it
+    // reloads exactly twice.
+    expect(await breakAndVerify()).toBe(2);
+    expect((await readJournal(moxxy, begun.txnId)).state).toBe('escalated');
+  });
+
+  it('restores the previous working version when a MODIFY fails to load', async () => {
+    const moxxy = await makeMoxxyDir();
+    const host = new FakeHost(moxxy);
+    const t = tools(host.deps());
+    const ctx = makeCtx();
+
+    const good = 'export default { name: "bar" };\n';
+    await writePlugin(moxxy, 'bar', good);
+
+    const begun = (await t.self_update_begin!.handler({ kind: 'plugin', name: 'bar' }, ctx)) as {
+      txnId: string;
+      existedBefore: boolean;
+    };
+    expect(begun.existedBefore).toBe(true);
+
+    await writePlugin(moxxy, 'bar', 'BROKEN now\n');
+    const res = (await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx)) as {
+      ok: boolean;
+      recovered: boolean;
+    };
+    expect(res.ok).toBe(false);
+    expect(res.recovered).toBe(true);
+    // Previous working entry is back, and it's loadable again.
+    expect(await fs.readFile(path.join(moxxy, 'plugins', 'bar', 'index.mjs'), 'utf8')).toBe(good);
+    expect(host.tools.has('bar_tool')).toBe(true);
+  });
+});
+
+describe('tier-1 serialization', () => {
+  it('refuses a second begin while a non-terminal txn for the same target is open', async () => {
+    const moxxy = await makeMoxxyDir();
+    const host = new FakeHost(moxxy);
+    const t = tools(host.deps());
+    const ctx = makeCtx();
+
+    const first = (await t.self_update_begin!.handler({ kind: 'plugin', name: 'dup' }, ctx)) as {
+      txnId: string;
+    };
+    // Second begin on the SAME target must refuse (state is still 'open').
+    await expect(t.self_update_begin!.handler({ kind: 'plugin', name: 'dup' }, ctx)).rejects.toThrow(
+      /already in progress/,
+    );
+    // A different target is unaffected.
+    await expect(t.self_update_begin!.handler({ kind: 'plugin', name: 'other' }, ctx)).resolves.toBeTruthy();
+
+    // After the first is rolled back, a fresh begin on the same target is allowed.
+    await t.self_update_rollback!.handler({ txnId: first.txnId }, ctx);
+    await expect(t.self_update_begin!.handler({ kind: 'plugin', name: 'dup' }, ctx)).resolves.toBeTruthy();
+  });
+});
+
+describe('rollback', () => {
+  it('deletes a committed new plugin and reloads', async () => {
+    const moxxy = await makeMoxxyDir();
+    const host = new FakeHost(moxxy);
+    const t = tools(host.deps());
+    const ctx = makeCtx();
+
+    const begun = (await t.self_update_begin!.handler({ kind: 'plugin', name: 'temp' }, ctx)) as {
+      txnId: string;
+    };
+    await writePlugin(moxxy, 'temp', 'export default { name: "temp" };\n');
+    await t.self_update_verify!.handler({ txnId: begun.txnId }, ctx);
+    expect(host.tools.has('temp_tool')).toBe(true);
+
+    await t.self_update_rollback!.handler({ txnId: begun.txnId, reason: 'not needed' }, ctx);
+    await expect(fs.access(path.join(moxxy, 'plugins', 'temp'))).rejects.toBeTruthy();
+    expect(host.tools.has('temp_tool')).toBe(false);
+    expect((await readJournal(moxxy, begun.txnId)).state).toBe('rolled_back');
+  });
+
+  it('serializes core txns: begin refuses while another core txn is in flight', async () => {
+    const moxxy = await makeMoxxyDir();
+    // Fake a resolvable @moxxy/core install so begin gets past resolveCoreInstall
+    // and reaches the serialization guard (before any git clone).
+    const coreDir = path.join(moxxy, 'node_modules', '@moxxy', 'core');
+    await fs.mkdir(coreDir, { recursive: true });
+    await fs.writeFile(
+      path.join(coreDir, 'package.json'),
+      JSON.stringify({ version: '1.0.0', gitHead: 'abc123' }),
+      'utf8',
+    );
+    const fromUrl = pathToFileURL(path.join(moxxy, 'caller.js')).href;
+
+    // An active (provisioned = non-terminal) core txn already exists on disk.
+    await writeCoreJournal(moxxy, {
+      txnId: 'CTXN_ACTIVE',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      packages: ['@moxxy/core'],
+      version: '1.0.0',
+      gitHead: 'abc123',
+      repoDir: path.join(moxxy, 'self-update', 'repo'),
+      state: 'provisioned',
+      attempts: [],
+    });
+
+    const deps: SelfUpdateDeps = { ...new FakeHost(moxxy).deps(), coreUpdate: { fromUrl } };
+    const begin = tools(deps)['self_update_core_begin']!;
+    await expect(begin.handler({ packages: ['@moxxy/core'] }, makeCtx())).rejects.toThrow(
+      /already in progress/,
+    );
+  });
+});