dsh-home-hosted 0.9.4 → 0.9.5

package/docs/DESIGN.md

@@ -42,8 +42,9 @@ stop-then-start pair. Both are gone: it pins `home-hosted@^0.9.x` — 0.9.0 at t
 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
-`home-hosted migrate` before this plugin will write it; see [PANEL](PANEL.md#upgrading-an-existing-state-root).
+run moves the state into `.hh/`. A root a 0.8-era panel left on config schema 1 is lifted
+automatically: a failed start makes the plugin run the panel's own `migrate` and retry, at boot and from
+the page alike. See [PANEL](PANEL.md#upgrading-an-existing-state-root).
 
 ## Tests
 

package/docs/PANEL.md

@@ -87,15 +87,28 @@ path. A 0.8.x panel is not a lesser-supported copy — it is one this plugin can
 
 ### Upgrading an existing state root
 
-A root a 0.8-era panel wrote is on config schema 1. Run the panel's own migration once, before letting
-0.9 — or this plugin — write it:
+A root a 0.8-era panel wrote is on config schema 1, and 0.9 refuses to boot it.
+
+**This plugin lifts the panel it manages for you.** Both start paths — the page's Start button and the
+generated launcher a boot entry runs — ask the panel's own `migrate --dry-run` after a failed start, and
+when it reports a pending migration they apply `migrate --yes` and retry once. So an upgrade that raised
+the schema heals itself: at boot, with no page open, and without you running anything.
 
 ```sh
-home-hosted migrate --dry-run   # print the steps, write nothing
-home-hosted migrate --yes       # keep a .bak beside each rewritten file
+# what runs for you, in order
+home-hosted migrate --dry-run   # the question: is a migration pending?
+home-hosted migrate --yes       # only if it is; keeps a .bak beside each rewritten file
 ```
 
-Both sides are then on schema 2, and every write stays readable by the release that pinned it.
+The decision is the panel's own printed plan, never the failure text, so a start that failed for another
+reason is left alone and a reworded refusal cannot disable the repair. Nothing here implements a
+migration step: `migrate` keeps the backups, validates its output, and refuses a config it cannot lift —
+that refusal is reported verbatim.
+
+**A root that is not the one this plugin manages is not touched.** Run the two commands by hand against
+it, exactly as above. The same applies when the panel refuses for a reason `migrate` cannot fix (a file
+from a *newer* release, an unreadable config): the start's own error is what you get, with the migration's
+refusal appended.
 
 **0.7.21 widens that nullable set by one field, and it closed a bug here.** Clearing a server's label
 sent an empty string, which the panel accepts and saves — so the entry kept a blank label instead of

package/lib/index.js

@@ -3017,7 +3017,7 @@ function buildHomeHostedBootSpec(facts, launch, options) {
 }
 
 // src/home-hosted/resolve.ts
-var EXPECTED_RANGE = "^0.9.6";
+var EXPECTED_RANGE = "^0.9.7";
 var MIN_SUPPORTED_VERSION = "0.9.0";
 function pinnedManifestPath() {
   try {
@@ -3411,20 +3411,113 @@ import process7 from "node:process";
 import fs13 from "node:fs";
 import path12 from "node:path";
 import process6 from "node:process";
+
+// src/home-hosted/panel-migrate.ts
+var MIGRATION_STEP_ANCHOR = /^migrating .+: config schema \d+ → \d+$/m;
+var MIGRATION_STEP_SOURCE = MIGRATION_STEP_ANCHOR.source;
+function cliText(answer2) {
+  return [answer2.stdout, answer2.stderr].filter((part) => typeof part === "string" && part.trim().length > 0).join("\n").trim();
+}
+function migrationSteps(answer2) {
+  const text = [answer2.stdout, answer2.stderr].join("\n");
+  return text.split("\n").filter((line) => MIGRATION_STEP_ANCHOR.test(line));
+}
+function migrationTransitions(steps) {
+  const jumps = steps.map((step) => /config schema (\d+) → (\d+)/.exec(step)).filter((match) => match !== null).map((match) => `${match[1]} \u2192 ${match[2]}`);
+  return [...new Set(jumps)];
+}
+function migrationNote(transitions) {
+  const from = transitions.length === 0 ? "the config schema" : `config schema ${transitions.join(", ")}`;
+  return `${from} made this panel refuse to start, so it was lifted with \`home-hosted migrate --yes\` (a .bak sits beside each rewritten file)`;
+}
+async function repairPanelMigration(run2) {
+  const plan = await run2(["migrate", "--dry-run"]);
+  const steps = migrationSteps(plan);
+  if (steps.length === 0)
+    return { note: null, failure: null };
+  const applied = await run2(["migrate", "--yes"]);
+  if (applied.code !== 0)
+    return { note: null, failure: cliText(applied) || `home-hosted migrate exited ${String(applied.code)}` };
+  return { note: migrationNote(migrationTransitions(steps)), failure: null };
+}
+
+// src/home-hosted/launcher.ts
 function launcherDir(stateDir) {
   return path12.join(stateDir, "bin");
 }
 function launcherPath(stateDir) {
   return path12.join(launcherDir(stateDir), "home-hosted.mjs");
 }
-var LAUNCH_CHILD = `function launchChild(program, argv, useShell) {
-  const child = spawn(program, argv, { stdio: 'inherit', shell: useShell })
-  for (const signal of ['SIGTERM', 'SIGINT', 'SIGQUIT', 'SIGHUP'])
-    process.on(signal, () => { try { child.kill(signal) } catch {} })
-  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
-  child.on('error', (error) => {
-    console.error('[dsh-home-hosted] could not start ' + program + ': ' + error.message)
-    process.exit(1)
+var LAUNCH_CHILD = `let current = null
+let stopping = false
+for (const signal of ['SIGTERM', 'SIGINT', 'SIGQUIT', 'SIGHUP'])
+  process.on(signal, () => { stopping = true; try { current.kill(signal) } catch {} })
+
+/** Run a child with this process's own stdio; resolves with how it ended. */
+function launchChild(program, argv, useShell) {
+  return new Promise((resolve) => {
+    const child = spawn(program, argv, { stdio: 'inherit', shell: useShell })
+    current = child
+    child.on('exit', (code, signal) => resolve({ code, signal }))
+    child.on('error', (error) => {
+      console.error('[dsh-home-hosted] could not start ' + program + ': ' + error.message)
+      // A child that never started is a failure, and exitWith reads a null code with no signal as
+      // success \u2014 which would report a launcher that started nothing as having exited cleanly.
+      resolve({ code: 1, signal: null })
+    })
+  })
+}
+
+/** The exit code a launcher reports for a child's outcome, as before. */
+function exitWith(result) {
+  process.exit(result.code ?? (result.signal ? 1 : 0))
+}`;
+var MIGRATION_REPAIR = `/**
+ * Ask the panel's own migrate whether this root needs lifting, apply it if so, and say
+ * whether a retry is worthwhile (null means "no, the original failure stands").
+ *
+ * Only this script's own '--foreground' daemon run is repaired. The boot entry passes it, so a
+ * failure there is the one nothing else can heal; a 'down' or a one-off command that failed is
+ * left alone, because lifting a config is not what a person asked those for.
+ */
+async function repairMigration(program, prefix, args) {
+  if (!args.includes('--foreground')) return null
+  const dirs = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '--home' && args[index + 1] !== undefined) dirs.push('--home', args[index + 1])
+    if (args[index] === '--project' && args[index + 1] !== undefined) dirs.push('--project', args[index + 1])
+  }
+
+  // The decision is the panel's answer, never its failure text: one 'migrating ...' line per
+  // file it would lift, at column 0. A failed start for any other reason prints none.
+  const plan = await runQuiet(program, [...prefix, 'migrate', '--dry-run', ...dirs])
+  const anchor = new RegExp(${JSON.stringify(MIGRATION_STEP_SOURCE)}, 'm')
+  if (!anchor.test(plan.output))
+    return null
+
+  console.error('[dsh-home-hosted] the panel config is on an older schema, which this panel refuses to boot; lifting it with \`home-hosted migrate --yes\` (a .bak is kept beside each file)')
+  // Not through launchChild: a stop signal must not kill the process that is rewriting the
+  // person's config, so 'current' stays null and a pending stop waits for this to finish.
+  const applied = await runQuiet(program, [...prefix, 'migrate', '--yes', ...dirs])
+  if (applied.code !== 0) {
+    console.error('[dsh-home-hosted] the migration did not succeed: ' + applied.output)
+    return null
+  }
+  console.error('[dsh-home-hosted] migrated; starting the panel again')
+  return true
+}
+
+/** Run the CLI with its output captured (both streams), for a question rather than a daemon. */
+function runQuiet(program, argv) {
+  return new Promise((resolve) => {
+    const child = spawn(program, argv, { stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = ''
+    const collect = (chunk) => { output = (output + chunk).slice(-65536) }
+    child.stdout?.on('data', collect)
+    child.stderr?.on('data', collect)
+    child.on('exit', code => resolve({ code, output }))
+    // A child that never started cannot have applied anything, and a null code reads as success.
+    child.on('error', error => resolve({ code: 1, output: String(error && error.message) }))
   })
 }`;
 function launcherRecordPath(stateDir) {
@@ -3629,12 +3722,30 @@ if (entry === null) {
   process.exit(1)
 }
 
+${MIGRATION_REPAIR}
+
 const args = process.argv.slice(2)
 const isScript = /\\.(mjs|cjs|js)$/.test(entry)
-if (isScript)
-  launchChild(process.execPath, [entry, ...args], false)
-else
-  launchChild(entry, args, process.platform === 'win32' && /\\.(cmd|bat)$/i.test(entry))
+const program = isScript ? process.execPath : entry
+const useShell = !isScript && process.platform === 'win32' && /\\.(cmd|bat)$/i.test(entry)
+
+// What precedes the command word: node runs an entry script, and a shim or global executable is
+// itself the program.
+const prefix = isScript ? [entry] : []
+const argv = [...prefix, ...args]
+
+const first = await launchChild(program, argv, useShell)
+if (first.code === 0 || stopping) exitWith(first)
+
+// The panel refused to start, and at boot nothing else can repair it: this launcher is
+// what the entry runs, and a config on an older schema fails here forever. Ask the
+// panel's own migrate whether that is the reason, lift it if so, and retry once.
+const repaired = await repairMigration(program, prefix, args)
+// A stop that arrived while the migration ran has already reported its outcome: starting the
+// panel now would undo it, and a unit stopping while its launcher starts a daemon is the
+// orphaned-panel case this launcher exists to prevent.
+if (repaired === null || stopping) exitWith(first)
+exitWith(await launchChild(program, argv, useShell))
 `;
 }
 function writeLauncher(options) {
@@ -3842,10 +3953,13 @@ if (entry === null) {
 }
 
 const args = process.argv.slice(2)
-if (/\\.(mjs|cjs|js)$/.test(entry))
-  launchChild(process.execPath, [entry, ...args], false)
-else
-  launchChild(entry, args, process.platform === 'win32' && /\\.(cmd|bat)$/i.test(entry))
+const isScript = /\\.(mjs|cjs|js)$/.test(entry)
+const program = isScript ? process.execPath : entry
+const argv = isScript ? [entry, ...args] : args
+// .then rather than top-level await: this launcher ships as CommonJS too (a .cjs entry gets a
+// .cjs launcher), where top-level await is a syntax error \u2014 and a launcher that cannot parse is a
+// boot entry that starts nothing.
+launchChild(program, argv, !isScript && process.platform === 'win32' && /\\.(cmd|bat)$/i.test(entry)).then(exitWith)
 `;
 }
 function writeDshLauncher(options) {
@@ -4474,35 +4588,46 @@ import { spawn as spawn2 } from "node:child_process";
 import fs16 from "node:fs";
 import path15 from "node:path";
 import process9 from "node:process";
-function cliArgs(deps, command) {
-  const args = [...deps.launch?.args ?? [], command, "--home", deps.home];
+function cliArgs(deps, words) {
+  const args = [...deps.launch?.args ?? [], ...words, "--home", deps.home];
   if (deps.projectDir)
     args.push("--project", deps.projectDir);
   return args;
 }
-async function runCli(deps, command) {
-  const args = cliArgs(deps, command);
+async function runCliArgs(deps, words) {
+  const args = cliArgs(deps, words);
   if (deps.exec !== void 0)
     return await deps.exec(args, deps.env);
   const launch = deps.launch;
   if (launch === null)
-    return { code: null, stdout: "", stderr: "no home-hosted CLI is available", error: null };
+    return { command: "", args, code: null, signal: null, stdout: "", stderr: "no home-hosted CLI is available", timedOut: false, error: null };
   return await run(launch.program, args, {
     env: deps.env,
     timeoutMs: deps.timeoutMs ?? 9e4
   });
 }
 async function startPanel(deps) {
-  const result = await runCli(deps, "up");
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || result.stdout.trim() || `the CLI exited ${String(result.code)}`;
-    return { ok: false, detail };
-  }
-  const match = /https?:\/\/[^\s]+/.exec(result.stdout);
-  return { ok: true, detail: "the panel is answering", url: match?.[0] ?? null };
+  const result = await runCliArgs(deps, ["up"]);
+  if (result.code === 0) {
+    const match2 = /https?:\/\/[^\s]+/.exec(result.stdout);
+    return { ok: true, detail: "the panel is answering", url: match2?.[0] ?? null };
+  }
+  const failed2 = result.stderr.trim() || result.stdout.trim() || `the CLI exited ${String(result.code)}`;
+  const migration = await repairPanelMigration((words) => runCliArgs(deps, words));
+  if (migration.failure !== null)
+    return { ok: false, detail: `${failed2}; the panel config needs a migration and it did not apply: ${migration.failure}` };
+  if (migration.note === null)
+    return { ok: false, detail: failed2 };
+  const retried = await runCliArgs(deps, ["up"]);
+  if (retried.code !== 0) {
+    const again = retried.stderr.trim() || retried.stdout.trim() || `the CLI exited ${String(retried.code)}`;
+    return { ok: false, detail: `${migration.note}, but the panel still did not start: ${again}` };
+  }
+  const match = /https?:\/\/[^\s]+/.exec(retried.stdout);
+  return { ok: true, detail: `${migration.note}; the panel is answering`, url: match?.[0] ?? null };
 }
 async function stopPanel(deps) {
-  const result = await runCli(deps, "down");
+  const result = await runCliArgs(deps, ["down"]);
   if (result.code !== 0) {
     const detail = result.error ?? (result.stderr.trim() || result.stdout.trim() || `the CLI exited ${String(result.code)}`);
     return { ok: false, detail: `the panel did not stop: ${detail}` };
@@ -5028,7 +5153,7 @@ async function ensureToken(options) {
 async function reclaimToken(options) {
   return await serialised(options.stateDir, options.slot, async () => await enrollFreshToken(options));
 }
-async function runCli2(exec, args, env) {
+async function runCli(exec, args, env) {
   try {
     const result = await exec(args, env);
     if (result.code !== 0) {
@@ -5053,7 +5178,7 @@ async function enrollToken(options) {
     };
   }
   const token = generateToken();
-  const enrolled = await runCli2(options.exec, ["--home", options.home, "set-token"], { HHOSTED_TOKEN: token });
+  const enrolled = await runCli(options.exec, ["--home", options.home, "set-token"], { HHOSTED_TOKEN: token });
   if (enrolled.result === void 0) {
     return {
       token: null,
@@ -5066,7 +5191,7 @@ async function enrollToken(options) {
 }
 async function enrollFreshToken(options) {
   const token = generateToken();
-  const enrolled = await runCli2(options.exec, ["--home", options.home, "set-token"], { HHOSTED_TOKEN: token });
+  const enrolled = await runCli(options.exec, ["--home", options.home, "set-token"], { HHOSTED_TOKEN: token });
   if (enrolled.result === void 0) {
     return {
       token: null,
@@ -7049,7 +7174,9 @@ var ENTRY_FIELDS = {
   resources: { type: "object", additionalProperties: true, description: "Resource policy: maxRssBytes \u2014 restart when the tree exceeds it; 0 disables" },
   backupPaths: { type: "array", items: { type: "string" }, description: "Paths included in backups for this entry (templates allowed)" },
   logBufferLines: { type: "number", description: "Live log lines kept for this entry, 50..100000" },
-  backupIgnoreGenerated: { type: "boolean", description: "Skip build output and dependency directories (node_modules, dist, caches) inside the declared backup paths" }
+  backupIgnoreGenerated: { type: "boolean", description: "Skip build output and dependency directories (node_modules, dist, caches) inside the declared backup paths" },
+  dump: { oneOf: [{ type: "object", additionalProperties: true }, { type: "null" }], description: "Backup hook run before this entry's data is captured: command, args, env, timeoutMs. Write into {dumpDir}; a failed dump refuses the backup \u2014 or null" },
+  load: { oneOf: [{ type: "object", additionalProperties: true }, { type: "null" }], description: "Restore hook run on this entry's next start, once its port answers: command, args, env, timeoutMs, waitMs. Read from {dumpDir} \u2014 or null" }
 };
 var ENTRY_PARAM = {
   type: "object",