polkadot-cli 1.22.0 → 1.23.0

package/README.md

@@ -81,6 +81,24 @@ To pull the latest skill updates:
 /plugin marketplace update polkadot-cli
 ```
 
+## Plugins
+
+`dot` supports git/cargo-style external subcommands: any executable named `dot-<name>` on your PATH runs as `dot <name>`, with the remaining arguments forwarded verbatim, stdio inherited, and the plugin's exit code passed through.
+
+```bash
+npm install -g dot-example     # ships a `dot-example` binary
+dot example status --json      # runs: dot-example status --json
+```
+
+This is how domain-specific tooling extends `dot` without the CLI loading third-party code into its own process. Plugins are ordinary child processes — the intended pattern is that a plugin invokes `dot` itself for anything chain- or signing-related (e.g. `dot tx.… --from <account>`), so key handling stays inside `dot`.
+
+Plugins receive a `DOT_BIN` environment variable pointing at the entry script of the `dot` that dispatched them (the same convention as cargo's `CARGO`), so they can invoke the exact same installation rather than whatever `dot` is first on PATH.
+
+Notes:
+
+- Only a bare first token dispatches: `dot foo.bar` is always dot-path syntax, `./file.yaml` is always file input — neither will hit the plugin lookup.
+- Built-in commands and categories always win over a plugin of the same name.
+
 ## Usage
 
 ### Manage chains
@@ -797,6 +815,8 @@ dot polkadot.const.Balances.ExistentialDeposit --json | jq
 
 Works offline from cached metadata after the first fetch. The chain is required. Prefer the chain-prefix-on-target form (`dot inspect polkadot.System`); `--chain` is equivalent. Note that `dot polkadot.inspect.X` does **not** parse — `inspect` is a top-level command, not a dotpath category.
 
+`inspect` is **forgiving**: it accepts the same dot-paths you use to invoke a call and degrades to discovery rather than erroring. A `kind` segment (`tx`/`query`/`const`/`events`/`errors`/…) is tolerated and ignored — so `dot inspect polkadot.tx.System.remark` describes the `System.remark` call just like `dot inspect polkadot.System.remark` does. Partial paths list rather than fail: `dot inspect polkadot.query.System` (and the bare `dot inspect System`) list the pallet's items.
+
 Output is **width-aware**: short type signatures stay on a single line, longer ones expand across multiple lines with field names aligned. Composite struct fields, enum variants, and call arguments are color-coded (cyan field names, yellow primitives, magenta container keywords like `Vec`/`Option`, green enum variants) when stdout is a TTY; piped output stays plain.
 
 ```bash

package/dist/cli.mjs

@@ -3819,8 +3819,8 @@ var exports_complete = {};
 __export(exports_complete, {
   generateCompletions: () => generateCompletions
 });
-function matchCategory2(s) {
-  return CATEGORY_ALIASES2[s.toLowerCase()];
+function matchCategory3(s) {
+  return CATEGORY_ALIASES3[s.toLowerCase()];
 }
 async function loadPallets(_config, chainName) {
   const raw = await loadMetadata(chainName);
@@ -3951,7 +3951,7 @@ function detectCategory(words, _knownChains) {
       continue;
     const parts = w.split(".");
     for (const part of parts) {
-      const cat = matchCategory2(part);
+      const cat = matchCategory3(part);
       if (cat)
         return cat;
     }
@@ -3973,11 +3973,11 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
     return filterPrefix(candidates, partial);
   }
   const first = completeSegments[0] ?? "";
-  const firstIsCategory = matchCategory2(first) !== undefined;
+  const firstIsCategory = matchCategory3(first) !== undefined;
   const firstIsChain = knownChains.some((c) => c.toLowerCase() === first.toLowerCase());
   const chainFromFlag = resolveChainFromArgs(precedingWords, config);
   if (firstIsCategory) {
-    const category = matchCategory2(first);
+    const category = matchCategory3(first);
     if (category === "apis") {
       return completeApisCategory(first, numComplete, endsWithDot, completeSegments, currentWord, config, chainFromFlag);
     }
@@ -4037,7 +4037,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
       return filterPrefix(candidates, currentWord);
     }
     if (numComplete === 2) {
-      const category = matchCategory2(completeSegments[1]);
+      const category = matchCategory3(completeSegments[1]);
       if (!category)
         return [];
       if (category === "apis") {
@@ -4058,7 +4058,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
       return filterPrefix(candidates, endsWithDot ? currentWord.slice(0, -1) : currentWord);
     }
     if (numComplete === 3) {
-      const category = matchCategory2(completeSegments[1]);
+      const category = matchCategory3(completeSegments[1]);
       if (!category)
         return [];
       if (category === "apis") {
@@ -4140,7 +4140,7 @@ async function completeRpcCategory(prefix, numComplete, endsWithDot, currentWord
   }
   return [];
 }
-var CATEGORIES2, CATEGORY_ALIASES2, NAMED_COMMANDS, CHAIN_SUBCOMMANDS, ACCOUNT_SUBCOMMANDS, GLOBAL_OPTIONS, TX_OPTIONS, QUERY_OPTIONS;
+var CATEGORIES2, CATEGORY_ALIASES3, NAMED_COMMANDS, CHAIN_SUBCOMMANDS, ACCOUNT_SUBCOMMANDS, GLOBAL_OPTIONS, TX_OPTIONS, QUERY_OPTIONS;
 var init_complete = __esm(() => {
   init_accounts_store();
   init_store();
@@ -4158,7 +4158,7 @@ var init_complete = __esm(() => {
     "extensions",
     "rpc"
   ];
-  CATEGORY_ALIASES2 = {
+  CATEGORY_ALIASES3 = {
     query: "query",
     tx: "tx",
     const: "const",
@@ -4216,7 +4216,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.22.0";
+var version = "1.23.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -6964,10 +6964,42 @@ init_output();
 init_pretty_type();
 init_cli();
 
+// src/utils/parse-dot-path.ts
+var CATEGORY_ALIASES = {
+  query: "query",
+  tx: "tx",
+  const: "const",
+  consts: "const",
+  constants: "const",
+  events: "events",
+  event: "events",
+  errors: "errors",
+  error: "errors",
+  apis: "apis",
+  api: "apis",
+  extensions: "extensions",
+  extension: "extensions",
+  ext: "extensions",
+  rpc: "rpc"
+};
+function matchCategory(segment) {
+  return CATEGORY_ALIASES[segment.toLowerCase()];
+}
+
 // src/utils/parse-target.ts
+function stripKindSegment(parts, knownChains) {
+  if (parts.length >= 3 && parts[0] && knownChains.some((c) => c.toLowerCase() === parts[0].toLowerCase()) && parts[1] && matchCategory(parts[1])) {
+    return [parts[0], ...parts.slice(2)];
+  }
+  if (parts.length >= 2 && parts[0] && matchCategory(parts[0])) {
+    return parts.slice(1);
+  }
+  return parts;
+}
 function parseTarget(input, options) {
-  const parts = input.split(".");
+  let parts = input.split(".");
   if (options?.allowPalletOnly) {
+    parts = stripKindSegment(parts, options.knownChains ?? []);
     switch (parts.length) {
       case 1:
         if (!parts[0]) {
@@ -6988,7 +7020,7 @@ function parseTarget(input, options) {
         }
         return { chain: parts[0], pallet: parts[1], item: parts[2] };
       default:
-        throw new Error(`Invalid target "${input}". Expected format: Pallet, Pallet.Item, or Chain.Pallet.Item`);
+        throw new Error(`Invalid target "${input}". Expected format: Pallet, Pallet.Item, Chain.Pallet.Item, ` + `or a dot-path with a kind segment (e.g. polkadot.tx.System.remark)`);
     }
   }
   switch (parts.length) {
@@ -9522,6 +9554,24 @@ function printGlobalDryRunHint() {
 `);
 }
 
+// src/core/external-command.ts
+var PLUGIN_PREFIX = "dot-";
+function isExternalCommandCandidate(name) {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name);
+}
+function findExternalCommand(name) {
+  if (!isExternalCommandCandidate(name))
+    return null;
+  return Bun.which(`${PLUGIN_PREFIX}${name}`, { PATH: process.env.PATH ?? "" });
+}
+function runExternalCommand(binPath, args) {
+  const result = Bun.spawnSync([binPath, ...args], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: { ...process.env, DOT_BIN: process.argv[1] ?? "dot" }
+  });
+  return result.exitCode ?? 1;
+}
+
 // src/core/file-loader.ts
 init_errors();
 import { access as access4, readFile as readFile7 } from "node:fs/promises";
@@ -9936,7 +9986,7 @@ function formatRuntimeError2(err) {
 }
 
 // src/utils/parse-dot-path.ts
-var CATEGORY_ALIASES = {
+var CATEGORY_ALIASES2 = {
   query: "query",
   tx: "tx",
   const: "const",
@@ -9953,8 +10003,8 @@ var CATEGORY_ALIASES = {
   ext: "extensions",
   rpc: "rpc"
 };
-function matchCategory(segment) {
-  return CATEGORY_ALIASES[segment.toLowerCase()];
+function matchCategory2(segment) {
+  return CATEGORY_ALIASES2[segment.toLowerCase()];
 }
 function matchChain(segment, knownChains) {
   return knownChains.some((c) => c.toLowerCase() === segment.toLowerCase());
@@ -9963,35 +10013,35 @@ function parseDotPath(input, knownChains = []) {
   const parts = input.split(".");
   switch (parts.length) {
     case 1: {
-      const cat = matchCategory(parts[0]);
+      const cat = matchCategory2(parts[0]);
       if (cat)
         return { category: cat };
       throw new Error(`Unknown command "${parts[0]}". Expected a category (query, tx, const, events, errors, apis, extensions, rpc) or a named command.`);
     }
     case 2: {
-      const cat = matchCategory(parts[0]);
+      const cat = matchCategory2(parts[0]);
       if (cat) {
         return { category: cat, pallet: parts[1] };
       }
-      const cat2 = matchCategory(parts[1]);
+      const cat2 = matchCategory2(parts[1]);
       if (cat2 && matchChain(parts[0], knownChains)) {
         return { chain: parts[0], category: cat2 };
       }
       throw new Error(`Unknown command "${input}". Expected format: category.Pallet or Chain.category (e.g. query.System or polkadot.query)`);
     }
     case 3: {
-      const cat = matchCategory(parts[0]);
+      const cat = matchCategory2(parts[0]);
       if (cat) {
         return { category: cat, pallet: parts[1], item: parts[2] };
       }
-      const cat2 = matchCategory(parts[1]);
+      const cat2 = matchCategory2(parts[1]);
       if (cat2 && matchChain(parts[0], knownChains)) {
         return { chain: parts[0], category: cat2, pallet: parts[2] };
       }
       throw new Error(`Unknown command "${input}". Expected format: category.Pallet.Item or Chain.category.Pallet`);
     }
     case 4: {
-      const cat = matchCategory(parts[1]);
+      const cat = matchCategory2(parts[1]);
       if (cat && matchChain(parts[0], knownChains)) {
         return { chain: parts[0], category: cat, pallet: parts[2], item: parts[3] };
       }
@@ -10082,6 +10132,9 @@ if (process.argv[2] === "__complete") {
     console.log("  init               Initialize a local .polkadot workspace in this directory");
     console.log("  which              Show the active config root (workspace, DOT_HOME, or global)");
     console.log();
+    console.log("Plugins:");
+    console.log('  dot <name> \u2026       Runs a "dot-<name>" executable found on PATH (git/cargo-style)');
+    console.log();
     console.log("Global options:");
     console.log("  --chain <name>     Target chain (required)");
     console.log("  --rpc <url>        Override RPC endpoint");
@@ -10175,7 +10228,14 @@ if (process.argv[2] === "__complete") {
     try {
       parsed = parseDotPath(dotpath, knownChains);
     } catch {
-      throw new CliError2(`Unknown command "${dotpath}". Run "dot --help" for available commands.`);
+      if (process.argv[2] === dotpath) {
+        const externalBin = findExternalCommand(dotpath);
+        if (externalBin) {
+          process.exit(runExternalCommand(externalBin, process.argv.slice(3)));
+        }
+      }
+      const pluginHint = isExternalCommandCandidate(dotpath) ? ` No "dot-${dotpath}" plugin found on PATH.` : "";
+      throw new CliError2(`Unknown command "${dotpath}". Run "dot --help" for available commands.${pluginHint}`);
     }
     const isFlatCategory = parsed.category === "rpc" || parsed.category === "extensions";
     if (!parsed.pallet && args.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {