@wirecat/cli-core 0.504.0 → 0.505.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ shape of this file.
 
 ## Unreleased
 
+## 0.505.0 — 31.10.2026
+
+### Added
+
+- **`appDoctorCommand` takes `--online`, and a messenger's and an app's `doctor` now say one thing.** Both use the
+  summary "the state this installation is in, without connecting unless --online" and the option text "also connect
+  once and read the account; sends nothing" (one constant, `doctor-text.ts`). Without the flag the answer is as before
+  and nothing is called. With it, `online` joins the answer: `{ ok, duration_ms, version: { current, latest, newer } }`,
+  plus the fields of the new `AppDoctorOptions.online(env)` hook, where a CLI checks its own service (a login, a folder
+  read); a throw there is `ok: false` with `error_code` and `error`, never a failed command. `version` comes from npm
+  (the `latestVersion` that `upgrade` uses) when the CLI passes the new `AppDoctorOptions.packageName`; without it that
+  check is left out. The command's effects are now `REMOTE_READ`, as the messenger's.
+
 ## 0.504.0 — 31.10.2026
 
 ### Added

package/dist/cli/app-doctor-command.d.ts

@@ -9,6 +9,15 @@ export interface AppDoctorOptions {
     oauthClient?: (env: NodeJS.ProcessEnv) => {
         client: "wirecat" | "own";
     };
+    /** The npm package, so `--online` can say whether a newer version is published; without it that check is left out. */
+    packageName?: string;
+    /**
+     * What `--online` checks of the service: a login, a folder read. Its fields join the `online` answer, and `ok: false`
+     * (or a throw, reported as `error_code` and `error`) makes the whole check fail without failing the command.
+     */
+    online?: (env: NodeJS.ProcessEnv) => Promise<{
+        ok: boolean;
+    } & Record<string, unknown>>;
 }
 /**
  * Run when everything else is broken, so a problem in the config file or the OAuth setting is a field, never a throw.
@@ -103,5 +112,9 @@ export declare const appDoctorReport: (app: AppIdentity, configuration: Configur
     };
     fixes: string[] | never[];
 };
-/** `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`. */
+/**
+ * `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`, and both
+ * say the same thing: the state from disk, and only with `--online` a call out. Here that call is `options.online`
+ * and, with `options.packageName`, whether npm has a newer version.
+ */
 export declare const appDoctorCommand: (app: AppIdentity, configuration: Configuration, options?: AppDoctorOptions) => Command;

package/dist/cli/app-doctor-command.js

@@ -2,15 +2,48 @@ import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { CliError, configFilePath, resolvePaths } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
+import { isNewer, latestVersion } from "@wirecat/cli-base/update";
 import { Command } from "commander";
 import { envName, readOnlyLockOf } from "../ports/app.js";
 import { storePath } from "../store/path.js";
 import { environmentOf, outputFor } from "./context.js";
-import { LOCAL_READ } from "./effects.js";
+import { DOCTOR_ONLINE_OPTION, DOCTOR_SUMMARY } from "./doctor-text.js";
+import { REMOTE_READ } from "./effects.js";
 import { itemOf, renderAnswer } from "./envelope.js";
 import { privateFiles } from "./messenger/private-files.js";
 import { unknownPermissionIssues } from "./permission-keys.js";
 import { profileFree } from "./profile.js";
+const onlineCheck = async (app, env, fetcher, options) => {
+    const started = Date.now();
+    let service = { ok: true };
+    if (options.online)
+        try {
+            service = await options.online(env);
+        }
+        catch (error) {
+            service = {
+                ok: false,
+                error_code: error instanceof CliError ? error.code : "generic_failure",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    const latest = options.packageName
+        ? await latestVersion(options.packageName, fetcher, { timeoutMs: 3000 })
+        : undefined;
+    return {
+        ...service,
+        duration_ms: Date.now() - started,
+        ...(options.packageName
+            ? {
+                version: {
+                    current: app.version,
+                    latest: latest ?? null,
+                    newer: latest !== undefined && isNewer(latest, app.version),
+                },
+            }
+            : {}),
+    };
+};
 const failure = (error) => {
     if (error instanceof CliError)
         return error.message;
@@ -85,17 +118,26 @@ export const appDoctorReport = (app, configuration, env, command, options = {})
         };
     }
 };
-/** `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`. */
+/**
+ * `doctor` for a CLI that is not a messenger: gcal, drive, zoom. A messenger's is `doctorCommand(messenger)`, and both
+ * say the same thing: the state from disk, and only with `--online` a call out. Here that call is `options.online`
+ * and, with `options.packageName`, whether npm has a newer version.
+ */
 export const appDoctorCommand = (app, configuration, options = {}) => profileFree(annotate(new Command("doctor"), {
-    effects: LOCAL_READ,
+    effects: REMOTE_READ,
     examples: [`${app.command} doctor`, `${app.command} doctor --json`],
 }))
-    .description("check this installation: version, paths, config, profiles, store; no keyring or network")
-    .action(function () {
-    const env = environmentOf(this).env ?? process.env;
+    .description(DOCTOR_SUMMARY)
+    .option("--online", DOCTOR_ONLINE_OPTION)
+    .action(async function () {
+    const environment = environmentOf(this);
+    const env = environment.env ?? process.env;
     const { report, fixes } = appDoctorReport(app, configuration, env, this, options);
+    const online = this.opts().online
+        ? await onlineCheck(app, env, environment.fetch ?? fetch, options)
+        : undefined;
     const output = outputFor(this);
-    renderAnswer(this, output, itemOf(report));
+    renderAnswer(this, output, itemOf(online ? { ...report, online } : report));
     for (const fix of fixes)
         output.renderer.note(`to make it private: ${fix}`);
 });

package/dist/cli/doctor-text.d.ts

@@ -0,0 +1,2 @@
+export declare const DOCTOR_SUMMARY = "the state this installation is in, without connecting unless --online";
+export declare const DOCTOR_ONLINE_OPTION = "also connect once and read the account; sends nothing";

package/dist/cli/doctor-text.js

@@ -0,0 +1,2 @@
+export const DOCTOR_SUMMARY = "the state this installation is in, without connecting unless --online";
+export const DOCTOR_ONLINE_OPTION = "also connect once and read the account; sends nothing";

package/dist/cli/messenger/doctor-command.js

@@ -10,6 +10,7 @@ import { FloodMemory, floodPathFor } from "../../sends/flood.js";
 import { SendJournal, sendsPathFor } from "../../sends/journal.js";
 import { storePath } from "../../store/path.js";
 import { baseContext, environmentOf, outputFor } from "../context.js";
+import { DOCTOR_ONLINE_OPTION, DOCTOR_SUMMARY } from "../doctor-text.js";
 import { destroysNothing, LOCAL_WRITE, NO_EFFECTS, REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { unknownPermissionIssues } from "../permission-keys.js";
@@ -28,8 +29,8 @@ import { storeSummary } from "./store-maintenance-command.js";
  */
 export const doctorCommand = (messenger) => {
     const command = annotate(new Command("doctor"), { effects: REMOTE_READ })
-        .description("the state this installation is in, without connecting unless --online")
-        .option("--online", "also connect once and read the account; sends nothing")
+        .description(DOCTOR_SUMMARY)
+        .option("--online", DOCTOR_ONLINE_OPTION)
         .action(async function () {
         const { online } = this.opts();
         const { report, renderer, fixes = [] } = await diagnose(this, messenger);

package/package.json

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