@wirecat/cli-core 0.346.0 → 0.347.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ shape of this file.
 
 ## Unreleased
 
+## 0.347.0 — 18.10.2026
+
+### Added
+
+- **`loginQr` shows a login QR code the same way in every messenger CLI**: drawn on the diagnostic stream, which
+  `--quiet` does not hide, or written to the `--qr-file` PNG with `writeSecurely` (a temporary file created with
+  mode `0600`, renamed over the path, never chmodded afterwards). On a terminal too narrow for the code it draws
+  nothing and says to widen the terminal or pass `--qr-file`; it opens nothing. `close()` removes the image it
+  wrote, never a file it did not. `qrNeedsTerminal(command)` is the shared refusal when nobody could scan, and
+  `atTerminal(input)` the shared test. `parity.json` plans `--qr-file` on `session start` and `setup` for max, beside tg and wa.
+
+### Fixed
+
+- **A list that takes a query prints its help for `--help`.** Since 0.343.0, `chats list --help`, `tasks list --help`,
+  `contacts list --help` and every other list with `[query...]` refused `--help` as a mistyped option (exit 2), because
+  commander looks for it only after the query check had run. A mistyped `--limt` is still refused.
+- **`help` and `guide` need no permission key**: `keyForCommand` returned nothing for them, so a tool that maps every
+  command to a key (max) crashed on `help options`. They are housekeeping now, like `commands` and `skill`.
+- **`parity.json` has a `guide` row**, planned for max, tg and wa, so `cli-core-parity` stops failing a tool that
+  mounts it with "guide: not in the manifest".
+
 ## 0.346.0 — 18.10.2026
 
 ### Added

package/dist/index.d.ts

@@ -22,5 +22,6 @@ export { defaultRules, ModerationRules, moderationPathFor } from "./moderation/r
 export { type OutputOptions, resolveOutput } from "./output.js";
 export { pollLines, type RenderOptions, renderMessage, renderMessages } from "./render/messages.js";
 export { isId, type PeopleLookup, pickChat, pickPerson } from "./resolve.js";
+export { atTerminal, type LoginQr, type LoginQrOptions, loginQr, qrNeedsTerminal, } from "./terminal/login-qr.js";
 export { readSecret, type SecretInput } from "./terminal/prompt.js";
 export { qrPng, terminalQr } from "./terminal/qr.js";

package/dist/index.js

@@ -15,5 +15,6 @@ export { defaultRules, ModerationRules, moderationPathFor } from "./moderation/r
 export { resolveOutput } from "./output.js";
 export { pollLines, renderMessage, renderMessages } from "./render/messages.js";
 export { isId, pickChat, pickPerson } from "./resolve.js";
+export { atTerminal, loginQr, qrNeedsTerminal, } from "./terminal/login-qr.js";
 export { readSecret } from "./terminal/prompt.js";
 export { qrPng, terminalQr } from "./terminal/qr.js";

package/dist/meetings/cli/query-options.js

@@ -8,7 +8,11 @@ export const queryWordsAfterOptions = (command) => {
     command.parseOptions = (args) => {
         const parsed = parse(args);
         const end = parsed.unknown.indexOf("--");
-        const typo = parsed.unknown.slice(0, end < 0 ? undefined : end).find((word) => word.startsWith("--"));
+        // Commander looks for --help in what parseOptions leaves unknown, after it returns.
+        const help = command._getHelpOption();
+        const typo = parsed.unknown
+            .slice(0, end < 0 ? undefined : end)
+            .find((word) => word.startsWith("--") && !help?.is(word));
         if (typo !== undefined) {
             command.allowUnknownOption(false);
             command.unknownOption(typo);

package/dist/sends/permissions.js

@@ -341,6 +341,8 @@ export const WRITE_KEYS = [
 ];
 /** Commands that look after the tool and its files and never show a message: no level stops them. */
 const HOUSEKEEPING = new Set([
+    "help",
+    "guide",
     "config",
     "session",
     "doctor",

package/dist/terminal/login-qr.d.ts

@@ -0,0 +1,27 @@
+import { CliError } from "@wirecat/cli-base";
+/** Whether a person can scan a code drawn here and answer what the login asks next. */
+export declare const atTerminal: (input: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}) => boolean;
+/** The one refusal of a QR login that nobody could scan. */
+export declare const qrNeedsTerminal: (command: string) => CliError;
+export interface LoginQrOptions {
+    /** `--qr-file`: the PNG to write instead of drawing the code. */
+    qrFile?: string;
+    /** Where the code and the narrow-terminal hint go; `--quiet` must not hide either. */
+    diagnostic: (text: string) => void;
+    /** Where the file's location is said. */
+    note: (text: string) => void;
+    /** How far the code sits right, to line up under a setup step. */
+    indent?: number;
+    /** Read on every code, so a widened terminal draws the next one. Unknown draws the code. */
+    columns?: () => number | undefined;
+}
+export interface LoginQr {
+    readonly path: string | undefined;
+    /** Never throws for a code that does not fit: the messengers call it from inside their own event loops. */
+    show: (link: string) => void;
+    /** The image logs the account in while it is valid; call this in `finally`. */
+    close: () => void;
+}
+export declare const loginQr: ({ qrFile, diagnostic, note, indent: pad, columns, }: LoginQrOptions) => LoginQr;

package/dist/terminal/login-qr.js

@@ -0,0 +1,44 @@
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { CliError, indent, writeSecurely } from "@wirecat/cli-base";
+import { inputPolicy } from "../cli/input-policy.js";
+import { qrPng, terminalQr } from "./qr.js";
+const MARGIN = 2;
+/** Whether a person can scan a code drawn here and answer what the login asks next. */
+export const atTerminal = (input) => input.isTTY === true && !inputPolicy(input).noInput;
+/** The one refusal of a QR login that nobody could scan. */
+export const qrNeedsTerminal = (command) => new CliError("validation_error", `${command} shows a QR code to scan — run it in a terminal, or pass --qr-file <png>`, {
+    param: "--qr-file",
+    reason: "input.required",
+});
+export const loginQr = ({ qrFile, diagnostic, note, indent: pad = 0, columns = () => process.stderr.columns, }) => {
+    const path = qrFile === undefined ? undefined : resolve(qrFile);
+    // Only what this login wrote is removed: a refused or never-reached write leaves the owner's file alone.
+    let written = false;
+    return {
+        path,
+        show: (link) => {
+            if (path) {
+                writeSecurely(path, qrPng(link), 0o600);
+                written = true;
+                note(`the QR code is in ${path} — it is replaced when the code renews`);
+                return;
+            }
+            const drawn = terminalQr(link);
+            const need = drawn.width + pad + MARGIN;
+            const width = columns();
+            if (width !== undefined && need > width) {
+                diagnostic(`the terminal is ${width} columns wide and the QR code needs ${need} — widen it, ` +
+                    "or run again with --qr-file <png>");
+                return;
+            }
+            diagnostic(`\n${indent(drawn.text, pad + MARGIN)}`);
+        },
+        close: () => {
+            if (!path || !written)
+                return;
+            written = false;
+            rmSync(path, { force: true });
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.346.0",
+  "version": "0.347.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": "Apache-2.0",
   "author": "Viacheslav Ptsarev",

package/parity.json

@@ -2847,6 +2847,14 @@
         "wa": "wa backlog: mount the shared flood command"
       }
     },
+    "guide": {
+      "in": [],
+      "planned": {
+        "max": "help-navigation pass: max-cli#737 mounts guide with scenarios",
+        "tg": "help-navigation pass: mount guide with scenarios",
+        "wa": "help-navigation pass: mount guide with scenarios"
+      }
+    },
     "images": {
       "in": "all"
     },
@@ -4047,7 +4055,9 @@
         },
         "--qr-file": {
           "in": ["tg", "wa"],
-          "reason": "ruled tg-only with the app registration it belongs to"
+          "planned": {
+            "max": "max-cli#736, on the cli-core release that exports loginQr"
+          }
         },
         "--sms": {
           "in": ["tg"],
@@ -4066,7 +4076,9 @@
         "--method": "all",
         "--qr-file": {
           "in": ["tg", "wa"],
-          "reason": "Telegram can expose its temporary QR login token as a PNG"
+          "planned": {
+            "max": "max-cli#736, on the cli-core release that exports loginQr"
+          }
         }
       }
     },