@dan-ai-studio/dshopencodego 0.1.47 → 0.1.48

package/README.en.md

@@ -247,7 +247,7 @@ npm test            # contract tests against a real local HTTP mock gateway
 
 **Order matters**: `npm run build` must come before `npm test` — `tests/pack-contents.spec.ts` walks every `exports` target, and whether `lib/` exists decides whether that check runs or is silently skipped (it does not fail, it just stops protecting you). `package.json` no longer carries `prepare`, so `npm ci` will not build for you; all three CI workflows run `npm run build` explicitly.
 
-The suite covers configuration validation, the protocol ladder, gateway and online metadata, the catalog projection, the adapter on the wire (all three protocols), Remote contracts and services, session-header invariants, usage windows and the meter, the client controller and usage pill, both halves' mounting and registration, the error mapping for stream idle timeouts and aborts, the exit-code contract of the verification scripts, and several **structural invariants** (inject declarations match the source's reads, peer coverage holds both ways, the READMEs match the manifest, and the READMEs' claims about the upstream match the upstream actually installed). That is **45 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
+The suite covers configuration validation, the protocol ladder, gateway and online metadata, the catalog projection, the adapter on the wire (all three protocols), Remote contracts and services, session-header invariants, usage windows and the meter, the client controller and usage pill, both halves' mounting and registration, the error mapping for stream idle timeouts and aborts, the exit-code contract of the verification scripts, and several **structural invariants** (inject declarations match the source's reads, peer coverage holds both ways, the READMEs match the manifest, and the READMEs' claims about the upstream match the upstream actually installed). That is **46 test files** — a number `tests/readme-consistency.spec.ts` checks against the `tests/` directory, so it cannot drift.
 
 ## Releasing (maintainers)
 

package/README.md

@@ -247,7 +247,7 @@ npm test            # 契约测试：真实 HTTP mock 网关，断言请求头/
 
 **顺序有讲究**：`npm run build` 要排在 `npm test` 之前——`tests/pack-contents.spec.ts` 会遍历 `exports` 的每个目标，`lib/` 存在与否决定这条检查是执行还是被跳过（不报错，但会少一层保护）。`package.json` 已移除 `prepare`，因此 `npm ci` 不会再替你隐式构建；三个 CI workflow 都显式跑了 `npm run build`。
 
-测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **45 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
+测试覆盖配置校验、协议阶梯、网关与在线元数据、目录投影、适配器（三种协议的线上请求）、Remote 契约与服务、会话头不变量、用量窗口与计量、客户端控制器与用量组件、两半的挂载与登记、流空闲超时与中止的错误映射、验证脚本的退出码契约、以及几条**结构性不变量**（inject 声明与源码读取一致、peer 覆盖双向、README 与 manifest 一致、README 对上游的断言与实装的上游一致）。共 **46 个测试文件**——这个数字由 `tests/readme-consistency.spec.ts` 对着 `tests/` 目录校验，不会漂移。
 
 ## 发布（维护者）
 

package/lib/index.js

@@ -17788,8 +17788,8 @@ function getBunSandboxEnvValue(name2) {
   if (procEnvCache === null) {
     procEnvCache = /* @__PURE__ */ new Map();
     try {
-      const { readFileSync } = __require("node:fs");
-      const data = readFileSync("/proc/self/environ", "utf-8");
+      const { readFileSync: readFileSync2 } = __require("node:fs");
+      const data = readFileSync2("/proc/self/environ", "utf-8");
       for (const entry of data.split("\0")) {
         const idx = entry.indexOf("=");
         if (idx > 0) {
@@ -42462,6 +42462,8 @@ Check your ChatGPT usage: ${CHATGPT_USAGE_URL}` : errorMessage;
 });
 
 // src/index.ts
+import { homedir } from "node:os";
+import { join as join3 } from "node:path";
 import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
 import * as llm2 from "@deepseek-ai/dsh-llm";
@@ -42626,6 +42628,78 @@ async function fetchModelIds(baseURL, signal) {
 
 // src/catalog/go-doc.ts
 import { attributionHeaders as attributionHeaders2, LlmError as LlmError3 } from "@deepseek-ai/dsh-llm";
+
+// src/catalog/go-doc-discovery.ts
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join as join2 } from "node:path";
+var DISCOVERY_URL = "https://api.github.com/repos/anomalyco/opencode/git/trees/dev?recursive=1";
+var DOCUMENT_NAME = /^go[^/]*\.mdx$/i;
+var DISCOVERY_MAX_BYTES = 8 * 1024 * 1024;
+var DISCOVERY_TIMEOUT_MS = 1e4;
+var CACHE_FILE = "go-doc-paths.json";
+var CACHE_VERSION = 1;
+function selectDocumentPaths(paths) {
+  const selected = [];
+  for (const path5 of paths) {
+    const name2 = path5.slice(path5.lastIndexOf("/") + 1);
+    if (!DOCUMENT_NAME.test(name2)) continue;
+    if (!/(^|\/)(docs?|content|console)\//i.test(path5) && !/^packages\/web\/src\/content\/docs\//i.test(path5)) continue;
+    selected.push(path5);
+  }
+  return selected.sort((left, right) => right.length - left.length);
+}
+function mirrorsOf(path5) {
+  const encoded = path5.split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  return [
+    `https://raw.githubusercontent.com/anomalyco/opencode/dev/${encoded}`,
+    `https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/${encoded}`
+  ];
+}
+async function discoverDocumentPaths(signal, fetchImpl = fetch) {
+  const timeout = AbortSignal.timeout(DISCOVERY_TIMEOUT_MS);
+  try {
+    const response = await fetchImpl(DISCOVERY_URL, {
+      headers: { accept: "application/vnd.github+json", "user-agent": "dshopencodego" },
+      signal: signal === void 0 ? timeout : AbortSignal.any([signal, timeout])
+    });
+    if (!response.ok) return [];
+    const body = await response.text();
+    if (body.length > DISCOVERY_MAX_BYTES) return [];
+    const listing = JSON.parse(body);
+    const paths = (listing.tree ?? []).map((entry) => entry.path).filter((path5) => typeof path5 === "string");
+    return selectDocumentPaths(paths);
+  } catch {
+    return [];
+  }
+}
+function readCachedPaths(cacheDir) {
+  if (cacheDir === void 0) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(join2(cacheDir, CACHE_FILE), "utf8"));
+    if (parsed.version !== CACHE_VERSION || !Array.isArray(parsed.paths)) return [];
+    return parsed.paths.filter((path5) => typeof path5 === "string");
+  } catch {
+    return [];
+  }
+}
+function rememberPaths(cacheDir, discovered) {
+  const known = readCachedPaths(cacheDir);
+  const merged = [];
+  for (const path5 of [...discovered, ...known]) {
+    if (!merged.includes(path5)) merged.push(path5);
+  }
+  if (cacheDir === void 0 || discovered.length === 0) return merged;
+  try {
+    mkdirSync(cacheDir, { recursive: true });
+    const file = { version: CACHE_VERSION, paths: merged, updatedAt: Date.now() };
+    writeFileSync(join2(cacheDir, CACHE_FILE), `${JSON.stringify(file, null, 2)}
+`, "utf8");
+  } catch {
+  }
+  return merged;
+}
+
+// src/catalog/go-doc.ts
 var GO_DOC_URLS = [
   "https://raw.githubusercontent.com/anomalyco/opencode/dev/services/www/src/docs/content/console/go.mdx",
   "https://cdn.jsdelivr.net/gh/anomalyco/opencode@dev/services/www/src/docs/content/console/go.mdx"
@@ -42725,18 +42799,46 @@ async function readSource(url, signal) {
     return { failure: `${url}: ${error instanceof Error ? error.message : String(error)}` };
   }
 }
-async function fetchGoDocument(signal) {
-  const attempts = await Promise.all(GO_DOC_URLS.map((url) => readSource(url, signal)));
+async function fetchGoDocument(signal, options = {}) {
   const failures = [];
-  for (const attempt of attempts) {
-    if ("document" in attempt) return attempt.document;
-    failures.push(attempt.failure);
+  const known = await readSources(GO_DOC_URLS, signal);
+  if (known.document !== void 0) return known.document;
+  failures.push(...known.failures);
+  const remembered = readCachedPaths(options.cacheDir).filter((path5) => !GO_DOC_URLS.some((url) => url.endsWith(path5)));
+  if (remembered.length > 0) {
+    const cached = await readSources(remembered.flatMap(mirrorsOf), signal);
+    if (cached.document !== void 0) return cached.document;
+    failures.push(...cached.failures);
+  }
+  const discover = options.discover ?? discoverDocumentPaths;
+  const discovered = await discover(signal);
+  if (discovered.length === 0) {
+    failures.push("the provider repository named no document");
+  } else {
+    const merged = rememberPaths(options.cacheDir, discovered);
+    const fresh = merged.filter((path5) => !GO_DOC_URLS.some((url) => url.endsWith(path5))).flatMap(mirrorsOf);
+    if (fresh.length === 0) {
+      failures.push("the provider repository named the path that was already tried");
+    } else {
+      const result = await readSources(fresh, signal);
+      if (result.document !== void 0) return result.document;
+      failures.push(...result.failures);
+    }
   }
   throw new LlmError3(
     `could not read the Go documentation (${failures.join("; ")})`,
     "DOCUMENT_UNAVAILABLE"
   );
 }
+async function readSources(urls, signal) {
+  const attempts = await Promise.all(urls.map((url) => readSource(url, signal)));
+  const failures = [];
+  for (const attempt of attempts) {
+    if ("document" in attempt) return { document: attempt.document, failures };
+    failures.push(attempt.failure);
+  }
+  return { failures };
+}
 
 // src/catalog/protocol.ts
 var WIRE_PROTOCOLS = [
@@ -43074,7 +43176,7 @@ var OpencodeGoCatalog = class {
    */
   async build(signal) {
     const builtin = builtinModels(this.options.baseURL);
-    const readDocument = this.options.readDocument ?? fetchGoDocument;
+    const readDocument = this.options.readDocument ?? ((signal2) => fetchGoDocument(signal2, { cacheDir: this.options.cacheDir }));
     const [listing, metadata, documentation] = await Promise.allSettled([
       fetchModelIds(this.options.baseURL),
       this.refreshMetadata(builtin),
@@ -45028,6 +45130,7 @@ var OpencodeGoAdapter = class extends LlmAdapter {
           },
           overrides: config.modelProtocols,
           ...this.options.readDocument === void 0 ? {} : { readDocument: this.options.readDocument },
+          ...this.options.cacheDir === void 0 ? {} : { cacheDir: this.options.cacheDir },
           observers: {
             ...this.options.onFallback === void 0 ? {} : { onFallback: this.options.onFallback },
             ...this.options.onUnconfigured === void 0 ? {} : { onUnconfigured: this.options.onUnconfigured }
@@ -45764,7 +45867,7 @@ function createUpdateChecker(deps) {
 }
 
 // src/update/version.ts
-var PLUGIN_VERSION = true ? "0.1.47" : "0.0.0-dev";
+var PLUGIN_VERSION = true ? "0.1.48" : "0.0.0-dev";
 
 // src/update/service.ts
 import { TypertRemoteService as TypertRemoteService2 } from "@deepseek-ai/dsh-typert-protocol";
@@ -45901,6 +46004,18 @@ var inject = ["llm"];
 function isLiveConfig(raw) {
   return typeof raw === "object" && raw !== null && typeof raw.enabled === "object" && typeof raw.enabled?.get === "function";
 }
+function resolveCacheDir(ctx) {
+  const home = ctx.dshHomePath;
+  if (typeof home === "function") {
+    try {
+      return home("cache", "@dan-ai-studio/dshopencodego");
+    } catch {
+    }
+  }
+  const configured = process.env.DSH_HOME?.trim();
+  const root = configured !== void 0 && configured.length > 0 ? configured : join3(homedir(), ".dsh");
+  return join3(root, "cache", "@dan-ai-studio/dshopencodego");
+}
 function apply(ctx, raw) {
   const live = isLiveConfig(raw) ? raw : void 0;
   const constant = live === void 0 ? PlainConfig(raw ?? {}) : void 0;
@@ -45921,6 +46036,7 @@ function apply(ctx, raw) {
   const adapter = new OpencodeGoAdapter({
     config: current,
     resolveApiKey,
+    cacheDir: resolveCacheDir(ctx),
     imageAccess: {
       resolveAttachments: () => ctx.get("attachments"),
       resolveImageAccess: (attachments, ref) => llm2.resolveImageAttachmentAccess(

package/lib/types/adapter.d.ts

@@ -52,6 +52,13 @@ export interface OpencodeGoAdapterOptions {
      * a fixed document so the suite stays offline. Production omits this.
      */
     readonly readDocument?: () => Promise<GoDoc>;
+    /**
+     * Where the discovered provider-document paths are remembered.
+     *
+     * Absent means the plugin keeps them in memory only, which costs one
+     * discovery per start and nothing else.
+     */
+    readonly cacheDir?: string;
     /**
      * Observe the provider's own usage for one completed call. This is the only
      * honest source of token counts: the gateway's `/usage` endpoint reports

package/lib/types/catalog/go-doc-discovery.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Finding the provider's document without being told where it is.
+ *
+ * The document is the provider's own statement of each model's protocol, and
+ * the provider moves it: `go.mdx` lived at
+ * `packages/web/src/content/docs/go.mdx` until the `packages/web` tree was
+ * restructured, and the plugin then read 404 from both mirrors for as long as
+ * the old path was hardcoded. A hardcoded path is a promise the provider did
+ * not make.
+ *
+ * So the path is discovered instead of declared. The discovery is a read-only
+ * listing of the provider's own repository, and it runs only when every known
+ * path has already failed — the common case costs one request to a file that
+ * is there, and the rare case costs one listing.
+ *
+ * The paths that discovery finds are remembered on disk, as a *set of paths
+ * known to have existed*, not as one current path. That distinction matters:
+ * a cache holding a single path would hand back a stale path the moment the
+ * provider moved the file again, which is exactly the moment the cache is
+ * consulted. A set is only ever a list of candidates to try, so a stale entry
+ * costs one failed request and nothing else.
+ *
+ * @module @dan-ai-studio/dshopencodego/catalog/go-doc-discovery
+ */
+/** A repository listing is large; the cap keeps a hostile response bounded. */
+export declare const DISCOVERY_MAX_BYTES: number;
+/**
+ * The repository paths a discovery run found.
+ *
+ * A path is only useful if it names the document this plugin parses, and the
+ * listing also contains unrelated `go.mdx` files in other packages' fixtures.
+ * The path must therefore sit under a documentation tree.
+ * @param paths - every repository path the listing mentioned.
+ * @returns the paths that name the provider's Go document.
+ */
+export declare function selectDocumentPaths(paths: readonly string[]): readonly string[];
+/**
+ * The mirrors a repository path can be read from.
+ *
+ * Two hosts, one file: the repository itself and a CDN that caches it. They
+ * fail independently, which is why both are tried.
+ * @param path - a repository-relative path.
+ * @returns the URLs to read that path from.
+ */
+export declare function mirrorsOf(path: string): readonly string[];
+/**
+ * Ask the provider's repository where its document is.
+ *
+ * The listing is unauthenticated, so it is rate-limited. That is why this runs
+ * only after every known path has failed, and why the paths it finds are
+ * remembered: the next process starts with the answer and never asks.
+ * @param signal - caller cancellation.
+ * @param fetchImpl - the fetch to use; injected for tests.
+ * @returns the repository paths that name the document; empty when the
+ *   listing could not be read or named nothing.
+ */
+export declare function discoverDocumentPaths(signal?: AbortSignal, fetchImpl?: typeof fetch): Promise<readonly string[]>;
+/**
+ * The paths the cache remembers, most recently discovered first.
+ *
+ * A cache that cannot be read is an empty cache: the caller then tries the
+ * paths it knows and discovers again.
+ * @param cacheDir - the plugin's cache directory.
+ * @returns the remembered repository paths.
+ */
+export declare function readCachedPaths(cacheDir: string | undefined): readonly string[];
+/**
+ * Remember the paths a discovery run found.
+ *
+ * The known paths are merged rather than replaced, newest first, so a cache
+ * that a concurrent process also wrote does not lose the other process's
+ * entry. A cache that cannot be written is not an error: the paths stay in
+ * memory for this process and are rediscovered next time.
+ * @param cacheDir - the plugin's cache directory.
+ * @param discovered - the paths a discovery run found.
+ * @returns the merged set, in the order it should be tried.
+ */
+export declare function rememberPaths(cacheDir: string | undefined, discovered: readonly string[]): readonly string[];

package/lib/types/catalog/go-doc.d.ts

@@ -55,6 +55,23 @@ export interface GoDoc {
  *   document does not carry the expected tables.
  */
 export declare function parseGoDocument(markdown: string): GoDoc;
+/**
+ * How the document is found and where the answer is kept.
+ *
+ * The discovery is injectable so a test can decide what the provider's
+ * repository says without reaching the network — which is the only way this
+ * module can be exercised offline at all.
+ */
+export interface GoDocOptions {
+    /** Where the discovered document paths are remembered. */
+    readonly cacheDir?: string | undefined;
+    /**
+     * Ask the provider's repository where its document is.
+     *
+     * Defaults to the real listing. A test injects a fixed answer.
+     */
+    readonly discover?: (signal?: AbortSignal) => Promise<readonly string[]>;
+}
 /**
  * Fetch and parse the documentation, asking every source concurrently.
  *
@@ -64,9 +81,16 @@ export declare function parseGoDocument(markdown: string): GoDoc;
  * quota badge and the protocol fallback. `GO_DOC_URLS` order still decides:
  * the repository file is examined before its cache mirror, and a source that
  * fails is reported with its own reason.
+ *
+ * The known paths are tried first, then the paths a previous discovery
+ * remembered, and only then is the provider's repository asked where its
+ * document is. That order is what keeps the cost at one request in the common
+ * case while still surviving the provider moving the file: a path that is
+ * there is used, and a path that is not is replaced by a discovered one.
  * @param signal - caller cancellation; it reaches every source's fetch and
  *   aborts all of them, so a cancelled discovery stops waiting on the network.
+ * @param options - where the discovered paths are remembered.
  * @returns the parsed document from the first source that carried one.
  * @throws {LlmError} `DOCUMENT_UNAVAILABLE` when every source failed.
  */
-export declare function fetchGoDocument(signal?: AbortSignal): Promise<GoDoc>;
+export declare function fetchGoDocument(signal?: AbortSignal, options?: GoDocOptions): Promise<GoDoc>;

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

@@ -106,6 +106,14 @@ export interface CatalogOptions {
      * cancellation, forwarded to every documentation request.
      */
     readonly readDocument?: (signal?: AbortSignal) => Promise<GoDoc>;
+    /**
+     * Where the discovered document paths are remembered.
+     *
+     * Absent means the plugin cannot write a cache, and the paths are then only
+     * known to the running process. That costs one discovery per start, and
+     * nothing else.
+     */
+    readonly cacheDir?: string;
 }
 /**
  * One gateway's catalog. Requests reuse a cached snapshot; explicit discovery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dan-ai-studio/dshopencodego",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "description": "OpenCode Go provider for DeepSeek Harness: live gateway catalog, per-conversation session header, usage",
   "type": "module",
   "license": "MIT",