@wirecat/cli-core 0.371.0 → 0.372.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ shape of this file.
 
 ## Unreleased
 
+## 0.372.0 — 20.10.2026
+
+### Added
+
+- **Setup wizard helpers from `./cli`**: `AGENTS`, `type Agent`, `screenFor(context, quiet, steps)` and
+  `agentFor(context, given, pad, prompt?)`, for the `setup` command of a messenger CLI. `screenFor` prints the
+  numbered step headings (`[2/5] …`, details indented by 6) to stderr for a person, hides them under `--quiet`,
+  and keeps plain notes in a machine mode. `agentFor` asks which agent to install only at a terminal in the pretty
+  format and answers `none` otherwise; an unknown answer is a `validation_error`. Both take the minimum shape they
+  read (`format`, `streams.diagnostic`, `renderer.note`, `stdin`), so tg-cli's and whatsapp-cli's contexts fit as they
+  are. Pass the wizard's step count as `steps`, and the prompt's `input`, `output` and `signal` as `prompt`
+  (`secretInputOf(command)` plus the signal, or `{ input: context.stdin }`). No profile or agent is chosen for the
+  caller. This replaces the copies in both CLIs' `src/commands/setup.ts`.
+- **`restartServers(app, script, env, spawn?)` from `./cli`** restarts the `serve` of every profile that is running,
+  with `<script> <profile> server restart`, and answers `{ restarted, left }`: the shape `upgradeCommand`'s
+  `afterUpdate` port returns, so `afterUpdate: () => restartServers(app, script, env, environment.spawn)` is the whole
+  host side. `script` is the new install's own entry point; `spawn` replaces the child process in a test. A serve started
+  by hand refuses the restart and lands in `left`. This replaces the copies in both CLIs' `src/commands/update.ts` and
+  `src/update.ts`.
+- **`ARGV_LOG` and `argvLogSetup` from `./testing`**: the path `coverage/argv.jsonl` under the working directory, and
+  a vitest `globalSetup` function that clears it, for the test matrix that checks which commands and options a run
+  drove. A CLI's own `src/testing/argv-log.ts` can go. Vitest takes a package specifier as `globalSetup` only with a
+  named `setup` or a default export, so keep a one-line file: `export { argvLogSetup as default } from
+  "@wirecat/cli-core/testing"`.
+
 ## 0.371.0 — 20.10.2026
 
 ### Added

package/dist/cli/index.d.ts

@@ -127,7 +127,8 @@ export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOpt
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
+export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";
 export { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
-export { type UpgradeContext, upgradeCommand } from "./upgrade-command.js";
+export { restartServers, type UpgradeContext, upgradeCommand } from "./upgrade-command.js";

package/dist/cli/index.js

@@ -122,7 +122,8 @@ export { createProgram, run } from "./program.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { count, first, flag, fromFile, NONE_NAMED, plain, settingsFor, } from "./settings.js";
+export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";
 export { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
-export { upgradeCommand } from "./upgrade-command.js";
+export { restartServers, upgradeCommand } from "./upgrade-command.js";

package/dist/cli/setup-screen.d.ts

@@ -0,0 +1,25 @@
+import { type Renderer, type RenderFormat, type Streams } from "@wirecat/cli-base";
+import { type SecretInput } from "../terminal/prompt.js";
+export declare const AGENTS: readonly ["none", "codex", "cursor", "claude", "gemini", "all"];
+export type Agent = (typeof AGENTS)[number];
+/**
+ * A person sees each step as a heading with its details indented under it. `--quiet` hides both, as it
+ * hides notes; a machine mode keeps the plain notes it always had, since stderr there is a log.
+ */
+export declare const screenFor: (context: {
+    format: RenderFormat;
+    streams: Pick<Streams, "diagnostic">;
+    renderer: Pick<Renderer, "note">;
+}, quiet: boolean, steps: number) => {
+    step: (index: number, title: string) => void;
+    detail: (text: string) => void;
+    title: (text: string) => void;
+    indent: number;
+};
+/** Asks only a person at a terminal; every other run gets "none", so no agent is ever installed unasked. */
+export declare const agentFor: (context: {
+    format: RenderFormat;
+    stdin: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+}, given: Agent | undefined, pad: number, prompt?: Pick<SecretInput, "input" | "output" | "signal">) => Promise<Agent>;

package/dist/cli/setup-screen.js

@@ -0,0 +1,39 @@
+import { CliError, indent } from "@wirecat/cli-base";
+import { readSecret } from "../terminal/prompt.js";
+import { inputPolicy } from "./input-policy.js";
+export const AGENTS = ["none", "codex", "cursor", "claude", "gemini", "all"];
+const DETAIL = 6;
+/**
+ * A person sees each step as a heading with its details indented under it. `--quiet` hides both, as it
+ * hides notes; a machine mode keeps the plain notes it always had, since stderr there is a log.
+ */
+export const screenFor = (context, quiet, steps) => {
+    const person = context.format === "pretty";
+    const say = (text) => {
+        if (!quiet)
+            context.streams.diagnostic(text);
+    };
+    return {
+        step: (index, title) => person ? say(`\n[${index}/${steps}] ${title}`) : context.renderer.note(`${index}/${steps} — ${title}`),
+        detail: (text) => (person ? say(indent(text, DETAIL)) : context.renderer.note(text)),
+        title: (text) => (person ? say(text) : context.renderer.note(text)),
+        indent: person ? DETAIL : 0,
+    };
+};
+/** Asks only a person at a terminal; every other run gets "none", so no agent is ever installed unasked. */
+export const agentFor = async (context, given, pad, prompt = {}) => {
+    if (given)
+        return given;
+    if (context.format !== "pretty" || !context.stdin.isTTY || inputPolicy(context.stdin).noInput)
+        return "none";
+    const answer = (await readSecret(`${" ".repeat(pad)}Agent [codex/cursor/claude/gemini/all/none] (none): `, {
+        ...prompt,
+        echo: true,
+    }))
+        .trim()
+        .toLowerCase() || "none";
+    const agent = AGENTS.find((known) => known === answer);
+    if (agent === undefined)
+        throw new CliError("validation_error", `unknown agent — choose ${AGENTS.join(", ")} with --agent`);
+    return agent;
+};

package/dist/cli/upgrade-command.d.ts

@@ -7,4 +7,13 @@ export interface UpgradeContext extends Omit<PackageUpgradePorts, "onInstall"> {
     format: RenderFormat;
     streams: Streams;
 }
+/**
+ * A running serve keeps the code it started with; the update replaced the files under it. Each is restarted by
+ * the new `script` — `server restart` refuses a serve started by hand, which is then named in `left`.
+ * `spawn` replaces the child process, as in `UpdateEnvironment`.
+ */
+export declare const restartServers: (app: AppIdentity, script: string, env: NodeJS.ProcessEnv, spawn?: (argv: string[]) => number) => {
+    restarted: string[];
+    left: string[];
+};
 export declare const upgradeCommand: (app: AppIdentity, packageName: string, contextFor: (command: Command) => UpgradeContext) => Command;

package/dist/cli/upgrade-command.js

@@ -1,9 +1,35 @@
+import { spawnSync } from "node:child_process";
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
+import { servingProfiles } from "../background/lock.js";
 import { upgradePackage } from "../services/package-upgrade.js";
 import { grantsAuthority, LOCAL_WRITE } from "./effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
+import { usableProfileName } from "./profile.js";
+/**
+ * A running serve keeps the code it started with; the update replaced the files under it. Each is restarted by
+ * the new `script` — `server restart` refuses a serve started by hand, which is then named in `left`.
+ * `spawn` replaces the child process, as in `UpdateEnvironment`.
+ */
+export const restartServers = (app, script, env, spawn) => {
+    const restarted = [];
+    const left = [];
+    for (const profile of servingProfiles(app, env)) {
+        try {
+            usableProfileName(profile);
+        }
+        catch {
+            continue;
+        }
+        const argv = [script, profile, "server", "restart"];
+        const code = spawn
+            ? spawn([process.execPath, ...argv])
+            : (spawnSync(process.execPath, argv, { env, shell: false, stdio: ["ignore", 2, 2] }).status ?? 1);
+        (code === 0 ? restarted : left).push(profile);
+    }
+    return { restarted, left };
+};
 export const upgradeCommand = (app, packageName, contextFor) => grantsAuthority(annotate(new Command("upgrade"), {
     effects: LOCAL_WRITE,
     mcp: false,

package/dist/kit/argv-log.d.ts

@@ -0,0 +1,4 @@
+/** Where each test run records which commands and options it drove (`pnpm test:matrix`). */
+export declare const ARGV_LOG: string;
+/** A vitest `globalSetup`: one run, one log. */
+export declare const argvLogSetup: () => void;

package/dist/kit/argv-log.js

@@ -0,0 +1,9 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/** Where each test run records which commands and options it drove (`pnpm test:matrix`). */
+export const ARGV_LOG = join(process.cwd(), "coverage", "argv.jsonl");
+/** A vitest `globalSetup`: one run, one log. */
+export const argvLogSetup = () => {
+    mkdirSync(join(process.cwd(), "coverage"), { recursive: true });
+    rmSync(ARGV_LOG, { force: true });
+};

package/dist/kit/index.d.ts

@@ -1,3 +1,4 @@
+export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { type ContractCase, type ContractOptions, contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { type FakeAdapter, fakeAdapter } from "./fake.js";
 export { type McpStdio, type McpStdioStreams, type McpToolResult, mcpOverStdio } from "./mcp-stdio.js";

package/dist/kit/index.js

@@ -1,3 +1,4 @@
+export { ARGV_LOG, argvLogSetup } from "./argv-log.js";
 export { contractCases, OPTIONAL_METHODS } from "./contract.js";
 export { fakeAdapter } from "./fake.js";
 export { mcpOverStdio } from "./mcp-stdio.js";

package/package.json

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