wattetheria 0.3.2 → 0.3.4

package/.env.release

@@ -1,5 +1,5 @@
 # Coordinated release image set
-RELEASE_TAG=1.0.3
+RELEASE_TAG=1.0.4
 
 WATTETHERIA_KERNEL_IMAGE=ghcr.io/wattetheria/wattetheria-kernel:${RELEASE_TAG}
 WATTSWARM_KERNEL_IMAGE=ghcr.io/wattetheria/wattswarm-kernel:${RELEASE_TAG}

package/README.md

@@ -556,9 +556,11 @@ Agent commands such as `identity`, `wallet`, and `servicenet` are forwarded to t
 native `wattetheria-client-cli`; installed release packages should not require Rust on the user's
 machine. The JS wrapper resolves `WATTETHERIA_CLI_BIN` first, then the matching optional native
 package such as `@wattetheria/cli-win32-x64`, then `bin/native/<platform>-<arch>/`, then `PATH`.
-If no host native CLI is available but the local Wattetheria node deployment is installed, the
-wrapper runs the same command inside the `kernel` container using the node's
-`/var/lib/wattetheria` data directory.
+`identity` and `wallet` are lightweight local setup commands for ServiceNet publishing and wallet
+binding when no local Wattetheria node identity or wallet exists. If a local node already has
+identity or wallet state, the wrapper refuses to create a separate local identity or wallet through
+those setup commands. ServiceNet commands can still run through an installed node when no host
+native CLI is available.
 
 NPM publish flow:
 
@@ -583,14 +585,16 @@ CLI saves the provider/card context locally:
 ```bash
 npx wattetheria servicenet agent-card init
 # or write the template into a specific directory:
-npx wattetheria servicenet agent-card init --out ./agents/hermes
+npx wattetheria servicenet agent-card init --out <output-directory>
 
-npx wattetheria servicenet provider register --card ./agent-card.json
+npx wattetheria servicenet register
+# If the card is not in the current directory:
+npx wattetheria servicenet register --card <path-to-agent-card.json>
 ```
 
 Then publish through the ServiceNet business command with the returned agent id. The publish
-command reads the saved provider id, ServiceNet URL, endpoint URL, and card path from local
-context instead of asking for repeated flags:
+command reads the saved provider id, endpoint URL, and card path from local context instead of
+asking for repeated flags:
 
 ```bash
 npx wattetheria servicenet publish <agent-id>

package/lib/cli.js

@@ -73,10 +73,25 @@ Commands:
   doctor      Check local prerequisites
   help        Show this help
 
-Agent subcommands (forwarded to the bundled native CLI when available):
-  identity    init | show | export-seed
-  wallet      manage wallet payment accounts
-  servicenet  agent-card init | provider register | publish <agent-id>
+Agent subcommands:
+  identity
+    init                         Initialize a lightweight local identity for ServiceNet publishing or wallet binding
+    show                         Show the local identity public DID and public key
+    export-seed                  Export the local identity seed; treat it like a password
+
+  wallet
+    create-payment-account       Create a local payment account for ServiceNet payment binding
+    import-payment-account       Import a local payment account for ServiceNet payment binding
+    watch-payment-account        Track a payment address without importing its private key
+    list-payment-accounts        List local payment accounts
+    bind-payment-account         Select the active local payment account
+    active-payment-account       Show the active local payment account
+
+  servicenet
+    agent-card init              Generate an editable agent-card.json template in the current directory
+    register --card <path-to-agent-card.json>
+                                 Register the agent card and local identity with ServiceNet; returns agent_id and provider_id
+    publish <agent-id>           Publish a registered ServiceNet agent using the agent_id returned by register
 
 Options:
   --version, -v          Alias for \`version\`
@@ -94,6 +109,15 @@ Options:
 `);
 }
 
+function throwCommandSuggestion(argv) {
+  if (argv[0] === "provider" && argv[1] === "register") {
+    throw new Error("Unknown command: provider register. Use `wattetheria servicenet register`.");
+  }
+  if (argv[0] === "register") {
+    throw new Error("Unknown command: register. Use `wattetheria servicenet register`.");
+  }
+}
+
 function parseArgs(argv) {
   let command = DEFAULT_COMMAND;
   let index = 0;
@@ -1291,11 +1315,25 @@ function bundledRustBinaryPath() {
 
 function missingNativeCliError(commandName) {
   const platformKey = nativePlatformKey() || `${process.platform}-${process.arch}`;
+  if (commandName === "identity" || commandName === "wallet") {
+    return new Error(
+      [
+        `Cannot run '${commandName}' because the Wattetheria native CLI for ${platformKey} was not found.`,
+        "",
+        "`wattetheria identity` and `wattetheria wallet` are lightweight local setup commands",
+        "for ServiceNet publishing and wallet binding. They do not require a local Wattetheria",
+        "node, but they do require the native CLI package for this system.",
+        "",
+        "Install the matching Wattetheria native CLI package, then retry."
+      ].join("\n")
+    );
+  }
+
   const deployment = deploymentState();
   if (deployment.installed) {
     return new Error(
       `Wattetheria node deployment was found at ${deployment.dir}, but this npm package does not include ` +
-        `the native publisher CLI for ${platformKey}. ` +
+        `the native CLI for ${platformKey}. ` +
         `Run 'npx wattetheria status' to check the installed node, or update the local node image.`
     );
   }
@@ -1306,6 +1344,103 @@ function missingNativeCliError(commandName) {
   );
 }
 
+function forwardedSubcommand(rawArgv) {
+  for (let index = 1; index < rawArgv.length; index += 1) {
+    const arg = rawArgv[index];
+    if (arg.startsWith("-")) {
+      if (!arg.includes("=")) {
+        index += 1;
+      }
+      continue;
+    }
+    return arg;
+  }
+  return "";
+}
+
+function isIdentityWriteCommand(commandName, rawArgv) {
+  return commandName === "identity" && forwardedSubcommand(rawArgv) === "init";
+}
+
+function isWalletWriteCommand(commandName, rawArgv) {
+  if (commandName !== "wallet") {
+    return false;
+  }
+  return new Set([
+    "create-payment-account",
+    "import-payment-account",
+    "watch-payment-account",
+    "bind-payment-account"
+  ]).has(forwardedSubcommand(rawArgv));
+}
+
+function installedNodeArtifacts(deployment = deploymentState()) {
+  return {
+    identityPath: path.join(deployment.stateDir, "identity.json"),
+    walletMetadataPath: path.join(deployment.stateDir, ".watt-wallet", "metadata.json"),
+    walletKeystorePath: path.join(deployment.stateDir, ".watt-wallet", "keystore.json")
+  };
+}
+
+function explicitDataDir(rawArgv) {
+  const option = parsePathOption(rawArgv, "--data-dir", 1);
+  if (!option) {
+    return "";
+  }
+  if (!option.value) {
+    throw new Error("Missing value for --data-dir");
+  }
+  return path.resolve(option.value);
+}
+
+function usesSeparateDataDir(rawArgv, deployment) {
+  const dataDir = explicitDataDir(rawArgv);
+  return Boolean(dataDir) && dataDir !== path.resolve(deployment.stateDir);
+}
+
+function ensureLightweightCommandAllowed(commandName, rawArgv) {
+  if (!(isIdentityWriteCommand(commandName, rawArgv) || isWalletWriteCommand(commandName, rawArgv))) {
+    return;
+  }
+  const deployment = deploymentState();
+  if (!deployment.installed || usesSeparateDataDir(rawArgv, deployment)) {
+    return;
+  }
+  const artifacts = installedNodeArtifacts(deployment);
+  if (isIdentityWriteCommand(commandName, rawArgv) && fs.existsSync(artifacts.identityPath)) {
+    throw new Error(
+      [
+        "Refusing to initialize a separate local identity.",
+        "",
+        "A local Wattetheria node is already installed and has an identity at:",
+        deployment.stateDir,
+        "",
+        "`wattetheria identity init` is only for lightweight local setup when no Wattetheria",
+        "node identity exists. Use the installed node's identity instead, or choose a separate",
+        "data directory only for isolated testing."
+      ].join("\n")
+    );
+  }
+  if (
+    isWalletWriteCommand(commandName, rawArgv)
+    && fs.existsSync(artifacts.walletMetadataPath)
+    && fs.existsSync(artifacts.walletKeystorePath)
+  ) {
+    throw new Error(
+      [
+        "Refusing to modify a separate local wallet.",
+        "",
+        "A local Wattetheria node is already installed and has wallet state at:",
+        deployment.stateDir,
+        "",
+        "`wattetheria wallet` setup commands are only for lightweight local setup when no",
+        "Wattetheria node wallet exists. Use the installed node's wallet instead, or choose a",
+        "separate data directory only for isolated testing."
+      ].join("\n")
+    );
+  }
+}
+
 function forwardedArgsForInstalledNode(commandName, rawArgv) {
   const args = [commandName];
   if (!rawArgv.some((arg) => arg === "--data-dir" || arg.startsWith("--data-dir="))) {
@@ -1315,6 +1450,158 @@ function forwardedArgsForInstalledNode(commandName, rawArgv) {
   return args;
 }
 
+function isServicenetAgentCardInit(commandName, rawArgv) {
+  return commandName === "servicenet"
+    && rawArgv[1] === "agent-card"
+    && rawArgv[2] === "init";
+}
+
+function isServicenetRegister(commandName, rawArgv) {
+  return commandName === "servicenet"
+    && rawArgv[1] === "register";
+}
+
+function isServicenetPublish(commandName, rawArgv) {
+  return commandName === "servicenet"
+    && rawArgv[1] === "publish";
+}
+
+function usesWorkspaceMount(commandName, rawArgv) {
+  return isServicenetAgentCardInit(commandName, rawArgv)
+    || isServicenetRegister(commandName, rawArgv)
+    || isServicenetPublish(commandName, rawArgv);
+}
+
+function findExistingAncestor(targetPath) {
+  let cursor = path.resolve(targetPath);
+  while (!fs.existsSync(cursor)) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      throw new Error(`No existing parent directory found for ${targetPath}`);
+    }
+    cursor = parent;
+  }
+  return cursor;
+}
+
+function toContainerPath(relativePath) {
+  if (!relativePath || relativePath === ".") {
+    return "/workspace";
+  }
+  return `/workspace/${relativePath.split(path.sep).join("/")}`;
+}
+
+function parsePathOption(rawArgv, optionName, startIndex) {
+  const equalsPrefix = `${optionName}=`;
+  for (let index = startIndex; index < rawArgv.length; index += 1) {
+    const arg = rawArgv[index];
+    if (arg === optionName) {
+      return { index, value: rawArgv[index + 1], style: "separate" };
+    }
+    if (arg.startsWith(equalsPrefix)) {
+      return { index, value: arg.slice(equalsPrefix.length), style: "equals" };
+    }
+  }
+  return null;
+}
+
+function pathMountFor(targetPath) {
+  const requestedPath = path.resolve(targetPath);
+  const existingPath = fs.existsSync(requestedPath) ? requestedPath : "";
+  const mountSource = existingPath
+    ? (
+      fs.statSync(existingPath).isDirectory()
+        ? existingPath
+        : path.dirname(existingPath)
+    )
+    : findExistingAncestor(requestedPath);
+  return {
+    mountSource,
+    containerPath: toContainerPath(path.relative(mountSource, requestedPath))
+  };
+}
+
+function rewritePathOption(rawArgv, parsedOption, containerPath) {
+  const rewrittenArgv = [...rawArgv];
+  if (parsedOption.style === "separate") {
+    rewrittenArgv[parsedOption.index + 1] = containerPath;
+  } else {
+    rewrittenArgv[parsedOption.index] = `${rewrittenArgv[parsedOption.index].split("=")[0]}=${containerPath}`;
+  }
+  return rewrittenArgv;
+}
+
+function dockerWorkspaceInvocation(commandName, rawArgv) {
+  if (isServicenetAgentCardInit(commandName, rawArgv)) {
+    const outputArg = parsePathOption(rawArgv, "--out", 3);
+    const outputPath = outputArg?.value || process.cwd();
+    if (outputArg && !outputArg.value) {
+      throw new Error("Missing value for --out");
+    }
+    const outputMount = pathMountFor(outputPath);
+    const rewrittenArgv = outputArg
+      ? rewritePathOption(rawArgv, outputArg, outputMount.containerPath)
+      : rawArgv;
+    return {
+      args: outputArg
+        ? forwardedArgsForInstalledNode(commandName, rewrittenArgv)
+        : [...forwardedArgsForInstalledNode(commandName, rawArgv), "--out", outputMount.containerPath],
+      mountSource: outputMount.mountSource
+    };
+  }
+
+  if (isServicenetRegister(commandName, rawArgv)) {
+    const cardArg = parsePathOption(rawArgv, "--card", 2);
+    if (!cardArg) {
+      return {
+        args: forwardedArgsForInstalledNode(commandName, rawArgv),
+        mountSource: process.cwd()
+      };
+    }
+    if (!cardArg.value) {
+      throw new Error("Missing value for --card");
+    }
+    const cardMount = pathMountFor(cardArg.value);
+    return {
+      args: forwardedArgsForInstalledNode(
+        commandName,
+        rewritePathOption(rawArgv, cardArg, cardMount.containerPath)
+      ),
+      mountSource: cardMount.mountSource
+    };
+  }
+
+  return {
+    args: forwardedArgsForInstalledNode(commandName, rawArgv),
+    mountSource: process.cwd()
+  };
+}
+
+function hostPathFromWorkspace(containerPath, mountSource) {
+  if (containerPath === "/workspace") {
+    return mountSource;
+  }
+  if (!containerPath.startsWith("/workspace/")) {
+    return containerPath;
+  }
+  return path.join(mountSource, containerPath.slice("/workspace/".length));
+}
+
+function rewriteWorkspaceJsonStdout(stdout, mountSource) {
+  if (!stdout.trim()) {
+    return stdout;
+  }
+  try {
+    const payload = JSON.parse(stdout);
+    if (typeof payload.card === "string") {
+      payload.card = hostPathFromWorkspace(payload.card, mountSource);
+    }
+    return `${JSON.stringify(payload, null, 2)}\n`;
+  } catch (_error) {
+    return stdout;
+  }
+}
+
 function runInstalledNodeCli(commandName, rawArgv, deployment) {
   const dockerCommand = resolveDockerCommand();
   if (!dockerCommand) {
@@ -1323,6 +1610,41 @@ function runInstalledNodeCli(commandName, rawArgv, deployment) {
         `to run '${commandName}' inside the installed node. Start Docker Desktop and retry.`
     );
   }
+  if (usesWorkspaceMount(commandName, rawArgv)) {
+    const invocation = dockerWorkspaceInvocation(commandName, rawArgv);
+    const result = spawnSync(
+      dockerCommand,
+      [
+        "compose",
+        "--project-name",
+        DEFAULT_PROJECT_NAME,
+        "--env-file",
+        deployment.envPath,
+        "-f",
+        deployment.composePath,
+        "run",
+        "--rm",
+        "--no-deps",
+        "-T",
+        "--entrypoint",
+        "/app/target/release/wattetheria-client-cli",
+        "-v",
+        `${invocation.mountSource}:/workspace`,
+        "-w",
+        "/workspace",
+        "kernel",
+        ...invocation.args
+      ],
+      { stdio: ["inherit", "pipe", "inherit"], encoding: "utf8" }
+    );
+    if (result.stdout) {
+      process.stdout.write(rewriteWorkspaceJsonStdout(result.stdout, invocation.mountSource));
+    }
+    if (typeof result.status === "number") {
+      process.exit(result.status);
+    }
+    throw result.error ?? new Error(`Failed to run '${commandName}' inside the installed node`);
+  }
   const result = spawnSync(
     dockerCommand,
     [
@@ -1348,6 +1670,8 @@ function runInstalledNodeCli(commandName, rawArgv, deployment) {
 }
 
 function forwardToRustBinary(commandName, rawArgv) {
+  ensureLightweightCommandAllowed(commandName, rawArgv);
+
   // Only the Rust binary name is allowed here. The bare `wattetheria` name
   // resolves to this JS shim on most user PATHs (via the npm bin link), so
   // including it would create an infinite spawn loop.
@@ -1374,6 +1698,9 @@ function forwardToRustBinary(commandName, rawArgv) {
   }
 
   const deployment = deploymentState();
+  if (commandName === "identity" || commandName === "wallet") {
+    throw missingNativeCliError(commandName);
+  }
   if (deployment.runnable) {
     runInstalledNodeCli(commandName, rawArgv, deployment);
     return;
@@ -1383,6 +1710,8 @@ function forwardToRustBinary(commandName, rawArgv) {
 }
 
 async function run(argv) {
+  throwCommandSuggestion(argv);
+
   if (argv[0] && FORWARDED_SUBCOMMANDS.has(argv[0])) {
     forwardToRustBinary(argv[0], argv);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wattetheria",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Wattetheria deployment CLI",
   "license": "Apache-2.0",
   "type": "commonjs",