dsh-hot-reload 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 All notable changes to `dsh-hot-reload` are documented here. This project
 follows [semantic versioning](https://semver.org/).
 
+## 0.2.4
+
+`dsh-hot-reload` now hot-reloads itself when its own package is upgraded, and its
+tracked reload state now survives both a self-reload and a restart. Config and
+API unchanged: `debounce` and `profileDir` are still the only keys.
+
+**Added**
+
+- **The plugin now hot-reloads itself.** Upgrading `dsh-hot-reload` used to need
+  a manual dsh restart, because the running instance was the one doing the
+  swapping. Now the running instance imports the new module, commits its own
+  version and persists it, closes its watcher, and then swaps its own fiber in
+  place. The new `apply()` re-reads state and opens its own watcher — the old
+  watcher is closed before the new one opens, so there is never more than one
+  live watcher.
+- **Reload state is persisted to a file.** `versions` / `failedVersions` /
+  `noticedVersions` are now written to `profileDir/.dsh-hot-reload-state.json`
+  and read back at startup, so a fresh instance inherits the versions the
+  previous one committed instead of treating already-loaded plugins as new and
+  spuriously re-reloading them. The file is written **atomically** — a `.tmp`
+  file is written and then renamed over the target, so a crash mid-write never
+  leaves a truncated file.
+
+**Changed**
+
+- **An unwritable state file now stops the plugin from starting.** Previously
+  that state lived only in memory and was lost on a self-reload or restart. If
+  the state file cannot be written at startup, `apply()` now throws instead of
+  running with in-memory-only state that a later self-reload or restart would
+  lose.
+
+## 0.2.3
+
+A plugin that loads after `dsh-hot-reload` in the bundle order is now reloaded
+when it is upgraded, and every reload outcome — not just successes — reaches the
+terminal. Config and API unchanged.
+
+**Fixes**
+
+- **A plugin loaded after this one now hot-reloads when upgraded.** A first-seen
+  package used to be adopted at face value whatever its version, so a plugin that
+  appears later in the bundle order (for example `dsh-crew`) kept running old
+  code when it had already been upgraded before this plugin's first cycle — the
+  change was silently missed. A first-seen package that has a live fiber is now
+  reloaded instead of adopted; a first-seen package with no live fiber is still
+  adopted, because there is nothing running to replace.
+- **Every outcome now reaches the terminal.** `report()` used to write its stderr
+  line only for a successful reload. A failed or stale reload was then visible
+  only as a transient pop-up and a log line dsh never prints, so the "restart
+  dsh" instruction never reached anyone watching the terminal. stderr is now
+  written for every outcome — reloaded, failed, and stale.
+
 ## 0.2.2
 
 Reloads now re-import a plugin's whole package, not just its entry module.

package/README-zh.md

@@ -35,6 +35,24 @@ dsh 自带的热重载（`cordis-plugin-hmr`）刻意忽略 `node_modules`，所
   重载。提示是**每个版本只给一次**，不是每次检查都给——所以，如果该插件已有
   足够时间启动，你却仍看到同一个版本被报告，请重启 dsh。
 
+### 升级 dsh-hot-reload 自身
+
+`dsh-hot-reload` 也能热重载**它自己**。当它自己的包被升级时，运行中的实例会
+导入新模块、提交自己的版本并持久化、关闭自己的 watcher，然后就地把自己的 fiber
+换掉。新实例会重新读取状态文件并打开自己的 watcher——旧 watcher 先关闭、新 watcher
+后打开，因此任何时刻都不会有超过一个存活的 watcher。
+
+为了让这次交接——以及一次普通重启——安全，本插件把跟踪状态保存在一个文件里：
+`profileDir/.dsh-hot-reload-state.json`。里面存放已提交的 `versions`、永不重试的
+`failedVersions`，以及每个版本只提示一次的 `noticedVersions`。文件是**原子写入**的
+——先写一个 `.tmp` 文件，再重命名覆盖目标文件，所以写入中途崩溃绝不会留下残缺文件
+——并在启动时读回，因此新实例会继承上一实例提交的内容，而不会把已加载的插件当作
+新插件再重载一遍。
+
+这个状态文件是**必需的**。如果启动时无法写入它，本插件会**拒绝启动**（直接抛错），
+而不会带着只存在内存里的状态继续运行——那样的话，一次后续的自我重载或重启就会丢失
+这些状态。
+
 它**绝不会替你重启 dsh**——重启交给你（以及你的守护进程，如果有的话）。
 
 ## 你如何知道发生了什么
@@ -42,7 +60,7 @@ dsh 自带的热重载（`cordis-plugin-hmr`）刻意忽略 `node_modules`，所
 插件会把每个结果写进 dsh 的日志。但 dsh 不会把日志打印到你的终端，所以这些内容
 很容易被忽略。另有两个地方会告诉你发生了什么。
 
-**1. 每次重载成功，在你的终端里输出一行。** 任意 profile 都有：
+**1. 每种结果，在你的终端里输出一行。** 任意 profile 都有：
 
 ```
 dsh-hot-reload: hot-reloaded some-plugin@1.2.0 (1 module(s))
@@ -75,8 +93,9 @@ web 那一部分只在运行 web 服务器的 profile 中加载，并通过
 
 ### 如果你想在终端里看到全部内容
 
-上面那一行只覆盖成功的重载。若想看到本插件写进日志的全部内容（包括失败），请把
-dsh 的控制台日志插件加进你的 profile。它是一个独立的包：
+上面那一行覆盖每一种重载结果——成功、失败和 stale（未尝试、旧代码仍在运行）。若想
+看到本插件写进日志的其它内容（它的警告和诊断信息），请把 dsh 的控制台日志插件加进
+你的 profile。它是一个独立的包：
 
 ```sh
 dsh plugin --profile web add @deepseek-ai/cordis-plugin-logger-console
@@ -192,6 +211,16 @@ web 应用里的提示（且仅这一部分）还用到：
   这些内容，所以并没有多暴露什么秘密。但如果你把 dsh 绑定到 `0.0.0.0`，请把它
   算作局域网里任何人都能打开的又一个地址。
 
+- 在 bundle 顺序里排在 `dsh-hot-reload` **之后**加载的插件，会在启动后的第一次
+  lockfile 写入时被重载一次——重载到它当前的版本——即使那次写入针对的是另一个
+  包。在本插件跨过一轮循环、跟踪到该包之前，它无法分辨运行中的代码是旧版还是当前
+  版本，所以它选择重载，而不是采纳一个可能从未运行过的版本。对于 HMR 安全的插件，
+  这只是无害的单次多余重载。
+
+- 状态文件是**必需的**。本插件会把跟踪状态写入
+  `profileDir/.dsh-hot-reload-state.json`。如果这个文件无法写入——例如 profile
+  目录只读——本插件会拒绝启动（直接抛错），而不会带着只存在内存里的状态继续运行。
+
 范围说明：本插件处理的是**已加载插件的升级**。安装一个**全新**插件是另一回事
 （把它的行加入 `cordis.patch.yml`，这个 dsh 本身已经会热应用）。
 

package/README.md

@@ -41,6 +41,27 @@ Two cases produce no reload, by design:
   You are told **once per version**, not once per check — so if you still see
   the same version reported after the plugin has had time to start, restart dsh.
 
+### Upgrading dsh-hot-reload itself
+
+`dsh-hot-reload` can hot-reload **itself** too. When its own package is
+upgraded, the running instance imports the new module, commits its own version
+and persists it, closes its watcher, and then swaps its own fiber in place. The
+new instance re-reads the state file and opens its own watcher — the old watcher
+is closed before the new one opens, so there is never more than one live watcher.
+
+To make that handoff — and a plain restart — safe, the plugin keeps its tracked
+state in a file: `profileDir/.dsh-hot-reload-state.json`. It holds the committed
+`versions`, the never-retried `failedVersions`, and the once-announced
+`noticedVersions`. The file is written **atomically** — a `.tmp` file is written
+and then renamed over the target, so a crash mid-write never leaves a truncated
+file — and read back at startup, so a fresh instance inherits what the previous
+one committed instead of treating already-loaded plugins as new and re-reloading
+them.
+
+This state file is **required**. If it cannot be written at startup, the plugin
+refuses to start (it throws) rather than running with in-memory-only state that
+a later self-reload or restart would lose.
+
 It **never restarts dsh for you** — restarting is left to you (and your
 supervisor, if any).
 
@@ -50,7 +71,7 @@ The plugin writes every result to dsh's log. But dsh does not print its log to
 your terminal, so those lines are easy to miss. Two extra places show you what
 happened.
 
-**1. One line in your terminal, for each reload that worked.** You get this in
+**1. One line in your terminal, for every outcome.** You get this in
 every profile:
 
 ```
@@ -88,9 +109,10 @@ reload the page to start again.
 
 ### If you want every line in your terminal
 
-The terminal line above only covers reloads that worked. To see everything this
-plugin writes to the log, including failures, add dsh's console logger to your
-profile. It is a separate package:
+The terminal line above covers every reload outcome — reloaded, failed, and
+stale (not attempted — the old code is still running). To see everything else this plugin writes to the log (its warnings and
+diagnostics), add dsh's console logger to your profile. It is a separate
+package:
 
 ```sh
 dsh plugin --profile web add @deepseek-ai/cordis-plugin-logger-console
@@ -221,6 +243,19 @@ live fiber to swap). It does **not** detect *silent* leaks:
   secret. But if you bind dsh to `0.0.0.0`, count it as one more address that
   anyone on your network can open.
 
+- A plugin that loads **after** `dsh-hot-reload` in the bundle order is reloaded
+  once — to its current version — on the first lockfile write after boot, even
+  when that write was for an unrelated package. Until this plugin has tracked the
+  package across one cycle, it cannot tell whether the running code is the old or
+  the current version, so it reloads rather than adopting a version that may
+  never have run. For an HMR-safe plugin this is a harmless single redundant
+  reload.
+
+- The state file is **required**. The plugin writes its tracked state to
+  `profileDir/.dsh-hot-reload-state.json`. If that file cannot be written — for
+  example because the profile directory is read-only — the plugin refuses to
+  start (it throws) rather than running with in-memory-only state.
+
 Scope note: this handles **upgrades of already-loaded plugins**. Installing a
 *brand-new* plugin is a separate concern (adding its row to `cordis.patch.yml`,
 which dsh already hot-applies).

package/lib/index.js

@@ -18,9 +18,9 @@
 // row with no fiber attached yet is reported and left for a later change.
 //
 // Outcomes are announced on two surfaces besides ctx.logger — one stderr line
-// per successful reload, and an SSE channel the browser half (lib/client.js)
-// turns into a transient toast. Both are additive and best-effort; see the
-// "notification surfaces" section in apply().
+// per outcome (reloaded, failed, or stale), and an SSE channel the browser half
+// (lib/client.js) turns into a transient toast. Both are additive and
+// best-effort; see the "notification surfaces" section in apply().
 //
 // NOTE: the reload path uses cordis/loader internals (loader.internal.loadCache,
 // registry.plugin/delete, fiber.entry) — the same ones HMR uses. If a future
@@ -28,7 +28,7 @@
 // crash dsh.
 
 import { watch } from "chokidar";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync, renameSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, join } from "node:path";
@@ -44,6 +44,12 @@ const cjsRequire = createRequire(import.meta.url);
  *  package has no build step to generate a shared one from. */
 const EVENTS_ENDPOINT = "/dsh-hot-reload/events";
 
+/** File under profileDir that persists versions / failedVersions / noticedVersions
+ *  across a self-reload (and a restart), so a fresh apply() inherits the
+ *  committed versions instead of treating them as first-seen and re-reloading
+ *  unrelated plugins. Written atomically (a .tmp then rename). */
+const STATE_FILE = ".dsh-hot-reload-state.json";
+
 /** handlePackage outcome: a reload was attempted and failed — never retry it. */
 const TERMINAL = Symbol("dsh-hot-reload:terminal");
 
@@ -72,6 +78,7 @@ export function apply(ctx, config = {}) {
   }
   const lockfile = join(profileDir, "pnpm-lock.yaml");
   const nodeModules = join(profileDir, "node_modules");
+  const stateFile = join(profileDir, STATE_FILE);
   // Validate the auto-detected dir loudly: watching a wrong/nonexistent lockfile
   // would silently track 0 packages and never fire.
   if (!existsSync(lockfile)) {
@@ -87,10 +94,11 @@ export function apply(ctx, config = {}) {
   // and neither may throw into a reload cycle: a broken notification must never
   // turn a working reload into a failed one.
   //
-  //  - stderr, successful reloads only. cordis's logger fans messages out to
+  //  - stderr, every cycle outcome. cordis's logger fans messages out to
   //    registered exporters, and the dsh host process registers none (only the
   //    browser shell does), so nothing this plugin logs reaches the terminal dsh
-  //    runs in. One line per reload is the profile-independent baseline.
+  //    runs in. One line per outcome — reloaded, failed, or stale — is the
+  //    profile-independent baseline.
   //  - an SSE channel the web half subscribes to (lib/client.js) and renders as
   //    a transient toast. Registered only when a webServer service exists, so a
   //    profile without one — tui — behaves exactly as it does today.
@@ -112,17 +120,23 @@ export function apply(ctx, config = {}) {
    *
    *  `kind` is "reloaded" (it worked), "failed" (attempted and rolled back), or
    *  "stale" (not attempted; the old code is still running). It selects the log
-   *  level and the browser's icon, and only "reloaded" reaches stderr. Callers
-   *  pass the bare message — every surface adds its own prefix. */
+   *  level and the browser's icon. Every kind also reaches stderr — successes
+   *  and failures alike — because the dsh host registers no cordis logger
+   *  exporter, so the log.* line above never reaches the terminal on its own.
+   *  Callers pass the bare message — every surface adds its own prefix. */
   function report(kind, message) {
     if (kind === "reloaded") {
       log.info?.(`dsh-hot-reload: ${message}`);
-      try {
-        process.stderr.write(`dsh-hot-reload: ${message}\n`);
-      } catch {}
     } else {
       log.warn?.(`dsh-hot-reload: ${message}`);
     }
+    // One durable, profile-independent line per outcome, written for every kind.
+    // A failed/stale reload used to be visible only as a transient toast plus an
+    // invisible log line (dsh exports no logger), so "restart needed" never
+    // reached anyone looking at the terminal dsh runs in.
+    try {
+      process.stderr.write(`dsh-hot-reload: ${message}\n`);
+    } catch {}
     if (!connections.size) return;
     const line = `data: ${JSON.stringify({ type: "notice", kind, text: message })}\n\n`;
     for (const res of connections) {
@@ -353,6 +367,24 @@ export function apply(ctx, config = {}) {
     // context that began tearing down while we were awaiting.
     if (disposed) throw new Error("dsh-hot-reload disposed mid-reload");
 
+    // ---- self-reload handoff ----
+    //
+    // Reloading THIS package destroys this closure: registry.delete(oldPlugin)
+    // below disposes this fiber and runs this instance's disposer. Before that
+    // destructive swap, commit the self version and persist + close the watcher,
+    // so the new apply() (run by the reattach) reads committed versions for
+    // everything — including the just-upgraded self — and opens its own watcher
+    // while this one is already closed: never two live watchers at once.
+    const isSelf = pkg === name;
+    if (isSelf) {
+      versions[pkg] = importedVersion;
+      delete failedVersions[pkg];
+      delete noticedVersions[pkg];
+      persistState(); // throws -> the swap is aborted and reported as failed
+      await closeWatcher();
+      selfReloading = true; // from here on the disposer must NOT abort the swap
+    }
+
     // Snapshot fibers before disposal, then swap: dispose old (runs ctx disposers),
     // re-instantiate the new plugin against each old fiber's entry + config.
     const fibers = [...runtime.fibers];
@@ -479,14 +511,115 @@ export function apply(ctx, config = {}) {
   // tracked state. Accepted tradeoff — if the loader is degraded at boot AND
   // the very first lockfile event is a real upgrade, that upgrade is adopted
   // silently (old code keeps running, no notice). Deliberate, not an oversight.
-  let versions = boot ? currentVersions(boot) : null;
-  const failedVersions = Object.create(null); // pkg -> version whose reload failed (never retried)
-  const noticedVersions = Object.create(null); // pkg -> version already announced on a retryable path
+
+  // ---- persisted state ----
+  //
+  // versions / failedVersions / noticedVersions used to be closure-only, so a
+  // self-reload (registry.delete of THIS plugin) destroyed them and the fresh
+  // apply() treated every already-loaded plugin as first-seen, spuriously
+  // reloading them. They now persist to profileDir/.dsh-hot-reload-state.json.
+  const persisted = loadState();
+
+  // Seed from what a previous instance committed, then let the boot snapshot be
+  // authoritative for what is actually on disk NOW. The boot override keeps a
+  // normal dsh restart from re-reloading plugins that were upgraded while it was
+  // down (persisted is stale there); only packages the boot snapshot never saw —
+  // loaded "late" relative to this instance — keep their persisted version.
+  let versions = persisted?.versions ?? null;
+  if (!versions) {
+    versions = boot ? currentVersions(boot) : null;
+  } else if (boot) {
+    const bootVersions = currentVersions(boot);
+    for (const pkg in bootVersions) {
+      // A null boot read (package.json momentarily unreadable) is not
+      // authoritative — keep the persisted version rather than "changing" it.
+      if (bootVersions[pkg] != null) versions[pkg] = bootVersions[pkg];
+    }
+  }
+  const failedVersions = persisted?.failedVersions ?? Object.create(null); // pkg -> version, never retried
+  const noticedVersions = persisted?.noticedVersions ?? Object.create(null); // pkg -> version, announced once
+
+  let watcher = null;
+  let watcherClosed = false;
+  let selfReloading = false; // true while THIS instance is swapping itself out
   let timer = null;
   let pending = false; // at most ONE cycle queued behind the running one; bursts coalesce into it
   let disposed = false;
   let running = Promise.resolve(); // serializes reload cycles across debounce batches
 
+  /** Copy a JSON-parsed object into a null-prototype map, matching how these
+   *  maps are created everywhere else in this file — membership is tested with
+   *  `in`, so a plain object would report inherited names like "constructor". */
+  function toNullProto(obj) {
+    const out = Object.create(null);
+    if (obj && typeof obj === "object") {
+      for (const key in obj) out[key] = obj[key];
+    }
+    return out;
+  }
+
+  /** Read the persisted state, or null when there is none / it is unreadable. */
+  function loadState() {
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(stateFile, "utf8"));
+    } catch {
+      return null;
+    }
+    // A null/absent `versions` field means "no baseline yet" (adopt on the first
+    // successful snapshot); a non-object field (hand-edited/corrupt) is treated
+    // the same rather than being diffed against as a fake baseline.
+    const versions =
+      raw && typeof raw.versions === "object" && raw.versions ? toNullProto(raw.versions) : null;
+    return {
+      versions,
+      failedVersions: toNullProto(raw?.failedVersions),
+      noticedVersions: toNullProto(raw?.noticedVersions),
+    };
+  }
+
+  /** Atomically persist the tracked maps (write a .tmp then rename over it, so a
+   *  crash mid-write never leaves a truncated file). Throws — fail-loud — on any
+   *  write or rename failure: running on with a state file that cannot be written
+   *  would lose every committed version at the next self-reload/restart and
+   *  spuriously reload unrelated plugins. `versions` is written verbatim so a
+   *  null baseline round-trips as null (not {}). */
+  function persistState() {
+    const payload = JSON.stringify(
+      {
+        versions,
+        failedVersions,
+        noticedVersions,
+      },
+      null,
+      2
+    );
+    const tmp = `${stateFile}.tmp`;
+    try {
+      writeFileSync(tmp, payload);
+      renameSync(tmp, stateFile);
+    } catch (err) {
+      throw new Error(
+        `dsh-hot-reload: cannot persist reload state to ${stateFile}: ${err?.message ?? err}`,
+        { cause: err }
+      );
+    }
+  }
+
+  /** Close the watcher exactly once, whatever path (self-reload or teardown)
+   *  reaches here first. */
+  async function closeWatcher() {
+    if (watcherClosed || !watcher) return;
+    watcherClosed = true;
+    try {
+      await watcher.close();
+    } catch {}
+  }
+
+  // Fail loud at startup: if the state file cannot be written now, stop rather
+  // than run with in-memory-only state that a later self-reload would lose.
+  persistState();
+
   async function runCycle() {
     if (disposed) return;
     // ONE loader enumeration + ONE package.json read per package for the whole
@@ -511,8 +644,21 @@ export function apply(ctx, config = {}) {
         continue;
       }
       if (!(pkg in versions)) {
-        versions[pkg] = version; // newly loaded row: dsh just loaded it fresh, nothing to reload
-        continue;
+        // A package our boot snapshot never saw. Two cases:
+        //  - no live fiber: nothing is running yet (mid-import, or only disabled
+        //    rows), so there is no stale code to replace — dsh loads fresh code
+        //    itself. Adopt the version.
+        //  - has a live fiber: the package was already running before we first
+        //    saw it — it loaded after our boot snapshot, as a bundle entry
+        //    ordered after this plugin. Its running code may therefore predate
+        //    this version. Reload it rather than silently adopting a version
+        //    that never ran (otherwise a late-loaded plugin upgraded before the
+        //    first cycle keeps its old code forever, with no notice).
+        if (!snap[pkg].live.length) {
+          versions[pkg] = version;
+          continue;
+        }
+        // fall through: treat as changed and reload
       }
       if (versions[pkg] === version) continue;
       // A version whose reload failed is never re-attempted: each attempt tears
@@ -522,10 +668,12 @@ export function apply(ctx, config = {}) {
       const commit = await handlePackage(pkg, snap[pkg]);
       if (commit === TERMINAL) {
         failedVersions[pkg] = version; // attempted, failed: don't try this version again
+        persistState();
       } else if (commit) {
         versions[pkg] = commit; // the version actually imported, not the cycle-start one
         delete failedVersions[pkg];
         delete noticedVersions[pkg];
+        persistState();
       }
       // commit === false: not attempted (teardown, or nothing attached yet) —
       // leave it uncommitted and retryable on a later event.
@@ -534,13 +682,16 @@ export function apply(ctx, config = {}) {
     // when its directory is missing. A point-in-time fs probe is wrong twice
     // over: a dangling pnpm symlink mid-swap would evict a live plugin, and a
     // removed plugin row whose package stays installed would be tracked forever.
+    let dropped = false;
     for (const pkg of Object.keys(versions)) {
       if (!(pkg in snap)) {
         delete versions[pkg];
         delete failedVersions[pkg];
         delete noticedVersions[pkg];
+        dropped = true;
       }
     }
+    if (dropped) persistState();
   }
 
   const trigger = () => {
@@ -559,12 +710,20 @@ export function apply(ctx, config = {}) {
     }, debounceMs);
   };
 
-  const watcher = watch(lockfile, { ignoreInitial: true });
+  watcher = watch(lockfile, { ignoreInitial: true });
   watcher.on("change", trigger);
   watcher.on("add", trigger);
   watcher.on("error", (e) => log.warn?.("dsh-hot-reload: watcher error", e));
 
   ctx.effect(() => async () => {
+    if (selfReloading) {
+      // The self-reload swap is in flight: reloadEntry has already persisted
+      // state and closed the watcher. Do NOT set `disposed` (it would abort the
+      // swap mid-flight) and do NOT close the watcher again. Only keep an
+      // in-flight cycle rejection from going unhandled.
+      running.catch(() => {});
+      return;
+    }
     // Never wait on an in-flight reload: dsh's shutdown must not hang on an
     // arbitrary plugin's apply()/fiber.await(). Setting `disposed` first makes
     // any straggling cycle harmless — it stops between modules, and a reload
@@ -573,9 +732,7 @@ export function apply(ctx, config = {}) {
     disposed = true;
     if (timer) clearTimeout(timer);
     running.catch(() => {}); // keep an in-flight rejection from going unhandled
-    try {
-      await watcher.close();
-    } catch {}
+    await closeWatcher();
   });
 
   // ---- notice channel ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hot-reload",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "Live-reload upgraded DeepSeek Harness (dsh) plugins without restarting dsh \u2014 the running plugin is swapped in place, and a reload that fails rolls back to the working old version and asks for a manual restart.",
   "keywords": [