@elgora/cli 7.4.0 → 7.5.0

package/README.md

@@ -21,6 +21,10 @@ Or run one command without installing:
 npx @elgora/cli --help
 ```
 
+Every command refuses to start on a Node outside the `engines` range the
+package declares, and says which range it needs. `--version` and `help` still
+answer.
+
 ## Commands
 
 - `poster:publish-fund` publishes approved `bounty_challenge.md` bytes and

package/dist/cli.js

@@ -1142,8 +1142,12 @@ async function openAesKeyForRecipient(input) {
     }
   }
   if (!matched) {
+    const wanted = [...new Set(wrappedKeys.map((key) => key.key_id))].sort();
+    const configured = [
+      ...new Set(privateKeys.map((key) => key.key_id))
+    ].sort();
     throw new Error(
-      "no matching Guardian private key for private artifact envelope"
+      `no matching Guardian private key for private artifact envelope: this envelope was sealed for key_id ${JSON.stringify(wanted)}, but ELGORA_GUARDIAN_PRIVATE_KEYS_JSON configures key_id ${JSON.stringify(configured)}. key_id must be this Guardian's own registered roster name (the name passed to roster:add-guardian), not its account address.`
     );
   }
   throw new Error("matching Guardian private key could not open wrapped key", {
@@ -6902,6 +6906,70 @@ function resolveChainId(selector) {
   );
 }
 
+// src/version.ts
+var CLI_VERSION = true ? "7.5.0" : "0.0.0-dev";
+var CLI_NODE_ENGINES = true ? ">=24 <25" : ">=24 <25";
+
+// src/node-engines.ts
+function unsupportedNodeMessage(running = process.versions.node, range = CLI_NODE_ENGINES) {
+  if (satisfiesRange(running, range)) return null;
+  return `elgora-cli needs Node ${range}; this is Node ${running}. Install a Node inside that range and run the command again. --version and help still answer.`;
+}
+function satisfiesRange(version, range) {
+  const running = parseVersion(version);
+  if (!running) return false;
+  return range.split("||").some(
+    (alternative) => alternative.trim().split(/\s+/).filter(Boolean).every((comparator) => satisfiesComparator(running, comparator))
+  );
+}
+function satisfiesComparator(running, comparator) {
+  const match = /^(>=|<=|>|<|=|\^|~)?v?(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/.exec(
+    comparator
+  );
+  if (!match) return false;
+  const operator = match[1] ?? "=";
+  const major = Number(match[2]);
+  const minorRaw = match[3];
+  const patchRaw = match[4];
+  const wildcard = minorRaw === void 0 || minorRaw === "x" || minorRaw === "*" || patchRaw === void 0 || patchRaw === "x" || patchRaw === "*";
+  const bound = [
+    major,
+    minorRaw && !["x", "*"].includes(minorRaw) ? Number(minorRaw) : 0,
+    patchRaw && !["x", "*"].includes(patchRaw) ? Number(patchRaw) : 0
+  ];
+  const order = compareVersions(running, bound);
+  switch (operator) {
+    case ">":
+      return order > 0;
+    case ">=":
+      return order >= 0;
+    case "<":
+      return order < 0;
+    case "<=":
+      return order <= 0;
+    case "^":
+      return order >= 0 && running[0] === major;
+    case "~": {
+      const anyMinor = minorRaw === void 0 || minorRaw === "x" || minorRaw === "*";
+      return order >= 0 && running[0] === major && (anyMinor || running[1] === bound[1]);
+    }
+    default:
+      return wildcard ? running[0] === major && (minorRaw === void 0 || ["x", "*"].includes(minorRaw) || running[1] === bound[1]) : order === 0;
+  }
+}
+function parseVersion(version) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
 // src/poster-open-winning-submission.ts
 import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
@@ -7276,6 +7344,11 @@ function loadPublishFundConfig(env, apiBaseUrlOverride) {
   };
 }
 
+// src/required-env.ts
+function missingRequiredEnv(required4, env) {
+  return required4.filter((envName) => !env[envName]?.trim());
+}
+
 // src/roster-add-guardian.ts
 import { isAddress as isAddress4 } from "viem";
 import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
@@ -7312,6 +7385,11 @@ async function main10(env = process.env, argv = process.argv.slice(2)) {
       `${args.guardianAccount} is already on the Guardian roster`
     );
   }
+  if (roster.some((guardian) => guardian.name === args.name)) {
+    throw new Error(
+      `"${args.name}" is already the name of a Guardian on the roster; names must be unique`
+    );
+  }
   const contractArgs = [
     args.name,
     args.guardianAccount,
@@ -7395,6 +7473,14 @@ function parseRosterAddGuardianArgs(argv) {
   const guardianAccount = positional[1]?.trim();
   const encryptionPublicKey = positional[2]?.trim();
   if (!name) throw usageError2();
+  if (!KEY_ID_RE.test(name)) {
+    throw new Error(
+      // A Solver's CLI seals private artifacts against this exact string as
+      // the Guardian's key_id, so it can't contain spaces or punctuation the
+      // wire format rejects — no display-only rendering happens in between.
+      `name must match ${KEY_ID_RE.source} (it becomes this Guardian's private-artifact key_id)`
+    );
+  }
   if (!guardianAccount || !isAddress4(guardianAccount)) {
     throw new Error("guardian_account must be a valid EVM address");
   }
@@ -7928,6 +8014,23 @@ function requirePinnedGuardianRosterHash(hubGuardianRosterHash, apiGuardianRoste
     );
   }
 }
+function requireUsableGuardianNames(roster) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const guardian of roster) {
+    if (!KEY_ID_RE.test(guardian.name)) {
+      throw new Error(
+        `Guardian ${guardian.account} has roster name ${JSON.stringify(guardian.name)}, which cannot be used as a private-artifact key_id (must match ${KEY_ID_RE.source}). This roster cannot receive private submissions until its admin corrects the name.`
+      );
+    }
+    const collidingAccount = seen.get(guardian.name);
+    if (collidingAccount) {
+      throw new Error(
+        `Guardians ${collidingAccount} and ${guardian.account} share the roster name ${JSON.stringify(guardian.name)}. Names must be unique on the pinned roster so each Guardian's key_id resolves to exactly one recipient.`
+      );
+    }
+    seen.set(guardian.name, guardian.account);
+  }
+}
 function requireMatchingSubmitTransaction(actual, expected) {
   if (actual.chain_id !== expected.chain_id || actual.to.toLowerCase() !== expected.to.toLowerCase() || actual.value !== expected.value || actual.data.toLowerCase() !== expected.data.toLowerCase() || actual.function_name !== expected.function_name || actual.args.bounty_id !== expected.args.bounty_id || actual.args.submission_commitment.toLowerCase() !== expected.args.submission_commitment.toLowerCase() || actual.args.guardian_roster_hash.toLowerCase() !== expected.args.guardian_roster_hash.toLowerCase() || actual.args.extra_data !== expected.args.extra_data) {
     throw new Error(
@@ -7949,9 +8052,10 @@ function requireOpenSubmittableBounty(bountyFacts, bountyId) {
 async function buildSolverSubmissionEnvelope(input) {
   const solver = input.solver.toLowerCase();
   const bountyId = input.bountyId.toString();
+  requireUsableGuardianNames(input.guardianRoster);
   const guardianRecipients = input.guardianRoster.map(
     (guardian) => ({
-      key_id: guardian.account.toLowerCase(),
+      key_id: guardian.name,
       suite: PRIVATE_ARTIFACT_HPKE_SUITE,
       public_key: guardian.encryptionPublicKey
     })
@@ -8215,19 +8319,19 @@ function usageError4() {
   return new Error(VERIFICATION_RECORD_USAGE);
 }
 
-// src/version.ts
-var CLI_VERSION = true ? "7.4.0" : "0.0.0-dev";
-
 // src/cli.ts
-var dotenvPath = path4.resolve(process.env.DOTENV_CONFIG_PATH ?? ".env");
-var dotenvResult = loadDotenv({
-  quiet: true,
-  ...process.env.DOTENV_CONFIG_PATH ? { path: process.env.DOTENV_CONFIG_PATH } : void 0
-});
-process.stderr.write(
-  `Env: ${dotenvPath} (${dotenvResult.error ? "not found, using process env only" : "loaded"})
+if (process.env.DOTENV_CONFIG_PATH) {
+  const dotenvPath = path4.resolve(process.env.DOTENV_CONFIG_PATH);
+  const dotenvResult = loadDotenv({ path: dotenvPath, quiet: true });
+  process.stderr.write(
+    `Env: ${dotenvPath} (${dotenvResult.error ? `not found: ${dotenvResult.error.message}` : "loaded"})
 `
-);
+  );
+} else {
+  process.stderr.write(
+    "Env: DOTENV_CONFIG_PATH not set; reading process.env only\n"
+  );
+}
 var COMMANDS = {
   "guardian:judgeable": main5,
   "guardian:open": main3,
@@ -8342,7 +8446,7 @@ var COMMAND_HELP = {
   "roster:add-guardian": {
     usage: "elgora-cli roster:add-guardian [--roster-admin-address <address>]\n   <name> <guardian_account> <encryption_public_key>",
     title: "Append one Guardian to the live roster.",
-    description: "Call ElgoraHub's guardianRosterAdmin-only addGuardian directly. Only\n  future bounties see the new roster; open bounties keep judging\n  against the hash pinned when they were created. With\n  --roster-admin-address, the transaction is simulated and printed\n  unsigned (to, data, value) for an external signer such as a Safe,\n  instead of being sent. Run roster:prepare-guardian-proof,\n  guardian:prove-roster-key, and roster:verify-guardian-proof against\n  the proposed Guardian before ever calling this.",
+    description: "Call ElgoraHub's guardianRosterAdmin-only addGuardian directly. Only\n  future bounties see the new roster; open bounties keep judging\n  against the hash pinned when they were created. With\n  --roster-admin-address, the transaction is simulated and printed\n  unsigned (to, data, value) for an external signer such as a Safe,\n  instead of being sent. Run roster:prepare-guardian-proof,\n  guardian:prove-roster-key, and roster:verify-guardian-proof against\n  the proposed Guardian before ever calling this. name becomes this\n  Guardian's key_id for every private submission a Solver seals\n  afterward \u2014 it must be unique on the roster and is what this\n  Guardian's own ELGORA_GUARDIAN_PRIVATE_KEYS_JSON entries must use as\n  their key_id, not the account address.",
     required: [],
     defaulted: ["ELGORA_CHAIN_ID", "ELGORA_HUB_ADDRESS", "ELGORA_RPC_URL"]
   },
@@ -8434,6 +8538,32 @@ async function run(rawArgv) {
     printCommandHelpOrUsage(subcommand);
     return;
   }
+  const nodeProblem = unsupportedNodeMessage();
+  if (nodeProblem) {
+    process.stderr.write(`${nodeProblem}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  const missing = missingRequiredEnv(
+    COMMAND_HELP[subcommand]?.required ?? [],
+    env
+  );
+  if (missing.length > 0) {
+    process.stderr.write(
+      `${[
+        `${subcommand} is missing required environment variable${missing.length > 1 ? "s" : ""}:`,
+        ...missing.map((envName) => `  ${envName}`),
+        "",
+        "This CLI reads only process.env (plus DOTENV_CONFIG_PATH if you set it)",
+        "\u2014 it never assumes a secrets location. Provide these before invoking",
+        `elgora-cli, or run \`elgora-cli help ${subcommand}\` for the full list.`
+      ].join("\n")}
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
   await command(env, rest);
 }
 function printUsage() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elgora/cli",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "Command-line client for Elgora, a decentralized bounty marketplace for science. Lets Posters, Solvers, and Guardians interact with Elgora's public API and on-chain contracts.",
   "type": "module",
   "license": "MIT",