@openclaw/plugin-inspector 0.3.15 → 0.3.16

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.3.16 - 2026-06-23
+
+### Fixed
+
+- Write `package.json` updates atomically for `init --scripts` and `prune-workspace-dev-deps`, including symlink-preserving target rewrites and temp-file cleanup on staging failures. Thanks @KrasimirKralev.
+- Mock the Lark SDK HTTP interceptor surface during runtime capture so Feishu plugin bundles load successfully.
+
 ## 0.3.15 - 2026-06-12
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/capture-api.js

@@ -151,7 +151,7 @@ export function createCaptureContext(options = {}) {
     resolvePath: options.resolvePath ?? ((value) => value),
     runtime: options.runtime ?? createRuntimeContext(options),
     secrets: options.secrets ?? createSecretContext(options),
-    store: options.store ?? createStoreContext(options),
+    store: options.store ?? createStoreContext(),
     paths: options.paths ?? {
       cacheDir: ".plugin-inspector/cache",
       configDir: ".plugin-inspector/config",

package/src/cli.js

@@ -38,7 +38,7 @@ try {
     await runConfig(commandArgs);
   } else if (command === "inspect" || command === "report") {
     if (command === "inspect" && !commandArgs.includes("--config")) {
-      await runCheck(commandArgs);
+      await runCheck(commandArgs, { check: commandArgs.includes("--check") });
     } else {
       await runReport(command, commandArgs);
     }
@@ -100,7 +100,7 @@ async function runConfig(commandArgs) {
   }
 }
 
-async function runCheck(commandArgs) {
+async function runCheck(commandArgs, options = {}) {
   const configPath = readFlag(commandArgs, "--config");
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
@@ -133,7 +133,7 @@ async function runCheck(commandArgs) {
     console.log(renderTextSummary(report, { artifacts: paths }));
   }
 
-  if (report.status !== "pass") {
+  if ((options.check ?? true) && report.status !== "pass") {
     throw new Error(`plugin-inspector found ${report.summary.breakageCount} breakages`);
   }
 }
@@ -288,7 +288,7 @@ async function runCapture(commandArgs) {
   const entrypoint = findCaptureEntrypoint(commandArgs);
   const outputPath = readFlag(commandArgs, "--output");
   const pluginRoot = readFlag(commandArgs, "--plugin-root");
-  const mockSdk = readMockSdkFlag(commandArgs) ?? commandArgs.includes("--mock-sdk");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? true;
   const allowExecution = readAllowExecutionFlag(commandArgs);
   if (!entrypoint) {
     throw new Error("capture requires an entrypoint path");

package/src/init.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { inferPluginSeams, packageId } from "./config.js";
+import { writeJsonFileAtomic } from "./json-file.js";
 
 export const defaultInitConfigPath = "plugin-inspector.config.json";
 export const defaultInitWorkflowPath = ".github/workflows/plugin-inspector.yml";
@@ -59,7 +60,7 @@ export async function writePluginInspectorInit(options = {}) {
       ...defaultInitPackageScripts,
     };
     if (!dryRun) {
-      await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+      await writeJsonFileAtomic(packageJsonPath, packageJson);
     }
     written.push(packageJsonPath);
   }

package/src/issues.js

@@ -48,7 +48,7 @@ export const knownIssueCodes = new Set([
 
 const authorRemediationDocsUrl = (code) => `https://docs.openclaw.ai/clawhub/plugin-validation-fixes#${code}`;
 
-const authorRemediation = (summary) => ({ summary });
+const authorRemediation = (summary, ..._details) => ({ summary });
 
 const migrationRemediation = authorRemediation;
 
@@ -462,10 +462,7 @@ export function buildIssues({ breakages = [], warnings = [], suggestions = [], t
       runtimeCoverage: finding.runtimeCoverage ?? null,
       ...(finding.authorRemediation
         ? {
-            authorRemediation: {
-              summary: finding.authorRemediation.summary,
-              docsUrl: authorRemediationDocsUrl(finding.code),
-            },
+            authorRemediation: withAuthorRemediationDocs(finding.code, finding.authorRemediation),
           }
         : {}),
     }));
@@ -491,10 +488,7 @@ export function issueMetadata(finding, targetOpenClaw) {
   };
   const authorMetadata = metadata.authorRemediation
     ? {
-        authorRemediation: {
-          summary: metadata.authorRemediation.summary,
-          docsUrl: authorRemediationDocsUrl(finding.code),
-        },
+        authorRemediation: withAuthorRemediationDocs(finding.code, metadata.authorRemediation),
       }
     : {};
   return {
@@ -505,6 +499,13 @@ export function issueMetadata(finding, targetOpenClaw) {
   };
 }
 
+function withAuthorRemediationDocs(code, remediation) {
+  return {
+    ...remediation,
+    docsUrl: authorRemediationDocsUrl(code),
+  };
+}
+
 export function classifyIssueFinding(finding, targetOpenClaw, metadata = {}) {
   const compatStatus = compatStatusFor(finding, targetOpenClaw);
   const deprecated = compatStatus === "deprecated";

package/src/json-file.js

@@ -1,5 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { lstat, open, readFile, readlink, realpath, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 
 export async function readJsonFile(jsonPath) {
   return JSON.parse(await readFile(jsonPath, "utf8"));
@@ -8,3 +10,98 @@ export async function readJsonFile(jsonPath) {
 export async function readOptionalJsonFile(jsonPath) {
   return existsSync(jsonPath) ? readJsonFile(jsonPath) : null;
 }
+
+// Writes JSON.stringify(value, null, 2) + newline atomically: stage to a sibling
+// temp file, fsync, then rename over the destination. A crash mid-write can only
+// truncate the temp file, so an interrupted run never corrupts an existing
+// manifest. The destination file mode is preserved exactly (including any
+// special bits) so the atomic replace stays permission-neutral. Existing
+// symlinked manifests resolve to their target before staging so the link itself
+// is never replaced.
+export async function writeJsonFileAtomic(jsonPath, value) {
+  const writePath = await resolveJsonWritePath(jsonPath);
+  const data = `${JSON.stringify(value, null, 2)}\n`;
+  const tempPath = join(dirname(writePath), `.${basename(writePath)}.${process.pid}.${randomUUID()}.tmp`);
+
+  let existingMode;
+  try {
+    existingMode = (await stat(writePath)).mode & 0o7777;
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const handle = await open(tempPath, "wx");
+  let stagingError = null;
+  try {
+    await handle.writeFile(data, "utf8");
+    await handle.sync();
+    if (existingMode !== undefined) {
+      await handle.chmod(existingMode);
+    }
+  } catch (error) {
+    stagingError = error;
+  } finally {
+    try {
+      await handle.close();
+    } catch (error) {
+      stagingError ??= error;
+    }
+  }
+
+  if (stagingError) {
+    await unlink(tempPath).catch(() => {});
+    throw stagingError;
+  }
+
+  try {
+    await rename(tempPath, writePath);
+  } catch (error) {
+    await unlink(tempPath).catch(() => {});
+    throw error;
+  }
+}
+
+async function resolveJsonWritePath(jsonPath) {
+  try {
+    return await realpath(jsonPath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  let writePath = jsonPath;
+  const seen = new Set();
+  for (let hops = 0; hops < 40; hops += 1) {
+    const normalizedPath = resolve(writePath);
+    if (seen.has(normalizedPath)) {
+      const error = new Error(`too many symbolic links resolving ${jsonPath}`);
+      error.code = "ELOOP";
+      throw error;
+    }
+    seen.add(normalizedPath);
+
+    let entry;
+    try {
+      entry = await lstat(writePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return writePath;
+      }
+      throw error;
+    }
+
+    if (!entry.isSymbolicLink()) {
+      return writePath;
+    }
+
+    const target = await readlink(writePath);
+    writePath = resolve(dirname(writePath), target);
+  }
+
+  const error = new Error(`too many symbolic links resolving ${jsonPath}`);
+  error.code = "ELOOP";
+  throw error;
+}

package/src/profile-diff.js

@@ -194,12 +194,16 @@ function registrySurfaceChecks(baseline, current) {
     action: "pass",
     metric,
     message: "registry surface delta is tracked as context",
-    baseline: baseline.targetOpenClaw[metric],
-    current: current.targetOpenClaw[metric],
-    delta: current.targetOpenClaw[metric] - baseline.targetOpenClaw[metric],
+    baseline: registrySurfaceCount(baseline.targetOpenClaw[metric]),
+    current: registrySurfaceCount(current.targetOpenClaw[metric]),
+    delta: registrySurfaceCount(current.targetOpenClaw[metric]) - registrySurfaceCount(baseline.targetOpenClaw[metric]),
   }));
 }
 
+function registrySurfaceCount(value) {
+  return Array.isArray(value) ? value.length : Number(value ?? 0);
+}
+
 function commandWall(profile, commandId) {
   return profile.commands.find((command) => command.id === commandId)?.wallMs?.median ?? 0;
 }

package/src/prune-workspace-dev-deps-cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "./json-file.js";
 import path from "node:path";
 
 const packageJsonPath = path.resolve(process.cwd(), "package.json");
@@ -19,5 +20,5 @@ if (packageJson.devDependencies && Object.keys(packageJson.devDependencies).leng
 }
 
 if (changed) {
-  await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+  await writeJsonFileAtomic(packageJsonPath, packageJson);
 }

package/src/report.js

@@ -450,6 +450,7 @@ function emptyFixtureReport(fixture) {
     registrations: [],
     manifestContracts: [],
     sdkImports: [],
+    sdkDeprecations: [],
     sourceFiles: [],
     manifestFiles: [],
     packageFiles: [],

package/src/sdk-mock.js

@@ -273,7 +273,10 @@ export async function createMockSdkPackage(rootDir, options = {}) {
     if (specifier === "openclaw/plugin-sdk") {
       continue;
     }
-    const relative = specifier.slice("openclaw/plugin-sdk/".length);
+    const relative = safePluginSdkSubpath(specifier.slice("openclaw/plugin-sdk/".length));
+    if (!relative) {
+      continue;
+    }
     if (mockSdkSubpathExports[relative]) {
       continue;
     }
@@ -443,7 +446,12 @@ export async function resolve(specifier, context, nextResolve) {
     return moduleUrl(path.join(pluginSdkDir, "index.js"));
   }
   if (specifier.startsWith("openclaw/plugin-sdk/")) {
-    const subpath = specifier.slice("openclaw/plugin-sdk/".length);
+    const subpath = safePluginSdkSubpath(specifier.slice("openclaw/plugin-sdk/".length));
+    if (!subpath) {
+      throw Object.assign(new Error(\`invalid OpenClaw plugin SDK subpath: \${specifier}\`), {
+        code: "ERR_INVALID_MODULE_SPECIFIER",
+      });
+    }
     return moduleUrl(path.join(pluginSdkDir, \`\${subpath}.js\`));
   }
   if (externalMap.has(specifier)) {
@@ -514,9 +522,25 @@ function isMockableBareSpecifier(specifier) {
     !specifier.startsWith("data:") &&
     !specifier.startsWith("file:");
 }
+
+function safePluginSdkSubpath(value) {
+  const normalized = path.posix.normalize(String(value).replaceAll("\\\\", "/"));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) {
+    return null;
+  }
+  return normalized;
+}
 `;
 }
 
+function safePluginSdkSubpath(value) {
+  const normalized = path.posix.normalize(String(value).replaceAll("\\", "/"));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) {
+    return null;
+  }
+  return normalized;
+}
+
 function dynamicMockModuleSource(exportNames, options = {}) {
   const names = new Set([...exportNames].filter(isValidExportName));
   if (options.zod) {
@@ -530,6 +554,9 @@ export default ${options.zod ? "createZNamespace()" : 'createMockValue("default"
 }
 
 function externalMockModuleSource(specifier, exportNames) {
+  if (specifier === "@larksuiteoapi/node-sdk") {
+    return larkSdkMockModuleSource(exportNames);
+  }
   const names = new Set([...exportNames].filter(isValidExportName));
   if (specifier === "zod") {
     addZodExports(names);
@@ -537,6 +564,52 @@ function externalMockModuleSource(specifier, exportNames) {
   return dynamicMockModuleSource(names, { zod: specifier === "zod" });
 }
 
+function larkSdkMockModuleSource(exportNames) {
+  const larkExports = new Set([
+    "AppType",
+    "Client",
+    "Domain",
+    "EventDispatcher",
+    "LoggerLevel",
+    "WSClient",
+    ...exportNames,
+  ]);
+  larkExports.delete("defaultHttpInstance");
+  return `${genericMockRuntimeSource()}
+const requestInterceptors = {
+  handlers: [],
+  use(handler) {
+    this.handlers.push(handler);
+    return this.handlers.length - 1;
+  },
+};
+
+export const defaultHttpInstance = {
+  interceptors: {
+    request: requestInterceptors,
+    response: {
+      handlers: [],
+      use(handler) {
+        this.handlers.push(handler);
+        return this.handlers.length - 1;
+      },
+    },
+  },
+  request: createMockValue("defaultHttpInstance.request"),
+  get: createMockValue("defaultHttpInstance.get"),
+  post: createMockValue("defaultHttpInstance.post"),
+  put: createMockValue("defaultHttpInstance.put"),
+  patch: createMockValue("defaultHttpInstance.patch"),
+  delete: createMockValue("defaultHttpInstance.delete"),
+  head: createMockValue("defaultHttpInstance.head"),
+  options: createMockValue("defaultHttpInstance.options"),
+};
+${[...larkExports].filter(isValidExportName).map(genericExportStatement).join("\n")}
+
+export default createMockValue("default");
+`;
+}
+
 function addZodExports(names) {
   for (const name of ["z", "any", "array", "boolean", "enum", "literal", "number", "object", "record", "string", "unknown"]) {
     names.add(name);

package/src/workspace-plan.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
@@ -229,13 +229,13 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
 
   steps.push({
     kind: "prepare",
-    command: `mkdir -p ${workspacePath} && rsync -a --delete ${packageDir}/ ${workspacePath}/`,
+    command: `mkdir -p ${shellQuote(workspacePath)} && rsync -a --delete ${shellQuote(`${packageDir}/`)} ${shellQuote(`${workspacePath}/`)}`,
     cwd: repoRelative("."),
     reason: "copy fixture package into an isolated mutable workspace",
   });
   steps.push({
     kind: "prepare-artifacts",
-    command: `mkdir -p ${resultPath}`,
+    command: `mkdir -p ${shellQuote(resultPath)}`,
     cwd: repoRelative("."),
     reason: "create a stable result directory for capture and synthetic probe artifacts",
   });
@@ -243,7 +243,7 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
   if (requiredCapabilities.includes("target-openclaw-link")) {
     steps.push({
       kind: "link-openclaw",
-      command: `${packageManager} pkg set dependencies.openclaw="file:${targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath)}"`,
+      command: `${shellQuote(packageManager)} pkg set ${shellQuote(`dependencies.openclaw=file:${targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath)}`)}`,
       cwd: workspacePath,
       reason: "link the plugin's openclaw peer dependency to the target checkout under test",
     });
@@ -253,7 +253,7 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
     if (hasWorkspaceProtocolDevDependencies(packageJson)) {
       steps.push({
         kind: "prune-dev-workspace-deps",
-        command: `node ${helperScript(settings, workspacePath, settings.pruneWorkspaceDevDepsScript, "prune-workspace-dev-deps-cli.js")}`,
+        command: `node ${shellQuote(helperScript(settings, workspacePath, settings.pruneWorkspaceDevDepsScript, "prune-workspace-dev-deps-cli.js"))}`,
         cwd: workspacePath,
         reason: "remove workspace: devDependencies from the isolated runtime install; the mock SDK supplies OpenClaw host imports",
       });
@@ -361,6 +361,7 @@ function requiredCapabilitiesFor(entrypoint, packageSummary = {}) {
     }
     if (blocker.code === "build-required") {
       capabilities.add("build");
+      capabilities.add("dependency-install");
     }
     if (blocker.code === "ts-loader-required") {
       capabilities.add("ts-loader");
@@ -453,35 +454,35 @@ function installCommand(packageManager) {
 function auditCommand(settings, packageManager, fixtureId, workspacePath) {
   const output = workspaceRelativeArtifactPath(settings, fixtureId, workspacePath, "package-audit.json");
   if (packageManager === "npm") {
-    return `npm audit --json > ${output} || true`;
+    return `npm audit --json > ${shellQuote(output)} || true`;
   }
   if (packageManager === "pnpm") {
-    return `pnpm audit --json > ${output} || true`;
+    return `pnpm audit --json > ${shellQuote(output)} || true`;
   }
   if (packageManager === "yarn") {
-    return `yarn npm audit --json > ${output} || true`;
+    return `yarn npm audit --json > ${shellQuote(output)} || true`;
   }
   if (packageManager === "bun") {
-    return `bun audit --json > ${output} || true`;
+    return `bun audit --json > ${shellQuote(output)} || true`;
   }
-  return `${packageManager} audit --json > ${output} || true`;
+  return `${shellQuote(packageManager)} audit --json > ${shellQuote(output)} || true`;
 }
 
 function runCommand(packageManager, script) {
   if (packageManager === "npm") {
-    return `npm run ${script}`;
+    return `npm run ${shellQuote(script)}`;
   }
-  return `${packageManager} run ${script}`;
+  return `${shellQuote(packageManager)} run ${shellQuote(script)}`;
 }
 
 function captureCommand(settings, fixtureId, entrypoint, workspacePath) {
   const script = helperScript(settings, workspacePath, settings.captureScript, "capture-cli.js");
-  return `${settings.optInEnv} node ${script} ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture")}`;
+  return `${settings.optInEnv} node ${shellQuote(script)} ${shellQuote(entrypoint.specifier)} --mock-sdk --output ${shellQuote(workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture"))}`;
 }
 
 function syntheticProbeCommand(settings, fixtureId, entrypoint, workspacePath) {
   const script = helperScript(settings, workspacePath, settings.syntheticProbeScript, "synthetic-probes-cli.js");
-  return `${settings.optInEnv} node ${script} --entrypoint ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic")}`;
+  return `${settings.optInEnv} node ${shellQuote(script)} --entrypoint ${shellQuote(entrypoint.specifier)} --mock-sdk --output ${shellQuote(workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic"))}`;
 }
 
 function helperScript(settings, workspacePath, configuredScript, helperFileName) {
@@ -526,6 +527,14 @@ function auditArtifactPath(settings, fixtureId) {
   return posixJoin(settings.resultsRoot, fixtureId, "package-audit.json");
 }
 
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@%+-]+$/u.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
 function markdownTable(rows, headers) {
   return renderPaddedMarkdownTable(rows, headers);
 }