dsh-ccswitch-sync 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 msyzzm
+
+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.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# dsh-ccswitch-sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](README.zh.md) · [npm](https://www.npmjs.com/package/dsh-ccswitch-sync) · [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) · [Plugin directory](https://dshtui.com/plugins)
+
+A [dsh-TUI](https://dshtui.com) plugin that mirrors the DSH configuration **CC Switch** keeps
+in its own profile into the `dsh-tui` profile, and shows how fresh the mirror is in the footer.
+
+CC Switch writes `llm-pi-ai.providers` and `cc-switch-mcp-*` rows into
+`~/.dsh/profiles/web/cordis.patch.yml` (falling back to `desktop`). dsh-TUI runs its own
+profile, `~/.dsh/profiles/dsh-tui`, so those providers and MCP servers never show up there.
+This plugin ports the CC Switch mirror into the plugin itself: the same text splice, executed
+from inside the TUI, with a footer field so you can see whether the mirror is current.
+
+```
+ccs 3p 4mcp 1m        ← 3 providers, 4 MCP servers, patch written 1 minute ago
+```
+
+## Install
+
+```sh
+# from npm
+dsh plugin --profile dsh-tui add dsh-ccswitch-sync
+
+# or from a local checkout
+dsh plugin --profile dsh-tui add link:/path/to/dsh-ccswitch-sync
+```
+
+Inside the terminal, `/plugin install <spec>` works too. Restart dsh-TUI after installing —
+a bundle is only composed when the process starts.
+
+```sh
+dsh plugin --profile dsh-tui remove dsh-ccswitch-sync
+```
+
+## Use
+
+| | |
+| --- | --- |
+| `/ccswitch` | Provider count, MCP count, patch age |
+| `/ccswitch sync` | Mirror now (this rewrites the profile patch, see below) |
+| footer field `ccswitch` | Same counters, refreshed every 60s; `left-tail`/`right-head`/`right-tail` via the `slot` option |
+
+The footer field is a plugin field, so `/settings → statusBar.pluginFields` can hide it and
+`statusBar.pluginFieldsOrder` can place it per slot group. Turn the field off and the command
+still works.
+
+## When it syncs
+
+**It never syncs on its own.** Installing, activating, reloading and switching sessions all
+leave the profile untouched:
+
+- `/ccswitch sync` — mirror once, now.
+- `DSH_CCSWITCH_SYNC_ON_START=1` — opt in to mirroring once at activation.
+- No file watcher, no timer that writes. The only timer refreshes the footer text.
+
+That default is deliberate. dsh-TUI profiles use `patchReload: live`, so writing
+`cordis.patch.yml` reloads the whole composition — and the row that runs this plugin lives in
+that same file. A mirror that fires on activation would reload the profile that just activated
+it. Doing it on demand keeps that reload a deliberate act.
+
+## How the mirror works
+
+The managed rows go into one marked block at the end of the target patch:
+
+```yaml
+# >>> cc-switch sync (managed) >>>
+- id: llm-pi-ai
+  config:
+    providers: { ... }
+- insert:
+    - id: cc-switch-mcp-context7
+      ...
+# <<< cc-switch sync (managed) <<<
+```
+
+- **Text splice, not YAML round-trip.** Blocks are copied verbatim, so comments, ordering and
+  quoting in the source survive. No YAML dependency, no re-serialisation surprises.
+- **Idempotent.** The composed text is compared with the current file; identical bytes mean no
+  write, no `mtime` change, no reload. This is what keeps the live reload from looping.
+- **Atomic.** Written to `<patch>.candidate.yml` and renamed over the target.
+- **Backed up.** The previous patch is copied to `~/.dsh-tui/ccswitch-sync/backups/` before
+  each rewrite; the newest 20 are kept.
+- **Inside the markers only.** A stale `llm-pi-ai` row outside the block is removed (otherwise
+  the composition would have two) — nothing else outside the block is touched.
+- **Source preference.** `web` is mirrored when it exists, `desktop` otherwise.
+
+## What it does not touch
+
+- `~/.dsh/.credentials.yaml` and every credential. Provider entries reference
+  `CC_SWITCH_DSH_*` environment names; the secrets stay where CC Switch put them.
+- `~/.dsh/skills` and any shared skill tree.
+- Rows outside the managed block, and every other profile.
+- CC Switch's own files: it only reads them.
+
+## Declared permissions
+
+`dsh-plugin.json` declares exactly three (`/plugin` shows the same rows):
+
+| Permission | Scope |
+| --- | --- |
+| `dsh-ccswitch-sync.profile.read` | `~/.dsh/profiles/{web,desktop}/cordis.patch.yml` |
+| `dsh-ccswitch-sync.profile.write` | `~/.dsh/profiles/dsh-tui/cordis.patch.yml` |
+| `dsh-ccswitch-sync.state.write` | `~/.dsh-tui/ccswitch-sync/` |
+
+Permissions are behavioural declarations, not an OS sandbox: as with any dsh-TUI plugin, this
+code runs in-process with the privileges of your terminal (`trusted-in-process`).
+
+## Uninstall and leftover data
+
+`disable` marks the row `disabled`; `remove` takes the bundle out of the profile. Both are
+reversible/ordinary profile operations. **Neither deletes user data**, so after a `remove`:
+
+| Left behind | Where |
+| --- | --- |
+| Patch backups and `plugin.log` | `~/.dsh-tui/ccswitch-sync/` |
+| The managed block in the profile patch | `~/.dsh/profiles/dsh-tui/cordis.patch.yml` |
+
+Delete that directory if you want the backups gone. To drop the managed block, delete the two
+`# >>> / # <<<` marker lines and everything between them — `/ccswitch sync` recreates the block
+on the next run.
+
+## Compatibility
+
+- dsh-TUI ≥ 0.20.0 (the two host seams it uses: footer fields `tuiStatus.setField`, and the
+  `commands` service). Both are probed softly through `ctx.inject`; if either is missing the
+  plugin degrades to a no-op instead of breaking startup.
+- Manifest: Community v0.15 (`dsh-plugin.json`), facet `v1alpha1`.
+- Node `^22.19 || >=24`, ESM only, zero runtime dependencies.
+- Windows, macOS and Linux. All paths come from `DSH_HOME`/`~`, never from a hardcoded drive.
+
+## Development
+
+```sh
+npm test                           # splicing (idempotency, markers, BOM) + file-level sync
+node scripts/check-manifest.mjs    # dependency-free manifest shape check
+```
+
+The authoritative manifest validator is the Community v0.15 parser (`@dsh-std/manifest`);
+`dsh-plugin.json` here parses and projects cleanly under `0.1.1-rc.2`.
+
+## Links
+
+- dsh-TUI: <https://github.com/ccch1mneyyy/dsh-TUI> · <https://dshtui.com>
+- Plugin admission and development guide:
+  <https://github.com/ccch1mneyyy/dsh-TUI/blob/main/tui-profile/docs/plugin-admission-and-development.md>
+- Ecosystem organisation: <https://github.com/dsh-tui-ecosystem>
+
+## License
+
+MIT.

package/README.zh.md

@@ -0,0 +1,144 @@
+# dsh-ccswitch-sync
+
+[English](README.md) · [npm](https://www.npmjs.com/package/dsh-ccswitch-sync) · [dsh-TUI](https://github.com/ccch1mneyyy/dsh-TUI) · [插件目录](https://dshtui.com/plugins)
+
+把 **CC Switch** 写在自己 profile 里的 DSH 配置，镜像进 `dsh-tui` profile 的
+[dsh-TUI](https://dshtui.com) 插件；底栏顺带显示这份镜像有多新。
+
+CC Switch 把 `llm-pi-ai.providers` 和 `cc-switch-mcp-*` 写进
+`~/.dsh/profiles/web/cordis.patch.yml`（没有就退到 `desktop`）。dsh-TUI 跑的是自己的
+profile `~/.dsh/profiles/dsh-tui`，所以那些 provider 与 MCP 在 TUI 里一个都看不见。
+本插件把 CC Switch 的镜像逻辑搬进了插件自己：同一套文本拼接，在 TUI 进程内执行，
+再用一个底栏字段告诉你镜像是不是新鲜的。
+
+```
+ccs 3p 4mcp 1m        ← 3 个 provider、4 个 MCP、1 分钟前写入
+```
+
+## 安装
+
+```sh
+# 从 npm 装
+dsh plugin --profile dsh-tui add dsh-ccswitch-sync
+
+# 或从本地检出装
+dsh plugin --profile dsh-tui add link:/path/to/dsh-ccswitch-sync
+```
+
+终端里 `/plugin install <spec>` 同样可用。装完**重启 dsh-TUI**——bundle 只在新进程启动时
+组合。
+
+```sh
+dsh plugin --profile dsh-tui remove dsh-ccswitch-sync
+```
+
+## 用法
+
+| | |
+| --- | --- |
+| `/ccswitch` | provider 数、MCP 数、patch 年龄 |
+| `/ccswitch sync` | 立刻镜像一次（会重写 profile 补丁，见下） |
+| 底栏字段 `ccswitch` | 同样的计数，每 60 秒刷新；`slot` 选项可放 `left-tail` / `right-head` / `right-tail` |
+
+底栏字段属于插件字段：`/settings → statusBar.pluginFields` 能关掉它，
+`statusBar.pluginFieldsOrder` 能按槽组给它排序。关掉字段不影响命令。
+
+## 什么时候同步
+
+**它不会自己同步。** 安装、激活、重载、切会话都不会动 profile：
+
+- `/ccswitch sync` —— 现在镜像一次。
+- `DSH_CCSWITCH_SYNC_ON_START=1` —— 显式选择「激活时镜像一次」。
+- 没有文件监听，没有会写盘的定时器。唯一的定时器只刷新底栏文本。
+
+这个默认值是刻意的。dsh-TUI 的 profile 是 `patchReload: live`：写
+`cordis.patch.yml` 会重载整份组合——而跑这个插件的那一行就写在同一份文件里。
+激活即镜像等于让插件重载刚刚激活它的 profile。改成手动，那次重载才是一个明确的动作。
+
+## 镜像怎么做的
+
+托管的行会进目标补丁末尾的一个标记区块：
+
+```yaml
+# >>> cc-switch sync (managed) >>>
+- id: llm-pi-ai
+  config:
+    providers: { ... }
+- insert:
+    - id: cc-switch-mcp-context7
+      ...
+# <<< cc-switch sync (managed) <<<
+```
+
+- **文本拼接，不是 YAML 往返。** 区块逐字节照搬，注释、顺序、引号风格都不会被改写。
+  没有 YAML 依赖，也就没有重新序列化带来的意外。
+- **幂等。** 拼装结果与当前文件逐字节比较，一样就一个字节都不写：`mtime` 不变，
+  不触发重载。这是让 live reload 不打转的关键。
+- **原子写。** 先写 `<patch>.candidate.yml`，再 rename 覆盖目标。
+- **留备份。** 每次重写前把旧补丁拷到 `~/.dsh-tui/ccswitch-sync/backups/`，保留最新 20 份。
+- **只动标记以内。** 区块外若残留一条 `llm-pi-ai`，会被去掉（否则组合里会有两条）；
+  区块之外的其他行一律不碰。
+- **来源优先。** 有 `web` 就镜像 `web`，否则用 `desktop`。
+
+## 不碰什么
+
+- `~/.dsh/.credentials.yaml` 与任何凭证。provider 条目引用的是 `CC_SWITCH_DSH_*`
+  环境变量名，密钥留在 CC Switch 放的位置。
+- `~/.dsh/skills` 与任何共享技能树。
+- 托管区块以外的行，以及其他所有 profile。
+- CC Switch 自己的文件：只读，不写。
+
+## 声明的权限
+
+`dsh-plugin.json` 里正好三条（`/plugin` 的授权矩阵显示同样的行）：
+
+| 权限 | 范围 |
+| --- | --- |
+| `dsh-ccswitch-sync.profile.read` | `~/.dsh/profiles/{web,desktop}/cordis.patch.yml` |
+| `dsh-ccswitch-sync.profile.write` | `~/.dsh/profiles/dsh-tui/cordis.patch.yml` |
+| `dsh-ccswitch-sync.state.write` | `~/.dsh-tui/ccswitch-sync/` |
+
+权限是行为声明，不是 OS 沙箱：与任何 dsh-TUI 插件一样，这段代码以进程内全信任
+（`trusted-in-process`）运行，拥有你终端的权限。
+
+## 卸载与残留数据
+
+`disable` 把行标成 `disabled`；`remove` 把 bundle 从 profile 里摘掉。两者都是普通的、
+可复原的 profile 操作。**它们都不删用户数据**，所以 `remove` 之后还会留下：
+
+| 残留 | 位置 |
+| --- | --- |
+| 补丁备份与 `plugin.log` | `~/.dsh-tui/ccswitch-sync/` |
+| profile 补丁里的托管区块 | `~/.dsh/profiles/dsh-tui/cordis.patch.yml` |
+
+要把备份删干净，删那个目录即可。要去掉托管区块，删掉两行 `# >>>` / `# <<<` 标记
+以及它们之间的内容——下次 `/ccswitch sync` 会重新造出来。
+
+## 兼容性
+
+- dsh-TUI ≥ 0.20.0（用到两个宿主接缝：底栏字段 `tuiStatus.setField` 与 `commands` 服务）。
+  两者都经 `ctx.inject` 软探测；缺了其中一个时插件退化为空操作，不会拖垮启动。
+- 清单：Community v0.15（`dsh-plugin.json`），facet `v1alpha1`。
+- Node `^22.19 || >=24`，纯 ESM，零运行时依赖。
+- Windows / macOS / Linux。路径全部来自 `DSH_HOME` 与 `~`，没有写死的盘符。
+
+## 开发
+
+```sh
+npm test                           # 拼接逻辑（幂等、标记、BOM）+ 文件级同步
+node scripts/check-manifest.mjs    # 无依赖的清单形状检查
+```
+
+权威校验器是 Community v0.15 parser（`@dsh-std/manifest`）；本仓库的 `dsh-plugin.json`
+在 `0.1.1-rc.2` 下 parse 与 project 均通过。
+
+## 链接
+
+- dsh-TUI：<https://github.com/ccch1mneyyy/dsh-TUI> · <https://dshtui.com>
+- 插件准入与开发指南：
+  <https://github.com/ccch1mneyyy/dsh-TUI/blob/main/tui-profile/docs/plugin-admission-and-development.md>
+- 生态组织：<https://github.com/dsh-tui-ecosystem>
+
+## 许可
+
+MIT。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# Row contributed by this bundle. The loader resolves the name through the
+# profile's node_modules; `dsh plugin add <path>` links it there first.
+- insert:
+    - id: ccswitch-sync
+      name: 'dsh-ccswitch-sync'

package/dsh-plugin.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://unpkg.com/@dsh-std/manifest@0.1.1-rc.2/schema/dsh-plugin-0.15.schema.json",
+  "id": "msyzzm.dsh-ccswitch-sync",
+  "name": "CC Switch → dsh-TUI sync",
+  "version": "0.1.1",
+  "manifestVersion": "0.15",
+  "facets": {
+    "host": {
+      "entry": "lib/index.js",
+      "apiVersion": "v1alpha1"
+    }
+  },
+  "requires": {
+    "contracts": []
+  },
+  "permissions": [
+    {
+      "name": "dsh-ccswitch-sync.profile.read",
+      "scope": "~/.dsh/profiles/web/cordis.patch.yml, ~/.dsh/profiles/desktop/cordis.patch.yml",
+      "reason": "Reads the CC Switch-managed parts (llm-pi-ai providers, cc-switch-mcp-* rows) out of the source profile patches. Read-only; nothing else in those files is inspected."
+    },
+    {
+      "name": "dsh-ccswitch-sync.profile.write",
+      "scope": "~/.dsh/profiles/dsh-tui/cordis.patch.yml",
+      "reason": "Writes the mirrored rows into one marked block of the dsh-tui profile patch. The write is atomic, only happens when the composed text actually differs, and never touches text outside the block markers."
+    },
+    {
+      "name": "dsh-ccswitch-sync.state.write",
+      "scope": "~/.dsh-tui/ccswitch-sync/",
+      "reason": "Keeps the last 20 copies of the target patch before each rewrite, plus a diagnostic log. Best effort: a failure here never blocks or rewrites a sync."
+    }
+  ],
+  "contributes": {
+    "commands": [
+      {
+        "id": "msyzzm.ccswitch",
+        "title": "ccswitch",
+        "description": "Show the mirror status (providers, MCP servers, patch age); `/ccswitch sync` mirrors now."
+      }
+    ]
+  },
+  "subscriptions": [],
+  "license": "MIT",
+  "source": {
+    "repository": "https://github.com/msyzzm/dsh-ccswitch-sync"
+  },
+  "compat": {
+    "hosts": [
+      "dsh-tui >=0.20.0"
+    ]
+  }
+}

package/lib/index.js

@@ -0,0 +1,185 @@
+/**
+ * dsh-ccswitch-sync — mirror CC Switch's DSH configuration into the dsh-tui
+ * profile, and show how fresh it is.
+ *
+ * The mirror runs on `/ccswitch sync`, or at activation when
+ * `DSH_CCSWITCH_SYNC_ON_START=1` is set. Writing `cordis.patch.yml` from a row
+ * inside that same file triggers the profile's live reload, which is harmless
+ * once at startup and disruptive in the middle of a turn — hence off by
+ * default. `syncOnce` only writes when the composed text actually differs, so
+ * the reload it causes settles after one pass.
+ *
+ * Service discovery goes through `ctx.inject`: on a cold boot the status and
+ * command services mount after this row, so a one-shot `ctx.get` at apply time
+ * would silently miss them.
+ */
+import { appendFile, mkdir, readFile, stat } from 'node:fs/promises'
+import { appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { STATE_DIR, defaultPaths, syncOnce } from './sync.mjs'
+
+export const name = 'ccswitch-sync'
+
+const LOG_PATH = join(STATE_DIR, 'plugin.log')
+
+// Import-time probe: distinguishes "module never imported" from "apply never
+// called" when the row fails to mount on a cold boot. Opt-in — a plugin should
+// not create files just by being imported.
+const DEBUG = process.env.DSH_CCSWITCH_DEBUG === '1'
+if (DEBUG) {
+  try {
+    appendFileSync(LOG_PATH, `[${new Date().toISOString()}] import: module evaluated pid=${process.pid}\n`)
+  } catch {
+    // probe only
+  }
+}
+/** Same file the sync writes, so the status always describes what was synced. */
+const PATCH_PATH = defaultPaths().target
+
+const FIELD_KEY = 'ccswitch'
+const REFRESH_MS = 60_000
+const MAX_STATUS_CELLS = 20
+const STARTUP_DELAY_MS = 200
+/** Activation-time sync is opt-in; installing must never rewrite the profile. */
+const SYNC_ON_START = process.env.DSH_CCSWITCH_SYNC_ON_START === '1'
+
+async function log(line) {
+  try {
+    await mkdir(STATE_DIR, { recursive: true })
+    await appendFile(LOG_PATH, `[${new Date().toISOString()}] ${line}\n`)
+  } catch {
+    // logging is best effort
+  }
+}
+
+function humanAge(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return '?'
+  const seconds = Math.floor(ms / 1000)
+  if (seconds < 90) return `${seconds}s`
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 90) return `${minutes}m`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 48) return `${hours}h`
+  return `${Math.floor(hours / 24)}d`
+}
+
+async function snapshot() {
+  const text = await readFile(PATCH_PATH, 'utf8').catch(() => '')
+  const statInfo = await stat(PATCH_PATH).catch(() => undefined)
+  return {
+    providers: (text.match(/^\s+apiKeyEnv:/gm) ?? []).length,
+    mcp: (text.match(/id: cc-switch-mcp-/g) ?? []).length,
+    patchedAt: statInfo ? statInfo.mtimeMs : undefined,
+  }
+}
+
+function statusText(snap) {
+  if (snap.patchedAt === undefined) return 'ccs no patch'
+  const age = humanAge(Date.now() - snap.patchedAt)
+  // The key is internal to the host, so the field needs its own visible label.
+  return `ccs ${snap.providers}p ${snap.mcp}mcp ${age}`.slice(0, MAX_STATUS_CELLS)
+}
+
+function describe(snap) {
+  return [
+    `providers: ${snap.providers}`,
+    `mcp: ${snap.mcp}`,
+    snap.patchedAt === undefined
+      ? 'patch: 未找到'
+      : `patch: ${new Date(snap.patchedAt).toLocaleString()}（${humanAge(Date.now() - snap.patchedAt)} 前）`,
+    '',
+    '/ccswitch sync 立即同步（会触发 profile 重载）',
+  ].join('\n')
+}
+
+export function apply(ctx) {
+  let syncing
+  let refreshField
+  void log('apply: mounted')
+
+  const runSync = (origin) => {
+    if (syncing !== undefined) return syncing
+    syncing = (async () => {
+      try {
+        const result = await syncOnce(defaultPaths())
+        await log(`sync(${origin}): ${result.note}`)
+        await refreshField?.()
+        return result
+      } catch (error) {
+        const message = error && error.message ? error.message : String(error)
+        await log(`sync(${origin}) failed: ${message}`)
+        return { changed: false, note: `failed: ${message}` }
+      } finally {
+        syncing = undefined
+      }
+    })()
+    return syncing
+  }
+
+  ctx.inject(['tuiStatus'], (child) => {
+    let disposer
+    const refresh = async () => {
+      try {
+        const snap = await snapshot()
+        disposer = child.tuiStatus.setField(FIELD_KEY, statusText(snap), {
+          slot: 'right-head',
+          tone: 'dim',
+          maxCells: MAX_STATUS_CELLS,
+          detail:
+            snap.patchedAt === undefined
+              ? 'cc-switch → dsh-tui: profile patch not found'
+              : `cc-switch → dsh-tui: ${snap.providers} providers, ${snap.mcp} MCP`,
+        })
+      } catch {
+        // the status bar is optional
+      }
+    }
+    void refresh()
+    refreshField = refresh
+    const timer = setInterval(() => void refresh(), REFRESH_MS)
+    ctx.effect(() => () => {
+      clearInterval(timer)
+      try {
+        disposer?.()
+      } catch {
+        // ignore
+      }
+    })
+  })
+
+  ctx.inject(['commands'], (child) => {
+    try {
+      const dispose = child.commands.register({
+        name: 'ccswitch',
+        description: 'CC Switch → dsh-tui 同步状态（/ccswitch sync 立即同步）',
+        handler: async (invocation) => {
+          const raw = String(invocation?.rawInput ?? '').trim().toLowerCase()
+          if (raw === 'sync') {
+            const result = await runSync('manual')
+            return {
+              kind: 'success',
+              text: result.changed
+                ? `已同步并写入 profile：${result.note}\n（profile 会重载，稍等几秒）`
+                : `无需写入：${result.note}`,
+            }
+          }
+          return { kind: 'success', text: describe(await snapshot()) }
+        },
+      })
+      ctx.effect(() => () => {
+        try {
+          dispose?.()
+        } catch {
+          // ignore
+        }
+      })
+    } catch {
+      // commands service may be absent in bare compositions
+    }
+  })
+
+  if (SYNC_ON_START) {
+    const starting = setTimeout(() => void runSync('startup'), STARTUP_DELAY_MS)
+    ctx.effect(() => () => clearTimeout(starting))
+  }
+}

package/lib/sync.mjs

@@ -0,0 +1,215 @@
+/**
+ * The mirror itself: copy the CC Switch-managed parts of a DSH profile patch
+ * (`llm-pi-ai.providers` and the `cc-switch-mcp-*` insert rows) into the
+ * dsh-tui profile patch, inside a marked block.
+ *
+ * Pure text splicing on purpose: the source blocks are copied verbatim, so no
+ * YAML parser is needed and nothing outside the markers is touched. The write
+ * is atomic and only happens when the composed text actually differs, which is
+ * what keeps the live reload from looping.
+ */
+import { copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export const BEGIN_MARK = '# >>> cc-switch sync (managed) >>>'
+export const END_MARK = '# <<< cc-switch sync (managed) <<<'
+
+const EMPTY_PROVIDERS_BLOCK = '- id: llm-pi-ai\n  config:\n    providers: {}\n'
+const KEEP_BACKUPS = 20
+const STABLE_READ_DELAY_MS = 150
+const STABLE_READ_ATTEMPTS = 5
+/** Plugin state (backups, log). The env override keeps tests off the real directory. */
+export const STATE_DIR = join(process.env.CCSWITCH_SYNC_STATE || join(homedir(), '.dsh-tui'), 'ccswitch-sync')
+
+export function defaultPaths() {
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  const profiles = join(home, 'profiles')
+  const targetDir = process.env.DSH_PROFILE_DIR || join(profiles, 'dsh-tui')
+  return {
+    sources: [
+      join(profiles, 'web', 'cordis.patch.yml'),
+      join(profiles, 'desktop', 'cordis.patch.yml'),
+    ],
+    target: join(targetDir, 'cordis.patch.yml'),
+  }
+}
+
+/** A leading BOM would hide the first "- " entry from blockSpans. */
+function stripBom(text) {
+  return text.startsWith('\uFEFF') ? text.slice(1) : text
+}
+
+function linesWithEnds(text) {
+  const out = []
+  let index = 0
+  while (index < text.length) {
+    const newline = text.indexOf('\n', index)
+    if (newline === -1) {
+      out.push(text.slice(index))
+      break
+    }
+    out.push(text.slice(index, newline + 1))
+    index = newline + 1
+  }
+  return out
+}
+
+/** Character spans of every top-level "- " entry in a YAML sequence. */
+export function blockSpans(text) {
+  const spans = []
+  let position = 0
+  let start
+  for (const line of linesWithEnds(text)) {
+    if (line.startsWith('- ')) {
+      if (start !== undefined) spans.push({ start, end: position })
+      start = position
+    }
+    position += line.length
+  }
+  if (start !== undefined) spans.push({ start, end: position })
+  return spans
+}
+
+function firstLine(block) {
+  const newline = block.indexOf('\n')
+  return newline === -1 ? block : block.slice(0, newline)
+}
+
+export function isLlmPiAiBlock(block) {
+  return /^- id:\s*llm-pi-ai\s*$/.test(firstLine(block).trimEnd())
+}
+
+export function isManagedInsert(block) {
+  return block.startsWith('- insert:') && block.includes('cc-switch-mcp-')
+}
+
+/** The blocks to mirror, always with an `llm-pi-ai` entry. */
+export function extractManaged(rawSourceText) {
+  const sourceText = stripBom(rawSourceText)
+  const blocks = blockSpans(sourceText).map(({ start, end }) => sourceText.slice(start, end))
+  const wanted = blocks.filter((block) => isLlmPiAiBlock(block) || isManagedInsert(block))
+  if (!wanted.some(isLlmPiAiBlock)) wanted.unshift(EMPTY_PROVIDERS_BLOCK)
+  return wanted.map((block) => (block.endsWith('\n') ? block : `${block}\n`))
+}
+
+function dropBlocks(text, predicate) {
+  const spans = blockSpans(text)
+    .filter(({ start, end }) => predicate(text.slice(start, end)))
+  let result = text
+  for (let i = spans.length - 1; i >= 0; i -= 1) {
+    result = result.slice(0, spans[i].start) + result.slice(spans[i].end)
+  }
+  return result
+}
+
+/** Remove a lone `[]` line (an empty YAML sequence) when nothing else is left. */
+function dropEmptyFlowSequence(text) {
+  const meaningful = text
+    .split('\n')
+    .map((line) => line.replace(/^\uFEFF/, '').trim())
+    .filter((line) => line !== '' && !line.startsWith('#'))
+  if (meaningful.length !== 1 || meaningful[0] !== '[]') return text
+  return (
+    text
+      .split('\n')
+      .filter((line) => line.replace(/^\uFEFF/, '').trim() !== '[]')
+      .join('\n')
+      .replace(/\n+$/, '') + '\n'
+  )
+}
+
+/** Splice the managed block into the target patch text. */
+export function composePatch(rawTargetText, managedBlocks) {
+  const targetText = stripBom(rawTargetText)
+  const managed = `${BEGIN_MARK}\n${managedBlocks.join('')}${END_MARK}\n`
+  let head = targetText
+  let tail = ''
+  const begin = targetText.indexOf(BEGIN_MARK)
+  const end = targetText.indexOf(END_MARK)
+  if (begin !== -1 && end > begin) {
+    head = targetText.slice(0, begin)
+    tail = targetText.slice(end + END_MARK.length)
+  }
+  head = dropBlocks(head, isLlmPiAiBlock)
+  tail = dropBlocks(tail, isLlmPiAiBlock)
+  head = dropEmptyFlowSequence(head)
+  const trimmedHead = head.replace(/\n+$/, '')
+  let out = trimmedHead === '' ? managed : `${trimmedHead}\n${managed}`
+  if (tail.trim() !== '') out += tail.replace(/^\n+/, '')
+  return out
+}
+
+/**
+ * Read until two consecutive reads agree, so a file another process is still
+ * writing is not mirrored half-written. Gives up after a few attempts and
+ * returns the latest read.
+ */
+async function readStable(path) {
+  try {
+    let previous = await readFile(path, 'utf8')
+    for (let attempt = 1; attempt < STABLE_READ_ATTEMPTS; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, STABLE_READ_DELAY_MS))
+      const current = await readFile(path, 'utf8')
+      if (current === previous) return current
+      previous = current
+    }
+    return previous
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return undefined
+    throw error
+  }
+}
+
+async function backupTarget(target) {
+  try {
+    const stamp = new Date()
+      .toISOString()
+      .replace(/[-:]/g, '')
+      .replace('T', '-')
+      .slice(0, 15)
+    const dir = join(STATE_DIR, 'backups')
+    await mkdir(dir, { recursive: true })
+    const dest = join(dir, `cordis.patch.${stamp}.yml`)
+    await copyFile(target, dest)
+    const names = (await readdir(dir)).filter((name) => name.endsWith('.yml')).sort()
+    for (const name of names.slice(0, Math.max(0, names.length - KEEP_BACKUPS))) {
+      await unlink(join(dir, name)).catch(() => {})
+    }
+  } catch {
+    // backups are best-effort; never block the write
+  }
+}
+
+/**
+ * Mirror the first existing source (web, then desktop) into the target.
+ * @returns `{ changed, note }` — `changed` is true only when bytes were written.
+ */
+export async function syncOnce(paths = defaultPaths()) {
+  const candidates = []
+  for (const path of paths.sources) {
+    try {
+      await stat(path)
+      candidates.push(path)
+    } catch {
+      // missing profile: skip
+    }
+  }
+  if (candidates.length === 0) return { changed: false, note: 'no source profile patch found' }
+
+  const source = candidates[0]
+  const profile = dirname(source).split(/[\\/]/).pop()
+  const sourceText = await readStable(source)
+  if (sourceText === undefined) return { changed: false, note: `source=${profile}: unreadable` }
+
+  let targetText = (await readStable(paths.target)) ?? ''
+  const composed = composePatch(targetText, extractManaged(sourceText))
+  if (composed === targetText) return { changed: false, note: `source=${profile}: already in sync` }
+
+  await mkdir(dirname(paths.target), { recursive: true })
+  const stage = `${paths.target}.candidate.yml`
+  await writeFile(stage, composed, 'utf8')
+  await backupTarget(paths.target)
+  await rename(stage, paths.target)
+  return { changed: true, note: `source=${profile}: wrote ${composed.length} bytes` }
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "dsh-ccswitch-sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Mirror CC Switch's DSH providers and MCP servers into the dsh-tui profile, and show how fresh the mirror is.",
+  "keywords": [
+    "dsh",
+    "dsh-tui",
+    "dsh-plugin",
+    "cc-switch",
+    "ccswitch",
+    "cordis"
+  ],
+  "homepage": "https://github.com/msyzzm/dsh-ccswitch-sync#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/msyzzm/dsh-ccswitch-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/msyzzm/dsh-ccswitch-sync/issues"
+  },
+  "author": "msyzzm",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "dsh-plugin.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "scripts": {
+    "check": "node --check lib/index.js && node --check lib/sync.mjs",
+    "check:manifest": "node scripts/check-manifest.mjs",
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}