dsh-qoder-connect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corrine Hu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,147 @@
+# DSH Qoder Connect
+
+**English** | [简体中文](./README.md)
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that brings your **Qoder subscription** models into DSH through a Personal Access Token (PAT). One plugin serves both Qoder product lines — each with its own settings card, provider id, credential file and saved catalog, never mixed:
+
+| Variant | Provider id | Card title | Where the PAT is minted |
+|---|---|---|---|
+| China (国内版) | `qoder` | Qoder | qoder.com.cn |
+| International (国际版) | `qoder-global` | Qoder Global | qoder.com |
+
+Configure only what you use: a variant with no saved PAT shows no model group and never interferes with the other one. Streaming, reasoning content and tool calls ride the plugin's built-in Qoder transport; the conversation loop, compaction and permissions stay Harness-owned.
+
+## Features
+
+- **PAT: save it and it works** — paste a PAT into the card and press *Save*; the token is validated live against that variant's region before anything is written, and the model group appears immediately — no DSH restart. Once signed in, *Replace PAT* (the new token overwrites only after it validates, so a mistyped paste can never strand a working credential) and *Clear PAT* are one click away.
+- **Two independent variants** — `qoder` (china) and `qoder-global` (global) keep separate credential files, routes and saved catalogs: a token minted on qoder.com does not work against the China deployment and vice versa.
+- **Three-tier model catalog (live → saved → fallback)** — the card states where the list on screen came from: *“Model list updated …”* (fetched now), *“Showing the saved model list from …”* (this account's last successful fetch, restored after a restart or a failed fetch), or *“Showing the built-in model list (not yet updated from Qoder)”* (the roster compiled into the plugin). The reason of the most recent failed fetch is shown too, and a *Refresh model list* button sits right there.
+- **One-toggle context window** — each variant card's *Context window* tab lists every model's capacity (the default and the largest declared window) and carries its own *“Use the largest declared context window”* preference (on by default): on, requests declare the maximum (e.g. Qwen3.8-Max at 1M); off, the default (200K). The two variants keep independent toggle state.
+- **Sidebar quota card + credit details** — the *“Qoder sidebar display”* card toggles a per-variant sidebar quota widget (off by default; each toggle needs its variant's PAT saved) with one shared refresh interval (default 5 min, minimum 1 min). Clicking the sidebar widget opens the *Qoder quota* panel: one row per credit package — *“Remaining / Total + bar | Expires”* — plus the cycle share and reset time. Click the same widget again to close; click the other to switch variants.
+- **Rate display `x<priceFactor>`** — each model name is suffixed with the upstream-reported price multiplier (e.g. `Some Model · x0.79`, free is `x0`), spelled `x<n>` from the catalog's `price_factor`. Display only — it never changes the request; models whose rate the upstream did not report simply show no suffix.
+
+## Screenshots
+
+### Sidebar quota widgets & credit details
+
+Once enabled on the *“Qoder sidebar display”* card, a per-variant quota widget sits at the sidebar's foot; clicking it opens the *Qoder quota* panel with one row per credit package, switchable between the two variants at any time.
+
+**China (after clicking the sidebar widget):**
+
+![China sidebar quota details](assets/1.png)
+
+**International (after clicking the sidebar widget):**
+
+![International sidebar quota details](assets/2.png)
+
+### Sidebar toggles
+
+The *“Qoder sidebar display”* card controls both widgets' visibility and the shared refresh interval:
+
+![Sidebar display toggles](assets/3.png)
+
+### Picking a model in a session
+
+Once a PAT is saved, the model picker gains a Qoder group with per-model rate multipliers (`x0.5`, `x0`, …):
+
+![Model picker in a session](assets/4.png)
+
+### Context-window settings
+
+Each variant card's *Context window* tab lists capacities per model under the *“Use the largest declared context window”* preference:
+
+**China:**
+
+![China context-window settings](assets/5.png)
+
+**International:**
+
+![International context-window settings](assets/6.png)
+
+## Install
+
+Prerequisites:
+
+- DSH core `0.1.5-rc.1` or newer (this plugin peers on the `@deepseek-ai/*` `^0.1.5-rc.1` line);
+- Node.js `^22.19.0 || >=24.0.0` (per `package.json` engines);
+- your own Qoder account and at least one Personal Access Token.
+
+```sh
+# From GitHub (recommended)
+dsh plugin --profile web add github:masknull/dsh-qoder-connect
+# Or from npm, once published
+dsh plugin --profile web add dsh-qoder-connect
+```
+
+Swap the `--profile` value for the profile you use (`web` / `desktop` / `tui`, e.g. `dsh plugin --profile desktop add dsh-qoder-connect`) — data stays inside that profile, so web / desktop / tui never collide. On a terminal-only profile (TUI) there is no browser card: manage the PAT and check status through the bundled CLI instead; the settings card and sidebar widgets require Web or Desktop.
+
+## Configuration
+
+### Mint a PAT
+
+- **Qoder (China)**: sign in at qoder.com.cn → account settings → Personal Access Token.
+- **Qoder Global**: sign in at qoder.com → account settings → Personal Access Token.
+
+(The card repeats the same guidance: *“Generate a PAT in your qoder.com account settings (Account → Personal Access Token), then paste it here.”*)
+
+### Save it on the card
+
+DSH → Settings → Plugins → the variant's card: paste the PAT into the password field and press *Save* (*“Validating and saving…”* while it runs). The token is validated against that variant's region first — a refusal saves nothing and the card says *“That PAT was rejected — generate a new one in your account settings and try again.”*. Do this on both cards to run both groups side by side.
+
+### Environment-variable fallback
+
+For headless setups, the plugin reads an environment fallback **only when no credential file exists**:
+
+| Variant | Environment variable |
+|---|---|
+| `qoder` (china) | `QODER_CN_PERSONAL_ACCESS_TOKEN` |
+| `qoder-global` | `QODER_PERSONAL_ACCESS_TOKEN` |
+
+The precedence is **file > env**: as soon as a valid credential file is saved, a stray environment token stops mattering (the saved token always wins). Env-sourced credentials show as *source: environment variable* on the card, with no saved-at time.
+
+## Data & privacy
+
+### File layout
+
+Everything the plugin owns lives in one data directory: `<profile>/.dsh-qoder-connect/` — credentials at the root, rebuildable caches under `state/` (so “clear the cache” can never touch a credential):
+
+```text
+<profile>/.dsh-qoder-connect/
+├── .qoder-auth.json              # China PAT ({version:2, pat, region, savedAt})
+├── .qoder-global-auth.json       # Global PAT
+└── state/
+    ├── .qoder-catalog.json       # China per-account saved catalog
+    ├── .qoder-global-catalog.json
+    ├── .qoder-probe.json         # China reasoning-effort probe records
+    ├── .qoder-global-probe.json
+    ├── .qoder-host-heartbeat.json    # host heartbeat (doctor uses it)
+    └── .qoder-machine-id         # transport machine-id seed (never written to ~/.qoder)
+```
+
+The directory follows the profile that declares this plugin (found under `$DSH_HOME/profiles/`), falling back to the Harness home when none can be determined; `DSH_QODER_DATA_DIR` overrides it explicitly.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build      # tsdown → lib/ (host bundle + client bundle)
+pnpm test           # vitest run (tests/**/*.spec.ts)
+pnpm run test:qoder # node --test (tests/qoder/*.test.ts, the Qoder transport suite)
+pnpm run typecheck  # tsc across the host and client tsconfigs
+pnpm run check      # typecheck + test + test:qoder + build in one gate
+```
+
+The upstream `node:test` suite for the Qoder transport layer now lives in `tests/qoder/` (run it with `pnpm run test:qoder`; the pristine `reference-qoder-tests/` copy has been removed) — `package.json` scripts are the source of truth.
+
+## Provenance & license
+
+- Derived from [masknull/dsh-workbuddy-connect](https://github.com/masknull/dsh-workbuddy-connect) (MIT) — the connect-plugin skeleton this project was refactored from.
+- Qoder transport layer ported from [mo-n/dsh-provider-qoder](https://github.com/mo-n/dsh-provider-qoder) (MIT).
+
+Released under the [MIT](./LICENSE) license; see [NOTICE](./NOTICE) for the upstream attributions. This is a community adapter — not affiliated with, authorized by, or endorsed by Qoder or DeepSeek, and not an official implementation.
+
+## Disclaimer
+
+- Qoder's endpoints come from the upstream repositories: upstream may change, rate-limit or block them at any time, breaking part or all of this plugin with no compatibility window to promise.
+- For personal learning and research only; this tool drives **your own** Qoder account. Do not use it commercially or beyond reasonable personal use. You are responsible for complying with Qoder's terms of service and for any consequence — account restriction, quota loss, service interruption — of using this project.
+- The authors are not liable for any direct or indirect loss arising from use or misuse of this project. The names Qoder, DeepSeek and related marks belong to their respective owners and appear here only to describe compatibility.

package/README.md

@@ -0,0 +1,148 @@
+# DSH Qoder Connect
+
+[English](./README.en.md) | **简体中文**
+
+把 **Qoder 订阅**的模型以个人访问令牌（PAT）接入 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的社区插件。一个插件同时服务两条 Qoder 产品线，各自一张设置卡片、一个 provider、一套凭证与模型目录，互不混用：
+
+| 变体 | provider id | 卡片标题（中文界面） | PAT 生成站点 |
+|---|---|---|---|
+| 国内版 | `qoder` | Qoder（国内版） | qoder.com.cn |
+| 国际版 | `qoder-global` | Qoder Global（国际版） | qoder.com |
+
+只需要哪一版就只配哪一版：未保存 PAT 的变体不显示模型分组，另一版完全不受影响。流式输出、推理内容、工具调用走插件内置的 Qoder 传输层；对话循环、压缩与权限始终由 DSH 本体掌控。
+
+## 功能
+
+- **PAT 即存即用**：在卡片上粘贴 PAT 点「保存」，插件先对该变体的区域实时校验，通过才落盘，模型分组立即出现，无需重启 DSH。已登录后可「更换 PAT」（新令牌校验通过才覆盖，粘贴打错不会把可用凭据弄丢）与「清除 PAT」。
+- **双变体独立配置**：`qoder`（china）与 `qoder-global`（global）各有自己的凭证文件、路由与已保存目录——qoder.com 生成的令牌对中国区无效，反之亦然，两套永不互串。
+- **模型目录三级降级（live → saved → fallback）**：卡片明示当前列表来自哪里——「模型列表更新于 …」（实时拉取）、「当前显示已保存的模型列表，更新于 …」（本账号上次成功目录，重启或断网后顶上来）、「当前显示内置模型列表（尚未从 Qoder 更新）」（编译进插件的兜底名单）；最近一次拉取失败时附带原因，并可在卡片上手动「刷新模型列表」。
+- **上下文窗口一键切换**：两张变体卡片的「上下文窗口」页列出每个模型的容量（默认值与上游声明的最大值），并各自提供「使用上游声明的最大上下文窗口」开关（默认勾选）：勾选按最大窗口（如 Qwen3.8-Max 的 1M）发请求，不勾选按默认窗口（200K），两版开关状态独立保存、互不影响。
+- **侧栏额度展示 + 额度明细**：「Qoder 侧栏展示」卡片可分别为两版开启侧栏底部的额度小卡（默认关，开启前需为该变体保存 PAT），共享一个刷新间隔（默认 5 分钟，最小 1 分钟）。点侧栏小卡在中间面板打开「Qoder 额度」明细：按资源包逐行给出「剩余 / 总量 + 进度条｜到期时间」，合计占比与本轮重置时间一并展示；再点同一张卡关闭，点另一张切换到对应版本。
+- **倍率显示 `x<priceFactor>`**：模型名后直接拼上游报价的价格倍率（如 `某模型 · x0.79`，免费为 `x0`），来自目录接口的 `price_factor` 字段，仅作展示、不影响请求；上游未报倍率的模型不显示后缀，不会凭空补一个数。
+
+## 界面一览
+
+### 侧栏额度小卡与额度明细
+
+在「Qoder 侧栏展示」卡片开启后，侧栏底部出现该变体的额度小卡；点击小卡在中间面板打开「Qoder 额度」明细，按套餐逐行展示，可随时在两版之间切换。
+
+**国内版（侧栏点击后）：**
+
+![国内版侧栏额度明细](assets/1.png)
+
+**国际版（侧栏点击后）：**
+
+![国际版侧栏额度明细](assets/2.png)
+
+### 侧栏开关设置
+
+「Qoder 侧栏展示」卡片控制两张侧栏小卡的显隐与刷新间隔（间隔对两卡同时生效）：
+
+![侧栏展示开关设置](assets/3.png)
+
+### 会话内选择模型
+
+保存 PAT 后，模型选择器出现 Qoder 分组，模型名后跟随价格倍率（`x0.5`、`x0` 等）：
+
+![会话模型选择器](assets/4.png)
+
+### 上下文窗口设置
+
+「上下文窗口」页按模型列出容量与最大声明值，顶部是「使用上游声明的最大上下文窗口」开关：
+
+**国内版：**
+
+![国内版上下文窗口设置](assets/5.png)
+
+**国际版：**
+
+![国际版上下文窗口设置](assets/6.png)
+
+## 安装
+
+前置条件：
+
+- DSH 核心 `0.1.5-rc.1` 及以上（本插件 peer 依赖 `@deepseek-ai/*` `^0.1.5-rc.1` 线）；
+- Node.js `^22.19.0 || >=24.0.0`（`package.json` engines）；
+- 你自己的 Qoder 账号，以及至少一枚个人访问令牌。
+
+```sh
+# 从 GitHub 安装（推荐）
+dsh plugin --profile web add github:masknull/dsh-qoder-connect
+# 或已发布 npm 后从 npm 安装
+dsh plugin --profile web add dsh-qoder-connect
+```
+
+按你使用的 profile 换 `--profile` 的值（`web` / `desktop` / `tui`，如 `dsh plugin --profile desktop add dsh-qoder-connect`）。装到哪个 profile，数据就落在哪个 profile 目录里，web / desktop / tui 各自独立。没有浏览器卡片的终端环境（TUI）下依旧可用 CLI 保存 PAT 并驱动模型；设置卡片与侧栏额度卡需要 Web/Desktop 界面。
+
+## 配置与使用
+
+### 生成 PAT
+
+- **Qoder（中国版）**：登录 qoder.com.cn → 账号设置 → 个人访问令牌，生成后复制。
+- **Qoder Global（国际版）**：登录 qoder.com → 账号设置 → 个人访问令牌，生成后复制。
+
+（卡片内也有同样指引：「请先在 qoder.com.cn 的账号设置（账号 → 个人访问令牌）中生成 PAT，再粘贴到下方输入框。」）
+
+### 在卡片上保存
+
+DSH → 设置 → 插件 → 对应卡片，展开后把 PAT 粘贴进密码输入框，点「保存」（期间显示「校验并保存中…」）。保存动作会先经 Qoder 校验令牌对该变体的区域有效，失败则不落盘并提示「PAT 无效或已过期 — 请到账号设置重新生成后再试。」两版各填各的卡片即可两组并存。
+
+### 环境变量兜底
+
+不方便走卡片的场景可用环境变量：**未保存过凭证文件**时插件读取 env 兜底——
+
+| 变体 | 环境变量 |
+|---|---|
+| `qoder`（china） | `QODER_CN_PERSONAL_ACCESS_TOKEN` |
+| `qoder-global` | `QODER_PERSONAL_ACCESS_TOKEN` |
+
+优先级为 **文件 > env**：只要该变体保存过有效的凭证文件，环境变量就不再生效（保存的令牌永远压过游离的 env）。env 来源的令牌在卡片上标为「来源：环境变量」，且没有保存时间。
+
+## 数据与隐私
+
+### 文件布局
+
+插件的全部自有文件收在数据目录一处：`<profile>/.dsh-qoder-connect/`（凭据在根，可重建的缓存在 `state/` 子目录，「清缓存」永远碰不到凭据）：
+
+```text
+<profile>/.dsh-qoder-connect/
+├── .qoder-auth.json              # 中国版 PAT（{version:2, pat, region, savedAt}）
+├── .qoder-global-auth.json       # 国际版 PAT
+└── state/
+    ├── .qoder-catalog.json       # 中国版按账号保存的模型目录
+    ├── .qoder-global-catalog.json
+    ├── .qoder-probe.json         # 中国版推理档位探测记录
+    ├── .qoder-global-probe.json
+    ├── .qoder-host-heartbeat.json    # host 心跳（doctor 判断宿主是否在跑）
+    └── .qoder-machine-id         # 传输层机器标识种子（不落 ~/.qoder）
+```
+
+数据目录按 profile 归属（在 `$DSH_HOME/profiles/` 下找声明本插件的 profile），无法确定时回落到 Harness home；环境变量 `DSH_QODER_DATA_DIR` 可显式覆盖。
+
+
+## 开发
+
+```sh
+pnpm install
+pnpm run build      # tsdown 产出 lib/（宿主 bundle + client bundle）
+pnpm test           # vitest run（tests/**/*.spec.ts）
+pnpm run test:qoder # node --test（tests/qoder/*.test.ts，Qoder 传输层用例）
+pnpm run typecheck  # tsc：宿主 + client 两份 tsconfig
+pnpm run check      # typecheck + test + test:qoder + build 一条命令全过
+```
+
+Qoder 传输层的上游 `node:test` 用例已移植进 `tests/qoder/`（用 `pnpm run test:qoder` 跑，原件 `reference-qoder-tests/` 已移除）；命令以 `package.json` scripts 为准。
+
+## 出处与许可
+
+- 骨架与 connect 机制改造自 [masknull/dsh-workbuddy-connect](https://github.com/masknull/dsh-workbuddy-connect)（MIT）；
+- Qoder 传输层移植自 [mo-n/dsh-provider-qoder](https://github.com/mo-n/dsh-provider-qoder)（MIT）。
+
+本项目按 [MIT](./LICENSE) 许可发布，双上游出处详见 [NOTICE](./NOTICE)。本仓库与 Qoder、DeepSeek 官方均无关联，是社区适配器——非官方实现。
+
+## 免责声明
+
+- Qoder 的接口来自上游仓库：上游随时可能改动、限流或封禁调用方，导致本插件部分或全部功能失效；届时可能只有等社区跟进，不保证兼容窗口。
+- 本工具仅供个人学习研究，用于驱动**使用者自己的** Qoder 账号；请勿用于商业转售或任何超出个人合理使用的场景。使用即表示你自行承担账号被限制、额度损失、服务中断等一切后果，并遵守 Qoder 的服务条款。
+- 作者不对因使用或滥用本插件产生的任何直接或间接损失负责。文中出现的 Qoder、DeepSeek 等名称与商标归各自权利人所有，仅作兼容性描述之用。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Register the Qoder provider without changing the profile's current
+# default model. Credentials are Personal Access Tokens (PATs) the user
+# pastes into the plugin's card; no OAuth or device flow is started.
+- insert:
+    - id: llm-qoder
+      name: dsh-qoder-connect

package/lib/bin.d.ts

@@ -0,0 +1,6 @@
+//#region src/bin.d.ts
+/** Standalone status/diagnostics/PAT CLI for the dsh-qoder-connect bundle. */
+/** Execute one boot-free command. */
+declare function run(argv: readonly string[]): Promise<number>;
+//#endregion
+export { run };

package/lib/bin.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+import { B as qoderCredentialIdentity, D as FALLBACK_QODER_MODELS, E as qoderCatalogPath, R as QoderCredentialStore, T as QoderCatalogStore, b as createQoderTransport, f as QODER_CONNECT_VERSION, i as variantFor, l as qoderHostHeartbeatPath, m as QoderUpstreamClient, r as QODER_VARIANTS, s as isHeartbeatProcessAlive, t as CHINA_VARIANT, u as readHostHeartbeat, y as validateApiKey } from "./variants-jbFhMKO8.js";
+import { readFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/bin.ts
+/** Standalone status/diagnostics/PAT CLI for the dsh-qoder-connect bundle. */
+const JSON_SCHEMA_VERSION = 1;
+/** Remove token-like strings from an unexpected diagnostic message. */
+function safeMessage(error) {
+	return (error instanceof Error ? error.message : String(error)).replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[redacted token]").replace(/(\b(?:code|token|pat)=)[^&\s]+/giu, "$1[redacted]");
+}
+function printHelp() {
+	process.stdout.write([
+		"Usage: dsh-qoder-connect <doctor|status|pat|logout|catalog> [--provider <id>] [--json] [--file <path>]",
+		"",
+		"  doctor         secret-free environment diagnostics",
+		"  status         credential state and remaining Qoder credit",
+		"  pat set        validate and store a Personal Access Token (arg, --file, or stdin)",
+		"  pat clear      remove the stored credential",
+		"  logout         alias for `pat clear`",
+		"  catalog refresh   re-fetch the model list and save it for this account",
+		"",
+		"  --provider  which product to act on; defaults to qoder",
+		`              one of: ${QODER_VARIANTS.map((variant) => variant.id).join(", ")}`,
+		"  --json      emit one secret-free JSON document (doctor/status only)",
+		"  --file      file to read the token from with `pat set`; \"-\" reads standard input",
+		"",
+		"  A token can also arrive as the positional argument after `pat set`.",
+		"  Environment fallback: QODER_CN_PERSONAL_ACCESS_TOKEN (qoder) or",
+		"  QODER_PERSONAL_ACCESS_TOKEN (qoder-global) when no file is saved.",
+		""
+	].join("\n"));
+}
+function printJson(value) {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+/** One variant's store. */
+function makeStore(variant) {
+	return new QoderCredentialStore({ variant });
+}
+/** One variant's store plus the upstream client riding its transport. */
+function makeClient(store, variant) {
+	const transport = createQoderTransport({
+		region: variant.region,
+		resolvePat: () => store.patPromise()
+	});
+	return new QoderUpstreamClient({
+		region: variant.region,
+		providerId: variant.id,
+		getPat: () => store.patPromise(),
+		transport
+	});
+}
+async function doctor(jsonOutput, variant) {
+	const store = makeStore(variant);
+	const status = await store.status();
+	const heartbeat = await readHostHeartbeat();
+	const hostAlive = heartbeat !== void 0 && isHeartbeatProcessAlive(heartbeat);
+	const report = {
+		schemaVersion: JSON_SCHEMA_VERSION,
+		package: "dsh-qoder-connect",
+		version: QODER_CONNECT_VERSION,
+		node: process.version,
+		provider: variant.id,
+		displayName: variant.displayName,
+		region: variant.region,
+		credentialFile: store.ownAuthPath(),
+		hostHeartbeat: {
+			path: qoderHostHeartbeatPath(),
+			present: heartbeat !== void 0,
+			...heartbeat === void 0 ? {} : {
+				registeredAt: heartbeat.registeredAt,
+				pid: heartbeat.pid
+			},
+			processAlive: hostAlive
+		},
+		signIn: status.state,
+		...status.pat === void 0 ? {} : { pat: status.pat },
+		...status.reason === void 0 ? {} : { reason: status.reason },
+		fallbackModels: FALLBACK_QODER_MODELS.length,
+		hints: [...status.state === "configured" ? [] : [`Save a token with \`dsh-qoder-connect pat set <token> --provider ${variant.id}\`, or from the plugin's settings card.`], ...hostAlive ? [] : ["Host bundle not running in this DSH profile (or the process exited). The browser card is unavailable until DSH starts the plugin; the pat command above still works."]]
+	};
+	if (jsonOutput) printJson(report);
+	else process.stdout.write([
+		`${variant.displayName} Connect ${QODER_CONNECT_VERSION} on ${process.version}`,
+		`Region: ${report.region}`,
+		`Credential file: ${report.credentialFile}`,
+		`Host bundle: ${hostAlive ? `running (pid ${heartbeat.pid})` : heartbeat !== void 0 ? "stale heartbeat (process exited)" : "not started"}`,
+		`Credential: ${status.state === "configured" ? `configured (${status.pat?.source ?? "file"}${status.pat?.patTail === void 0 ? "" : `, tail …${status.pat.patTail}`})` : "missing"}`,
+		...status.reason === void 0 ? [] : [`Note: ${status.reason}`],
+		`Static fallback models: ${report.fallbackModels}`,
+		...report.hints.map((hint) => `Hint: ${hint}`),
+		""
+	].join("\n"));
+	return status.state === "configured" ? 0 : 1;
+}
+async function status(jsonOutput, variant) {
+	const store = makeStore(variant);
+	const auth = await store.status();
+	const base = {
+		schemaVersion: JSON_SCHEMA_VERSION,
+		package: "dsh-qoder-connect",
+		version: QODER_CONNECT_VERSION,
+		provider: variant.id,
+		region: variant.region,
+		credentialFile: auth.filePath,
+		signIn: auth.state,
+		...auth.pat === void 0 ? {} : { pat: auth.pat },
+		...auth.reason === void 0 ? {} : { reason: auth.reason }
+	};
+	if (auth.state !== "configured") {
+		if (jsonOutput) printJson({
+			...base,
+			credits: void 0
+		});
+		else process.stdout.write([
+			`${variant.displayName}: no credential configured at ${auth.filePath}`,
+			...auth.reason === void 0 ? [] : [`Note: ${auth.reason}`],
+			"Save a token with `pat set` or from the plugin’s settings card.",
+			""
+		].join("\n"));
+		return 1;
+	}
+	const client = makeClient(store, variant);
+	try {
+		const credits = await client.fetchCredits();
+		if (jsonOutput) printJson({
+			...base,
+			credits
+		});
+		else process.stdout.write([
+			`${variant.displayName} (${variant.region}): token from ${auth.pat?.source ?? "file"}${auth.pat?.patTail === void 0 ? "" : `, tail …${auth.pat.patTail}`}`,
+			credits.unlimited ? "Quota: unlimited for the current cycle" : `Quota: ${Math.max(0, 100 - credits.total).toFixed(1)}% remaining of the cycle allowance`,
+			...credits.accounts.map((account) => `  ${account.packageName}: ${account.remain}/${account.size}${account.unlimited ? " (unlimited)" : ""}`),
+			...credits.cycleResetTime === void 0 ? [] : [`  resets: ${credits.cycleResetTime}`],
+			""
+		].join("\n"));
+		return 0;
+	} catch (error) {
+		if (jsonOutput) printJson({
+			...base,
+			creditsError: safeMessage(error)
+		});
+		else process.stdout.write(`${variant.displayName}: credential stored, but the quota call failed: ${safeMessage(error)}\n`);
+		return 1;
+	}
+}
+/** Read a token from the positional arg, --file, or standard input. */
+async function readPat(source, rest) {
+	const inline = rest.find((argument) => !argument.startsWith("--"));
+	const pat = (source === void 0 ? inline ?? await readStdin() : source === "-" ? await readStdin() : await readFile(source, "utf8"))?.trim() ?? "";
+	if (pat === "") throw new Error("no token given: pass it as an argument, via --file <path>, or on standard input");
+	return pat;
+}
+async function readStdin() {
+	const chunks = [];
+	for await (const chunk of process.stdin) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	return Buffer.concat(chunks).toString("utf8");
+}
+async function patSet(variant, file, rest) {
+	const store = makeStore(variant);
+	const pat = await readPat(file, rest);
+	process.stdout.write(`Validating a token against ${variant.displayName} (${variant.region})…\n`);
+	if (!await validateApiKey(pat, variant.region)) {
+		process.stderr.write(`dsh-qoder-connect: the token was refused by ${variant.displayName} (${variant.region}). Nothing was saved.\n`);
+		process.stderr.write("If this token belongs to the other Qoder product, use --provider for that one.\n");
+		return 2;
+	}
+	await store.save(pat, "cli");
+	const status = await store.status();
+	process.stdout.write([
+		`Saved to ${store.ownAuthPath()}${status.pat?.patTail === void 0 ? "" : ` (tail …${status.pat.patTail})`}`,
+		"The running plugin picks the token up on its next sweep; no restart needed.",
+		""
+	].join("\n"));
+	return 0;
+}
+async function patClear(variant) {
+	const store = makeStore(variant);
+	await store.clear();
+	const status = await store.status();
+	process.stdout.write(status.state === "configured" ? `${variant.displayName} Connect: removed the stored file, but a token is still active from the environment (${status.pat?.source ?? "env"}).\n` : `${variant.displayName} Connect: signed out; removed ${store.ownAuthPath()}\n`);
+	return 0;
+}
+async function catalogRefresh(variant) {
+	const store = makeStore(variant);
+	const credential = await store.resolve();
+	const client = makeClient(store, variant);
+	const models = await client.fetchModels();
+	const identity = qoderCredentialIdentity(credential);
+	const fetch = client.lastCatalog;
+	new QoderCatalogStore({ path: qoderCatalogPath(variant.catalogFilename) }).set(identity, {
+		source: fetch?.source ?? "unknown",
+		fetchedAtMs: fetch?.fetchedAtMs ?? Date.now(),
+		models: [...models]
+	});
+	process.stdout.write(`${variant.displayName}: fetched ${models.length} models; saved for account ${identity}.\n`);
+	return 0;
+}
+/** Execute one boot-free command. */
+async function run(argv) {
+	if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+		printHelp();
+		return 0;
+	}
+	const [rawAction, ...flags] = argv;
+	if (![
+		"doctor",
+		"status",
+		"pat",
+		"logout",
+		"catalog"
+	].includes(rawAction)) {
+		process.stderr.write(`dsh-qoder-connect: expected doctor, status, pat, logout, or catalog; got ${JSON.stringify(rawAction)}\n`);
+		return 1;
+	}
+	const action = rawAction;
+	const jsonOutput = flags.includes("--json");
+	let providerId;
+	let file;
+	const rest = [];
+	for (let index = 0; index < flags.length; index += 1) {
+		const flag = flags[index];
+		if (flag === "--provider") {
+			providerId = flags[index + 1];
+			index += 1;
+			continue;
+		}
+		if (flag.startsWith("--provider=")) {
+			providerId = flag.slice(11);
+			continue;
+		}
+		if (flag === "--file") {
+			file = flags[index + 1];
+			index += 1;
+			continue;
+		}
+		if (flag.startsWith("--file=")) {
+			file = flag.slice(7);
+			continue;
+		}
+		rest.push(flag);
+	}
+	const variant = providerId === void 0 ? CHINA_VARIANT : variantFor(providerId);
+	if (variant === void 0) {
+		process.stderr.write(`dsh-qoder-connect: unknown provider ${JSON.stringify(providerId)}; expected one of ${QODER_VARIANTS.map((v) => v.id).join(", ")}\n`);
+		return 1;
+	}
+	let patCommand;
+	let catalogCommand;
+	if (action === "pat") {
+		const sub = rest.shift();
+		patCommand = sub === "set" || sub === "clear" ? sub : void 0;
+		if (patCommand === void 0) {
+			process.stderr.write(`dsh-qoder-connect: pat needs set or clear; got ${JSON.stringify(sub ?? "")}\n`);
+			return 1;
+		}
+	}
+	if (action === "catalog") {
+		const sub = rest.shift();
+		catalogCommand = sub === "refresh" ? sub : void 0;
+		if (catalogCommand === void 0) {
+			process.stderr.write(`dsh-qoder-connect: catalog needs refresh; got ${JSON.stringify(sub ?? "")}\n`);
+			return 1;
+		}
+	}
+	if (rest.filter((flag) => flag !== "--json" && !flag.startsWith("--")).length > 0 || jsonOutput && action !== "doctor" && action !== "status") {
+		process.stderr.write(`dsh-qoder-connect: invalid options for ${action}: ${flags.join(" ")}\n`);
+		return 1;
+	}
+	if (action !== "pat" && file !== void 0) {
+		process.stderr.write(`dsh-qoder-connect: --file applies to pat set, not ${action}\n`);
+		return 1;
+	}
+	try {
+		switch (action) {
+			case "doctor": return await doctor(jsonOutput, variant);
+			case "status": return await status(jsonOutput, variant);
+			case "pat": return patCommand === "set" ? await patSet(variant, file, rest) : await patClear(variant);
+			case "logout": return await patClear(variant);
+			case "catalog": return await catalogRefresh(variant);
+		}
+	} catch (error) {
+		process.stderr.write(`dsh-qoder-connect: ${action} failed: ${safeMessage(error)}\n`);
+		return 1;
+	}
+}
+if (process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) process.exitCode = await run(process.argv.slice(2));
+//#endregion
+export { run };