@dan-ai-studio/dshopencodego 0.1.83 → 0.1.84

package/lib/types/catalog/constants.d.ts

@@ -69,3 +69,16 @@ export declare const MODEL_METADATA_MAX_BYTES: number;
  * without a restart, and long enough that a bad id costs one fetch.
  */
 export declare const UNKNOWN_MODEL_PROBE_COOLDOWN_MS: number;
+/**
+ * How old a catalog may be before it counts as stale, no matter the
+ * configured TTL.
+ *
+ * `refreshMinutes` answers "how long may requests reuse one listing", and a
+ * deployment may set it as high as seven days. Staleness answers a different
+ * question — "how long may the plugin go without asking what changed" — and
+ * that one is capped at a day: past it, the next read refreshes in the
+ * background even when the TTL has not expired, so a gateway that adds or
+ * retires models is noticed within a day. A lower TTL keeps working exactly
+ * as before; the cap only shortens longer ones.
+ */
+export declare const MAX_CATALOG_STALENESS_MS: number;

package/lib/types/catalog/index.d.ts

@@ -23,12 +23,24 @@ import type { LlmDiscoveredModel } from '@deepseek-ai/dsh-llm';
 import type { GoDoc } from './go-doc.ts';
 import type { ModelDefaults, ModelFacts } from './metadata.ts';
 import type { GoQuota } from '../go-limits.ts';
-export { PROVIDER_ID, DISPLAY_NAME, DEFAULT_BASE_URL, CONSOLE_BASE_URL } from './constants.ts';
+export { PROVIDER_ID, DISPLAY_NAME, DEFAULT_BASE_URL, CONSOLE_BASE_URL, MAX_CATALOG_STALENESS_MS } from './constants.ts';
 export { readModelIds, fetchModelIds } from './gateway.ts';
 export { readOnlineMetadata, toPiModel, modelBaseURL } from './metadata.ts';
 export type { ModelFacts, OnlineMetadata, ModelDefaults } from './metadata.ts';
 export { decideProtocol, inferProtocol, protocolOfNpm } from './protocol.ts';
 export type { ProtocolDecision, ProtocolSource, WireProtocol } from './protocol.ts';
+/**
+ * Whether a snapshot still answers without a refresh.
+ *
+ * Freshness has a hard ceiling on top of the configured TTL: past a day, a
+ * catalog counts as stale no matter how long the TTL runs, and the next read
+ * refreshes it in the background. A shorter TTL behaves exactly as before;
+ * the ceiling only shortens longer ones. A snapshot that has never been
+ * built (age zero or less) is never fresh.
+ *
+ * Exported so tests can pin the ceiling without waiting a day.
+ */
+export declare function snapshotIsFresh(fetchedAtMs: number, nowMs: number, refreshMs: number): boolean;
 /**
  * One source the catalog could not read.
  *
@@ -142,6 +154,16 @@ export interface CatalogOptions {
      * nothing else.
      */
     readonly cacheDir?: string;
+    /**
+     * A snapshot baked in at publish time: the floor when the disk cache is
+     * empty (fresh installs, wiped caches, a first run on a new machine).
+     *
+     * The disk always wins when it has anything to say, and the endpoint must
+     * match — a seed built for Go never serves Console and vice versa. Like a
+     * remembered disk reading it is served stale with an immediate background
+     * refresh, never presented as current.
+     */
+    readonly seed?: unknown;
     /**
      * The fetch the gateway listing is read through.
      *
@@ -220,12 +242,22 @@ export declare class OpencodeGoCatalog {
      */
     settled(): Promise<void>;
     /**
-     * The catalog a previous build produced, read from disk.
+     * Present a past listing as a stale-but-serving snapshot.
      *
      * It is presented as what it is: a listing from the past, being brought up
      * to date in the background. The facts it carries are the ones the last
      * build produced, so the protocols and the thinking levels are the ones
      * that were true then.
+     */
+    private presentRemembered;
+    /**
+     * The catalog a previous build produced, read from disk — or, when the
+     * disk holds nothing, the snapshot baked in at publish time.
+     *
+     * The bundled seed is the floor, not a peer: the disk always wins when it
+     * has anything to say, and the endpoint must match — a seed built for Go
+     * never serves Console and vice versa. Either way the reading is served
+     * stale with an immediate background refresh, never presented as current.
      * @returns the remembered catalog, or undefined when there is none.
      */
     private readRememberedSnapshot;

package/lib/types/catalog/snapshot-cache.d.ts

@@ -24,6 +24,43 @@
 import type { GoQuota } from '../go-limits.ts';
 import type { ModelFacts } from './metadata.ts';
 import type { WireProtocol } from './protocol.ts';
+/** What the cache file holds. */
+export interface SnapshotFile {
+    readonly version: number;
+    /** The facts, by model id. */
+    readonly facts: Record<string, ModelFacts>;
+    /** The provider's allowances, by model id. */
+    readonly quotas?: Record<string, GoQuota>;
+    /** The provider's protocols, by model id. */
+    readonly protocols?: Record<string, WireProtocol>;
+    /**
+     * The endpoint the snapshot was built against. Disk readings omit it —
+     * they were built for the endpoint in force when they were written — but
+     * a bundled seed must name its endpoint, or it could serve one gateway's
+     * listing to another.
+     */
+    readonly baseURL?: string;
+    /** When the catalog was built. */
+    readonly updatedAt: number;
+}
+/** A validated snapshot file, ready to serve. */
+export interface ParsedSnapshotFile {
+    readonly facts: ReadonlyMap<string, ModelFacts>;
+    readonly quotas: ReadonlyMap<string, GoQuota>;
+    readonly protocols: ReadonlyMap<string, WireProtocol>;
+    readonly baseURL: string | undefined;
+    readonly updatedAt: number;
+}
+/**
+ * Validate a snapshot document, wherever it came from.
+ *
+ * One validator serves both readers: the disk cache and the bundled seed
+ * share the format on purpose, so a seed the format outgrows is refused
+ * rather than half-read.
+ * @param value - the parsed JSON document.
+ * @returns the validated reading, or undefined.
+ */
+export declare function parseSnapshotFile(value: unknown): ParsedSnapshotFile | undefined;
 /**
  * The catalog a previous build produced.
  *
@@ -32,12 +69,7 @@ import type { WireProtocol } from './protocol.ts';
  * @param cacheDir - the plugin's cache directory.
  * @returns the remembered catalog, or undefined.
  */
-export declare function readSnapshotCache(cacheDir: string | undefined): {
-    readonly facts: ReadonlyMap<string, ModelFacts>;
-    readonly quotas: ReadonlyMap<string, GoQuota>;
-    readonly protocols: ReadonlyMap<string, WireProtocol>;
-    readonly updatedAt: number;
-} | undefined;
+export declare function readSnapshotCache(cacheDir: string | undefined): ParsedSnapshotFile | undefined;
 /**
  * Remember the catalog a build produced.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dan-ai-studio/dshopencodego",
-  "version": "0.1.83",
+  "version": "0.1.84",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,8 @@
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "build": "node scripts/build.mjs",
+    "seed": "node scripts/seed-catalog.mjs",
+    "seed": "node scripts/seed-catalog.mjs",
     "typecheck": "tsc -p tsconfig.host.json --noEmit && tsc -p tsconfig.client.json --noEmit && tsc -p tsconfig.tests.json --noEmit",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",