@bitsocial/bitsocial-cli 0.19.45 → 0.19.47

package/dist/cli/commands/logs.js

@@ -27,6 +27,16 @@ export default class Logs extends Command {
         logPath: Flags.directory({
             description: "Specify the directory containing log files",
             required: false
+        }),
+        stdout: Flags.boolean({
+            description: "Show only stdout log entries",
+            default: false,
+            exclusive: ["stderr"]
+        }),
+        stderr: Flags.boolean({
+            description: "Show only stderr log entries (output of pkc-logger library)",
+            default: false,
+            exclusive: ["stdout"]
         })
     };
     static examples = [
@@ -35,7 +45,10 @@ export default class Logs extends Command {
         "bitsocial logs -n 50",
         "bitsocial logs --since 5m",
         "bitsocial logs --since 2026-01-02T13:23:37Z --until 2026-01-02T14:00:00Z",
-        "bitsocial logs --since 1h -f"
+        "bitsocial logs --since 1h -f",
+        "bitsocial logs --stdout",
+        "bitsocial logs --stderr",
+        "bitsocial logs --stdout -f"
     ];
     async _findLatestLogFile(logPath) {
         let entries;
@@ -76,6 +89,12 @@ export default class Logs extends Command {
             return null;
         return new Date(match[1]);
     }
+    _extractStream(line) {
+        const match = line.match(/^\[\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z\] \[(stdout|stderr)\] /);
+        if (!match)
+            return null;
+        return match[1];
+    }
     _parseLogEntries(content) {
         const lines = content.split("\n");
         const entries = [];
@@ -83,7 +102,8 @@ export default class Logs extends Command {
             const timestamp = this._extractTimestamp(line);
             if (timestamp !== null) {
                 // New timestamped entry
-                entries.push({ timestamp, lines: [line] });
+                const stream = this._extractStream(line);
+                entries.push({ timestamp, stream, lines: [line] });
             }
             else if (entries.length > 0) {
                 // Continuation line — belongs to the previous entry
@@ -91,7 +111,7 @@ export default class Logs extends Command {
             }
             else {
                 // Line before any timestamped entry (legacy/header)
-                entries.push({ timestamp: null, lines: [line] });
+                entries.push({ timestamp: null, stream: null, lines: [line] });
             }
         }
         return entries;
@@ -109,6 +129,9 @@ export default class Logs extends Command {
             return true;
         });
     }
+    _filterByStream(entries, stream) {
+        return entries.filter((entry) => entry.stream === stream);
+    }
     _tailEntries(entries, tailValue) {
         if (tailValue === "all")
             return entries;
@@ -126,33 +149,37 @@ export default class Logs extends Command {
         const latestLogFile = await this._findLatestLogFile(logPath);
         const since = flags.since ? this._parseTimestamp(flags.since) : undefined;
         const until = flags.until ? this._parseTimestamp(flags.until) : undefined;
+        const streamFilter = flags.stdout ? "stdout" : flags.stderr ? "stderr" : undefined;
         if (!flags.follow) {
             const content = await fsPromise.readFile(latestLogFile, "utf-8");
             const entries = this._parseLogEntries(content);
             const filtered = this._filterEntries(entries, since, until);
-            const tailed = this._tailEntries(filtered, flags.tail);
+            const streamFiltered = streamFilter ? this._filterByStream(filtered, streamFilter) : filtered;
+            const tailed = this._tailEntries(streamFiltered, flags.tail);
             const output = tailed.map((e) => e.lines.join("\n")).join("\n");
             if (output)
                 process.stdout.write(output + "\n");
             return;
         }
         // Follow mode: dump existing content (filtered + tailed) then watch for new data
-        const existingContent = await fsPromise.readFile(latestLogFile, "utf-8");
+        let currentLogFile = latestLogFile;
+        const existingContent = await fsPromise.readFile(currentLogFile, "utf-8");
         const entries = this._parseLogEntries(existingContent);
         const filtered = this._filterEntries(entries, since, until);
-        const tailed = this._tailEntries(filtered, flags.tail);
+        const streamFiltered = streamFilter ? this._filterByStream(filtered, streamFilter) : filtered;
+        const tailed = this._tailEntries(streamFiltered, flags.tail);
         const initialOutput = tailed.map((e) => e.lines.join("\n")).join("\n");
         if (initialOutput)
             process.stdout.write(initialOutput + "\n");
-        const stat = await fsPromise.stat(latestLogFile);
+        const stat = await fsPromise.stat(currentLogFile);
         let position = stat.size;
         let pendingBuffer = "";
         // Watch for new data using polling (works across filesystems including Docker volumes)
         const readNewData = async () => {
             try {
-                const currentStat = await fsPromise.stat(latestLogFile);
+                const currentStat = await fsPromise.stat(currentLogFile);
                 if (currentStat.size > position) {
-                    const fd = await fsPromise.open(latestLogFile, "r");
+                    const fd = await fsPromise.open(currentLogFile, "r");
                     const buf = new Uint8Array(currentStat.size - position);
                     const { bytesRead } = await fd.read(buf, 0, buf.length, position);
                     await fd.close();
@@ -166,14 +193,15 @@ export default class Logs extends Command {
                     }
                     pendingBuffer = chunk.slice(lastNewline + 1);
                     const completeText = chunk.slice(0, lastNewline + 1);
-                    if (!since && !until) {
-                        // No time filtering — pass through directly
+                    if (!since && !until && !streamFilter) {
+                        // No filtering — pass through directly
                         process.stdout.write(completeText);
                     }
                     else {
                         const newEntries = this._parseLogEntries(completeText.replace(/\n$/, ""));
                         const filteredNew = this._filterEntries(newEntries, since, until);
-                        const output = filteredNew.map((e) => e.lines.join("\n")).join("\n");
+                        const streamFilteredNew = streamFilter ? this._filterByStream(filteredNew, streamFilter) : filteredNew;
+                        const output = streamFilteredNew.map((e) => e.lines.join("\n")).join("\n");
                         if (output)
                             process.stdout.write(output + "\n");
                     }
@@ -183,14 +211,67 @@ export default class Logs extends Command {
                 // File may have been rotated or deleted
             }
         };
-        fs.watchFile(latestLogFile, { interval: 300 }, readNewData);
+        // Periodically check if a newer log file has appeared (e.g. after daemon restart)
+        const checkForNewLogFile = async () => {
+            try {
+                const newestFile = await this._findLatestLogFile(logPath);
+                if (newestFile === currentLogFile)
+                    return;
+                // Flush any remaining partial line from old file
+                if (pendingBuffer) {
+                    if (!since && !until && !streamFilter) {
+                        process.stdout.write(pendingBuffer + "\n");
+                    }
+                    else {
+                        const pbEntries = this._parseLogEntries(pendingBuffer);
+                        const pbFiltered = this._filterEntries(pbEntries, since, until);
+                        const pbStreamFiltered = streamFilter ? this._filterByStream(pbFiltered, streamFilter) : pbFiltered;
+                        const pbOutput = pbStreamFiltered.map((e) => e.lines.join("\n")).join("\n");
+                        if (pbOutput)
+                            process.stdout.write(pbOutput + "\n");
+                    }
+                }
+                // Switch watchers
+                fs.unwatchFile(currentLogFile, readNewData);
+                currentLogFile = newestFile;
+                pendingBuffer = "";
+                process.stderr.write(`\n--- switched to new log file: ${path.basename(newestFile)} ---\n\n`);
+                // Read and output entire new file content (with filters, no tail limit)
+                const newContent = await fsPromise.readFile(currentLogFile, "utf-8");
+                if (newContent) {
+                    if (!since && !until && !streamFilter) {
+                        process.stdout.write(newContent);
+                    }
+                    else {
+                        const newEntries = this._parseLogEntries(newContent.replace(/\n$/, ""));
+                        const filteredNew = this._filterEntries(newEntries, since, until);
+                        const streamFilteredNew = streamFilter
+                            ? this._filterByStream(filteredNew, streamFilter)
+                            : filteredNew;
+                        const output = streamFilteredNew.map((e) => e.lines.join("\n")).join("\n");
+                        if (output)
+                            process.stdout.write(output + "\n");
+                    }
+                }
+                const newStat = await fsPromise.stat(currentLogFile);
+                position = newStat.size;
+                fs.watchFile(currentLogFile, { interval: 300 }, readNewData);
+            }
+            catch {
+                // Directory listing failed or file disappeared — retry next cycle
+            }
+        };
+        fs.watchFile(currentLogFile, { interval: 300 }, readNewData);
+        const newFileCheckInterval = setInterval(checkForNewLogFile, 3000);
         // Keep the process alive and clean up on exit
         process.on("SIGINT", () => {
-            fs.unwatchFile(latestLogFile, readNewData);
+            clearInterval(newFileCheckInterval);
+            fs.unwatchFile(currentLogFile, readNewData);
             process.exit(0);
         });
         process.on("SIGTERM", () => {
-            fs.unwatchFile(latestLogFile, readNewData);
+            clearInterval(newFileCheckInterval);
+            fs.unwatchFile(currentLogFile, readNewData);
             process.exit(0);
         });
         // Keep process alive

package/dist/cli/commands/update/install.js

@@ -2,6 +2,7 @@ import { Args, Flags, Command } from "@oclif/core";
 import { spawn } from "child_process";
 import tcpPortUsed from "tcp-port-used";
 import { fetchLatestVersion, installGlobal } from "../../../update/npm-registry.js";
+import { fastInstallGlobal } from "../../../update/fast-update.js";
 import { compareVersions } from "../../../update/semver.js";
 import { getAliveDaemonStates } from "../../../common-utils/daemon-state.js";
 import PKC from "@pkcprotocol/pkc-js";
@@ -95,11 +96,25 @@ export default class Install extends Command {
             return;
         }
         this.log(`Installing bitsocial-cli@${targetVersion}...`);
-        try {
-            await installGlobal(targetVersion);
+        let installed = false;
+        if (!flags.force) {
+            try {
+                installed = await fastInstallGlobal(targetVersion, this.config.root, (msg) => this.log(msg));
+            }
+            catch {
+                installed = false;
+            }
         }
-        catch (err) {
-            this.error(`Update failed: ${err.message}`, { exit: 1 });
+        if (!installed) {
+            if (!flags.force) {
+                this.log("Falling back to full install...");
+            }
+            try {
+                await installGlobal(targetVersion);
+            }
+            catch (err) {
+                this.error(`Update failed: ${err.message}`, { exit: 1 });
+            }
         }
         this.log(`Installed bitsocial v${targetVersion} (was v${current}).`);
         // Restart daemons with the new binary
@@ -144,39 +159,60 @@ export default class Install extends Command {
         pkc.on("error", (err) => {
             errors.push(err);
         });
-        await new Promise((resolve, reject) => {
+        await new Promise((resolve) => {
             const timeout = setTimeout(() => {
-                const lastError = errors[errors.length - 1];
-                reject(lastError ?? new Error(`Timed out waiting for RPC server at ${pkcRpcUrl} to respond`));
-            }, 20000);
-            pkc.once("communitieschange", () => {
-                clearTimeout(timeout);
+                pkc.removeListener("communitieschange", handler);
                 resolve();
-            });
+            }, 20000);
+            const handler = () => {
+                if (pkc.communities.length > 0) {
+                    pkc.removeListener("communitieschange", handler);
+                    clearTimeout(timeout);
+                    resolve();
+                }
+            };
+            pkc.on("communitieschange", handler);
         });
         return pkc;
     }
     async _reportCommunityStatus(pkcRpcUrl) {
+        const POLL_INTERVAL_MS = 2000;
+        const TIMEOUT_MS = 120_000;
         let pkc;
         try {
             pkc = await this._connectToRpc(pkcRpcUrl);
-            const communities = pkc.communities;
-            if (communities.length === 0)
+            const communityAddresses = pkc.communities;
+            if (communityAddresses.length === 0)
                 return;
-            const statuses = await Promise.all(communities.map(async (address) => {
-                const community = await pkc.createCommunity({ address });
-                return community.started;
-            }));
-            const startedCount = statuses.filter(Boolean).length;
+            // Create community objects once — they are RPC proxies whose
+            // .started property reflects live daemon state
+            const communities = await Promise.all(communityAddresses.map((address) => pkc.createCommunity({ address })));
             const total = communities.length;
-            if (startedCount === total) {
-                this.log(`  ${startedCount} ${startedCount === 1 ? "community" : "communities"} started.`);
-            }
-            else if (startedCount > 0) {
-                this.log(`  ${startedCount} of ${total} communities started (remaining still loading).`);
-            }
-            else {
-                this.log(`  ${total} ${total === 1 ? "community" : "communities"} in data path (still loading). Check with: bitsocial community list`);
+            const deadline = Date.now() + TIMEOUT_MS;
+            let lastReportedCount = -1;
+            while (true) {
+                const startedCount = communities.filter((c) => c.started === true).length;
+                if (startedCount === total) {
+                    this.log(`  All ${total} ${total === 1 ? "community" : "communities"} started.`);
+                    return;
+                }
+                // Only print a progress update when the count changes
+                if (startedCount !== lastReportedCount) {
+                    if (startedCount > 0) {
+                        this.log(`  ${startedCount} of ${total} communities started...`);
+                    }
+                    lastReportedCount = startedCount;
+                }
+                if (Date.now() >= deadline) {
+                    if (startedCount > 0) {
+                        this.log(`  ${startedCount} of ${total} communities started (remaining still loading).`);
+                    }
+                    else {
+                        this.log(`  ${total} ${total === 1 ? "community" : "communities"} in data path (still loading). Check with: bitsocial community list`);
+                    }
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
             }
         }
         catch {

package/dist/update/fast-update.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Attempt a fast update by downloading only the tarball and reusing node_modules/
+ * and dist/webuis/ from the existing install. Falls back (returns false) if
+ * dependencies changed or any step fails.
+ */
+export declare function fastInstallGlobal(version: string, installRoot: string, log: (msg: string) => void): Promise<boolean>;

package/dist/update/fast-update.js

@@ -0,0 +1,182 @@
+import fs from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { finished as streamFinished } from "node:stream/promises";
+import decompress from "decompress";
+import { runNpmPack, ensureNpmAvailable } from "../challenge-packages/challenge-utils.js";
+import { PACKAGE_NAME } from "./npm-registry.js";
+/**
+ * Attempt a fast update by downloading only the tarball and reusing node_modules/
+ * and dist/webuis/ from the existing install. Falls back (returns false) if
+ * dependencies changed or any step fails.
+ */
+export async function fastInstallGlobal(version, installRoot, log) {
+    const stagingDir = installRoot + ".__fast_update_staging";
+    const backupDir = installRoot + ".__fast_update_backup";
+    // Phase: cleanup leftovers from any interrupted previous fast-update
+    await fs.rm(stagingDir, { recursive: true, force: true });
+    await fs.rm(backupDir, { recursive: true, force: true });
+    let nodeModulesMoved = false;
+    try {
+        // Phase: download tarball
+        await ensureNpmAvailable();
+        await fs.mkdir(stagingDir, { recursive: true });
+        log("Trying fast update...");
+        const tgzPath = await runNpmPack(`${PACKAGE_NAME}@${version}`, stagingDir);
+        // Phase: extract (strip: 1 removes the "package/" prefix in npm tarballs)
+        await decompress(tgzPath, stagingDir, { strip: 1 });
+        await fs.rm(tgzPath);
+        // Phase: compare dependencies
+        const oldPkg = JSON.parse(await fs.readFile(path.join(installRoot, "package.json"), "utf-8"));
+        const newPkg = JSON.parse(await fs.readFile(path.join(stagingDir, "package.json"), "utf-8"));
+        if (JSON.stringify(oldPkg.dependencies) !== JSON.stringify(newPkg.dependencies)) {
+            log("Dependencies changed, falling back to full install.");
+            await fs.rm(stagingDir, { recursive: true, force: true });
+            return false;
+        }
+        // Phase: reuse node_modules from old install (O(1) rename, same filesystem)
+        try {
+            await fs.rename(path.join(installRoot, "node_modules"), path.join(stagingDir, "node_modules"));
+            nodeModulesMoved = true;
+        }
+        catch (err) {
+            if (err.code === "EXDEV") {
+                log("Cross-device rename, falling back to full install.");
+                await fs.rm(stagingDir, { recursive: true, force: true });
+                return false;
+            }
+            throw err;
+        }
+        // Phase: reuse unchanged webuis, download only changed ones
+        const oldWebuis = oldPkg.webuis ?? [];
+        const newWebuis = newPkg.webuis ?? [];
+        const oldWebuisByUrl = new Map(oldWebuis.map((w) => [w.url, w.sha256OfHtmlZip]));
+        // Move the entire dist/webuis/ directory from old install to staging
+        const oldWebuisDir = path.join(installRoot, "dist", "webuis");
+        const newWebuisDir = path.join(stagingDir, "dist", "webuis");
+        let webuisDirMoved = false;
+        try {
+            await fs.access(oldWebuisDir);
+            await fs.rename(oldWebuisDir, newWebuisDir);
+            webuisDirMoved = true;
+        }
+        catch {
+            // webuis dir missing in old install — will create fresh
+        }
+        // Identify which webui entries changed
+        const changedWebuis = newWebuis.filter((w) => oldWebuisByUrl.get(w.url) !== w.sha256OfHtmlZip);
+        if (changedWebuis.length > 0 && webuisDirMoved) {
+            // Delete subdirectories for changed webuis so they get re-downloaded.
+            // We don't know exact dir names, but we can match by repo name from the URL.
+            const existingDirs = await fs.readdir(newWebuisDir, { withFileTypes: true })
+                .catch(() => []);
+            for (const changed of changedWebuis) {
+                const repoName = extractRepoName(changed.url);
+                if (!repoName)
+                    continue;
+                for (const entry of existingDirs) {
+                    if (entry.isDirectory() && entry.name.toLowerCase().includes(repoName.toLowerCase())) {
+                        await fs.rm(path.join(newWebuisDir, entry.name), { recursive: true, force: true });
+                    }
+                }
+            }
+        }
+        // Phase: atomic swap
+        await fs.rename(installRoot, backupDir);
+        await fs.rename(stagingDir, installRoot);
+        nodeModulesMoved = false; // now part of installRoot, no rollback needed
+        // Phase: download changed/missing webuis
+        if (changedWebuis.length > 0 || !webuisDirMoved) {
+            const webuisDir = path.join(installRoot, "dist", "webuis");
+            await fs.mkdir(webuisDir, { recursive: true });
+            const toDownload = !webuisDirMoved ? newWebuis : changedWebuis;
+            if (toDownload.length > 0) {
+                log(`Downloading ${toDownload.length} changed web UI(s)...`);
+                for (const entry of toDownload) {
+                    try {
+                        await downloadWebui(entry, webuisDir, log);
+                    }
+                    catch (err) {
+                        log(`Warning: failed to download ${entry.url}: ${err.message}`);
+                    }
+                }
+            }
+        }
+        // Phase: cleanup backup
+        await fs.rm(backupDir, { recursive: true, force: true });
+        return true;
+    }
+    catch (err) {
+        // Rollback: restore node_modules if we moved it out
+        if (nodeModulesMoved) {
+            try {
+                await fs.rename(path.join(stagingDir, "node_modules"), path.join(installRoot, "node_modules"));
+            }
+            catch {
+                // best-effort
+            }
+        }
+        // If installRoot was renamed to backup but staging didn't land, restore it
+        try {
+            await fs.access(installRoot);
+        }
+        catch {
+            try {
+                await fs.rename(backupDir, installRoot);
+            }
+            catch {
+                // best-effort
+            }
+        }
+        await fs.rm(stagingDir, { recursive: true, force: true });
+        log(`Fast update failed: ${err.message}`);
+        return false;
+    }
+}
+/** Extract repo name from a GitHub release URL (e.g. "seedit" from ".../plebbit/seedit/releases/tag/v0.5.10") */
+function extractRepoName(url) {
+    const match = url.match(/github\.com\/[^/]+\/([^/]+)\/releases\/tag\//);
+    return match?.[1];
+}
+/** Download a single webui entry — mirrors the logic in bin/postinstall.js */
+async function downloadWebui(entry, webuisDir, log) {
+    const match = entry.url.match(/github\.com\/([^/]+\/[^/]+)\/releases\/tag\/(.+)$/);
+    if (!match)
+        throw new Error(`Could not parse GitHub release URL: ${entry.url}`);
+    const [, ownerRepo, tag] = match;
+    const githubToken = process.env["GITHUB_TOKEN"];
+    const headers = {};
+    if (githubToken)
+        headers["authorization"] = `Bearer ${githubToken}`;
+    const releaseReq = await fetch(`https://api.github.com/repos/${ownerRepo}/releases/tags/${tag}`, { headers });
+    if (!releaseReq.ok)
+        throw new Error(`Failed to fetch release ${ownerRepo}@${tag}, status ${releaseReq.status}`);
+    const release = await releaseReq.json();
+    const htmlZipAsset = release.assets.find((asset) => asset.name.includes("html"));
+    if (!htmlZipAsset)
+        throw new Error(`No HTML zip asset in ${ownerRepo}@${tag}`);
+    const zipfilePath = path.join(webuisDir, htmlZipAsset.name);
+    const downloadReq = await fetch(htmlZipAsset["browser_download_url"], { headers });
+    if (!downloadReq.ok || !downloadReq.body)
+        throw new Error(`Failed to download ${htmlZipAsset.name}, status ${downloadReq.status}`);
+    const writer = createWriteStream(zipfilePath);
+    await streamFinished(Readable.fromWeb(downloadReq.body).pipe(writer));
+    writer.close();
+    // Verify SHA-256 checksum
+    const fileBuffer = await fs.readFile(zipfilePath);
+    const actualHash = createHash("sha256").update(fileBuffer).digest("hex");
+    if (actualHash !== entry.sha256OfHtmlZip) {
+        await fs.rm(zipfilePath);
+        throw new Error(`SHA-256 mismatch for ${htmlZipAsset.name}! Expected: ${entry.sha256OfHtmlZip}, Actual: ${actualHash}`);
+    }
+    await decompress(zipfilePath, webuisDir);
+    await fs.rm(zipfilePath);
+    // Rename index.html to prevent access to unconfigured version
+    const extractedDirName = htmlZipAsset.name.replace(".zip", "");
+    const indexPath = path.join(webuisDir, extractedDirName, "index.html");
+    const backupPath = path.join(webuisDir, extractedDirName, "index_backup_no_rpc.html");
+    await fs.rename(indexPath, backupPath);
+    log(`Downloaded ${ownerRepo}@${tag}`);
+}

package/dist/update/npm-registry.d.ts

@@ -1,3 +1,4 @@
+export declare const PACKAGE_NAME = "@bitsocial/bitsocial-cli";
 /** Query npm registry for the latest published version. */
 export declare function fetchLatestVersion(): Promise<string>;
 /** Query npm registry for all published versions (oldest-first). */

package/dist/update/npm-registry.js

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 import { getNpmCliPath, getNpmEnv, ensureNpmAvailable } from "../challenge-packages/challenge-utils.js";
-const PACKAGE_NAME = "@bitsocial/bitsocial-cli";
+export const PACKAGE_NAME = "@bitsocial/bitsocial-cli";
 function runNpmView(args) {
     return new Promise(async (resolve, reject) => {
         const npmCliPath = await getNpmCliPath();

package/dist/util.d.ts

@@ -25,8 +25,13 @@ export declare function getLanIpV4Address(): string | undefined;
 export declare function loadKuboConfigFile(pkcDataPath: string): Promise<any | undefined>;
 export declare function parseMultiAddrKuboRpcToUrl(kuboMultiAddrString: string): Promise<import("url").URL>;
 export declare function parseMultiAddrIpfsGatewayToUrl(ipfsGatewaymultiAddrString: string): Promise<import("url").URL>;
+/** Recursively replaces all `null` values with `undefined`.
+ * Used before calling community.edit() since pkc-js expects `undefined` for removal,
+ * but JSON/CLI input produces `null`. */
+export declare function replaceNullWithUndefined(obj: any): any;
 /**
  * Custom merge function that implements CLI-specific merge behavior.
  * This matches the expected behavior from the test suite.
  */
-export declare function mergeDeep(target: any, source: any): any;
+export declare function mergeDeep(target: any, source: any, arrayStrategy?: "concat" | "replace"): any;
+export declare function parseJsoncFile(filePath: string): Promise<Record<string, unknown>>;

package/dist/util.js

@@ -2,6 +2,7 @@ import os from "os";
 import path from "path";
 import fs from "fs";
 import * as fsPromises from "fs/promises";
+import stripJsonComments from "strip-json-comments";
 import PKCLogger from "@pkcprotocol/pkc-logger";
 export { PKCLogger };
 /**
@@ -75,11 +76,28 @@ export async function parseMultiAddrIpfsGatewayToUrl(ipfsGatewaymultiAddrString)
         throw new Error(`Unable to parse IPFS gateway multiaddr: ${ipfsGatewaymultiAddrString}`);
     return new URL(`http://${parsed.host}:${parsed.port}`);
 }
+/** Recursively replaces all `null` values with `undefined`.
+ * Used before calling community.edit() since pkc-js expects `undefined` for removal,
+ * but JSON/CLI input produces `null`. */
+export function replaceNullWithUndefined(obj) {
+    if (obj === null)
+        return undefined;
+    if (Array.isArray(obj))
+        return obj.map(replaceNullWithUndefined);
+    if (typeof obj === "object" && obj.constructor === Object) {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = replaceNullWithUndefined(value);
+        }
+        return result;
+    }
+    return obj;
+}
 /**
  * Custom merge function that implements CLI-specific merge behavior.
  * This matches the expected behavior from the test suite.
  */
-export function mergeDeep(target, source) {
+export function mergeDeep(target, source, arrayStrategy = "concat") {
     function isObject(item) {
         return item && typeof item === "object" && !Array.isArray(item);
     }
@@ -88,6 +106,10 @@ export function mergeDeep(target, source) {
     }
     // Handle arrays with CLI-specific behavior
     if (Array.isArray(target) && Array.isArray(source)) {
+        // RFC 7396 JSON Merge Patch: arrays are replaced entirely
+        if (arrayStrategy === "replace") {
+            return source;
+        }
         // Check if source is sparse (has holes/empty items) - indicates indexed assignment like --rules[2]
         const sourceHasHoles = source.length !== Object.keys(source).length;
         if (sourceHasHoles) {
@@ -97,7 +119,7 @@ export function mergeDeep(target, source) {
             for (let i = 0; i < maxLength; i++) {
                 if (i in source) {
                     if (i in target && isPlainObject(target[i]) && isPlainObject(source[i])) {
-                        result[i] = mergeDeep(target[i], source[i]);
+                        result[i] = mergeDeep(target[i], source[i], arrayStrategy);
                     }
                     else {
                         result[i] = source[i];
@@ -138,10 +160,10 @@ export function mergeDeep(target, source) {
         for (const key in source) {
             if (source.hasOwnProperty(key)) {
                 if (Array.isArray(target[key]) && Array.isArray(source[key])) {
-                    result[key] = mergeDeep(target[key], source[key]);
+                    result[key] = mergeDeep(target[key], source[key], arrayStrategy);
                 }
                 else if (isPlainObject(target[key]) && isPlainObject(source[key])) {
-                    result[key] = mergeDeep(target[key], source[key]);
+                    result[key] = mergeDeep(target[key], source[key], arrayStrategy);
                 }
                 else {
                     result[key] = source[key];
@@ -153,3 +175,21 @@ export function mergeDeep(target, source) {
     // If not both objects/arrays, source takes precedence
     return source;
 }
+export async function parseJsoncFile(filePath) {
+    const fileContent = await fsPromises.readFile(filePath, "utf-8");
+    const stripped = stripJsonComments(fileContent);
+    let parsed;
+    try {
+        parsed = JSON.parse(stripped);
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            throw new Error(`Invalid JSONC in file ${filePath}: ${e.message}`);
+        }
+        throw e;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("JSONC file must contain a JSON object (not an array, null, string, or number)");
+    }
+    return parsed;
+}