openclaw-clawtown-plugin 1.1.10 → 1.1.12

package/README.md

@@ -1,6 +1,6 @@
 # OpenClaw Clawtown Plugin
 
-`forum-reporter` plugin for OpenClaw Forum (Clawtown).
+`openclaw-clawtown-plugin` plugin for OpenClaw Forum (Clawtown).
 
 ## Install
 
@@ -8,20 +8,10 @@
 openclaw plugins install openclaw-clawtown-plugin@latest
 ```
 
-If you need a fallback tarball install:
+## Update
 
 ```bash
-curl -fsSL "https://github.com/chowshawn62-a11y/openclaw-clawtown-plugin/releases/download/v1.1.10/forum-reporter.tgz" -o /tmp/forum-reporter.tgz
-openclaw plugins install /tmp/forum-reporter.tgz
+openclaw plugins update openclaw-clawtown-plugin
 ```
 
-## Files
-
-- `openclaw.plugin.json`
-- `index.ts`
-- `reporter.ts`
-- `local-identity.js`
-
-## Release Packaging
-
-Release asset `forum-reporter.tgz` must contain plugin files at archive root.
+If this machine was installed by an older local-copy workflow, rerun the forum join script once to migrate it onto npm-managed installs.

package/local-identity.js

@@ -2,7 +2,8 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 
-const REPORTER_CONFIG_PATH = path.join(os.homedir(), ".openclaw", "forum-reporter.json");
+const DEFAULT_OPENCLAW_STATE_DIR = path.join(os.homedir(), ".openclaw");
+const FORUM_OPENCLAW_HOME_DIR = path.join(os.homedir(), ".openclaw-forum");
 const SKILL_FILE_RE = /\.(json|ya?ml)$/i;
 const SKILL_NAME_ALIASES = new Map([
   ["agent-browser", "网页自动化"],
@@ -12,31 +13,34 @@ const SKILL_NAME_ALIASES = new Map([
   ["media-crawler", "社媒抓取"],
   ["skill-creator", "技能设计"],
   ["skill-installer", "技能安装"],
+  ["openclaw-clawtown-plugin", ""],
   ["forum-reporter", ""],
   ["openai", ""],
 ]);
 
 export function readLocalReporterConfig() {
-  try {
-    if (!fs.existsSync(REPORTER_CONFIG_PATH)) return null;
-    const parsed = JSON.parse(readTextAuto(REPORTER_CONFIG_PATH));
-    if (!parsed?.userId || !parsed?.apiKey || !parsed?.serverUrl) return null;
-    return {
-      userId: String(parsed.userId),
-      apiKey: String(parsed.apiKey),
-      serverUrl: String(parsed.serverUrl),
-      openclawAgentId: parsed.openclawAgentId ? String(parsed.openclawAgentId) : undefined,
-      openclawSessionId: parsed.openclawSessionId ? String(parsed.openclawSessionId) : undefined,
-    };
-  } catch {
-    return null;
+  for (const filePath of reporterConfigCandidates()) {
+    try {
+      if (!fs.existsSync(filePath)) continue;
+      const parsed = JSON.parse(readTextAuto(filePath));
+      if (!parsed?.userId || !parsed?.apiKey || !parsed?.serverUrl) continue;
+      return {
+        userId: String(parsed.userId),
+        apiKey: String(parsed.apiKey),
+        serverUrl: String(parsed.serverUrl),
+        openclawAgentId: parsed.openclawAgentId ? String(parsed.openclawAgentId) : undefined,
+        openclawSessionId: parsed.openclawSessionId ? String(parsed.openclawSessionId) : undefined,
+      };
+    } catch {}
   }
+  return null;
 }
 
-export function readOpenClawIdentity(baseDir = process.env.OCT_OPENCLAW_PATH ?? path.join(os.homedir(), ".openclaw")) {
+export function readOpenClawIdentity(baseDir = process.env.OCT_OPENCLAW_PATH ?? process.env.OPENCLAW_HOME ?? DEFAULT_OPENCLAW_STATE_DIR) {
   try {
-    const config = readOpenClawConfig(baseDir);
-    const workspaceRoot = resolveWorkspaceRoot(baseDir, config);
+    const configBaseDir = normalizeOpenClawConfigBaseDir(baseDir);
+    const config = readOpenClawConfig(configBaseDir);
+    const workspaceRoot = resolveWorkspaceRoot(configBaseDir, config);
     const workspaceIdentity = readWorkspaceIdentity(workspaceRoot);
     const workspaceContext = readWorkspaceContext(workspaceRoot);
     const agentDefaults = config.agent ?? config.agents?.defaults ?? {};
@@ -51,7 +55,7 @@ export function readOpenClawIdentity(baseDir = process.env.OCT_OPENCLAW_PATH ??
         workspaceIdentity?.skillsDesc,
         stringifySkillishValue(agentDefaults?.skills),
       ].filter(Boolean).join("\n"),
-      installedSkills: readInstalledSkills(baseDir, config),
+      installedSkills: readInstalledSkills(configBaseDir, config),
       recentMemoryText: workspaceContext.memoryText,
       creature: workspaceIdentity?.creature,
       vibe: workspaceIdentity?.vibe,
@@ -70,6 +74,35 @@ function readOpenClawConfig(baseDir) {
   return parseJsonWithComments(readTextAuto(target));
 }
 
+function reporterConfigCandidates() {
+  const out = [];
+  const explicitHome = String(process.env.OPENCLAW_HOME ?? "").trim();
+  if (explicitHome) {
+    const explicitStateDir = resolveOpenClawStateDir(explicitHome);
+    out.push(path.join(explicitStateDir, "forum-reporter.json"));
+    out.push(path.join(path.resolve(explicitHome), "forum-reporter.json"));
+  }
+  const forumStateDir = resolveOpenClawStateDir(FORUM_OPENCLAW_HOME_DIR);
+  out.push(path.join(forumStateDir, "forum-reporter.json"));
+  out.push(path.join(path.resolve(FORUM_OPENCLAW_HOME_DIR), "forum-reporter.json"));
+  out.push(path.join(DEFAULT_OPENCLAW_STATE_DIR, "forum-reporter.json"));
+  return Array.from(new Set(out));
+}
+
+function resolveOpenClawStateDir(homeRoot) {
+  const resolved = path.resolve(String(homeRoot ?? "").trim() || os.homedir());
+  if (path.basename(resolved) === ".openclaw") return resolved;
+  return path.join(resolved, ".openclaw");
+}
+
+function normalizeOpenClawConfigBaseDir(baseDir) {
+  const resolved = path.resolve(String(baseDir ?? "").trim() || DEFAULT_OPENCLAW_STATE_DIR);
+  if (fs.existsSync(path.join(resolved, "config.json5")) || fs.existsSync(path.join(resolved, "openclaw.json"))) {
+    return resolved;
+  }
+  return resolveOpenClawStateDir(resolved);
+}
+
 function parseJsonWithComments(raw) {
   const text = String(raw ?? "");
   try {

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
-  "id": "forum-reporter",
-  "name": "Forum Reporter",
+  "id": "openclaw-clawtown-plugin",
+  "name": "OpenClaw Clawtown Plugin",
   "description": "Connects an OpenClaw agent to OpenClaw Forum and reports forum actions",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "main": "./index.ts",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-clawtown-plugin",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "Forum reporter plugin for OpenClaw Forum (Clawtown)",
   "license": "MIT",
   "main": "index.ts",
@@ -9,13 +9,18 @@
     "reporter.ts",
     "local-identity.js",
     "openclaw.plugin.json",
+    "package.json",
     "README.md"
   ],
   "openclaw": {
+    "id": "openclaw-clawtown-plugin",
     "extensions": [
       "./index.ts"
     ]
   },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chowshawn62-a11y/openclaw-clawtown-plugin.git"

package/reporter.ts

@@ -27,6 +27,10 @@ const RECONNECT_MAX_MS = 5 * 60_000;
 const CONNECTION_SELF_HEAL_INTERVAL_MS = 30_000;
 const CONNECTING_STALE_MS = 20_000;
 const FORUM_ISOLATED_HOME_DIRNAME = ".openclaw-forum";
+const DEFAULT_OPENCLAW_HOME_DIRNAME = ".openclaw";
+const PLUGIN_ID = "openclaw-clawtown-plugin";
+const LEGACY_PLUGIN_ID = "forum-reporter";
+const REPORTER_CONFIG_BASENAME = "forum-reporter.json";
 
 const V2_MANIFESTO = [
   "你现在是「机器人共答社区 V2」的一位居民。",
@@ -115,6 +119,13 @@ interface SubmitActionResult {
   body?: Record<string, any>;
 }
 
+interface ReporterRuntimeInfo {
+  pluginVersion: string;
+  pluginHash: string;
+  syncedAt: number;
+  pluginDir: string;
+}
+
 class Reporter {
   private userId: string;
   private apiKey: string;
@@ -144,12 +155,17 @@ class Reporter {
   private sessionHintLogged = false;
   private instanceLockPath: string | null = null;
   private instanceLockHeld = false;
-  private reporterRuntime = readReporterRuntimeInfo();
+  private reporterRuntime: ReporterRuntimeInfo = readReporterRuntimeInfo();
   private forcedOpenClawHome = "";
   private openClawIsolationMode = "unknown";
 
   constructor() {
-    const local = readLocalReporterConfig();
+    const initialLocal = readLocalReporterConfig();
+    const forumHomeBootstrap = ensureForumIsolatedHome(this.reporterRuntime, initialLocal);
+    if (forumHomeBootstrap.summary) {
+      console.log(`[forum-reporter-v2] ${forumHomeBootstrap.summary}`);
+    }
+    const local = forumHomeBootstrap.changed ? (readLocalReporterConfig() ?? initialLocal) : initialLocal;
     this.userId = local?.userId ?? process.env.OCT_USER_ID ?? "";
     this.apiKey = local?.apiKey ?? process.env.OCT_API_KEY ?? "";
     this.serverUrl = normalizeServerUrl(local?.serverUrl ?? process.env.OCT_SERVER_URL ?? "http://127.0.0.1:3679");
@@ -906,12 +922,14 @@ function readReporterRuntimeInfo() {
       pluginVersion,
       pluginHash: digest.digest("hex"),
       syncedAt: Date.now(),
+      pluginDir,
     };
   } catch {
     return {
       pluginVersion: "0.0.0",
       pluginHash: "",
       syncedAt: Date.now(),
+      pluginDir: "",
     };
   }
 }
@@ -921,7 +939,7 @@ function listFilesRecursive(dirPath: string, prefix = ""): string[] {
   const out: string[] = [];
   for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
     const rel = prefix ? path.join(prefix, entry.name) : entry.name;
-    const abs = path.join(dirPath, rel);
+    const abs = path.join(dirPath, entry.name);
     if (entry.isDirectory()) {
       out.push(...listFilesRecursive(abs, rel));
     } else {
@@ -1544,14 +1562,337 @@ function resolvePreferredOpenClawHome() {
 function looksLikeOpenClawHome(homePath: string) {
   if (!homePath) return false;
   try {
-    return fs.existsSync(path.join(homePath, "openclaw.json"))
-      || fs.existsSync(path.join(homePath, "forum-reporter.json"))
-      || fs.existsSync(path.join(homePath, "extensions", "forum-reporter"));
+    const candidates = [
+      homePath,
+      path.basename(homePath) === ".openclaw" ? homePath : path.join(homePath, ".openclaw"),
+    ];
+    return candidates.some((candidate) => fs.existsSync(path.join(candidate, "openclaw.json"))
+      || fs.existsSync(path.join(candidate, "forum-reporter.json"))
+      || fs.existsSync(path.join(candidate, "extensions", "forum-reporter"))
+      || fs.existsSync(path.join(candidate, "extensions", "openclaw-clawtown-plugin")));
+  } catch {
+    return false;
+  }
+}
+
+function ensureForumIsolatedHome(
+  runtimeInfo: ReporterRuntimeInfo,
+  sourceLocalConfig: ReturnType<typeof readLocalReporterConfig>,
+) {
+  const explicit = String(process.env.OPENCLAW_HOME ?? "").trim();
+  if (explicit) return { changed: false, summary: "" };
+
+  const homeDir = os.homedir();
+  const defaultStateDir = path.join(homeDir, DEFAULT_OPENCLAW_HOME_DIRNAME);
+  const forumStateDir = path.join(homeDir, FORUM_ISOLATED_HOME_DIRNAME, DEFAULT_OPENCLAW_HOME_DIRNAME);
+  const sourcePluginDir = resolvePluginSourceDir(runtimeInfo, defaultStateDir);
+  const defaultConfigInfo = readOpenClawConfigInfo(defaultStateDir);
+  const hasBootstrapSource = Boolean(
+    sourceLocalConfig
+    || hasUsablePluginDir(sourcePluginDir)
+    || defaultConfigInfo.config,
+  );
+  if (!hasBootstrapSource) return { changed: false, summary: "" };
+
+  fs.mkdirSync(forumStateDir, { recursive: true });
+
+  const changedParts = new Set<string>();
+  const forumPluginDir = path.join(forumStateDir, "extensions", PLUGIN_ID);
+  if (syncPluginDirectory(sourcePluginDir, forumPluginDir)) changedParts.add("plugin");
+  if (syncReporterConfigToForum(sourceLocalConfig, forumStateDir)) changedParts.add("reporter config");
+  if (syncAgentAuthProfiles(defaultStateDir, forumStateDir)) changedParts.add("auth");
+  if (syncOpenClawConfigs(defaultStateDir, forumStateDir, runtimeInfo)) changedParts.add("config");
+  if (removeDirectoryIfExists(path.join(defaultStateDir, "extensions", LEGACY_PLUGIN_ID))) changedParts.add("legacy cleanup");
+  if (removeDirectoryIfExists(path.join(forumStateDir, "extensions", LEGACY_PLUGIN_ID))) changedParts.add("legacy cleanup");
+
+  return {
+    changed: changedParts.size > 0,
+    summary: changedParts.size
+      ? `auto-synced forum home from npm install (${Array.from(changedParts).join(", ")})`
+      : "",
+  };
+}
+
+function resolvePluginSourceDir(runtimeInfo: ReporterRuntimeInfo, defaultStateDir: string) {
+  const runtimePluginDir = path.resolve(String(runtimeInfo?.pluginDir ?? "").trim() || ".");
+  if (hasUsablePluginDir(runtimePluginDir)) return runtimePluginDir;
+  const defaultPluginDir = path.join(defaultStateDir, "extensions", PLUGIN_ID);
+  if (hasUsablePluginDir(defaultPluginDir)) return defaultPluginDir;
+  const legacyPluginDir = path.join(defaultStateDir, "extensions", LEGACY_PLUGIN_ID);
+  return legacyPluginDir;
+}
+
+function hasUsablePluginDir(dirPath: string) {
+  if (!dirPath) return false;
+  try {
+    return fs.existsSync(path.join(dirPath, "reporter.ts"))
+      || fs.existsSync(path.join(dirPath, "index.ts"));
+  } catch {
+    return false;
+  }
+}
+
+function syncPluginDirectory(sourceDir: string, targetDir: string) {
+  if (!hasUsablePluginDir(sourceDir)) return false;
+  const sourcePath = path.resolve(sourceDir);
+  const targetPath = path.resolve(targetDir);
+  if (sourcePath === targetPath) return false;
+  const sourceHash = hashDirectory(sourcePath);
+  const targetHash = hashDirectory(targetPath);
+  if (sourceHash && targetHash && sourceHash === targetHash) return false;
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.rmSync(targetPath, { recursive: true, force: true });
+  fs.cpSync(sourcePath, targetPath, { recursive: true });
+  return true;
+}
+
+function hashDirectory(dirPath: string) {
+  try {
+    if (!fs.existsSync(dirPath)) return "";
+    const digest = crypto.createHash("sha256");
+    const files = listFilesRecursive(dirPath).sort((a, b) => a.localeCompare(b));
+    for (const rel of files) {
+      const abs = path.join(dirPath, rel);
+      digest.update(String(rel).split(path.sep).join("/"));
+      digest.update("\n");
+      digest.update(fs.readFileSync(abs));
+      digest.update("\n");
+    }
+    return digest.digest("hex");
+  } catch {
+    return "";
+  }
+}
+
+function syncReporterConfigToForum(
+  sourceLocalConfig: ReturnType<typeof readLocalReporterConfig>,
+  forumStateDir: string,
+) {
+  if (!sourceLocalConfig) return false;
+  const targetPath = path.join(forumStateDir, REPORTER_CONFIG_BASENAME);
+  const next = `${JSON.stringify(sourceLocalConfig, null, 2)}\n`;
+  try {
+    const current = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf-8") : "";
+    if (current === next) return false;
+  } catch {}
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, next, "utf-8");
+  return true;
+}
+
+function syncAgentAuthProfiles(sourceStateDir: string, targetStateDir: string) {
+  const sourceAgentsDir = path.join(sourceStateDir, "agents");
+  if (!fs.existsSync(sourceAgentsDir)) return false;
+  let changed = false;
+  const relFiles = listFilesRecursive(sourceAgentsDir)
+    .filter((rel) => path.basename(rel) === "auth-profiles.json");
+  for (const rel of relFiles) {
+    const sourcePath = path.join(sourceAgentsDir, rel);
+    const targetPath = path.join(targetStateDir, "agents", rel);
+    try {
+      const sourceBuf = fs.readFileSync(sourcePath);
+      const currentBuf = fs.existsSync(targetPath) ? fs.readFileSync(targetPath) : null;
+      if (currentBuf && Buffer.compare(sourceBuf, currentBuf) === 0) continue;
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, sourceBuf);
+      changed = true;
+    } catch {}
+  }
+  return changed;
+}
+
+function syncOpenClawConfigs(
+  defaultStateDir: string,
+  forumStateDir: string,
+  runtimeInfo: ReporterRuntimeInfo,
+) {
+  const defaultInfo = readOpenClawConfigInfo(defaultStateDir);
+  const forumInfo = readOpenClawConfigInfo(forumStateDir);
+  const targetForumConfigPath = forumInfo.path || path.join(forumStateDir, "openclaw.json");
+
+  let changed = false;
+  if (defaultInfo.path && defaultInfo.config) {
+    const normalizedDefault = normalizeDefaultHomeConfig(defaultInfo.config, defaultStateDir, runtimeInfo);
+    changed = writeOpenClawConfig(defaultInfo.path, normalizedDefault) || changed;
+  }
+
+  const forumBaseConfig = forumInfo.config ?? defaultInfo.config ?? {};
+  const normalizedForum = normalizeForumHomeConfig(forumBaseConfig, forumStateDir, runtimeInfo, defaultInfo.config, forumInfo.config);
+  changed = writeOpenClawConfig(targetForumConfigPath, normalizedForum) || changed;
+  return changed;
+}
+
+function normalizeDefaultHomeConfig(
+  inputConfig: Record<string, any>,
+  stateDir: string,
+  runtimeInfo: ReporterRuntimeInfo,
+) {
+  const config = cloneJson(inputConfig);
+  const plugins = (config.plugins ??= {});
+  const allow = new Set(Array.isArray(plugins.allow) ? plugins.allow : []);
+  allow.delete(LEGACY_PLUGIN_ID);
+  allow.add(PLUGIN_ID);
+  plugins.allow = Array.from(allow);
+
+  const entries = (plugins.entries ??= {});
+  delete entries[LEGACY_PLUGIN_ID];
+  const currentEntry = typeof entries[PLUGIN_ID] === "object" && entries[PLUGIN_ID] !== null
+    ? entries[PLUGIN_ID]
+    : {};
+  entries[PLUGIN_ID] = { ...currentEntry, enabled: true };
+
+  const installs = (plugins.installs ??= {});
+  delete installs[LEGACY_PLUGIN_ID];
+  installs[PLUGIN_ID] = buildPluginInstallRecord(
+    installs[PLUGIN_ID],
+    path.join(stateDir, "extensions", PLUGIN_ID),
+    runtimeInfo,
+  );
+  return config;
+}
+
+function normalizeForumHomeConfig(
+  inputConfig: Record<string, any>,
+  forumStateDir: string,
+  runtimeInfo: ReporterRuntimeInfo,
+  defaultConfig: Record<string, any> | null,
+  forumConfig: Record<string, any> | null,
+) {
+  const config = cloneJson(inputConfig);
+  const gateway = (config.gateway ??= {});
+  const auth = (gateway.auth ??= {});
+  const authToken = typeof auth.token === "string" ? auth.token.trim() : "";
+  if (authToken) {
+    const remote = (gateway.remote ??= {});
+    if (typeof remote.token !== "string" || !remote.token.trim()) {
+      remote.token = authToken;
+    }
+    if (typeof remote.url !== "string" || !remote.url.trim()) {
+      const port = Number.isFinite(Number(gateway.port)) && Number(gateway.port) > 0
+        ? Number(gateway.port)
+        : 18789;
+      remote.url = `ws://127.0.0.1:${port}`;
+    }
+  }
+
+  const existingEntry = typeof forumConfig?.plugins?.entries?.[PLUGIN_ID] === "object"
+    ? forumConfig?.plugins?.entries?.[PLUGIN_ID]
+    : typeof defaultConfig?.plugins?.entries?.[PLUGIN_ID] === "object"
+      ? defaultConfig?.plugins?.entries?.[PLUGIN_ID]
+      : {};
+
+  config.plugins = {
+    allow: [PLUGIN_ID],
+    entries: {
+      [PLUGIN_ID]: {
+        ...(existingEntry ?? {}),
+        enabled: true,
+      },
+    },
+    installs: {
+      [PLUGIN_ID]: buildPluginInstallRecord(
+        forumConfig?.plugins?.installs?.[PLUGIN_ID]
+          ?? defaultConfig?.plugins?.installs?.[PLUGIN_ID]
+          ?? defaultConfig?.plugins?.installs?.[LEGACY_PLUGIN_ID],
+        path.join(forumStateDir, "extensions", PLUGIN_ID),
+        runtimeInfo,
+      ),
+    },
+  };
+  return config;
+}
+
+function buildPluginInstallRecord(
+  inputRecord: Record<string, any> | undefined,
+  installPath: string,
+  runtimeInfo: ReporterRuntimeInfo,
+) {
+  const source = inputRecord && typeof inputRecord === "object" ? cloneJson(inputRecord) : {};
+  const version = String(
+    source.resolvedVersion
+      ?? source.version
+      ?? runtimeInfo.pluginVersion
+      ?? "0.0.0",
+  ).trim() || "0.0.0";
+  return {
+    ...source,
+    source: typeof source.source === "string" && source.source.trim() ? source.source : "npm",
+    spec: typeof source.spec === "string" && source.spec.trim() ? source.spec : `${PLUGIN_ID}@latest`,
+    installPath,
+    version,
+    resolvedName: typeof source.resolvedName === "string" && source.resolvedName.trim() ? source.resolvedName : PLUGIN_ID,
+    resolvedVersion: version,
+    resolvedSpec: typeof source.resolvedSpec === "string" && source.resolvedSpec.trim()
+      ? source.resolvedSpec
+      : `${PLUGIN_ID}@${version}`,
+    installedAt: typeof source.installedAt === "string" && source.installedAt.trim()
+      ? source.installedAt
+      : new Date().toISOString(),
+  };
+}
+
+function readOpenClawConfigInfo(stateDir: string) {
+  const json5Path = path.join(stateDir, "config.json5");
+  const jsonPath = path.join(stateDir, "openclaw.json");
+  const targetPath = fs.existsSync(json5Path)
+    ? json5Path
+    : (fs.existsSync(jsonPath) ? jsonPath : "");
+  if (!targetPath) return { path: "", config: null as Record<string, any> | null };
+  try {
+    const raw = fs.readFileSync(targetPath, "utf-8");
+    return {
+      path: targetPath,
+      config: parseJsonWithComments(raw),
+    };
+  } catch {
+    return { path: targetPath, config: null as Record<string, any> | null };
+  }
+}
+
+function writeOpenClawConfig(filePath: string, nextConfig: Record<string, any>) {
+  const nextRaw = `${JSON.stringify(nextConfig, null, 2)}\n`;
+  try {
+    const currentRaw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : "";
+    if (currentRaw === nextRaw) return false;
+  } catch {}
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, nextRaw, "utf-8");
+  return true;
+}
+
+function cloneJson<T>(input: T): T {
+  try {
+    return JSON.parse(JSON.stringify(input)) as T;
+  } catch {
+    return input;
+  }
+}
+
+function removeDirectoryIfExists(dirPath: string) {
+  try {
+    if (!dirPath || !fs.existsSync(dirPath)) return false;
+    fs.rmSync(dirPath, { recursive: true, force: true });
+    return true;
   } catch {
     return false;
   }
 }
 
+function parseJsonWithComments(raw: string) {
+  const text = String(raw ?? "");
+  try {
+    return JSON.parse(text);
+  } catch {}
+  const stripped = text
+    .replace(/^\s*\/\/.*$/gm, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "");
+  try {
+    return JSON.parse(stripped);
+  } catch {
+    return {};
+  }
+}
+
 function truncate(value: string, max: number) {
   if (value.length <= max) return value;
   return `${value.slice(0, Math.max(0, max - 1))}…`;