@bitsocial/bitsocial-cli 0.19.39

package/bin/dev

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+import oclif from "@oclif/core";
+import path from "path";
+import { fileURLToPath } from "url";
+import { register } from "ts-node";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const project = path.join(__dirname, "..", "tsconfig.json");
+
+// In dev mode -> use ts-node and dev plugins
+process.env.NODE_ENV = "development";
+
+register({ project });
+
+// In dev mode, always show stack traces
+oclif.settings.debug = true;
+
+// Start the CLI
+oclif.run(undefined, import.meta.url).then(oclif.flush).catch(oclif.Errors.handle);

package/bin/dev.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\dev" %*

package/bin/postinstall.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { finished as streamFinished } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import decompress from "decompress";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.join(__dirname, "..");
+
+async function main() {
+    const distDir = path.join(packageRoot, "dist");
+    try {
+        await fs.access(distDir);
+    } catch {
+        // dist/ doesn't exist — dev install before build, skip silently
+        return;
+    }
+
+    const dstOfWebui = path.join(distDir, "webuis");
+    try {
+        await fs.mkdir(dstOfWebui);
+    } catch (e) {
+        if (e.code === "EEXIST") {
+            console.log("Web UIs directory already exists, skipping download");
+            return;
+        }
+        throw e;
+    }
+
+    const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf-8"));
+    const webuis = pkg.webuis;
+    if (!webuis || webuis.length === 0) {
+        console.warn("Warning: No webuis configured in package.json");
+        return;
+    }
+
+    const githubToken = process.env["GITHUB_TOKEN"];
+    if (githubToken) console.log("Using GITHUB_TOKEN for API requests");
+
+    for (const entry of webuis) {
+        const { url, sha256OfHtmlZip } = entry;
+        try {
+            // Parse "https://github.com/{owner}/{repo}/releases/tag/{tag}"
+            const match = url.match(/github\.com\/([^/]+\/[^/]+)\/releases\/tag\/(.+)$/);
+            if (!match) {
+                console.warn(`Warning: Could not parse GitHub release URL: ${url}. Skipping.`);
+                continue;
+            }
+            const [, ownerRepo, tag] = match;
+
+            const headers = githubToken ? { authorization: `Bearer ${githubToken}` } : undefined;
+            const releaseReq = await fetch(`https://api.github.com/repos/${ownerRepo}/releases/tags/${tag}`, { headers });
+            if (!releaseReq.ok) {
+                console.warn(`Warning: Failed to fetch release for ${ownerRepo}@${tag}, status ${releaseReq.status}. Skipping.`);
+                continue;
+            }
+
+            const release = await releaseReq.json();
+            const htmlZipAsset = release.assets.find((asset) => asset.name.includes("html"));
+            if (!htmlZipAsset) {
+                console.warn(`Warning: No HTML zip asset found in ${ownerRepo}@${tag}. Skipping.`);
+                continue;
+            }
+
+            const zipfilePath = path.join(dstOfWebui, htmlZipAsset.name);
+            const downloadReq = await fetch(htmlZipAsset["browser_download_url"], { headers });
+            if (!downloadReq.ok || !downloadReq.body) {
+                console.warn(`Warning: Failed to download ${htmlZipAsset.name}, status ${downloadReq.status}. Skipping.`);
+                continue;
+            }
+
+            const writer = createWriteStream(zipfilePath);
+            await streamFinished(Readable.fromWeb(downloadReq.body).pipe(writer));
+            writer.close();
+            console.log(`Downloaded ${htmlZipAsset.name}`);
+
+            // Verify SHA-256 checksum
+            const fileBuffer = await fs.readFile(zipfilePath);
+            const actualHash = createHash("sha256").update(fileBuffer).digest("hex");
+            if (actualHash !== sha256OfHtmlZip) {
+                await fs.rm(zipfilePath);
+                console.error(
+                    `ERROR: SHA-256 mismatch for ${htmlZipAsset.name}!\n` +
+                        `  Expected: ${sha256OfHtmlZip}\n` +
+                        `  Actual:   ${actualHash}\n` +
+                        `This could indicate a supply chain attack. Aborting.`
+                );
+                process.exit(1);
+            }
+            console.log(`Verified SHA-256 checksum for ${htmlZipAsset.name}`);
+
+            await decompress(zipfilePath, dstOfWebui);
+            console.log(`Extracted ${htmlZipAsset.name}`);
+            await fs.rm(zipfilePath);
+
+            // Rename index.html to prevent access to unconfigured version
+            const extractedDirName = htmlZipAsset.name.replace(".zip", "");
+            const indexPath = path.join(dstOfWebui, extractedDirName, "index.html");
+            const backupPath = path.join(dstOfWebui, extractedDirName, "index_backup_no_rpc.html");
+            await fs.rename(indexPath, backupPath);
+            console.log(`Downloaded ${ownerRepo}@${tag} successfully`);
+        } catch (e) {
+            console.warn(`Warning: Failed to process ${url}: ${e}. Skipping.`);
+            continue;
+        }
+    }
+
+    // Verify at least one web UI was downloaded
+    const downloadedEntries = await fs.readdir(dstOfWebui, { withFileTypes: true });
+    const webuiDirs = downloadedEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    if (webuiDirs.length === 0) {
+        console.error("ERROR: No web UIs were downloaded. At least one web UI is required.");
+        process.exit(1);
+    }
+    console.log(`Successfully downloaded ${webuiDirs.length} web UI(s):`, webuiDirs);
+}
+
+main().catch((err) => {
+    console.warn(`Warning: postinstall webui download failed: ${err}`);
+    // Don't fail the install for non-checksum errors
+});

package/bin/run

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// Save and strip DEBUG before any imports so the debug module
+// doesn't auto-enable stderr output. The daemon command will
+// re-enable namespaces programmatically and redirect to the log file.
+if (process.env.DEBUG) {
+    process.env._PLEBBIT_DEBUG = process.env.DEBUG;
+    delete process.env.DEBUG;
+}
+
+// Dynamic import so the stripping above runs before oclif loads
+const oclif = await import("@oclif/core");
+oclif.default.run(undefined, import.meta.url).then(oclif.default.flush).catch(oclif.default.Errors.handle);

package/bin/run.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/dist/challenge-packages/challenge-utils.d.ts

@@ -0,0 +1,24 @@
+export interface InstalledChallenge {
+    name: string;
+    version: string;
+    description: string;
+    path: string;
+}
+export declare function getChallengesDir(dataPath?: string): string;
+export declare function ensureChallengesDir(dataPath?: string): Promise<string>;
+export declare function challengeNameToDir(challengesDir: string, name: string): string;
+export declare function readChallengePackageJson(challengeDir: string): Promise<{
+    name: string;
+    version?: string;
+    description?: string;
+    main?: string;
+    exports?: any;
+}>;
+export declare function listInstalledChallenges(dataPath?: string): Promise<InstalledChallenge[]>;
+export declare function getNpmCliPath(): Promise<string>;
+export declare function getNpmEnv(): NodeJS.ProcessEnv;
+export declare function ensureNpmAvailable(): Promise<void>;
+export declare function runNpmPack(packageSpec: string, destDir: string): Promise<string>;
+export declare function runNpmInstall(challengeDir: string): Promise<void>;
+export declare function verifyNativeModuleAbi(challengeDir: string): Promise<void>;
+export declare function loadChallengesIntoPKC(dataPath?: string): Promise<string[]>;

package/dist/challenge-packages/challenge-utils.js

@@ -0,0 +1,304 @@
+import path from "path";
+import { pathToFileURL } from "node:url";
+import fs from "fs/promises";
+import { execFileSync, spawn } from "child_process";
+import defaults from "../common-utils/defaults.js";
+export function getChallengesDir(dataPath) {
+    return path.join(dataPath || defaults.PKC_DATA_PATH, "challenges");
+}
+export async function ensureChallengesDir(dataPath) {
+    const dir = getChallengesDir(dataPath);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+export function challengeNameToDir(challengesDir, name) {
+    // Handles both scoped (@org/pkg) and unscoped (pkg) names
+    return path.join(challengesDir, ...name.split("/"));
+}
+export async function readChallengePackageJson(challengeDir) {
+    const pkgPath = path.join(challengeDir, "package.json");
+    const content = await fs.readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(content);
+    if (!pkg.name || typeof pkg.name !== "string") {
+        throw new Error(`Invalid package.json in ${challengeDir}: missing "name" field`);
+    }
+    return pkg;
+}
+export async function listInstalledChallenges(dataPath) {
+    const challengesDir = getChallengesDir(dataPath);
+    const results = [];
+    let entries;
+    try {
+        entries = await fs.readdir(challengesDir, { withFileTypes: true });
+    }
+    catch {
+        return results; // dir doesn't exist = no challenges
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith("@")) {
+            // Scoped package: read @scope/*/package.json
+            const scopeDir = path.join(challengesDir, entry.name);
+            let scopeEntries;
+            try {
+                scopeEntries = await fs.readdir(scopeDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const scopeEntry of scopeEntries) {
+                if (!scopeEntry.isDirectory())
+                    continue;
+                const pkgDir = path.join(scopeDir, scopeEntry.name);
+                try {
+                    const pkg = await readChallengePackageJson(pkgDir);
+                    results.push({
+                        name: pkg.name,
+                        version: pkg.version || "unknown",
+                        description: pkg.description || "",
+                        path: pkgDir
+                    });
+                }
+                catch {
+                    // skip invalid entries
+                }
+            }
+        }
+        else {
+            // Unscoped package
+            const pkgDir = path.join(challengesDir, entry.name);
+            try {
+                const pkg = await readChallengePackageJson(pkgDir);
+                results.push({
+                    name: pkg.name,
+                    version: pkg.version || "unknown",
+                    description: pkg.description || "",
+                    path: pkgDir
+                });
+            }
+            catch {
+                // skip invalid entries
+            }
+        }
+    }
+    return results;
+}
+function getNpmCliPathRelative(nodeExecPath) {
+    // npm-cli.js lives at a standard location relative to a Node binary.
+    const nodeDir = path.dirname(nodeExecPath);
+    if (process.platform === "win32") {
+        // Windows: <node-dir>/node_modules/npm/bin/npm-cli.js
+        return path.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js");
+    }
+    // Unix (nvm, official installers, distro packages):
+    //   <node-dir>/../lib/node_modules/npm/bin/npm-cli.js
+    return path.join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+}
+export async function getNpmCliPath() {
+    // 1. Try relative to our own Node binary (works for nvm / system Node)
+    const relativePath = getNpmCliPathRelative(process.execPath);
+    try {
+        await fs.access(relativePath);
+        return relativePath;
+    }
+    catch {
+        // Not found relative to process.execPath (e.g. oclif-bundled Node without npm)
+    }
+    // 2. Fall back to the system npm found on PATH
+    try {
+        const cmd = process.platform === "win32" ? "where.exe" : "which";
+        const npmBin = execFileSync(cmd, ["npm"], { encoding: "utf8" }).trim().split("\n")[0].trim();
+        // npmBin is a symlink or script; resolve to the real path, then derive npm-cli.js
+        // For most installs: npm -> <prefix>/lib/node_modules/npm/bin/npm-cli.js
+        const realNpmBin = await fs.realpath(npmBin);
+        // If realpath leads directly to npm-cli.js, use it
+        if (realNpmBin.endsWith("npm-cli.js")) {
+            return realNpmBin;
+        }
+        // Otherwise, the system npm binary lives beside a Node that has npm installed —
+        // derive npm-cli.js relative to that Node
+        const systemNodeDir = path.dirname(realNpmBin);
+        const systemNpmCli = process.platform === "win32"
+            ? path.join(systemNodeDir, "node_modules", "npm", "bin", "npm-cli.js")
+            : path.join(systemNodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+        await fs.access(systemNpmCli);
+        return systemNpmCli;
+    }
+    catch {
+        // Could not locate npm on PATH either
+    }
+    // Return the original relative path so callers get the familiar error message
+    return relativePath;
+}
+export function getNpmEnv() {
+    // Prepend our Node's directory to PATH so that npm subprocesses
+    // (node-gyp, lifecycle scripts) also use the same Node binary
+    const nodeDir = path.dirname(process.execPath);
+    const pathSep = process.platform === "win32" ? ";" : ":";
+    return {
+        ...process.env,
+        PATH: nodeDir + pathSep + (process.env["PATH"] || "")
+    };
+}
+const npmErrorMessage = `npm is required to install challenge packages but was not found at the expected location ` +
+    `relative to Node ${process.version} (${process.execPath}).\n` +
+    `Install Node.js ${process.version} from https://nodejs.org/ (npm is included with Node.js) and retry.`;
+export async function ensureNpmAvailable() {
+    const npmCliPath = await getNpmCliPath();
+    try {
+        await fs.access(npmCliPath);
+    }
+    catch {
+        throw new Error(npmErrorMessage);
+    }
+    return new Promise((resolve, reject) => {
+        // Run npm through our own Node binary so process.execPath is correct
+        const proc = spawn(process.execPath, [npmCliPath, "--version"], { stdio: "ignore", env: getNpmEnv() });
+        proc.on("error", () => {
+            reject(new Error(npmErrorMessage));
+        });
+        proc.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(npmErrorMessage));
+        });
+    });
+}
+export async function runNpmPack(packageSpec, destDir) {
+    const npmCliPath = await getNpmCliPath();
+    return new Promise((resolve, reject) => {
+        const proc = spawn(process.execPath, [npmCliPath, "pack", packageSpec, "--pack-destination", destDir], {
+            stdio: ["ignore", "pipe", "inherit"],
+            env: getNpmEnv()
+        });
+        let stdout = "";
+        proc.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.on("error", (err) => {
+            reject(new Error(`Failed to run npm pack: ${err.message}`));
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                // npm pack prints the tarball filename on the last non-empty line of stdout
+                const filename = stdout.trim().split("\n").pop()?.trim();
+                if (!filename) {
+                    reject(new Error("npm pack succeeded but produced no output"));
+                    return;
+                }
+                resolve(path.join(destDir, filename));
+            }
+            else {
+                reject(new Error(`npm pack exited with code ${code}`));
+            }
+        });
+    });
+}
+export async function runNpmInstall(challengeDir) {
+    const npmCliPath = await getNpmCliPath();
+    // Strip devDependencies from the manifest before running npm install.
+    // npm's Arborist resolves ALL declared deps (including dev) during tree
+    // building even with --omit=dev — unresolvable devDep versions cause
+    // ETARGET failures before the omit filter applies.  Removing them from
+    // the manifest prevents Arborist from creating those edges at all.
+    // The original package.json is restored after install (byte-identical).
+    const pkgJsonPath = path.join(challengeDir, "package.json");
+    const originalContent = await fs.readFile(pkgJsonPath, "utf-8");
+    const pkg = JSON.parse(originalContent);
+    const hadDevDeps = pkg.devDependencies !== undefined;
+    if (hadDevDeps) {
+        const stripped = { ...pkg };
+        delete stripped.devDependencies;
+        await fs.writeFile(pkgJsonPath, JSON.stringify(stripped, null, 2) + "\n");
+    }
+    try {
+        await new Promise((resolve, reject) => {
+            // Run npm through our own Node binary to guarantee ABI-compatible
+            // native modules — npm's process.execPath and lifecycle scripts
+            // will all use the same Node that's running bitsocial-cli.
+            // Use piped stdio and forward explicitly so output is visible even
+            // when the parent process has piped stdio (e.g. spawned by tests).
+            const args = [npmCliPath, "install", "--omit=dev", "--no-audit", "--no-fund"];
+            if (process.platform === "win32") {
+                args.push("--legacy-peer-deps");
+            }
+            const proc = spawn(process.execPath, args, {
+                cwd: challengeDir,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: getNpmEnv()
+            });
+            proc.stdout?.pipe(process.stdout);
+            proc.stderr?.pipe(process.stderr);
+            proc.on("error", (err) => {
+                reject(new Error(`Failed to run npm install: ${err.message}`));
+            });
+            proc.on("close", (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`npm install exited with code ${code}`));
+            });
+        });
+    }
+    finally {
+        if (hadDevDeps) {
+            await fs.writeFile(pkgJsonPath, originalContent);
+        }
+    }
+}
+export async function verifyNativeModuleAbi(challengeDir) {
+    // Scan for .node files (native addons) and try to dlopen each one.
+    // Node checks NODE_MODULE_VERSION before calling any init code,
+    // so this safely catches ABI mismatches without side effects.
+    const entries = await fs.readdir(challengeDir, { recursive: true });
+    const nodeFiles = entries.filter((entry) => typeof entry === "string" && entry.endsWith(".node"));
+    if (nodeFiles.length === 0)
+        return;
+    const mismatched = [];
+    for (const file of nodeFiles) {
+        const filePath = path.join(challengeDir, file);
+        const mod = { exports: {} };
+        try {
+            process.dlopen(mod, filePath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("NODE_MODULE_VERSION") || msg.includes("was compiled against a different")) {
+                mismatched.push(file);
+            }
+            // Other errors (missing dependencies, etc.) are fine at this stage —
+            // the module might still work once the full package is loaded
+        }
+    }
+    if (mismatched.length > 0) {
+        throw new Error(`ABI mismatch: the following native modules were compiled for a different Node.js version:\n` +
+            mismatched.map((f) => `  - ${f}`).join("\n") +
+            `\nThe running Node.js is ${process.version} (modules ABI ${process.versions.modules}).\n` +
+            `Ensure the challenge package was built for this Node.js version.`);
+    }
+}
+export async function loadChallengesIntoPKC(dataPath) {
+    const challenges = await listInstalledChallenges(dataPath);
+    if (challenges.length === 0)
+        return [];
+    const PKC = await import("@pkcprotocol/pkc-js");
+    const loadedNames = [];
+    for (const challenge of challenges) {
+        try {
+            const pkg = await readChallengePackageJson(challenge.path);
+            // Resolve the entry point
+            const entryPoint = pkg.main || "index.js";
+            const entryPath = path.resolve(challenge.path, entryPoint);
+            const imported = await import(pathToFileURL(entryPath).href);
+            const factory = imported.default || imported;
+            PKC.default.challenges[challenge.name] = factory;
+            loadedNames.push(challenge.name);
+        }
+        catch (err) {
+            console.error(`Failed to load challenge "${challenge.name}":`, err);
+        }
+    }
+    return loadedNames;
+}

package/dist/cli/base-command.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "@oclif/core";
+import PKC from "@pkcprotocol/pkc-js";
+type PKCInstance = Awaited<ReturnType<typeof PKC>>;
+export declare abstract class BaseCommand extends Command {
+    static baseFlags: {
+        pkcRpcUrl: import("@oclif/core/interfaces").OptionFlag<import("url").URL, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    init(): Promise<void>;
+    protected _connectToPkcRpc(pkcRpcUrl: string): Promise<PKCInstance>;
+}
+export {};

package/dist/cli/base-command.js

@@ -0,0 +1,45 @@
+import { Command, Flags } from "@oclif/core";
+import defaults from "../common-utils/defaults.js";
+import PKC from "@pkcprotocol/pkc-js";
+import { getPKCLogger, setupDebugLogger } from "../util.js";
+const getPKCConnectOverride = () => {
+    const globalWithOverride = globalThis;
+    return globalWithOverride.__PKC_RPC_CONNECT_OVERRIDE;
+};
+export class BaseCommand extends Command {
+    static baseFlags = {
+        pkcRpcUrl: Flags.url({
+            summary: "URL to PKC RPC",
+            required: true,
+            default: defaults.PKC_RPC_URL
+        })
+    };
+    async init() {
+        await super.init();
+        const Logger = await getPKCLogger();
+        setupDebugLogger(Logger, { enableDefaultNamespace: false });
+    }
+    async _connectToPkcRpc(pkcRpcUrl) {
+        const connectOverride = getPKCConnectOverride();
+        if (connectOverride) {
+            return connectOverride(pkcRpcUrl);
+        }
+        const pkc = await PKC({ pkcRpcClientsOptions: [pkcRpcUrl] });
+        const errors = [];
+        pkc.on("error", (err) => {
+            errors.push(err);
+            console.error("Error from pkc instance", err);
+        });
+        await new Promise((resolve, reject) => {
+            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);
+                resolve();
+            });
+        });
+        return pkc;
+    }
+}

package/dist/cli/commands/challenge/install.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "@oclif/core";
+export default class Install extends Command {
+    static description: string;
+    static args: {
+        package: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        "pkcOptions.dataPath": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}