adolf/scripts/e2e/lib/plugin-update/probe.mjs

// Probe script for plugin update E2E scenarios.
import fs from "node:fs";
import http from "node:http";
import os from "node:os";
import path from "node:path";
import { legacyPackageAcceptanceCompat } from "../package-compat.mjs";
import {
  readPluginInstallRecords,
  writePluginInstallIndexForE2E,
} from "../plugin-index-sqlite.mjs";

const home = os.homedir();
const OUTPUT_TAIL_BYTES = 64 * 1024;
const OUTPUT_TAIL_LINES = 120;
const OUTPUT_SCAN_WINDOW_BYTES = 8 * 1024;

const readJson = (file) => {
  try {
    return JSON.parse(fs.readFileSync(file, "utf8"));
  } catch {
    return {};
  }
};

const pluginRecordSnapshot = () => {
  const config = readJson(openclawPath("openclaw.json"));
  const records = readPluginInstallRecords({ fallbackRecords: config.plugins?.installs ?? {} });
  const record = records["lossless-claw"] ?? records["@example/lossless-claw"];
  if (!record) {
    throw new Error("missing plugin install record");
  }
  const { source, spec, resolvedName, resolvedVersion, resolvedSpec, integrity, shasum } = record;
  return { source, spec, resolvedName, resolvedVersion, resolvedSpec, integrity, shasum };
};

function openclawPath(...parts) {
  return path.join(home, ".openclaw", ...parts);
}

function writeJson(file, value) {
  fs.mkdirSync(path.dirname(file), { recursive: true });
  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
}

function seedInstallState() {
  writeJson(openclawPath("extensions", "lossless-claw", "package.json"), {
    name: "@example/lossless-claw",
    version: "0.9.0",
  });
  writeJson(process.env.OPENCLAW_CONFIG_PATH, { plugins: {} });
  writePluginInstallIndexForE2E({
    version: 1,
    warning: "DO NOT EDIT. This file is generated by OpenClaw plugin registry commands.",
    hostContractVersion: "docker-e2e",
    compatRegistryVersion: "docker-e2e",
    migrationVersion: 1,
    policyHash: "docker-e2e",
    generatedAtMs: 1777118400000,
    installRecords: {
      "lossless-claw": {
        source: "npm",
        spec: "@example/lossless-claw@0.9.0",
        installPath: "~/.openclaw/extensions/lossless-claw",
        resolvedName: "@example/lossless-claw",
        resolvedVersion: "0.9.0",
        resolvedSpec: "@example/lossless-claw@0.9.0",
        integrity: "sha512-same",
        shasum: "same",
      },
    },
    plugins: [],
    diagnostics: [],
  });
}

async function waitRegistry() {
  for (let attempt = 0; attempt < 50; attempt += 1) {
    if (await registryHealthy()) {
      return;
    }
    await new Promise((resolve) => {
      setTimeout(resolve, 100);
    });
  }
  throw new Error("Local npm metadata registry failed to start");
}

function registryHealthy() {
  return new Promise((resolve) => {
    const registry = process.env.NPM_CONFIG_REGISTRY ?? "http://127.0.0.1:4873";
    const req = http.get(`${registry.replace(/\/$/u, "")}/@example%2flossless-claw`, (res) => {
      resolve(res.statusCode === 200);
      res.resume();
    });
    req.on("error", () => resolve(false));
    req.setTimeout(200, () => {
      req.destroy();
      resolve(false);
    });
  });
}

function assertSnapshot(beforePath) {
  const before = readJson(beforePath);
  const after = pluginRecordSnapshot();
  if (JSON.stringify(before) !== JSON.stringify(after)) {
    throw new Error(
      `plugin install record changed unexpectedly: ${JSON.stringify({ before, after })}`,
    );
  }
}

function appendBufferTail(tail, chunk, maxBytes) {
  if (chunk.length >= maxBytes) {
    return chunk.subarray(chunk.length - maxBytes);
  }
  if (tail.length + chunk.length <= maxBytes) {
    return Buffer.concat([tail, chunk]);
  }
  return Buffer.concat([tail, chunk]).subarray(tail.length + chunk.length - maxBytes);
}

async function readOutputEvidence(logPath) {
  let outputTail = Buffer.alloc(0);
  let scanWindow = "";
  let sawDownload = false;
  let sawUpToDate = false;
  for await (const chunk of fs.createReadStream(logPath)) {
    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
    const text = buffer.toString("utf8");
    const searchable = `${scanWindow}${text}`;
    outputTail = appendBufferTail(outputTail, buffer, OUTPUT_TAIL_BYTES);
    sawDownload ||= searchable.includes("Downloading @example/lossless-claw");
    sawUpToDate ||= searchable.includes("lossless-claw is up to date (0.9.0).");
    scanWindow = searchable.slice(-OUTPUT_SCAN_WINDOW_BYTES);
  }
  return {
    outputTail: outputTail
      .toString("utf8")
      .split(/\r?\n/u)
      .slice(-OUTPUT_TAIL_LINES)
      .join("\n")
      .trimEnd(),
    sawDownload,
    sawUpToDate,
  };
}

async function assertOutput(logPath) {
  const evidence = await readOutputEvidence(logPath);
  const failure = evidence.sawDownload
    ? "Unexpected npm download/reinstall path"
    : !evidence.sawUpToDate
      ? "Expected up-to-date output missing"
      : "";
  if (failure) {
    throw new Error(`${failure}\nOutput tail:\n${evidence.outputTail}`);
  }
}

function assertCorruptUpdate(updateJsonPath, pluginId) {
  const payload = readJson(updateJsonPath);
  if (payload.status !== "ok") {
    throw new Error(`expected core update status ok, got ${JSON.stringify(payload.status)}`);
  }
  const plugins = payload.postUpdate?.plugins;
  if (!plugins) {
    throw new Error(`missing postUpdate.plugins in update output: ${JSON.stringify(payload)}`);
  }
  assertCorruptPluginTolerated(plugins, pluginId);
}

function assertCorruptPluginResult(pluginJsonPath, pluginId) {
  const plugins = readJson(pluginJsonPath);
  assertCorruptPluginTolerated(plugins, pluginId);
}

function assertCorruptPluginTolerated(plugins, pluginId) {
  const evidence = collectPluginEvidence(plugins, pluginId);
  if (plugins.status === "ok") {
    assertCorruptPluginCleanOrRepaired(evidence);
    return;
  }
  if (plugins.status !== "warning") {
    throw new Error(
      `expected post-update plugin status warning, got ${JSON.stringify(plugins.status)}`,
    );
  }
  assertCorruptPluginDetails(plugins, pluginId);
}

function isCorruptPluginDisabledAfterUpdate(evidence, pluginId) {
  const outcome = evidence.outcome;
  const message = typeof outcome?.message === "string" ? outcome.message : "";
  return (
    outcome?.status === "skipped" &&
    message.includes(`Disabled "${pluginId}" after plugin update failure`) &&
    message.includes("OpenClaw will continue without it")
  );
}

function assertCorruptPluginCleanOrRepaired(evidence) {
  if (evidence.outcome) {
    throw new Error(
      `expected clean or repaired corrupt plugin state, got ${JSON.stringify(evidence)}`,
    );
  }
  if (evidence.warning || evidence.integrityDrift || evidence.syncMessages.length > 0) {
    throw new Error(
      `expected warning post-update status for corrupt plugin evidence, got ok: ${JSON.stringify(
        evidence,
      )}`,
    );
  }
}

function assertCorruptPluginDetails(plugins, pluginId) {
  const evidence = collectPluginEvidence(plugins, pluginId);
  const outcome = evidence.outcome;
  const disabledAfterFailure = isCorruptPluginDisabledAfterUpdate(evidence, pluginId);
  if (!outcome || (outcome.status !== "error" && !disabledAfterFailure)) {
    throw new Error(
      `expected error or disabled-after-failure outcome for ${pluginId}, got ${JSON.stringify({
        outcomes: plugins.npm?.outcomes ?? [],
        warnings: plugins.warnings ?? [],
        sync: plugins.sync,
        integrityDrifts: plugins.integrityDrifts ?? [],
      })}`,
    );
  }
  const warning = evidence.warning;
  if (!warning) {
    throw new Error(
      `expected warning for ${pluginId}, got ${JSON.stringify(plugins.warnings ?? [])}`,
    );
  }
  const text = [outcome.message, warning.reason, warning.message, ...(warning.guidance ?? [])]
    .filter(Boolean)
    .join(" ");
  const expectedFragments = disabledAfterFailure
    ? [
        `Disabled "${pluginId}" after plugin update failure`,
        "OpenClaw will continue without it",
        "Run openclaw update repair to retry post-update plugin repair.",
        `Run openclaw plugins inspect ${pluginId} --runtime --json for details.`,
      ]
    : [
        "package.json is missing",
        "Run openclaw update repair to retry post-update plugin repair.",
        `Run openclaw plugins inspect ${pluginId} --runtime --json for details.`,
      ];
  for (const expected of expectedFragments) {
    if (!text.includes(expected)) {
      throw new Error(`expected update output to include ${expected}: ${text}`);
    }
  }
}

function collectPluginEvidence(plugins, pluginId) {
  const outcomes = plugins.npm?.outcomes ?? [];
  const warnings = plugins.warnings ?? [];
  const integrityDrifts = plugins.integrityDrifts ?? [];
  const syncMessages = [...(plugins.sync?.warnings ?? []), ...(plugins.sync?.errors ?? [])].filter(
    (message) => String(message).includes(pluginId),
  );
  return {
    outcome: outcomes.find((entry) => entry?.pluginId === pluginId),
    warning: warnings.find((entry) => entry?.pluginId === pluginId),
    integrityDrift: integrityDrifts.find((entry) => entry?.pluginId === pluginId),
    syncMessages,
  };
}

function assertLegacyPostUpdatePluginFailure(updateJsonPath) {
  const payload = readJson(updateJsonPath);
  if (payload.status !== "error" || payload.reason !== "post-update-plugins") {
    throw new Error(
      `expected legacy post-update plugin failure, got ${JSON.stringify({
        status: payload.status,
        reason: payload.reason,
      })}`,
    );
  }
  if (!payload.after?.version) {
    throw new Error(`expected core update to install a new version: ${JSON.stringify(payload)}`);
  }
}

const [command, arg, arg2] = process.argv.slice(2);
const commands = {
  "legacy-compat": () => console.log(legacyPackageAcceptanceCompat(arg || "") ? "1" : "0"),
  seed: seedInstallState,
  "wait-registry": waitRegistry,
  snapshot: () => process.stdout.write(JSON.stringify(pluginRecordSnapshot(), null, 2)),
  "assert-snapshot": () => assertSnapshot(arg),
  "assert-output": () => assertOutput(arg),
  "assert-corrupt-update": () => assertCorruptUpdate(arg, arg2),
  "assert-corrupt-plugin-result": () => assertCorruptPluginResult(arg, arg2),
  "assert-legacy-post-update-plugin-failure": () => assertLegacyPostUpdatePluginFailure(arg),
};
const run = commands[command];
await (
  run ??
  (() => {
    throw new Error(`Unknown plugin update probe command: ${command || "(missing)"}`);
  })
)();