@wirecat/cli-base 0.67.0 → 0.68.0

package/CHANGELOG.md

@@ -8,6 +8,38 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.68.0 — 31.10.2026
+
+### Removed
+
+- **WC-REL-10: a messenger CLI is released after the owner's yes in the conversation, with no signed report.**
+  `bin/release` in max-cli and whatsapp-cli no longer reads a release report or a `Signed off:` line. The agent asks
+  the owner before it runs `bin/release`; one yes covers one version.
+
+### Changed — may break callers
+
+- **`Credentials` in `auto` does the whole file fallback itself (WC-SECR-4).** A secret the file holds is read from the
+  file before the keyring, so a locked keyring is not tried for it, and a refresh `write` keeps it there. A sign-in
+  passes `write(account, secret, { signIn: true })`: it tries the keyring and, once the keyring takes it, removes the
+  file copy. The "could not reach the OS keyring" warning comes once per run (per `env` object), not once per
+  `Credentials`. Watch for: a file copy left next to a newer keyring entry by an older CLI now wins the read; sign in
+  again to move it back. CLIs can drop their own file-first read, "remove the file copy" step and `warnOnce`.
+- **WC-SECR-4 is the one credential-storage standard.** The keyring by default; when it fails, the file without
+  asking, one warning on stderr, and the answer that saved the secret says where it went;
+  `--credential-storage file` on the sign-in command chooses the file and is discouraged; a secret in the file is
+  read from there until a sign-in reaches the keyring again. No CLI asks, none is keyring-only. `Credentials` already
+  falls back this way in `auto`; the rule now says every CLI must use it.
+
+### Fixed
+
+- **`Credentials.remove` with `storage: "keyring"` leaves the file alone.** It also deleted the account from the
+  credentials file, so a CLI that cleared the keyring copy after a file sign-in lost the sign-in it had just saved.
+
+### Added
+
+- **`--credential-storage <storage>` in the flag vocabulary** (role `mode`), so `cli-dev lint` accepts it on a sign-in
+  command without a per-CLI override.
+
 ## 0.67.0 — 31.10.2026
 
 ### Added

package/dist/credentials.d.ts

@@ -38,17 +38,25 @@ export declare const keyringService: (service: string, _configDir?: string, _iso
  * shape `bin/keyring-dedupe` already finds and removes.
  */
 export declare const movedRunService: (service: string, configDir: string) => string;
+export interface WriteOptions {
+    /**
+     * A new sign-in rather than a refresh: it tries the keyring even when the file holds the account, and once the
+     * keyring takes it, removes the file copy (WC-SECR-4).
+     */
+    signIn?: boolean;
+}
 /**
- * Environment first, then the OS keyring, then a file.
+ * Environment first, then the OS keyring, then a file. In `auto`, a file that holds the account is read before the
+ * keyring and keeps its refreshes, so a locked keyring is not tried again for it; a sign-in moves it back.
  *
  * `auto` does not probe whether a keyring exists: it attempts the operation, and on failure warns
- * once and falls through. A probe would touch the user's keychain for nothing and could still
+ * once per run and falls through. A probe would touch the user's keychain for nothing and could still
  * succeed where the real operation fails.
  */
 export declare class Credentials {
     #private;
     constructor(options: CredentialsOptions);
     read(account: string): StoredCredential | undefined;
-    write(account: string, secret: string): CredentialSource;
+    write(account: string, secret: string, options?: WriteOptions): CredentialSource;
     remove(account: string): CredentialSource[];
 }

package/dist/credentials.js

@@ -15,11 +15,14 @@ export const keyringService = (service, _configDir, _isolated) => service;
  * shape `bin/keyring-dedupe` already finds and removes.
  */
 export const movedRunService = (service, configDir) => `${service}:${resolve(configDir)}`;
+// One warning per run, not per instance: a run over several profiles builds one Credentials for each.
+const warnedRuns = new WeakSet();
 /**
- * Environment first, then the OS keyring, then a file.
+ * Environment first, then the OS keyring, then a file. In `auto`, a file that holds the account is read before the
+ * keyring and keeps its refreshes, so a locked keyring is not tried again for it; a sign-in moves it back.
  *
  * `auto` does not probe whether a keyring exists: it attempts the operation, and on failure warns
- * once and falls through. A probe would touch the user's keychain for nothing and could still
+ * once per run and falls through. A probe would touch the user's keychain for nothing and could still
  * succeed where the real operation fails.
  */
 export class Credentials {
@@ -33,7 +36,6 @@ export class Credentials {
     #warn;
     /** Set only for a moved run with the system keyring. */
     #temporaryService;
-    #warned = false;
     constructor(options) {
         this.#configDir = options.configDir;
         this.#storage = options.storage ?? "auto";
@@ -50,23 +52,29 @@ export class Credentials {
         const fromEnv = this.#envVar ? this.#env[this.#envVar]?.trim() : undefined;
         if (fromEnv)
             return { secret: fromEnv, source: "environment" };
+        const fromFile = this.#storage === "keyring" ? undefined : this.#readFile()?.[account]?.secret;
+        if (fromFile)
+            return { secret: fromFile, source: "file" };
         if (this.#storage !== "file") {
             const temporary = this.#temporaryService;
             const fromKeyring = this.#tryKeyring(() => (temporary && this.#keyring.get(temporary, account)) || this.#keyring.get(this.#service, account));
             if (fromKeyring)
                 return { secret: fromKeyring, source: "keyring" };
         }
-        const secret = this.#readFile()?.[account]?.secret;
-        return secret ? { secret, source: "file" } : undefined;
+        return undefined;
     }
-    write(account, secret) {
-        if (this.#storage !== "file") {
+    write(account, secret, options = {}) {
+        const inFile = this.#storage === "auto" && this.#readFile()?.[account] !== undefined;
+        if (this.#storage === "keyring" || (this.#storage === "auto" && (options.signIn || !inFile))) {
             const stored = this.#tryKeyring(() => {
                 this.#keyring.set(this.#temporaryService ?? this.#service, account, secret);
                 return true;
             });
-            if (stored)
+            if (stored) {
+                if (inFile)
+                    this.#removeFromFile(account);
                 return "keyring";
+            }
         }
         const store = this.#readFile();
         if (!store) {
@@ -91,14 +99,18 @@ export class Credentials {
                         "moved folders never removes it");
             }
         }
-        const store = this.#readFile();
-        if (store?.[account] !== undefined) {
-            delete store[account];
-            this.#writeFile(store);
+        if (this.#storage !== "keyring" && this.#removeFromFile(account))
             removed.push("file");
-        }
         return removed;
     }
+    #removeFromFile(account) {
+        const store = this.#readFile();
+        if (store?.[account] === undefined)
+            return false;
+        delete store[account];
+        this.#writeFile(store);
+        return true;
+    }
     /** Only for the warning: a keyring that fails here must not fail a removal that already happened. */
     #ownersEntryExists(account) {
         try {
@@ -141,8 +153,8 @@ export class Credentials {
             return operation();
         }
         catch (error) {
-            if (!this.#warned) {
-                this.#warned = true;
+            if (!warnedRuns.has(this.#env)) {
+                warnedRuns.add(this.#env);
                 this.#warn(`could not reach the OS keyring — it may be locked, or no keyring service is running ` +
                     `(${error instanceof Error ? error.message : String(error)}); ` +
                     `using ${this.#path()} instead, readable only by you`);

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { BATCH_LIMITS, type BatchContext, type BatchHandler, type BatchOperation, type BatchReport, type BatchResult, type PreparedBatchRequest, prepareBatch, projectBatchAnswers, readBatchInput, runBatch, } from "./batch.js";
 export { loadConfigFile, saveConfigFile, writeSecurely } from "./config.js";
-export type { CredentialSource, CredentialStorage, CredentialsOptions, StoredCredential } from "./credentials.js";
+export type { CredentialSource, CredentialStorage, CredentialsOptions, StoredCredential, WriteOptions, } from "./credentials.js";
 export { CREDENTIAL_STORAGE, Credentials, keyringService, movedRunService } from "./credentials.js";
 export { createDeadline, type Deadline, type DeadlineOptions } from "./deadline.js";
 export { CliError, type CliErrorDetails, type ErrorCode, errorCodes, isCliError } from "./errors.js";

package/dist/standards/flags-how.js

@@ -375,6 +375,13 @@ export const HOW_FLAGS = [
         type: "string",
         meaning: "the browser program to open for sign-in",
     },
+    {
+        name: "--credential-storage",
+        value: "<storage>",
+        role: "mode",
+        type: "choice",
+        meaning: "where a sign-in is kept: keyring, which falls back to a private file by itself, or file (WC-SECR-4)",
+    },
     { name: "--checkpoint", value: "<file>", role: "mode", type: "path", meaning: "keep resume progress in this file" },
     {
         name: "--expected-event-id",

package/docs/standards/README.md

@@ -42,7 +42,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 | [Security](security.md) | `SECR` | 23 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting, OAuth sign-in, meeting secrets, keyring in moved-folder runs |
 | [Documents](docs.md) | `DOC` | 20 | User pages and developer pages, generated pages, current facts, changelog |
 | [Comparisons](comparisons.md) | `CMP` | 11 | Which tools a comparison page lists, rows as user tasks, agents and safety, where others are better, proof of marks |
-| [Releases](releases.md) | `REL` | 15 | `bin/release`, the release lock, versions, release reports, trusted publishing |
+| [Releases](releases.md) | `REL` | 15 | `bin/release`, the release lock, versions, the owner's yes, trusted publishing |
 | [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |
 | [Time](time.md) | `TIME` | 6 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone |
 | [Style](style.md) | `STYLE` | 10 | Comments, TypeScript habits, commit messages |

package/docs/standards/releases.md

@@ -4,7 +4,7 @@
 
 ## Scope
 
-How a CLI is released: `bin/release`, the release lock, version numbers, the release report and trusted publishing.
+How a CLI is released: `bin/release`, the release lock, version numbers, the owner's yes and trusted publishing.
 
 Rule ids on this page are `WC-REL-<n>`. How to read a rule, how ids work and which rule wins are in the
 [index](README.md). The changelog a release dates is on the [Documents](docs.md) page. The checks a release runs are
@@ -106,17 +106,16 @@ on the [CI](ci.md) page.
 
 ### WC-REL-9 · Merged into [WC-REL-8](#wc-rel-8--any-package-may-release-at-any-time)
 
-### WC-REL-10 · A messenger CLI is released only with a release report the owner signed for that commit
-
-- **Why:** the judgement half of a release (changelog wording, docs against the change, live checks) has no other
-  record that it ran for this exact commit.
-- **Enforced by:** `max-cli: bin/release` · `whatsapp-cli: bin/release`.
-- **Example:** max-cli's and whatsapp-cli's `bin/release` refuse unless the report has `Commit: <HEAD>` and
-  `Signed off: <date>`. When `bin/release` only renumbers or folds the changelog, it carries the report to the new
-  commit. A fork passes its own report with `bin/release --report <path>`.
-- **Exceptions:** none. max-cli and whatsapp-cli (from 0.1.0) check the report in `bin/release`. tg-cli has the
-  release skill, but its `bin/release` does not check a report yet.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+### WC-REL-10 · A messenger CLI is released only after the owner says yes in the conversation
+
+- **Why:** a messenger CLI acts on the owner's own accounts, so the owner decides when a new version ships. A signed
+  release report added a step without adding a check: the owner removed it on 2026-10-31 ("remove the signing
+  requirements instead just ask").
+- **Enforced by:** review only.
+- **Example:** the agent finishes the release skill, then asks "release max 0.91.0?". It runs `bin/release` only after
+  the owner says yes for that version. One yes covers one version.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** owner, 2026-10-31.
 
 ### WC-REL-11 · Publish from GitHub Actions with npm trusted publishing
 

package/docs/standards/security.md

@@ -67,19 +67,31 @@ name. Any other top-level key is written as `[not allowed]`. A key that names co
 ### WC-SECR-4 · Secrets come from the environment, then the OS keyring, then a private file
 
 cli-base's `Credentials` reads the environment variable first (for CI), then the OS keyring, then a file with mode
-`0600`. The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
+`0600` in the CLI's own folder. Storage is the keyring by default (`auto`): when the keyring fails (locked, not
+running, no D-Bus), the CLI uses the file without asking, warns once on stderr, and the answer that saved the secret
+says where it went (gcal: `credential_storage: "file"`). `--credential-storage file` on the sign-in command chooses
+the file outright; help and docs discourage it. Once the file holds a secret, it is read from the file, so a locked
+keyring is not tried again for it; the next sign-in that reaches the keyring moves it back and removes the file copy.
+`Credentials` in `auto` does all of this: the CLI passes `{ signIn: true }` to `write` for a new sign-in and nothing
+for a refresh.
+No CLI asks which store to use, and none is keyring-only.
+The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
 the command word people type (`max`, `gcal`). A run with moved folders reads the same entry, writes a temporary one,
 and never replaces or deletes the owner's
 ([WC-SECR-24](#wc-secr-24--a-run-with-moved-folders-shares-the-owners-keyring-entry-and-never-deletes-it)).
 
-- **Why:** the keyring is the safest store on the computer.
+- **Why:** the keyring is the safest store on the computer, and a sign-in that fails on a server or in a container
+  because no keyring runs there is a broken CLI, not a safe one.
 - **Enforced by:** `src/credentials.test.ts`.
 - **Example:** a bot token is read from `MAX_BOT_TOKEN`, then the keyring entry `bot:<profile>`, then the file.
-- **Exceptions:** `auto` storage tries the keyring and, when it fails, warns once on stderr and uses the file. A
-  messenger library's own device store, which the library opens as a file and which cannot live in the keyring
-  (WhatsApp's `private.db`), is an owner-only file under
-  [WC-SECR-10](#wc-secr-10--private-files-are-written-atomically-with-private-modes) instead.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-295.
+  `gcal personal session start` on a computer without a keyring signs in, warns once, and answers
+  `credential_storage: "file"`.
+- **Exceptions:** a messenger library's own device store, which the library opens as a file and which cannot live in
+  the keyring (WhatsApp's `private.db`, tg's session file), is an owner-only file under
+  [WC-SECR-10](#wc-secr-10--private-files-are-written-atomically-with-private-modes) instead. A copy between two
+  profiles that must land in the keyring (cli-core's bot transfer) may use `storage: "keyring"`.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-295; owner, 2026-10-31 (never ask, keyring
+  by default, fall back to a file on error, a discouraged flag for the file).
 
 ### WC-SECR-5 · A secret is never taken on the command line
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",