@moxxy/plugin-self-update 0.26.0

package/src/transaction.ts

@@ -0,0 +1,254 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { writeFileAtomic } from '@moxxy/sdk/server';
+
+/**
+ * Transactional bookkeeping for self-update. Every change to a user-scope
+ * artifact (a plugin directory or a skill file) is bracketed by a transaction:
+ * the target is snapshotted before edits, a persisted journal tracks state and
+ * failed attempts, and a rollback restores the snapshot (or deletes a freshly
+ * created artifact). This module is filesystem-only and imports no moxxy core,
+ * so it is trivially unit-testable against a temp directory.
+ */
+
+export type TargetKind = 'plugin' | 'skill';
+
+export type TxnState = 'open' | 'verified' | 'committed' | 'rolled_back' | 'escalated';
+
+export interface TxnTarget {
+  readonly kind: TargetKind;
+  readonly name: string;
+  /** Absolute path to the artifact (a directory for plugins, a file for skills). */
+  readonly path: string;
+}
+
+export interface TxnAttempt {
+  readonly at: string;
+  readonly stage: string;
+  readonly ok: boolean;
+  readonly message: string;
+}
+
+/** Registered contribution names per kind — used to diff what a change added. */
+export type RegistrySnapshot = Record<string, ReadonlyArray<string>>;
+
+export interface Journal {
+  readonly txnId: string;
+  readonly createdAt: string;
+  updatedAt: string;
+  readonly target: TxnTarget;
+  /** Whether the artifact existed before this transaction. false ⇒ rollback deletes it. */
+  readonly existedBefore: boolean;
+  state: TxnState;
+  attempts: TxnAttempt[];
+  /** Registry contributions captured at begin time, for an added-since diff. */
+  registryBefore?: RegistrySnapshot;
+}
+
+/** Names present in `after` but not in `before`, per kind. Empty keys dropped. */
+export function diffSnapshot(before: RegistrySnapshot, after: RegistrySnapshot): RegistrySnapshot {
+  const out: Record<string, ReadonlyArray<string>> = {};
+  for (const key of Object.keys(after)) {
+    const had = new Set(before[key] ?? []);
+    const added = (after[key] ?? []).filter((n) => !had.has(n));
+    if (added.length > 0) out[key] = added;
+  }
+  return out;
+}
+
+/** Max failed verify cycles for one transaction before we force escalation. */
+export const MAX_FAILED_ATTEMPTS = 2;
+
+const NAME_SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Paths excluded from a transaction snapshot. `node_modules` is reproducible
+ * from package.json (verify re-runs `npm install`), `.git` would balloon the
+ * copy, and `dist` is regenerated by the build — copying any of them turns a
+ * source snapshot into a multi-hundred-MB recursive copy of the dependency tree
+ * on every begin and every restore, which is slow and can exhaust disk.
+ */
+const SNAPSHOT_EXCLUDE = new Set(['node_modules', '.git', 'dist']);
+
+/**
+ * Build an `fs.cp` filter that skips excluded directory basenames so snapshots
+ * stay source-only — but never excludes the copy root itself (a plugin could,
+ * per NAME_SEGMENT_RE, legitimately be named e.g. `dist`).
+ */
+function snapshotFilter(root: string): (src: string) => boolean {
+  return (src) => src === root || !SNAPSHOT_EXCLUDE.has(path.basename(src));
+}
+
+export function selfUpdateRoot(moxxyDir: string): string {
+  return path.join(moxxyDir, 'self-update', 'txns');
+}
+
+export function txnDir(moxxyDir: string, txnId: string): string {
+  return path.join(selfUpdateRoot(moxxyDir), txnId);
+}
+
+/**
+ * Resolve the on-disk target for a (kind, name). Throws on unsafe names so a
+ * model-supplied name can never escape the user artifact directories.
+ */
+export function resolveTarget(moxxyDir: string, kind: TargetKind, name: string): TxnTarget {
+  if (!NAME_SEGMENT_RE.test(name)) {
+    throw new Error(
+      `invalid ${kind} name "${name}": only letters, digits, dot, dash and underscore are allowed`,
+    );
+  }
+  const p =
+    kind === 'plugin'
+      ? path.join(moxxyDir, 'plugins', name)
+      : path.join(moxxyDir, 'skills', `${name}.md`);
+  return { kind, name, path: p };
+}
+
+export function newTxnId(now: Date = new Date()): string {
+  const stamp = now.toISOString().replace(/[:.]/g, '-');
+  // crypto UUID (not Math.random): two begins in the same second must never
+  // collide on the txn dir, which beginTransaction's recursive mkdir would
+  // silently share — clobbering an existing txn's journal + before snapshot.
+  const rand = randomUUID().slice(0, 8);
+  return `${stamp}-${rand}`;
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Open a transaction: snapshot the current target (if any) into the txn dir
+ * and write the initial journal. Safe to call for a not-yet-existing target.
+ */
+export async function beginTransaction(opts: {
+  readonly moxxyDir: string;
+  readonly kind: TargetKind;
+  readonly name: string;
+  readonly now?: Date;
+}): Promise<Journal> {
+  const now = opts.now ?? new Date();
+  const target = resolveTarget(opts.moxxyDir, opts.kind, opts.name);
+  const txnId = newTxnId(now);
+  const dir = txnDir(opts.moxxyDir, txnId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const existedBefore = await pathExists(target.path);
+  if (existedBefore) {
+    const before = path.join(dir, 'before');
+    await fs.cp(target.path, before, { recursive: true, filter: snapshotFilter(target.path) });
+  }
+
+  const journal: Journal = {
+    txnId,
+    createdAt: now.toISOString(),
+    updatedAt: now.toISOString(),
+    target,
+    existedBefore,
+    state: 'open',
+    attempts: [],
+  };
+  await writeJournal(opts.moxxyDir, journal);
+  return journal;
+}
+
+export async function writeJournal(moxxyDir: string, journal: Journal): Promise<void> {
+  journal.updatedAt = new Date().toISOString();
+  const file = path.join(txnDir(moxxyDir, journal.txnId), 'journal.json');
+  await writeFileAtomic(file, JSON.stringify(journal, null, 2) + '\n');
+}
+
+export async function readJournal(moxxyDir: string, txnId: string): Promise<Journal> {
+  const file = path.join(txnDir(moxxyDir, txnId), 'journal.json');
+  const raw = await fs.readFile(file, 'utf8');
+  return JSON.parse(raw) as Journal;
+}
+
+export async function listTransactions(moxxyDir: string): Promise<ReadonlyArray<Journal>> {
+  const root = selfUpdateRoot(moxxyDir);
+  let ids: string[];
+  try {
+    ids = (await fs.readdir(root, { withFileTypes: true }))
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+  const out: Journal[] = [];
+  for (const id of ids) {
+    try {
+      out.push(await readJournal(moxxyDir, id));
+    } catch {
+      // ignore half-written / corrupt txn dirs
+    }
+  }
+  return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+export function recordAttempt(journal: Journal, attempt: Omit<TxnAttempt, 'at'>): void {
+  journal.attempts.push({ at: new Date().toISOString(), ...attempt });
+}
+
+export function failedAttemptCount(journal: Journal): number {
+  return journal.attempts.filter((a) => !a.ok).length;
+}
+
+/**
+ * Restore the target to its pre-transaction state: copy the snapshot back, or
+ * delete the artifact if it was newly created. Idempotent.
+ *
+ * The snapshot is source-only (SNAPSHOT_EXCLUDE drops node_modules/.git/dist),
+ * so a blanket `rm -rf` of the target before copying would wipe the installed
+ * runtime deps — and nothing re-installs them, leaving a plugin that fails to
+ * load on the very next deps.reload(). To keep the working `node_modules` (and
+ * the other reproducible-but-uncaptured dirs) across a MODIFICATION rollback, we
+ * remove only the captured source entries and overlay the snapshot back on top,
+ * never touching the excluded dirs. A newly-created target (no snapshot) is still
+ * deleted wholesale.
+ */
+export async function restoreSnapshot(moxxyDir: string, journal: Journal): Promise<void> {
+  const { target, existedBefore } = journal;
+  if (!existedBefore) {
+    await fs.rm(target.path, { recursive: true, force: true });
+    return;
+  }
+  const before = path.join(txnDir(moxxyDir, journal.txnId), 'before');
+  // A skill target is a single file, not a directory — replace it outright.
+  if (target.kind !== 'plugin') {
+    await fs.rm(target.path, { recursive: true, force: true });
+    await fs.cp(before, target.path, { recursive: true, filter: snapshotFilter(before) });
+    return;
+  }
+  // Plugin directory: clear only the non-excluded entries (the source the
+  // snapshot captured) so the live node_modules/.git/dist survive intact, then
+  // copy the source snapshot back over them.
+  let entries: string[] = [];
+  try {
+    entries = (await fs.readdir(target.path, { withFileTypes: true })).map((e) => e.name);
+  } catch {
+    // Target dir vanished — recreate it from the snapshot below.
+  }
+  for (const name of entries) {
+    if (SNAPSHOT_EXCLUDE.has(name)) continue;
+    await fs.rm(path.join(target.path, name), { recursive: true, force: true });
+  }
+  await fs.mkdir(target.path, { recursive: true });
+  await fs.cp(before, target.path, { recursive: true, filter: snapshotFilter(before) });
+}
+
+/** Keep the most recent `keep` terminal transactions; delete older ones. */
+export async function gcTransactions(moxxyDir: string, keep: number): Promise<void> {
+  const all = await listTransactions(moxxyDir);
+  const terminal = all.filter(
+    (j) => j.state === 'committed' || j.state === 'rolled_back' || j.state === 'escalated',
+  );
+  for (const j of terminal.slice(keep)) {
+    await fs.rm(txnDir(moxxyDir, j.txnId), { recursive: true, force: true });
+  }
+}

package/src/verify.test.ts

@@ -0,0 +1,82 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { verifyPluginBuild, verifySkillFile } from './verify.js';
+import { resolveTarget } from './transaction.js';
+
+const tempDirs: string[] = [];
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((d) => fs.rm(d, { recursive: true, force: true })));
+});
+
+async function tempPluginDir(): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'moxxy-verify-'));
+  tempDirs.push(dir);
+  return dir;
+}
+
+describe('verifyPluginBuild', () => {
+  it('is a no-op for a bare plugin with no package.json', async () => {
+    const dir = await tempPluginDir();
+    await fs.writeFile(path.join(dir, 'index.mjs'), 'export default {};\n', 'utf8');
+    const target = { kind: 'plugin' as const, name: 'bare', path: dir };
+    expect(await verifyPluginBuild(target)).toEqual([]);
+  });
+
+  it('reports a failing build script', async () => {
+    const dir = await tempPluginDir();
+    await fs.writeFile(
+      path.join(dir, 'package.json'),
+      JSON.stringify({ name: 'p', scripts: { build: 'exit 1' } }),
+      'utf8',
+    );
+    const stages = await verifyPluginBuild({ kind: 'plugin', name: 'p', path: dir });
+    expect(stages.at(-1)?.stage).toBe('build');
+    expect(stages.at(-1)?.ok).toBe(false);
+  }, 30_000);
+});
+
+describe('verifySkillFile', () => {
+  it('accepts a well-formed skill', async () => {
+    const dir = await tempPluginDir();
+    const moxxy = dir;
+    await fs.mkdir(path.join(moxxy, 'skills'), { recursive: true });
+    const target = resolveTarget(moxxy, 'skill', 'good');
+    await fs.writeFile(target.path, '---\nname: good\ndescription: does a thing\n---\n\nbody\n', 'utf8');
+    expect((await verifySkillFile(target)).ok).toBe(true);
+  });
+
+  it('rejects missing frontmatter', async () => {
+    const dir = await tempPluginDir();
+    await fs.mkdir(path.join(dir, 'skills'), { recursive: true });
+    const target = resolveTarget(dir, 'skill', 'bad');
+    await fs.writeFile(target.path, 'no frontmatter here\n', 'utf8');
+    const r = await verifySkillFile(target);
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects frontmatter missing name/description', async () => {
+    const dir = await tempPluginDir();
+    await fs.mkdir(path.join(dir, 'skills'), { recursive: true });
+    const target = resolveTarget(dir, 'skill', 'partial');
+    await fs.writeFile(target.path, '---\nname: x\n---\nbody\n', 'utf8');
+    expect((await verifySkillFile(target)).ok).toBe(false);
+  });
+
+  it('accepts a CRLF (Windows-authored) skill', async () => {
+    const dir = await tempPluginDir();
+    await fs.mkdir(path.join(dir, 'skills'), { recursive: true });
+    const target = resolveTarget(dir, 'skill', 'crlf');
+    await fs.writeFile(target.path, '---\r\nname: good\r\ndescription: does a thing\r\n---\r\n\r\nbody\r\n', 'utf8');
+    expect((await verifySkillFile(target)).ok).toBe(true);
+  });
+
+  it('rejects an empty quoted value that the old \\S+ check accepted', async () => {
+    const dir = await tempPluginDir();
+    await fs.mkdir(path.join(dir, 'skills'), { recursive: true });
+    const target = resolveTarget(dir, 'skill', 'emptyname');
+    await fs.writeFile(target.path, '---\nname: ""\ndescription: ok\n---\nbody\n', 'utf8');
+    expect((await verifySkillFile(target)).ok).toBe(false);
+  });
+});

package/src/verify.ts

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import type { TxnTarget } from './transaction.js';
+
+/**
+ * Build/test verification for a transaction target, run as child processes so a
+ * failing build can never crash the host. Pure I/O — no moxxy core imports.
+ */
+
+export interface StageResult {
+  readonly stage: string;
+  readonly ok: boolean;
+  readonly message: string;
+}
+
+export interface RunCmdResult {
+  readonly exitCode: number;
+  readonly output: string;
+}
+
+const CMD_TIMEOUT_MS = 5 * 60_000;
+/**
+ * Cap on retained child output. A model-triggered `npm run build/test` can emit
+ * unbounded output; holding it all in the live process risks OOM. Callers only
+ * read the trailing ~1.2KB, so a sliding tail is lossless for them.
+ */
+const MAX_CMD_OUTPUT_BYTES = 512 * 1024;
+
+function runCmd(cmd: string, args: ReadonlyArray<string>, cwd: string): Promise<RunCmdResult> {
+  return new Promise((resolve) => {
+    // `detached` lets a timeout SIGKILL the whole process group (npm fans out to
+    // node/esbuild/vitest workers that an immediate-child kill would orphan).
+    const child = spawn(cmd, [...args], { cwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+    let buf = '';
+    const onData = (d: Buffer): void => {
+      buf += d.toString('utf8');
+      if (buf.length > MAX_CMD_OUTPUT_BYTES) buf = buf.slice(buf.length - MAX_CMD_OUTPUT_BYTES);
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    const timer = setTimeout(() => killTree(child), CMD_TIMEOUT_MS);
+    let settled = false;
+    const finish = (r: RunCmdResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout.off('data', onData);
+      child.stderr.off('data', onData);
+      resolve(r);
+    };
+    child.on('error', (err) => finish({ exitCode: -1, output: `${cmd} failed to start: ${err.message}` }));
+    child.on('close', (code) => finish({ exitCode: code ?? -1, output: buf }));
+  });
+}
+
+/** SIGKILL a detached child's whole process group, tolerating an already-dead group. */
+function killTree(child: { pid?: number; kill: (s: NodeJS.Signals) => boolean }): void {
+  try {
+    if (child.pid != null) process.kill(-child.pid, 'SIGKILL');
+    else child.kill('SIGKILL');
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+function truncate(s: string, n = 1200): string {
+  return s.length <= n ? s : `…${s.slice(s.length - n)}`;
+}
+
+interface PkgJson {
+  readonly scripts?: Record<string, string>;
+  readonly dependencies?: Record<string, string>;
+  /** npm-standard `packageManager` field, e.g. "pnpm@9.0.0" — selects the verifier toolchain. */
+  readonly packageManager?: string;
+}
+
+async function readPkg(dir: string): Promise<PkgJson | null> {
+  try {
+    return JSON.parse(await fs.readFile(path.join(dir, 'package.json'), 'utf8')) as PkgJson;
+  } catch {
+    return null;
+  }
+}
+
+/** Per-package-manager invocations for the install / run-script / test steps. */
+interface PmCommands {
+  readonly install: ReadonlyArray<string>;
+  readonly run: (script: string) => ReadonlyArray<string>;
+  readonly test: ReadonlyArray<string>;
+  readonly bin: string;
+}
+
+const PM_COMMANDS: Record<string, PmCommands> = {
+  npm: { bin: 'npm', install: ['install', '--no-fund', '--no-audit'], run: (s) => ['run', s], test: ['test'] },
+  pnpm: { bin: 'pnpm', install: ['install'], run: (s) => ['run', s], test: ['test'] },
+  yarn: { bin: 'yarn', install: ['install'], run: (s) => ['run', s], test: ['test'] },
+  bun: { bin: 'bun', install: ['install'], run: (s) => ['run', s], test: ['test'] },
+};
+
+/**
+ * Pick the package manager from the npm-standard `packageManager` field
+ * ("pnpm@9", "yarn@4", …) so a non-npm plugin can declare its toolchain. The
+ * default is npm, preserving prior behavior for plugins that omit the field or
+ * name an unknown manager.
+ */
+function pmFor(pkg: PkgJson): PmCommands {
+  const name = (pkg.packageManager ?? '').split('@')[0]?.trim().toLowerCase();
+  return (name && PM_COMMANDS[name]) || PM_COMMANDS.npm!;
+}
+
+/**
+ * Run a plugin's own `build` and `test` npm scripts when present. A plugin
+ * scaffolded as a zero-build `.mjs` (no scripts) passes straight through —
+ * jiti / dynamic-import handles it at reload time, which is the real load test.
+ */
+export async function verifyPluginBuild(target: TxnTarget): Promise<ReadonlyArray<StageResult>> {
+  const results: StageResult[] = [];
+  const pkg = await readPkg(target.path);
+  if (!pkg) return results; // no package.json (e.g. bare .mjs) → nothing to build
+
+  const pm = pmFor(pkg);
+
+  // Install deps only if the plugin declares any and they aren't present yet.
+  if (pkg.dependencies && Object.keys(pkg.dependencies).length > 0) {
+    const hasModules = await fs
+      .access(path.join(target.path, 'node_modules'))
+      .then(() => true)
+      .catch(() => false);
+    if (!hasModules) {
+      const r = await runCmd(pm.bin, pm.install, target.path);
+      results.push({
+        stage: 'install',
+        ok: r.exitCode === 0,
+        message: r.exitCode === 0 ? 'deps installed' : truncate(r.output),
+      });
+      if (r.exitCode !== 0) return results;
+    }
+  }
+
+  if (pkg.scripts?.build) {
+    const r = await runCmd(pm.bin, pm.run('build'), target.path);
+    results.push({
+      stage: 'build',
+      ok: r.exitCode === 0,
+      message: r.exitCode === 0 ? 'build ok' : truncate(r.output),
+    });
+    if (r.exitCode !== 0) return results;
+  }
+
+  if (pkg.scripts?.test) {
+    const r = await runCmd(pm.bin, pm.test, target.path);
+    results.push({
+      stage: 'test',
+      ok: r.exitCode === 0,
+      message: r.exitCode === 0 ? 'tests ok' : truncate(r.output),
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Require a real (non-empty, non-blank-quoted) value after a frontmatter key.
+ * Rejects `name:`, `name: ""`, `name: '   '` — a quote alone satisfied the old
+ * `\S+`, accepting a structurally-present-but-empty field.
+ */
+const FRONTMATTER_FIELD = (key: string): RegExp =>
+  new RegExp(`^${key}:[ \\t]*(?:"[ \\t]*[^"\\s][^"]*"|'[ \\t]*[^'\\s][^']*'|[^"'\\s].*)$`, 'm');
+
+/** Minimal structural check that a skill file has the required frontmatter. */
+export async function verifySkillFile(target: TxnTarget): Promise<StageResult> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(target.path, 'utf8');
+  } catch {
+    return { stage: 'parse', ok: false, message: `skill file not found: ${target.path}` };
+  }
+  // Normalize CRLF so a Windows-authored skill isn't rejected by the \n anchors.
+  const normalized = raw.replace(/\r\n/g, '\n');
+  const fm = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) {
+    return { stage: 'parse', ok: false, message: 'missing YAML frontmatter block (--- … ---)' };
+  }
+  const body = fm[1] ?? '';
+  const hasName = FRONTMATTER_FIELD('name').test(body);
+  const hasDesc = FRONTMATTER_FIELD('description').test(body);
+  if (!hasName || !hasDesc) {
+    return {
+      stage: 'parse',
+      ok: false,
+      message: 'frontmatter must declare both a non-empty `name:` and `description:`',
+    };
+  }
+  return { stage: 'parse', ok: true, message: 'frontmatter ok' };
+}