dsh-hot-reload 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 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

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**——重启交给你（以及你的守护进程，如果有的话）。
 
 ## 你如何知道发生了什么
@@ -199,6 +217,10 @@ web 应用里的提示（且仅这一部分）还用到：
   版本，所以它选择重载，而不是采纳一个可能从未运行过的版本。对于 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).
 
@@ -230,6 +251,11 @@ live fiber to swap). It does **not** detect *silent* leaks:
   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

@@ -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)) {
@@ -360,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];
@@ -486,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
@@ -542,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.
@@ -554,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 = () => {
@@ -579,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
@@ -593,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.3",
+  "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": [