@wirecat/cli-core 0.595.0 → 0.596.0

package/CHANGELOG.md

@@ -5,7 +5,20 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.596.0 — 06.11.2026
+
+### Added
+
+- **`package.json` says which store schema the version speaks.** `wirecat.store` holds `speaks`, the newest schema
+  it migrates a file to, and `minCompatible`, the oldest schema that can still use a file it migrated, so an
+  installer can check a tool against the owner's store from the npm registry before installing it.
+
+### Fixed
+
+- **A read-only open migrates an older store first.** `openStore({ readOnly: true })` on a file at an older schema
+  opens it the ordinary way once, which migrates it, then opens it read-only, instead of refusing it with
+  `configuration_error`. A tool whose first command only reads no longer needs a workaround. A newer incompatible
+  schema is still refused, and a missing file is still not created.
 
 ## 0.595.0 — 06.11.2026
 

package/dist/store/sqlite/open-store.d.ts

@@ -1,7 +1,7 @@
 import { type DecisionPolicy } from "../decisions.js";
 import { type StoreContext } from "./open.js";
 export interface StoreOptions {
-    /** Open an existing compatible store without maintenance; SQLite refuses writes. */
+    /** Open an existing compatible store without maintenance, migrating an older one first; SQLite refuses writes. */
     readOnly?: boolean;
     path?: string;
     env?: NodeJS.ProcessEnv;
@@ -16,4 +16,4 @@ export interface StoreOptions {
     decisions?: DecisionPolicy;
 }
 export declare const BACKFILL_ON_OPEN = 5000;
-export declare const openStoreContext: ({ path, env, now, command, version, warn, readOnly, decisions, }?: StoreOptions) => Promise<StoreContext>;
+export declare const openStoreContext: (options?: StoreOptions) => Promise<StoreContext>;

package/dist/store/sqlite/open-store.js

@@ -14,7 +14,7 @@ import { logPruner } from "./log-pruning.js";
 import { openSqlite } from "./open.js";
 import { movePaymentFacts } from "./payment-facts.js";
 import { loadProviders } from "./providers.js";
-import { assertReadCompatible } from "./read-compatibility.js";
+import { assertReadCompatible, readCompatibility } from "./read-compatibility.js";
 import { pruneRollbackCopies } from "./rollback-copy.js";
 import { stemsState } from "./stems.js";
 import { fillStems, followDefaultStemmers } from "./stems-fill.js";
@@ -36,7 +36,32 @@ const createWritable = (file) => {
         throw new CliError("permission_error", "the message store cannot be written from here; run where it is writable, or set MESSAGING_STORE", { reason: "store.not-writable" });
     }
 };
-export const openStoreContext = async ({ path, env, now = Date.now, command, version, warn = (line) => process.stderr.write(`${line}\n`), readOnly = false, decisions = DEFAULT_DECISION_POLICY, } = {}) => {
+// A new tool's first command may only read; it migrates the file as its first write would.
+const openReadable = async (file, options) => {
+    const first = await openSqlite(file, { readOnly: true });
+    try {
+        if (readCompatibility(first.database, options.command) === "current")
+            return first;
+    }
+    catch (error) {
+        first.database.close();
+        throw error;
+    }
+    first.database.close();
+    const writable = await openStoreContext({ ...options, path: file, readOnly: false });
+    writable.database.close();
+    const migrated = await openSqlite(file, { readOnly: true });
+    try {
+        assertReadCompatible(migrated.database, options.command);
+        return migrated;
+    }
+    catch (error) {
+        migrated.database.close();
+        throw error;
+    }
+};
+export const openStoreContext = async (options = {}) => {
+    const { path, env, now = Date.now, command, version, warn = (line) => process.stderr.write(`${line}\n`), readOnly = false, decisions = DEFAULT_DECISION_POLICY, } = options;
     if (typeof readOnly !== "boolean")
         throw new CliError("validation_error", "readOnly must be a boolean");
     await storeCapable();
@@ -48,12 +73,10 @@ export const openStoreContext = async ({ path, env, now = Date.now, command, ver
     }
     else
         createWritable(file);
-    const opened = await openSqlite(file, { readOnly });
+    const opened = readOnly ? await openReadable(file, options) : await openSqlite(file, { readOnly });
     const database = opened.database;
     try {
-        if (readOnly)
-            assertReadCompatible(database, command);
-        else {
+        if (!readOnly) {
             const notice = migrate(database, {
                 now,
                 command,

package/dist/store/sqlite/read-compatibility.d.ts

@@ -1,2 +1,4 @@
 import type { CacheDatabase } from "../driver.js";
+/** "older" when the file needs migrating before a read-only open; throws for every file it may not read. */
+export declare const readCompatibility: (database: CacheDatabase, command?: string) => "current" | "older";
 export declare const assertReadCompatible: (database: CacheDatabase, command?: string) => void;

package/dist/store/sqlite/read-compatibility.js

@@ -1,7 +1,8 @@
 import { CliError } from "@wirecat/cli-base";
 import { MIGRATIONS } from "../migrations.js";
 import { refusalAdvice, storeClients } from "./clients.js";
-export const assertReadCompatible = (database, command) => {
+/** "older" when the file needs migrating before a read-only open; throws for every file it may not read. */
+export const readCompatibility = (database, command) => {
     const ours = MIGRATIONS.at(-1)?.version ?? 0;
     if (!database.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_migrations'").get())
         throw new CliError("configuration_error", "The store has no schema history; initialize it explicitly before a read-only open");
@@ -15,8 +16,11 @@ export const assertReadCompatible = (database, command) => {
         minCompatible < 1 ||
         minCompatible > version)
         throw new CliError("configuration_error", "The store schema history is invalid; read-only opening cannot repair it");
-    if (version < ours)
-        throw new CliError("configuration_error", `The store needs schema ${ours} maintenance before a read-only open (found ${version})`);
     if (minCompatible > ours)
         throw new CliError("configuration_error", `The store requires schema ${minCompatible}, but this tool supports ${ours}; ${refusalAdvice(storeClients(database), command, version)}`);
+    return version < ours ? "older" : "current";
+};
+export const assertReadCompatible = (database, command) => {
+    if (readCompatibility(database, command) === "older")
+        throw new CliError("configuration_error", `The store needs schema ${MIGRATIONS.at(-1)?.version ?? 0} maintenance before a read-only open`);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.595.0",
+  "version": "0.596.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",
@@ -13,6 +13,12 @@
     "url": "https://github.com/WireCatLabs/cli-core/issues"
   },
   "type": "module",
+  "wirecat": {
+    "store": {
+      "speaks": 53,
+      "minCompatible": 34
+    }
+  },
   "engines": {
     "node": "^22.16.0 || >=24"
   },