@bitsocial/bitsocial-cli 0.19.64 → 0.19.66

package/README.md

@@ -298,12 +298,19 @@ $ bitsocial community edit mysub.bso '--roles["author-address.bso"]' null
 ## Commands
 
 <!-- commands -->
+* [`bitsocial challenge add PACKAGE`](#bitsocial-challenge-add-package)
+* [`bitsocial challenge i PACKAGE`](#bitsocial-challenge-i-package)
 * [`bitsocial challenge install PACKAGE`](#bitsocial-challenge-install-package)
 * [`bitsocial challenge list`](#bitsocial-challenge-list)
+* [`bitsocial challenge ls`](#bitsocial-challenge-ls)
 * [`bitsocial challenge remove NAME`](#bitsocial-challenge-remove-name)
+* [`bitsocial challenge rm NAME`](#bitsocial-challenge-rm-name)
+* [`bitsocial challenge un NAME`](#bitsocial-challenge-un-name)
+* [`bitsocial challenge uninstall NAME`](#bitsocial-challenge-uninstall-name)
 * [`bitsocial community create`](#bitsocial-community-create)
 * [`bitsocial community delete ADDRESSES`](#bitsocial-community-delete-addresses)
 * [`bitsocial community edit ADDRESS`](#bitsocial-community-edit-address)
+* [`bitsocial community export [ADDRESS]`](#bitsocial-community-export-address)
 * [`bitsocial community get [ADDRESS]`](#bitsocial-community-get-address)
 * [`bitsocial community list`](#bitsocial-community-list)
 * [`bitsocial community start ADDRESSES`](#bitsocial-community-start-addresses)
@@ -315,6 +322,72 @@ $ bitsocial community edit mysub.bso '--roles["author-address.bso"]' null
 * [`bitsocial update install [VERSION]`](#bitsocial-update-install-version)
 * [`bitsocial update versions`](#bitsocial-update-versions)
 
+## `bitsocial challenge add PACKAGE`
+
+Install a challenge package (npm package name, git URL, tarball URL, or local path)
+
+```
+USAGE
+  $ bitsocial challenge add PACKAGE [--pkcOptions.dataPath <value>]
+
+ARGUMENTS
+  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)
+
+FLAGS
+  --pkcOptions.dataPath=<value>  Data path to install the challenge into
+
+DESCRIPTION
+  Install a challenge package (npm package name, git URL, tarball URL, or local path)
+
+ALIASES
+  $ bitsocial challenge i
+  $ bitsocial challenge add
+
+EXAMPLES
+  $ bitsocial challenge install @bitsocial/mintpass-challenge
+
+  $ bitsocial challenge install @bitsocial/mintpass-challenge@1.0.0
+
+  $ bitsocial challenge install github:user/repo
+
+  $ bitsocial challenge install https://example.com/my-challenge-1.0.0.tar.gz
+
+  $ bitsocial challenge install ./my-local-challenge
+```
+
+## `bitsocial challenge i PACKAGE`
+
+Install a challenge package (npm package name, git URL, tarball URL, or local path)
+
+```
+USAGE
+  $ bitsocial challenge i PACKAGE [--pkcOptions.dataPath <value>]
+
+ARGUMENTS
+  PACKAGE  Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)
+
+FLAGS
+  --pkcOptions.dataPath=<value>  Data path to install the challenge into
+
+DESCRIPTION
+  Install a challenge package (npm package name, git URL, tarball URL, or local path)
+
+ALIASES
+  $ bitsocial challenge i
+  $ bitsocial challenge add
+
+EXAMPLES
+  $ bitsocial challenge install @bitsocial/mintpass-challenge
+
+  $ bitsocial challenge install @bitsocial/mintpass-challenge@1.0.0
+
+  $ bitsocial challenge install github:user/repo
+
+  $ bitsocial challenge install https://example.com/my-challenge-1.0.0.tar.gz
+
+  $ bitsocial challenge install ./my-local-challenge
+```
+
 ## `bitsocial challenge install PACKAGE`
 
 Install a challenge package (npm package name, git URL, tarball URL, or local path)
@@ -332,6 +405,10 @@ FLAGS
 DESCRIPTION
   Install a challenge package (npm package name, git URL, tarball URL, or local path)
 
+ALIASES
+  $ bitsocial challenge i
+  $ bitsocial challenge add
+
 EXAMPLES
   $ bitsocial challenge install @bitsocial/mintpass-challenge
 
@@ -344,7 +421,7 @@ EXAMPLES
   $ bitsocial challenge install ./my-local-challenge
 ```
 
-_See code: [src/cli/commands/challenge/install.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/challenge/install.ts)_
+_See code: [src/cli/commands/challenge/install.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/challenge/install.ts)_
 
 ## `bitsocial challenge list`
 
@@ -361,13 +438,40 @@ FLAGS
 DESCRIPTION
   List installed challenge packages
 
+ALIASES
+  $ bitsocial challenge ls
+
 EXAMPLES
   $ bitsocial challenge list
 
   $ bitsocial challenge list -q
 ```
 
-_See code: [src/cli/commands/challenge/list.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/challenge/list.ts)_
+_See code: [src/cli/commands/challenge/list.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/challenge/list.ts)_
+
+## `bitsocial challenge ls`
+
+List installed challenge packages
+
+```
+USAGE
+  $ bitsocial challenge ls [-q] [--pkcOptions.dataPath <value>]
+
+FLAGS
+  -q, --quiet                        Only display challenge names
+      --pkcOptions.dataPath=<value>  Data path where challenges are installed
+
+DESCRIPTION
+  List installed challenge packages
+
+ALIASES
+  $ bitsocial challenge ls
+
+EXAMPLES
+  $ bitsocial challenge list
+
+  $ bitsocial challenge list -q
+```
 
 ## `bitsocial challenge remove NAME`
 
@@ -386,13 +490,102 @@ FLAGS
 DESCRIPTION
   Remove an installed challenge package
 
+ALIASES
+  $ bitsocial challenge uninstall
+  $ bitsocial challenge rm
+  $ bitsocial challenge un
+
 EXAMPLES
   $ bitsocial challenge remove my-challenge
 
   $ bitsocial challenge remove @scope/my-challenge
 ```
 
-_See code: [src/cli/commands/challenge/remove.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/challenge/remove.ts)_
+_See code: [src/cli/commands/challenge/remove.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/challenge/remove.ts)_
+
+## `bitsocial challenge rm NAME`
+
+Remove an installed challenge package
+
+```
+USAGE
+  $ bitsocial challenge rm NAME [--pkcOptions.dataPath <value>]
+
+ARGUMENTS
+  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)
+
+FLAGS
+  --pkcOptions.dataPath=<value>  Data path where challenges are installed
+
+DESCRIPTION
+  Remove an installed challenge package
+
+ALIASES
+  $ bitsocial challenge uninstall
+  $ bitsocial challenge rm
+  $ bitsocial challenge un
+
+EXAMPLES
+  $ bitsocial challenge remove my-challenge
+
+  $ bitsocial challenge remove @scope/my-challenge
+```
+
+## `bitsocial challenge un NAME`
+
+Remove an installed challenge package
+
+```
+USAGE
+  $ bitsocial challenge un NAME [--pkcOptions.dataPath <value>]
+
+ARGUMENTS
+  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)
+
+FLAGS
+  --pkcOptions.dataPath=<value>  Data path where challenges are installed
+
+DESCRIPTION
+  Remove an installed challenge package
+
+ALIASES
+  $ bitsocial challenge uninstall
+  $ bitsocial challenge rm
+  $ bitsocial challenge un
+
+EXAMPLES
+  $ bitsocial challenge remove my-challenge
+
+  $ bitsocial challenge remove @scope/my-challenge
+```
+
+## `bitsocial challenge uninstall NAME`
+
+Remove an installed challenge package
+
+```
+USAGE
+  $ bitsocial challenge uninstall NAME [--pkcOptions.dataPath <value>]
+
+ARGUMENTS
+  NAME  The challenge package name (e.g., my-challenge or @scope/my-challenge)
+
+FLAGS
+  --pkcOptions.dataPath=<value>  Data path where challenges are installed
+
+DESCRIPTION
+  Remove an installed challenge package
+
+ALIASES
+  $ bitsocial challenge uninstall
+  $ bitsocial challenge rm
+  $ bitsocial challenge un
+
+EXAMPLES
+  $ bitsocial challenge remove my-challenge
+
+  $ bitsocial challenge remove @scope/my-challenge
+```
 
 ## `bitsocial community create`
 
@@ -422,7 +615,7 @@ EXAMPLES
     $ bitsocial community create --jsonFile ./create-options.json
 ```
 
-_See code: [src/cli/commands/community/create.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/create.ts)_
+_See code: [src/cli/commands/community/create.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/create.ts)_
 
 ## `bitsocial community delete ADDRESSES`
 
@@ -447,7 +640,7 @@ EXAMPLES
   $ bitsocial community delete 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu
 ```
 
-_See code: [src/cli/commands/community/delete.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/delete.ts)_
+_See code: [src/cli/commands/community/delete.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/delete.ts)_
 
 ## `bitsocial community edit ADDRESS`
 
@@ -517,7 +710,48 @@ EXAMPLES
     $ bitsocial community edit bitsocial.bso --jsonFile ./edit-options.json
 ```
 
-_See code: [src/cli/commands/community/edit.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/edit.ts)_
+_See code: [src/cli/commands/community/edit.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/edit.ts)_
+
+## `bitsocial community export [ADDRESS]`
+
+Export a local community to a SQLite snapshot file. The export runs on the RPC server (daemon); once finished the snapshot is downloaded and its sha256 checksum is verified. Pass --includePrivateKey to produce a restorable backup that keeps the community's address.
+
+```
+USAGE
+  $ bitsocial community export [ADDRESS] --pkcRpcUrl <value> [--name <value>] [--publicKey <value>] [-o <value>]
+    [--includePrivateKey] [--force] [-q]
+
+ARGUMENTS
+  [ADDRESS]  Address of the community to export
+
+FLAGS
+  -o, --path=<value>       Destination file for the downloaded snapshot (default:
+                           <dataPath>/exports/<address>_<datetime>.sqlite)
+  -q, --quiet              Suppress progress output; only print the path of the downloaded snapshot
+      --force              Overwrite the destination file if it already exists
+      --includePrivateKey  Ask the RPC server to include the community signer's private key in the export. Required for
+                           a restorable backup that keeps the same community address. The daemon may refuse (see
+                           `bitsocial daemon --no-allowPrivateKeyExport`)
+      --name=<value>       Name of the community to export
+      --pkcRpcUrl=<value>  (required) [default: ws://localhost:9138/] URL to PKC RPC
+      --publicKey=<value>  Public key of the community to export
+
+DESCRIPTION
+  Export a local community to a SQLite snapshot file. The export runs on the RPC server (daemon); once finished the
+  snapshot is downloaded and its sha256 checksum is verified. Pass --includePrivateKey to produce a restorable backup
+  that keeps the community's address.
+
+EXAMPLES
+  $ bitsocial community export plebmusic.bso
+
+  $ bitsocial community export plebmusic.bso --includePrivateKey -o ./backups/plebmusic.sqlite
+
+  $ bitsocial community export --name my-community
+
+  $ bitsocial community export --publicKey 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu
+```
+
+_See code: [src/cli/commands/community/export.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/export.ts)_
 
 ## `bitsocial community get [ADDRESS]`
 
@@ -548,7 +782,7 @@ EXAMPLES
   $ bitsocial community get --publicKey 12D3KooWG3XbzoVyAE6Y9vHZKF64Yuuu4TjdgQKedk14iYmTEPWu
 ```
 
-_See code: [src/cli/commands/community/get.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/get.ts)_
+_See code: [src/cli/commands/community/get.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/get.ts)_
 
 ## `bitsocial community list`
 
@@ -571,7 +805,7 @@ EXAMPLES
   $ bitsocial community list
 ```
 
-_See code: [src/cli/commands/community/list.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/list.ts)_
+_See code: [src/cli/commands/community/list.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/list.ts)_
 
 ## `bitsocial community start ADDRESSES`
 
@@ -605,7 +839,7 @@ EXAMPLES
     $ bitsocial community start $(bitsocial community list -q) --concurrency 1
 ```
 
-_See code: [src/cli/commands/community/start.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/start.ts)_
+_See code: [src/cli/commands/community/start.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/start.ts)_
 
 ## `bitsocial community stop ADDRESSES`
 
@@ -630,7 +864,7 @@ EXAMPLES
   $ bitsocial community stop Qmb99crTbSUfKXamXwZBe829Vf6w5w5TktPkb6WstC9RFW
 ```
 
-_See code: [src/cli/commands/community/stop.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/community/stop.ts)_
+_See code: [src/cli/commands/community/stop.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/community/stop.ts)_
 
 ## `bitsocial daemon`
 
@@ -639,8 +873,12 @@ Run a network-connected Bitsocial node. Once the daemon is running you can creat
 ```
 USAGE
   $ bitsocial daemon --pkcRpcUrl <value> --logPath <value> [--chainProviderUrls <value>...]
+    [--allowPrivateKeyExport]
 
 FLAGS
+  --[no-]allowPrivateKeyExport    Allow RPC clients to request community exports that include the community signer's
+                                  private key (`bitsocial community export --includePrivateKey`). Disable with
+                                  --no-allowPrivateKeyExport when exposing the RPC to untrusted clients
   --chainProviderUrls=<value>...  [default:
                                   https://eth.drpc.org,https://ethereum.publicnode.com,https://ethereum-rpc.publicnode.c
                                   om,https://rpc.mevblocker.io,https://1rpc.io/eth,https://eth-pokt.nodies.app] RPC
@@ -669,9 +907,11 @@ EXAMPLES
   $ bitsocial daemon --pkcOptions.kuboRpcClientsOptions[0] https://remoteipfsnode.com
 
   $ bitsocial daemon --chainProviderUrls https://mainnet.infura.io/v3/YOUR_KEY
+
+  $ bitsocial daemon --no-allowPrivateKeyExport
 ```
 
-_See code: [src/cli/commands/daemon.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/daemon.ts)_
+_See code: [src/cli/commands/daemon.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/daemon.ts)_
 
 ## `bitsocial help [COMMAND]`
 
@@ -737,7 +977,7 @@ EXAMPLES
   $ bitsocial logs --stdout -f
 ```
 
-_See code: [src/cli/commands/logs.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/logs.ts)_
+_See code: [src/cli/commands/logs.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/logs.ts)_
 
 ## `bitsocial update check`
 
@@ -754,7 +994,7 @@ EXAMPLES
   $ bitsocial update check
 ```
 
-_See code: [src/cli/commands/update/check.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/update/check.ts)_
+_See code: [src/cli/commands/update/check.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/update/check.ts)_
 
 ## `bitsocial update install [VERSION]`
 
@@ -786,7 +1026,7 @@ EXAMPLES
   $ bitsocial update install --no-restart-daemons
 ```
 
-_See code: [src/cli/commands/update/install.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/update/install.ts)_
+_See code: [src/cli/commands/update/install.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/update/install.ts)_
 
 ## `bitsocial update versions`
 
@@ -808,7 +1048,7 @@ EXAMPLES
   $ bitsocial update versions --limit 5
 ```
 
-_See code: [src/cli/commands/update/versions.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.64/src/cli/commands/update/versions.ts)_
+_See code: [src/cli/commands/update/versions.ts](https://github.com/bitsocialnet/bitsocial-cli/blob/v0.19.66/src/cli/commands/update/versions.ts)_
 <!-- commandsstop -->
 
 ## Contribution

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

@@ -21,4 +21,5 @@ 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[]>;
+export declare function formatChallengeNameVersion(challenge: Pick<InstalledChallenge, "name" | "version">): string;
+export declare function loadChallengesIntoPKC(dataPath?: string): Promise<InstalledChallenge[]>;

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

@@ -285,12 +285,15 @@ export async function verifyNativeModuleAbi(challengeDir) {
             `Ensure the challenge package was built for this Node.js version.`);
     }
 }
+export function formatChallengeNameVersion(challenge) {
+    return challenge.version && challenge.version !== "unknown" ? `${challenge.name}@${challenge.version}` : challenge.name;
+}
 export async function loadChallengesIntoPKC(dataPath) {
     const challenges = await listInstalledChallenges(dataPath);
     if (challenges.length === 0)
         return [];
     const PKC = await import("@pkcprotocol/pkc-js");
-    const loadedNames = [];
+    const loaded = [];
     for (const challenge of challenges) {
         try {
             const pkg = await readChallengePackageJson(challenge.path);
@@ -300,11 +303,11 @@ export async function loadChallengesIntoPKC(dataPath) {
             const imported = await import(pathToFileURL(entryPath).href);
             const factory = imported.default || imported;
             PKC.default.challenges[challenge.name] = factory;
-            loadedNames.push(challenge.name);
+            loaded.push(challenge);
         }
         catch (err) {
             console.error(`Failed to load challenge "${challenge.name}":`, err);
         }
     }
-    return loadedNames;
+    return loaded;
 }

package/dist/cli/ascii-banner.d.ts

@@ -1 +1,8 @@
-export declare function printBanner(): void;
+interface RenderBannerOptions {
+    env?: Record<string, string | undefined>;
+    forceColor?: boolean;
+    stdoutIsTTY?: boolean;
+}
+export declare function renderBanner(options?: RenderBannerOptions): string;
+export declare function printBanner(options?: RenderBannerOptions): void;
+export {};

package/dist/cli/ascii-banner.js

@@ -5,8 +5,8 @@
 //
 // COLORS is the paint map. Each character corresponds 1:1 to the character
 // at the same position in SHAPE:
-//   B = blue   (#1a4fd0) — the sphere
-//   S = silver (#e5e7eb) — the rings and the "Bitsocial" text
+//   B = blue accent — the sphere
+//   S = default foreground — the rings and the "Bitsocial" text
 //   . = no color (pass the glyph through as-is; use this for spaces)
 //
 // To retouch the art, find a glyph in SHAPE, then flip the character at the
@@ -15,7 +15,8 @@
 //
 // Both grids MUST have the same number of rows. Each row in COLORS must be at
 // least as wide as the corresponding SHAPE row (extra chars are ignored).
-// Palette sourced from bitsocialnet/bitsocial-web/about/tailwind.config.ts.
+// Use the terminal's default foreground for the wordmark/rings so the banner
+// stays readable on both light and dark terminal themes.
 const SHAPE = [
     "                ⢀⣴⣿⣿⣦⡀                                                                                       ",
     "                ⣾⣿⠁⠈⣿⣷⡀                                                                                      ",
@@ -56,39 +57,45 @@ const COLORS = [
     "...............SSSSSSSS......................................................................................",
     "................SSSSSS......................................................................................."
 ];
-const BLUE = "\x1b[38;2;26;79;208m";
-const SILVER = "\x1b[38;2;229;231;235m";
-const RESET = "\x1b[0m";
+const BLUE = "\x1b[94m";
+const DEFAULT_FOREGROUND = "\x1b[39m";
 function paint(shape, colors) {
     let out = "";
-    let current = ".";
+    let blueActive = false;
     for (let i = 0; i < shape.length; i++) {
         const glyph = shape[i];
         const want = colors[i] ?? ".";
-        if (want !== current) {
-            if (current !== ".")
-                out += RESET;
-            if (want === "B")
-                out += BLUE;
-            else if (want === "S")
-                out += SILVER;
-            current = want;
+        const wantBlue = want === "B";
+        if (wantBlue !== blueActive) {
+            out += wantBlue ? BLUE : DEFAULT_FOREGROUND;
+            blueActive = wantBlue;
         }
         out += glyph;
     }
-    if (current !== ".")
-        out += RESET;
+    if (blueActive)
+        out += DEFAULT_FOREGROUND;
     return out;
 }
-function supportsColor() {
-    if (process.env["NO_COLOR"])
+function envForcesColor(value) {
+    if (value === undefined)
         return false;
-    if (process.env["FORCE_COLOR"])
+    return value !== "0" && value.toLowerCase() !== "false";
+}
+function supportsColor(options = {}) {
+    const env = options.env ?? process.env;
+    if (env["NO_COLOR"] !== undefined)
+        return false;
+    if (options.forceColor)
         return true;
-    return Boolean(process.stdout.isTTY);
+    if (env["FORCE_COLOR"] !== undefined)
+        return envForcesColor(env["FORCE_COLOR"]);
+    return Boolean(options.stdoutIsTTY ?? process.stdout.isTTY);
 }
-export function printBanner() {
-    const useColor = supportsColor();
+export function renderBanner(options = {}) {
+    const useColor = supportsColor(options);
     const lines = SHAPE.map((row, i) => (useColor ? paint(row, COLORS[i] ?? "") : row));
-    process.stdout.write(lines.join("\n") + "\n\n");
+    return lines.join("\n") + "\n\n";
+}
+export function printBanner(options = {}) {
+    process.stdout.write(renderBanner(options));
 }

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

@@ -1,6 +1,7 @@
 import { Command } from "@oclif/core";
 export default class Install extends Command {
     static description: string;
+    static aliases: string[];
     static args: {
         package: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };

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

@@ -6,6 +6,7 @@ import defaults from "../../../common-utils/defaults.js";
 import { ensureNpmAvailable, ensureChallengesDir, challengeNameToDir, readChallengePackageJson, runNpmPack, runNpmInstall, verifyNativeModuleAbi } from "../../../challenge-packages/challenge-utils.js";
 export default class Install extends Command {
     static description = "Install a challenge package (npm package name, git URL, tarball URL, or local path)";
+    static aliases = ["challenge:i", "challenge:add"];
     static args = {
         package: Args.string({
             description: "Package specifier — anything npm can install (name, name@version, git URL, tarball URL, local path)",
@@ -26,9 +27,9 @@ export default class Install extends Command {
         "bitsocial challenge install ./my-local-challenge"
     ];
     async run() {
+        const startTime = Date.now();
         const { args, flags } = await this.parse(Install);
         const dataPath = flags["pkcOptions.dataPath"] || defaults.PKC_DATA_PATH;
-        this.log("Installing challenge package — this may take a few minutes...");
         // 1. Check npm is available
         await ensureNpmAvailable();
         // 2. Use npm pack to download the package as a tarball
@@ -68,7 +69,16 @@ export default class Install extends Command {
             }
             // 5. Read package info
             const pkg = await readChallengePackageJson(pkgDir);
-            // 6. Check not already installed
+            // 6. Run npm install in the temp dir, so a failed install never
+            //    touches an existing working installation of the same package
+            process.stderr.write(`[challenge-install] starting npm install in ${pkgDir}\n`);
+            await runNpmInstall(pkgDir);
+            process.stderr.write("[challenge-install] npm install completed\n");
+            // 7. Verify native modules are ABI-compatible (still in the temp dir,
+            //    so failure needs no rollback — the temp dir is cleaned up below)
+            await verifyNativeModuleAbi(pkgDir);
+            // 8. Swap the verified package into the challenges dir, replacing any
+            //    existing installation (idempotent, like npm install)
             const challengesDir = await ensureChallengesDir(dataPath);
             const destDir = challengeNameToDir(challengesDir, pkg.name);
             let alreadyExists = true;
@@ -78,44 +88,30 @@ export default class Install extends Command {
             catch {
                 alreadyExists = false;
             }
-            if (alreadyExists) {
-                this.error(`Challenge "${pkg.name}" is already installed. Remove it first with: bitsocial challenge remove ${pkg.name}`);
-            }
-            // 7. Move to challenges dir
+            // Move any existing install aside (same filesystem — tmpDir lives under
+            // dataPath) so it can be restored if the final rename fails
+            const backupDir = path.join(tmpDir, "previous-install");
+            if (alreadyExists)
+                await fs.rename(destDir, backupDir);
             if (pkg.name.startsWith("@")) {
                 // Ensure scope dir exists for scoped packages
                 const scopeDir = path.dirname(destDir);
                 await fs.mkdir(scopeDir, { recursive: true });
             }
-            await fs.rename(pkgDir, destDir);
-            // 8. Run npm install
-            process.stderr.write(`[challenge-install] starting npm install in ${destDir}\n`);
-            await runNpmInstall(destDir);
-            process.stderr.write("[challenge-install] npm install completed\n");
-            // 9. Verify native modules are ABI-compatible
             try {
-                await verifyNativeModuleAbi(destDir);
+                await fs.rename(pkgDir, destDir);
             }
             catch (err) {
-                // Roll back the installation on ABI mismatch
-                await fs.rm(destDir, { recursive: true, force: true });
-                if (pkg.name.startsWith("@")) {
-                    const scopeDir = path.dirname(destDir);
-                    try {
-                        const entries = await fs.readdir(scopeDir);
-                        if (entries.length === 0)
-                            await fs.rmdir(scopeDir);
-                    }
-                    catch {
-                        // ignore
-                    }
-                }
-                this.error(err instanceof Error ? err.message : String(err));
+                // Restore the previous installation before surfacing the error
+                if (alreadyExists)
+                    await fs.rename(backupDir, destDir);
+                throw err;
             }
-            // 10. Print success
+            // 9. Print success (npm-style)
             const version = pkg.version ? `@${pkg.version}` : "";
-            this.log(`Installed challenge '${pkg.name}${version}'`);
-            // 11. Best-effort reload via daemon
+            const elapsedSeconds = Math.max(1, Math.round((Date.now() - startTime) / 1000));
+            this.log(`${alreadyExists ? "changed" : "added"} ${pkg.name}${version} in ${elapsedSeconds}s`);
+            // 10. Best-effort reload via daemon
             try {
                 await fetch("http://localhost:9138/api/challenges/reload", { method: "POST" });
             }
@@ -124,7 +120,7 @@ export default class Install extends Command {
             }
         }
         finally {
-            // 12. Clean up temp dir
+            // 11. Clean up temp dir (includes the previous-install backup, if any)
             await fs.rm(tmpDir, { recursive: true, force: true });
         }
     }