@wirecat/cli-core 0.442.0 → 0.443.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ shape of this file.
 
 ## Unreleased
 
+## 0.443.0 — 26.10.2026
+
+### Added
+
+- **`signInSteps` and `answerStdinOption` (`@wirecat/cli-core/cli`): a sign-in a window can drive.** With `--json`, a
+  tool prints each step of its sign-in as one JSON line on stderr: `open_url` (a page to open), `pairing_code` (a code
+  to type into the phone), `progress`, and `needs` (`field`, `secret`, `prompt`, `hint`), whose answer is one line on
+  stdin. A QR code stays `loginQr`'s `qr` line. Reading answers is opt-in, `--answer-stdin`, and needs `--json`:
+  without it a run with no terminal still refuses, so an agent's shell never waits on a question. One reader serves
+  the whole run, a question can be withdrawn when the answer came another way (a browser callback), stdin is let go
+  between questions so the tool ends with its work, and an answer is never printed or kept in a run record.
+
 ## 0.442.0 — 26.10.2026
 
 ### Security

package/dist/cli/index.d.ts

@@ -37,6 +37,7 @@ export { maskedAccount } from "../services/people.js";
 export { unanswered } from "../services/questions.js";
 export { openRequestTask } from "../services/task-rules.js";
 export { TASK_PAIR_QUERY, TASK_QUERY } from "../services/tasks.js";
+export { answerStdinOption, type Need, type SignInSteps, type SignInStepsOptions, signInSteps, } from "../terminal/sign-in-steps.js";
 export { type AgentPolicy, type AgentTask, type EvaluationResult, evaluateAgent, type Observation, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
 export type { ApiCommandInput, ApiCommands } from "./bot/api.js";

package/dist/cli/index.js

@@ -32,6 +32,7 @@ export { maskedAccount } from "../services/people.js";
 export { unanswered } from "../services/questions.js";
 export { openRequestTask } from "../services/task-rules.js";
 export { TASK_PAIR_QUERY, TASK_QUERY } from "../services/tasks.js";
+export { answerStdinOption, signInSteps, } from "../terminal/sign-in-steps.js";
 export { evaluateAgent, } from "./agent-evaluation.js";
 export { answerEntity } from "./answer-entity.js";
 export { apiFlagOf, apiJson, apiOptionKey, apiPlainJson, checkApiBody, checkApiParameter, parseApiJson, readApiBody, } from "./bot/api-input.js";

package/dist/terminal/sign-in-steps.d.ts

@@ -0,0 +1,38 @@
+import { Option } from "commander";
+/**
+ * Opt-in, because a read nobody answers hangs: an agent running `session start` in a shell must get the refusal it
+ * gets today, and only a caller that holds stdin open and answers each `needs` line (WireCat Desktop) passes it.
+ */
+export declare const answerStdinOption: () => Option;
+export interface Need {
+    /** What is asked, for the caller to pick a field: `phone`, `code`, `password`, `api_id`, `api_hash`, `token`, `redirect`… */
+    field: string;
+    /** Shown masked and never echoed. */
+    secret: boolean;
+    prompt: string;
+    hint?: string | undefined;
+}
+export interface SignInStepsOptions {
+    /** Writes one whole line to the diagnostic stream; stdout keeps only the answer. */
+    diagnostic: (line: string) => void;
+    /** Machine output (`--json`, `--jsonl`): only then are the steps printed. */
+    json: boolean;
+    /** `--answer-stdin`. */
+    answers: boolean;
+    input?: NodeJS.ReadableStream;
+}
+/**
+ * A sign-in told as JSON lines on the diagnostic stream, for a window to draw instead of a terminal: `open_url`,
+ * `pairing_code`, `progress`, and `needs`, whose answer is one line on stdin. A QR code is `loginQr`'s `qr` line.
+ */
+export interface SignInSteps {
+    readonly json: boolean;
+    /** Whether `ask` reads answers from stdin; tools keep their own terminal prompt otherwise. */
+    readonly answers: boolean;
+    openUrl: (url: string, purpose: string) => void;
+    pairingCode: (code: string, where: string, expiresAt?: Date) => void;
+    progress: (step: string, message: string) => void;
+    /** A `signal` that aborts withdraws the question: the caller got its answer another way (a browser callback). */
+    ask: (need: Need, signal?: AbortSignal) => Promise<string>;
+}
+export declare const signInSteps: ({ diagnostic, json, answers, input }: SignInStepsOptions) => SignInSteps;

package/dist/terminal/sign-in-steps.js

@@ -0,0 +1,87 @@
+import { StringDecoder } from "node:string_decoder";
+import { CliError } from "@wirecat/cli-base";
+import { Option } from "commander";
+import { MAX_SECRET_INPUT } from "../cli/input-policy.js";
+/**
+ * Opt-in, because a read nobody answers hangs: an agent running `session start` in a shell must get the refusal it
+ * gets today, and only a caller that holds stdin open and answers each `needs` line (WireCat Desktop) passes it.
+ */
+export const answerStdinOption = () => new Option("--answer-stdin", "with --json and no terminal: print each question as a `needs` line on stderr and read its answer, one line, from stdin");
+export const signInSteps = ({ diagnostic, json, answers, input = process.stdin }) => {
+    if (answers && !json)
+        throw new CliError("validation_error", "--answer-stdin needs --json");
+    const emit = (event) => {
+        if (json)
+            diagnostic(JSON.stringify(event));
+    };
+    const next = answers ? lineReader(input) : undefined;
+    return {
+        json,
+        answers,
+        openUrl: (url, purpose) => emit({ event: "open_url", url, purpose }),
+        pairingCode: (code, where, expiresAt) => emit({ event: "pairing_code", code, where, expires_at: expiresAt?.toISOString() ?? null }),
+        progress: (step, message) => emit({ event: "progress", step, message }),
+        ask: async ({ field, secret, prompt, hint }, signal) => {
+            if (!next)
+                throw new CliError("validation_error", `the ${prompt} must be typed at a terminal`, {
+                    reason: "input.required",
+                });
+            signal?.throwIfAborted();
+            emit({ event: "needs", field, secret, prompt, hint: hint ?? null });
+            return await next(signal);
+        },
+    };
+};
+/**
+ * One reader for the whole run, so a second answer that arrived with the first is not lost. It reads only while a
+ * question waits and pauses stdin between them, so a pipe the caller keeps open does not hold the process after the
+ * last answer.
+ */
+const lineReader = (input) => {
+    const decoder = new StringDecoder("utf8");
+    let buffered = "";
+    let ended = false;
+    return (signal) => new Promise((resolve, reject) => {
+        const cleanup = () => {
+            input.off("data", data).off("end", end).off("error", fail);
+            signal?.removeEventListener("abort", aborted);
+            input.pause();
+            // A paused pipe still holds the event loop; the tool must end once its work is done.
+            input.unref?.();
+        };
+        const fail = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const take = () => {
+            const at = buffered.indexOf("\n");
+            if (at < 0)
+                return false;
+            const line = buffered.slice(0, at).replace(/\r$/, "");
+            buffered = buffered.slice(at + 1);
+            cleanup();
+            resolve(line.trim());
+            return true;
+        };
+        const data = (chunk) => {
+            buffered += typeof chunk === "string" ? chunk : decoder.write(chunk);
+            if (take())
+                return;
+            if (buffered.length > MAX_SECRET_INPUT)
+                fail(new CliError("validation_error", "the answer exceeds its byte limit", { reason: "input.too-large" }));
+        };
+        const end = () => {
+            ended = true;
+            fail(new CliError("cancelled", "the input closed before the answer came", { reason: "input.closed" }));
+        };
+        const aborted = () => fail(signal?.reason ?? new CliError("cancelled", "cancelled"));
+        if (take())
+            return;
+        if (ended)
+            return end();
+        input.on("data", data).once("end", end).once("error", fail);
+        signal?.addEventListener("abort", aborted, { once: true });
+        input.ref?.();
+        input.resume();
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.442.0",
+  "version": "0.443.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",