@hardkas/cli 0.2.2-alpha → 0.3.0-alpha

package/dist/replay-verify-runner-Y3RARVD7.js

@@ -0,0 +1,50 @@
+import {
+  UI
+} from "./chunk-K7XPWWIO.js";
+
+// src/runners/replay-verify-runner.ts
+import { readTxPlanArtifact, readTxReceiptArtifact } from "@hardkas/artifacts";
+import { loadOrCreateLocalnetState, verifyReplay } from "@hardkas/localnet";
+import path from "path";
+import pc from "picocolors";
+async function runReplayVerify(options) {
+  const artifactDir = path.resolve(process.cwd(), options.path);
+  const planPath = path.join(artifactDir, "tx-plan.json");
+  const receiptPath = path.join(artifactDir, "tx-receipt.json");
+  UI.header(`Replay Verification: ${path.basename(artifactDir)}`);
+  try {
+    const plan = await readTxPlanArtifact(planPath);
+    const receipt = await readTxReceiptArtifact(receiptPath);
+    const state = await loadOrCreateLocalnetState();
+    const report = verifyReplay(state, plan, receipt);
+    console.log(`  Workflow:      ${report.checks.workflowDeterministic === "reproduced" ? pc.green("\u2713 REPRODUCED") : pc.red("\u2717 DIVERGED")}`);
+    console.log(`  Consensus:     ${pc.yellow("- UNIMPLEMENTED")} (HardKAS does not validate network consensus)`);
+    console.log(`  L2 Logic:      ${pc.yellow("- UNIMPLEMENTED")} (HardKAS does not validate bridge protocol)`);
+    console.log("");
+    if (report.invariantsOk) {
+      UI.success("Artifact workflow is deterministic.");
+      console.log(`  Plan Hash:     \u2713 MATCH`);
+      console.log(`  Semantic Diff: \u2713 NO CHANGES`);
+    } else {
+      UI.error("Replay Verification Failed");
+      if (report.divergences.length > 0) {
+        console.log(pc.bold("\n  Divergences found:"));
+        for (const div of report.divergences) {
+          console.log(`    ${pc.cyan(div.path)}:`);
+          console.log(`      Expected: ${pc.green(JSON.stringify(div.expected))}`);
+          console.log(`      Actual:   ${pc.red(JSON.stringify(div.actual))}`);
+        }
+      }
+      if (report.errors.length > 0 && report.divergences.length === 0) {
+        report.errors.forEach((err) => console.log(`  [!] ${err}`));
+      }
+      process.exitCode = 1;
+    }
+  } catch (e) {
+    UI.error(`Failed to perform replay verification: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+export {
+  runReplayVerify
+};

package/dist/{rpc-doctor-runner-RKGKFGMM.js → rpc-doctor-runner-V7H7AAX4.js}

@@ -1,6 +1,6 @@
 import {
   UI
-} from "./chunk-M54KNJEH.js";
+} from "./chunk-K7XPWWIO.js";
 
 // src/runners/rpc-doctor-runner.ts
 import { KaspaJsonRpcClient } from "@hardkas/kaspa-rpc";

package/dist/{snapshot-restore-runner-P26HDE74.js → snapshot-restore-runner-KIJNPLDV.js}

@@ -1,6 +1,6 @@
 import {
   UI
-} from "./chunk-M54KNJEH.js";
+} from "./chunk-K7XPWWIO.js";
 
 // src/runners/snapshot-restore-runner.ts
 import {

package/dist/{snapshot-verify-runner-UYTXXQ7A.js → snapshot-verify-runner-PGMADWLN.js}

@@ -1,6 +1,6 @@
 import {
   UI
-} from "./chunk-M54KNJEH.js";
+} from "./chunk-K7XPWWIO.js";
 
 // src/runners/snapshot-verify-runner.ts
 import { loadOrCreateLocalnetState, verifySnapshot } from "@hardkas/localnet";

package/dist/{tx-verify-runner-GPPVBQIF.js → tx-verify-runner-6EGY5ZN4.js}

@@ -1,9 +1,9 @@
 import {
   UI
-} from "./chunk-M54KNJEH.js";
+} from "./chunk-K7XPWWIO.js";
 
 // src/runners/tx-verify-runner.ts
-import { readTxPlanArtifact } from "@hardkas/artifacts";
+import { readTxPlanArtifact, verifyArtifactIntegrity } from "@hardkas/artifacts";
 import { verifyTxPlanSemantics } from "@hardkas/tx-builder";
 import { formatSompi } from "@hardkas/core";
 import path from "path";
@@ -12,6 +12,15 @@ async function runTxVerify(options) {
   UI.header(`Transaction Verification: ${path.basename(options.path)}`);
   try {
     const artifact = await readTxPlanArtifact(absolutePath);
+    const integrityResult = await verifyArtifactIntegrity(absolutePath);
+    if (!integrityResult.ok) {
+      UI.error("INTEGRITY VERIFICATION FAILED");
+      integrityResult.issues.forEach((issue) => {
+        console.log(`  [!] [${issue.code}] ${issue.message}`);
+      });
+      process.exitCode = 1;
+      return;
+    }
     const result = verifyTxPlanSemantics(artifact);
     if (options.json) {
       console.log(JSON.stringify(result, (key, value) => typeof value === "bigint" ? value.toString() : value, 2));

package/dist/ui-SUYOHGGP.js

@@ -0,0 +1,10 @@
+import {
+  UI,
+  handleError,
+  handleLockError
+} from "./chunk-K7XPWWIO.js";
+export {
+  UI,
+  handleError,
+  handleLockError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/cli",
-  "version": "0.2.2-alpha",
+  "version": "0.3.0-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -13,22 +13,24 @@
   "dependencies": {
     "commander": "^12.1.0",
     "enquirer": "^2.4.1",
+    "execa": "^9.5.2",
     "picocolors": "^1.1.1",
     "zod": "^3.23.8",
-    "@hardkas/kaspa-rpc": "0.2.2-alpha",
-    "@hardkas/accounts": "0.2.2-alpha",
-    "@hardkas/artifacts": "0.2.2-alpha",
-    "@hardkas/config": "0.2.2-alpha",
-    "@hardkas/core": "0.2.2-alpha",
-    "@hardkas/l2": "0.2.2-alpha",
-    "@hardkas/localnet": "0.2.2-alpha",
-    "@hardkas/query": "0.2.2-alpha",
-    "@hardkas/node-orchestrator": "0.2.2-alpha",
-    "@hardkas/node-runner": "0.2.2-alpha",
-    "@hardkas/query-store": "0.2.2-alpha",
-    "@hardkas/simulator": "0.2.2-alpha",
-    "@hardkas/sdk": "0.2.2-alpha",
-    "@hardkas/tx-builder": "0.2.2-alpha"
+    "@hardkas/accounts": "0.3.0-alpha",
+    "@hardkas/artifacts": "0.3.0-alpha",
+    "@hardkas/config": "0.3.0-alpha",
+    "@hardkas/core": "0.3.0-alpha",
+    "@hardkas/query": "0.3.0-alpha",
+    "@hardkas/l2": "0.3.0-alpha",
+    "@hardkas/kaspa-rpc": "0.3.0-alpha",
+    "@hardkas/node-orchestrator": "0.3.0-alpha",
+    "@hardkas/localnet": "0.3.0-alpha",
+    "@hardkas/node-runner": "0.3.0-alpha",
+    "@hardkas/query-store": "0.3.0-alpha",
+    "@hardkas/sdk": "0.3.0-alpha",
+    "@hardkas/simulator": "0.3.0-alpha",
+    "@hardkas/testing": "0.3.0-alpha",
+    "@hardkas/tx-builder": "0.3.0-alpha"
   },
   "devDependencies": {
     "tsup": "^8.3.5",
@@ -48,11 +50,15 @@
   },
   "homepage": "https://github.com/KasLabDevs/HardKas/tree/main/packages/cli#readme",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --clean",
+    "build": "tsup src/index.ts --format esm --clean --external vitest",
     "dev": "tsx src/index.ts",
     "hardkas": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
+    "docs:generate-cli": "tsx src/scripts/generate-cli-docs.ts",
+    "docs:check-cli": "tsx src/scripts/generate-cli-docs.ts --check",
     "test": "vitest run",
+    "test:docs": "tsx test/docs-drift.node.ts",
+    "test:examples": "node --import tsx --test test/examples-acceptance.node.ts",
     "lint": "eslint ."
   }
 }

package/dist/accounts-keystore-runners-CVRE6NVM.js

@@ -1,112 +0,0 @@
-import {
-  UI
-} from "./chunk-M54KNJEH.js";
-
-// src/runners/accounts-keystore-runners.ts
-import path from "path";
-import enquirer from "enquirer";
-import { KeystoreManager } from "@hardkas/accounts";
-var { Password } = enquirer;
-async function runAccountsKeystoreImport(options) {
-  const name = options.name || "default";
-  const address = options.address;
-  const privateKey = options.privateKey;
-  if (!options.encrypted) {
-    throw new Error("Plaintext import is handled by runAccountsRealImport. Use --encrypted for this runner.");
-  }
-  UI.warning("HardKAS encrypted keystore is for local developer workflows, not institutional custody.");
-  UI.info("Do not import mainnet keys unless you fully understand the risks.");
-  if (!address || !privateKey) {
-    throw new Error("Address and private key are required for import.");
-  }
-  const passwordPrompt = new Password({
-    name: "password",
-    message: "Enter keystore password:"
-  });
-  const password = await passwordPrompt.run();
-  if (!password) {
-    throw new Error("Password cannot be empty.");
-  }
-  const confirmPrompt = new Password({
-    name: "confirm",
-    message: "Confirm keystore password:"
-  });
-  const confirm = await confirmPrompt.run();
-  if (password !== confirm) {
-    throw new Error("Passwords do not match.");
-  }
-  const keystore = await KeystoreManager.createEncryptedKeystore(
-    {
-      address,
-      privateKey,
-      network: "devnet"
-      // Default for now
-    },
-    password,
-    {
-      label: name,
-      network: "devnet"
-    }
-  );
-  const keystoreDir = path.join(process.cwd(), ".hardkas", "keystore");
-  const filePath = path.join(keystoreDir, `${name}.json`);
-  await KeystoreManager.saveEncryptedKeystore(filePath, keystore);
-  return {
-    success: true,
-    name,
-    path: filePath,
-    formatted: `Successfully imported and encrypted account '${name}' to ${filePath}`
-  };
-}
-async function runAccountsKeystoreUnlock(options) {
-  const { name } = options;
-  const filePath = path.join(process.cwd(), ".hardkas", "keystore", `${name}.json`);
-  const keystore = await KeystoreManager.loadEncryptedKeystore(filePath);
-  const passwordPrompt = new Password({
-    name: "password",
-    message: `Enter password for account '${name}':`
-  });
-  const password = await passwordPrompt.run();
-  const result = await KeystoreManager.decryptEncryptedKeystore(keystore, password);
-  if (result.success) {
-    UI.success(`Password verified for account '${name}'.`);
-    UI.info("Unlock is session-only. Decrypted key is not persisted.");
-  } else {
-    throw new Error(result.error || "Failed to unlock keystore.");
-  }
-}
-async function runAccountsKeystoreChangePassword(options) {
-  const { name } = options;
-  const filePath = path.join(process.cwd(), ".hardkas", "keystore", `${name}.json`);
-  const keystore = await KeystoreManager.loadEncryptedKeystore(filePath);
-  const oldPasswordPrompt = new Password({
-    name: "old",
-    message: "Enter current password:"
-  });
-  const oldPassword = await oldPasswordPrompt.run();
-  const newPasswordPrompt = new Password({
-    name: "new",
-    message: "Enter new password:"
-  });
-  const newPassword = await newPasswordPrompt.run();
-  const confirmPrompt = new Password({
-    name: "confirm",
-    message: "Confirm new password:"
-  });
-  const confirm = await confirmPrompt.run();
-  if (newPassword !== confirm) {
-    throw new Error("New passwords do not match.");
-  }
-  const updatedKeystore = await KeystoreManager.changeKeystorePassword(
-    keystore,
-    oldPassword,
-    newPassword
-  );
-  await KeystoreManager.saveEncryptedKeystore(filePath, updatedKeystore);
-  UI.success(`Successfully changed password for account '${name}'.`);
-}
-export {
-  runAccountsKeystoreChangePassword,
-  runAccountsKeystoreImport,
-  runAccountsKeystoreUnlock
-};

package/dist/chunk-M54KNJEH.js

@@ -1,98 +0,0 @@
-// src/ui.ts
-import pc from "picocolors";
-import { formatSompi } from "@hardkas/core";
-var UI = {
-  header(text) {
-    console.log(pc.bold(pc.magenta(`
-  \u2550\u2550\u2550 ${text} \u2550\u2550\u2550`)));
-  },
-  divider() {
-    console.log(pc.dim("  " + "\u2500".repeat(50)));
-  },
-  info(text) {
-    console.log(`  ${pc.blue("\u2139")} ${text}`);
-  },
-  success(text) {
-    console.log(`  ${pc.green("\u2714")} ${text}`);
-  },
-  box(title, subtitle) {
-    const width = 40;
-    console.log(pc.magenta(`  \u2554${"\u2550".repeat(width - 2)}\u2557`));
-    console.log(pc.magenta(`  \u2551${pc.bold(pc.white(title.padStart((width - 2 + title.length) / 2).padEnd(width - 2)))}\u2551`));
-    if (subtitle) {
-      console.log(pc.magenta(`  \u2551${pc.italic(pc.dim(subtitle.padStart((width - 2 + subtitle.length) / 2).padEnd(width - 2)))}\u2551`));
-    }
-    console.log(pc.magenta(`  \u255A${"\u2550".repeat(width - 2)}\u255D`));
-    console.log("");
-  },
-  warning(text) {
-    console.log(pc.yellow(`
-  \u26A0\uFE0F  WARNING:`));
-    console.log(pc.yellow(`     ${text}`));
-  },
-  error(msg, suggestion) {
-    console.error(pc.red(`
-  \u2717 Error:`));
-    console.error(pc.red(`    ${msg}`));
-    if (suggestion) {
-      console.error(pc.cyan(`
-  \u{1F4A1} Suggestion:`));
-      console.error(pc.cyan(`    ${suggestion}`));
-    }
-  },
-  field(label, value) {
-    const val = value === void 0 || value === null ? pc.dim("none") : String(value);
-    console.log(`  ${pc.dim(label.padEnd(16))} ${pc.white(val)}`);
-  },
-  kas(label, sompi) {
-    this.field(label, pc.cyan(formatSompi(BigInt(sompi))));
-  },
-  footer(hint) {
-    if (hint) {
-      console.log(pc.dim(`
-  Hint: ${hint}`));
-    }
-    console.log("");
-  }
-};
-function handleError(e, context) {
-  const msg = e instanceof Error ? e.message : String(e);
-  const errorObj = e;
-  let reason = errorObj.reason;
-  let suggestion = errorObj.suggestion;
-  if (msg === "Real transaction signing is not available") {
-    console.error(`
-${msg}`);
-    if (reason) console.error(`
-Reason:
-  ${reason}`);
-    if (suggestion) console.error(`
-Suggestion:
-  ${suggestion}
-  No artifact was written.`);
-    return;
-  }
-  if (!suggestion) {
-    if (msg.includes("Localnet state not found")) {
-      suggestion = "Run 'hardkas localnet reset' to initialize the simulated environment.";
-    } else if (msg.includes("Insufficient funds")) {
-      suggestion = "Use 'hardkas faucet <address> <amount>' to add funds to your account.";
-    } else if (msg.includes("Account not found")) {
-      suggestion = "Check your 'hardkas.config.ts' or use a full Kaspa address.";
-    } else if (msg.includes("Docker") || msg.includes("container")) {
-      suggestion = "Ensure Docker is running and you have permissions to manage containers.";
-    } else if (msg.includes("L2 RPC") || msg.includes("L2 profile")) {
-      suggestion = "Check your L2 network configuration or pass a valid --url.";
-    } else if (msg.includes("RPC") || msg.includes("Connection refused")) {
-      suggestion = "The Kaspa node might still be starting. Try 'hardkas rpc health --wait'.";
-    } else if (msg.includes("submitTransaction is not exposed")) {
-      suggestion = "Ensure your node/RPC provider supports transaction submission and you are NOT on mainnet without --allow-mainnet-signing.";
-    }
-  }
-  UI.error(context ? `${context}: ${msg}` : msg, suggestion);
-}
-
-export {
-  UI,
-  handleError
-};

package/dist/replay-verify-runner-WBK2FCWC.js

@@ -1,37 +0,0 @@
-import {
-  UI
-} from "./chunk-M54KNJEH.js";
-
-// src/runners/replay-verify-runner.ts
-import { readTxPlanArtifact, readTxReceiptArtifact } from "@hardkas/artifacts";
-import { loadOrCreateLocalnetState, verifyReplay } from "@hardkas/localnet";
-import path from "path";
-async function runReplayVerify(options) {
-  const artifactDir = path.resolve(process.cwd(), options.path);
-  const planPath = path.join(artifactDir, "tx-plan.json");
-  const receiptPath = path.join(artifactDir, "tx-receipt.json");
-  UI.header(`Replay Verification: ${path.basename(artifactDir)}`);
-  try {
-    const plan = await readTxPlanArtifact(planPath);
-    const receipt = await readTxReceiptArtifact(receiptPath);
-    const state = await loadOrCreateLocalnetState();
-    const report = verifyReplay(state, plan, receipt);
-    if (report.invariantsOk) {
-      UI.success("Replay Verified Successfully");
-      console.log(`  Plan Hash:    \u2713 MATCH`);
-      console.log(`  State Hashes: \u2713 MATCH`);
-      console.log(`  Mass/Fees:    \u2713 MATCH`);
-      console.log(`  Status:       \u2713 MATCH`);
-    } else {
-      UI.error("Replay Verification Failed");
-      report.errors.forEach((err) => console.log(`  [!] ${err}`));
-      process.exitCode = 1;
-    }
-  } catch (e) {
-    UI.error(`Failed to perform replay verification: ${e.message}`);
-    process.exitCode = 1;
-  }
-}
-export {
-  runReplayVerify
-};

package/dist/ui-DXULTF7Q.js

@@ -1,8 +0,0 @@
-import {
-  UI,
-  handleError
-} from "./chunk-M54KNJEH.js";
-export {
-  UI,
-  handleError
-};