@leemour/cli-messaging 0.139.0 → 0.140.0

package/README.md

@@ -1,7 +1,7 @@
 # @leemour/cli-messaging
 
 The messenger-neutral half of a messaging command line tool, shared by
-[`tg-cli`](https://github.com/leemour/tg-cli) and, later, [`max-cli`](https://github.com/leemour/max-cli).
+[`tg-cli`](https://github.com/leemour/tg-cli) and [`max-cli`](https://github.com/leemour/max-cli).
 Built on [`@leemour/cli-core`](https://github.com/leemour/cli-core), a peer dependency: the CLI installs
 it itself, so the install holds one copy.
 
@@ -48,6 +48,15 @@ Without support, a validated target returns `url: null`, `access: unavailable`,
 Offline validates this account's stored message and returns reason `offline`, without connecting.
 A locator for another messenger or account is refused. Singular `link` differs from graph `links`.
 
+## Command discovery
+
+To discover arguments without reading the whole command tree, run
+`<cli> commands messages evidence --json`. Replace the path with any command or group;
+`<cli> commands messages --json` includes its descendants. The response retains global options
+and exit codes, includes options inherited from ancestor groups, and resolves command aliases.
+Give one command path per call; inspect other groups in separate calls.
+`<cli> commands --json` still returns the full tree.
+
 ## Evidence packets for agents
 
 `prepareEvidencePacket` from `@leemour/cli-messaging/services` packages a message page that the

package/dist/cli/commands-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands-command.d.ts","sourceRoot":"","sources":["../../src/cli/commands-command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAI3C;;;GAGG;AACH,eAAO,MAAM,QAAQ,IAAI,CAAA;AAEzB;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAS,WAAW,KAAG,OA6B7C,CAAA"}
+{"version":3,"file":"commands-command.d.ts","sourceRoot":"","sources":["../../src/cli/commands-command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAI3C;;;GAGG;AACH,eAAO,MAAM,QAAQ,IAAI,CAAA;AAEzB;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAS,WAAW,KAAG,OAiC7C,CAAA"}

package/dist/cli/commands-command.js

@@ -1,4 +1,4 @@
-import { EXIT_CODES, GENERIC_FAILURE } from "@leemour/cli-core";
+import { CliError, EXIT_CODES, GENERIC_FAILURE } from "@leemour/cli-core";
 import { describeOptions, describeProgram, flatten } from "@leemour/cli-core/commands";
 import { Command } from "commander";
 import { outputFor } from "./context.js";
@@ -13,11 +13,14 @@ export const CONTRACT = 0;
  * settings file: which commands exist does not depend on whether this machine has logged in.
  */
 export const commandsCommand = (app) => new Command("commands")
-    .description("every command, option and exit code as JSON — what an agent reads instead of --help")
-    .action(function () {
+    .description("commands, options and exit codes as JSON — inspect one command path per call")
+    .argument("[path...]", "one command path, for example: messages search; inspect other groups in separate calls")
+    .action(function (path) {
     const root = rootOf(this);
     const { renderer, format } = outputFor(this);
-    const commands = describeProgram(root);
+    const all = describeProgram(root);
+    const scoped = path.length > 0 ? scopeOf(root, all, path) : undefined;
+    const commands = scoped ? [scoped.command] : all;
     if (format === "pretty") {
         renderer.result(flatten(commands).map(({ usage, summary, description, mutates, state }) => ({
             command: usage,
@@ -33,8 +36,34 @@ export const commandsCommand = (app) => new Command("commands")
         contract: CONTRACT,
         description: root.description(),
         globalOptions: describeOptions(root),
+        ...(scoped ? { scope: scoped.command.path, inheritedOptions: scoped.inheritedOptions } : {}),
         commands,
         exitCodes: { ok: 0, generic_failure: GENERIC_FAILURE, ...EXIT_CODES },
     });
 });
+const scopeOf = (root, all, path) => {
+    let parent = root;
+    let available = all;
+    let selected;
+    const inheritedOptions = [];
+    for (const word of path) {
+        const child = parent.commands.find((command) => command.name() === word || command.aliases().includes(word));
+        const described = child && available.find(({ name }) => name === child.name());
+        if (!child || !described) {
+            const prefix = selected?.path ?? [];
+            const choices = available.map(({ name }) => name);
+            throw new CliError("validation_error", `unknown command path "${path.join(" ")}" — inspect \`${[root.name(), "commands", ...prefix, "--json"].join(" ")}\`; ` +
+                (choices.length ? `available here: ${choices.join(", ")}. ` : "this command has no subcommands. ") +
+                `Give one command path per call, not a list of groups: \`${root.name()} commands messages --json\` ` +
+                `and \`${root.name()} commands chats --json\` are separate calls`, { path, at: word, available: choices });
+        }
+        if (selected && selected.options.length > 0) {
+            inheritedOptions.push({ path: selected.path, options: [...selected.options] });
+        }
+        selected = described;
+        parent = child;
+        available = described.commands;
+    }
+    return { command: selected, inheritedOptions };
+};
 //# sourceMappingURL=commands-command.js.map

package/dist/cli/commands-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"commands-command.js","sourceRoot":"","sources":["../../src/cli/commands-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AACtF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAA;AAEzB;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAgB,EAAW,EAAE,CAC3D,IAAI,OAAO,CAAC,UAAU,CAAC;KACpB,WAAW,CAAC,qFAAqF,CAAC;KAClG,MAAM,CAAC;IACN,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;IACzB,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC5C,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;IAEtC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,QAAQ,CAAC,MAAM,CACb,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;YAC1E,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,OAAO,IAAI,WAAW;YACnC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;YAC5B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5B,CAAC,CAAC,CACJ,CAAA;QACD,OAAM;IACR,CAAC;IAED,QAAQ,CAAC,MAAM,CAAC;QACd,GAAG,EAAE,GAAG,CAAC,OAAO;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,QAAQ;QAClB,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;QAC/B,aAAa,EAAE,eAAe,CAAC,IAAI,CAAC;QACpC,QAAQ;QACR,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,eAAe,EAAE,eAAe,EAAE,GAAG,UAAU,EAAE;KACtE,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}
+{"version":3,"file":"commands-command.js","sourceRoot":"","sources":["../../src/cli/commands-command.ts"],"names":[],"mappings":"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"}

package/dist/store/driver.d.ts

@@ -34,5 +34,5 @@ export type OpenDatabase = (path: string) => CacheDatabase;
  *
  * `foreign_keys` is off by default in SQLite, which surprises everyone once.
  */
-export declare const PRAGMAS = "\n  PRAGMA journal_mode = WAL;\n  PRAGMA busy_timeout = 5000;\n  PRAGMA foreign_keys = ON;\n";
+export declare const PRAGMAS = "\n  PRAGMA busy_timeout = 5000;\n  PRAGMA journal_mode = WAL;\n  PRAGMA foreign_keys = ON;\n";
 //# sourceMappingURL=driver.d.ts.map

package/dist/store/driver.js

@@ -19,8 +19,8 @@
  * `foreign_keys` is off by default in SQLite, which surprises everyone once.
  */
 export const PRAGMAS = `
-  PRAGMA journal_mode = WAL;
   PRAGMA busy_timeout = 5000;
+  PRAGMA journal_mode = WAL;
   PRAGMA foreign_keys = ON;
 `;
 //# sourceMappingURL=driver.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leemour/cli-messaging",
-  "version": "0.139.0",
+  "version": "0.140.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "MIT",
   "author": "Viacheslav Ptsarev",

package/parity.json

@@ -1589,8 +1589,7 @@
       }
     },
     "messages link": {
-      "in": [],
-      "planned": { "max": "B1c feat/messages-link", "tg": "B1c feat/messages-link" }
+      "in": "all"
     },
     "messages links": {
       "in": "all"