dsh-home-hosted 0.9.0 → 0.9.2

package/docs/DESIGN.md

@@ -38,8 +38,8 @@ its page.
 `onPortConflict: kill` (0.6.0), `persistent` (0.6.3), `restart <id>` (0.7.13) and the nullable-`label`
 patch (0.7.21) all predate the release this plugin pins. The plugin used to consult the answering
 panel's version and refuse or drop those keys (`KILL_UNSUPPORTED`), and later to retry a `restart` as a
-stop-then-start pair. Both are gone: it pins `home-hosted@^0.9.0`, which refuses an older panel
-outright, so neither check could ever fire again.
+stop-then-start pair. Both are gone: it pins `home-hosted@^0.9.x` — 0.9.0 at the time of writing —
+which refuses an older panel outright, so neither check could ever fire again.
 
 An old state root is upgraded by running the latest 0.7.x **once, before installing 0.8** — its first
 run moves the state into `.hh/`. A root a 0.8-era panel left on config schema 1 needs

package/docs/PANEL.md

@@ -69,11 +69,17 @@ a config it created before any panel had run was unstartable on 0.9. It now stam
 every file it **creates**, reading the number from the pinned release rather than hard-coding it — a
 fixed `2` would break again at the next bump, from the other side.
 
-A file that already exists **without** a stamp is refused instead of stamped: its content may still
-need lifting, and stamping it would claim a migration that never ran and silently strand what the step
-rewrites. Measured: a schema-2 stamp over an old `notifications.telegram` block makes 0.9 report the
-key as unrecognized and ignore it, so the person's notifications end up silently off. Lifting a config
-is `home-hosted migrate`'s job, and the refusal names it.
+An existing file that does not already declare **the** schema the pinned panel reads is refused, in
+both directions: below it needs `home-hosted migrate`, above it was written by a newer home-hosted
+than this plugin pins. Stamping over either would claim a migration that never ran — measured, a
+schema-2 stamp over an old `notifications.telegram` block makes 0.9 report the key as unrecognized and
+ignore it, so the person's notifications end up silently off — and writing on regardless would leave
+this plugin editing a panel that cannot boot while every call reports success. Lifting or downgrading
+a config is `home-hosted migrate`'s job, and the refusal names the remedy for the direction it found.
+
+The page says so **before** a write is attempted: a config the panel cannot boot is reported as the
+panel's error, so the root is not shown as healthy until the first call fails. The entries are still
+listed — the file is readable, it is only un-bootable — so nothing looks lost while you migrate it.
 
 The floor is `0.9.0` for the same reason the pin is: a 0.8.x panel reads a schema-2 stamp as a *newer*
 release's file and refuses that in turn, so no stamp satisfies both and there is no version-conditional
@@ -102,6 +108,22 @@ recreating its own log, an unflushed log batch, a Windows test skip — touch no
 no `.proxy/proxy.json`, `ProxyService`, `terminatePid`, or `DELETE /api/logs`, and `serverSchema`,
 `CONFIG_SCHEMA`, `/_hh` and the CLI are unchanged.
 
+**0.9.4 also needs no adaptation, and that was checked by use.** It adds no command and no required
+field: `PUT /api/servers/:id`, `POST /api/servers/orphans/:id/stop`, presets and restore reporting are
+new routes and UI, none of which this plugin calls; `stoppedByPanel`, `orphans`, `healthRestarts` and
+the action-result `code` are new *optional* fields. `serverSchema`, `editableFields`, the merge keys,
+`CONFIG_SCHEMA` (still 2), the four `/_hh` routes and every CLI subcommand and flag are unchanged, so
+the pin moved and the floor did not. Verified by diffing the published sourcemaps of 0.9.2 and 0.9.4
+(34 changed files) and by driving a real 0.9.4 panel: this plugin's client lists, creates, patches,
+starts, stops and deletes an entry, and reads workspaces and settings, exactly as on 0.9.2.
+
+Two 0.9.4 behaviour changes reach the page without breaking it. `/healthz` now answers 503 for **any**
+crashed server rather than only an `autostart` one — measured, and harmless here because `probePanel`
+asks whether the panel answered at all, not whether it said 200. And the supervisor now bounds health
+force-restarts and then **stops** the entry, reporting it as `stopped` with `stoppedByPanel: true`; the
+page renders that as a plain `stopped`, so it reads like a deliberate stop. That is a fidelity gap in
+the status chip, not a break: the reason is still on the panel's own card and in `lastError`.
+
 That copy resolves to a pnpm path carrying a version and a peer hash, which moves on the next install
 and disappears when the profile is rebuilt. A boot entry that baked it in would fail exactly when it
 matters. So the entry runs a generated launcher in the plugin state dir (`bin/home-hosted.mjs`,

package/lib/index.js

@@ -109,6 +109,63 @@ var DEFAULT_SETTINGS = {
   cli: { prefer: "pinned" }
 };
 
+// src/rpc.ts
+function answer(endpoint, result) {
+  return Response.json({ v: RPC_VERSION, endpoint, result });
+}
+function registerRpc(ctx, service) {
+  ctx.inject(["connection"], (scoped) => {
+    const connection = scoped.connection;
+    if (connection?.fetch?.register === void 0)
+      return;
+    scoped.effect(() => {
+      let dispose;
+      try {
+        dispose = connection.fetch.register({
+          // The exact-route registry is keyed by the full request path, so the
+          // `/api` prefix belongs here; the page composes the same URL from
+          // API_BASE + RPC_PATH.
+          path: `/api${RPC_PATH}`,
+          methods: ["POST"],
+          requestBody: "buffered",
+          fetch: async (request) => {
+            let body;
+            try {
+              body = await request.json();
+            } catch {
+              return Response.json({ error: "the request body is not JSON" }, { status: 400 });
+            }
+            if (body === null || typeof body !== "object" || body.v !== RPC_VERSION) {
+              return Response.json(
+                { error: `this page and the host disagree on the protocol version (expected ${String(RPC_VERSION)})` },
+                { status: 409 }
+              );
+            }
+            try {
+              const value = await service.call(body.endpoint, body.payload);
+              return answer(body.endpoint, { ok: true, value });
+            } catch (error) {
+              const code = error?.code;
+              const message2 = error instanceof Error ? error.message : String(error);
+              const detail = error?.detail;
+              return answer(body.endpoint, { ok: false, error: { code: typeof code === "string" ? code : "INTERNAL", message: message2, ...detail === void 0 ? {} : { detail } } });
+            }
+          }
+        });
+      } catch (error) {
+        const logger = scoped.logger;
+        logger?.warn?.(`[dsh-home-hosted] could not register ${RPC_PATH}: ${error instanceof Error ? error.message : String(error)}`);
+        return () => {
+        };
+      }
+      return () => {
+        void Promise.resolve(dispose()).catch(() => {
+        });
+      };
+    }, "dsh-home-hosted: rpc route");
+  });
+}
+
 // src/service.ts
 import { Service } from "@deepseek-ai/cordis";
 import fs18 from "node:fs";
@@ -2960,7 +3017,7 @@ function buildHomeHostedBootSpec(facts, launch, options) {
 }
 
 // src/home-hosted/resolve.ts
-var EXPECTED_RANGE = "^0.9.0";
+var EXPECTED_RANGE = "^0.9.4";
 var MIN_SUPPORTED_VERSION = "0.9.0";
 function pinnedManifestPath() {
   try {
@@ -3176,9 +3233,12 @@ function readConfigSchemaFrom(manifestPath) {
 // src/home-hosted/config-file.ts
 var ConfigLayoutError = class extends Error {
   name = "ConfigLayoutError";
+  /** The wire code a caller reports; the root's layout is a readable config problem, not a crash. */
+  code = "CONFIG_UNREADABLE";
 };
 var ConfigPatchError = class extends Error {
   name = "ConfigPatchError";
+  code = "INVALID_PATCH";
 };
 function readConfig(home, workspace = DEFAULT_WORKSPACE) {
   const refusal = migrationRefusal(home);
@@ -3208,17 +3268,30 @@ function writeConfig(home, raw, writtenBy = "dsh-home-hosted", workspace = DEFAU
   writeFileAtomic(file, `${JSON.stringify(next, null, 2)}
 `);
 }
+function schemaRefusal(meta, where, creating) {
+  const pinned = panelConfigSchema();
+  if (pinned === null)
+    return null;
+  const declared = isRecord(meta) && typeof meta.schema === "number" ? meta.schema : null;
+  if (declared === null) {
+    return creating ? null : `${where} carries no meta.schema, so its config shape is unknown; run \`home-hosted migrate\` before this plugin writes it`;
+  }
+  if (declared === pinned)
+    return null;
+  return declared < pinned ? `${where} is on config schema ${declared}, which home-hosted ${pinned} refuses to boot; run \`home-hosted migrate\` before this plugin writes it` : `${where} is on config schema ${declared}, written by a newer home-hosted than this plugin's ${pinned}; update home-hosted, or pin this plugin to the release that wrote it`;
+}
 function stampedMeta(existing, writtenBy, where, file) {
-  const meta = isRecord(existing) ? { ...existing } : {};
-  if (typeof meta.schema !== "number") {
-    if (fs12.existsSync(file)) {
-      throw new ConfigLayoutError(
-        `${where} carries no meta.schema, so its config shape is unknown; run \`home-hosted migrate\` before this plugin writes it`
-      );
-    }
-    const schema = panelConfigSchema();
-    if (schema !== null)
-      meta.schema = schema;
+  const onDisk = fs12.existsSync(file) ? readJson(file) : null;
+  const diskMeta = isRecord(onDisk) && isRecord(onDisk.meta) ? onDisk.meta : {};
+  const meta = { ...diskMeta, ...isRecord(existing) ? existing : {} };
+  if (onDisk === null) {
+    const pinned = panelConfigSchema();
+    if (pinned !== null)
+      meta.schema = pinned;
+  } else {
+    const refusal = schemaRefusal(meta, where, false);
+    if (refusal !== null)
+      throw new ConfigLayoutError(refusal);
   }
   meta.writtenBy = writtenBy;
   return meta;
@@ -6461,6 +6534,8 @@ var HomeHostedService = class extends Service {
       servers = read.servers;
       if (read.error !== null)
         lastError ??= read.error;
+      const file = readConfig(this.options.home, this.managedWorkspace());
+      lastError ??= schemaRefusal(file.raw?.meta, `servers.config.json in ${this.managedWorkspace()}`, !file.exists);
     }
     return {
       defaultEntryId: this.options.defaultEntryId,
@@ -6694,63 +6769,6 @@ var HomeHostedService = class extends Service {
   }
 };
 
-// src/rpc.ts
-function answer(endpoint, result) {
-  return Response.json({ v: RPC_VERSION, endpoint, result });
-}
-function registerRpc(ctx, service) {
-  ctx.inject(["connection"], (scoped) => {
-    const connection = scoped.connection;
-    if (connection?.fetch?.register === void 0)
-      return;
-    scoped.effect(() => {
-      let dispose;
-      try {
-        dispose = connection.fetch.register({
-          // The exact-route registry is keyed by the full request path, so the
-          // `/api` prefix belongs here; the page composes the same URL from
-          // API_BASE + RPC_PATH.
-          path: `/api${RPC_PATH}`,
-          methods: ["POST"],
-          requestBody: "buffered",
-          fetch: async (request) => {
-            let body;
-            try {
-              body = await request.json();
-            } catch {
-              return Response.json({ error: "the request body is not JSON" }, { status: 400 });
-            }
-            if (body === null || typeof body !== "object" || body.v !== RPC_VERSION) {
-              return Response.json(
-                { error: `this page and the host disagree on the protocol version (expected ${String(RPC_VERSION)})` },
-                { status: 409 }
-              );
-            }
-            try {
-              const value = await service.call(body.endpoint, body.payload);
-              return answer(body.endpoint, { ok: true, value });
-            } catch (error) {
-              const code = error instanceof HomeHostedError ? error.code : "INTERNAL";
-              const message2 = error instanceof Error ? error.message : String(error);
-              const detail = error?.detail;
-              return answer(body.endpoint, { ok: false, error: { code, message: message2, ...detail === void 0 ? {} : { detail } } });
-            }
-          }
-        });
-      } catch (error) {
-        const logger = scoped.logger;
-        logger?.warn?.(`[dsh-home-hosted] could not register ${RPC_PATH}: ${error instanceof Error ? error.message : String(error)}`);
-        return () => {
-        };
-      }
-      return () => {
-        void Promise.resolve(dispose()).catch(() => {
-        });
-      };
-    }, "dsh-home-hosted: rpc route");
-  });
-}
-
 // src/home-hosted/instances-notice.ts
 var INSTANCES_CONTEXT_ORDER = 130;
 function instancesContextText(instances, enabled) {