dsh-home-hosted 0.7.2 → 0.7.4

package/docs/BOOT.md

@@ -92,6 +92,51 @@ stays `available` and its install reports "loads at the next login" instead of r
 `bootstrap`/`enable`/`print` steps need the domain, and they are skipped when it is unreachable. The
 daemon scope still needs root for `/Library/LaunchDaemons`.
 
+## Escaping is per setting, not per file
+
+A unit file is read by systemd, not by a shell, and its settings do not share one
+escaping rule. `ExecStart=` **is** unescaped (`\\`, `\"`, and `$`/`%` are special), which
+is why its words are quoted and a literal `$` or `%` is doubled. `WorkingDirectory=`
+and `Description=` are taken **verbatim**: measured with `systemctl show -p
+WorkingDirectory --value`, every backslash written came straight back, so doubling one
+turned a directory named `a\b` into `a\\b` and the unit died with
+`status=200/CHDIR`. Only `%` is special there — `%%` is a literal percent, and an
+unknown specifier such as `%i` in a system unit is fatal.
+
+The one hazard they *do* share is the line continuation: a setting whose value ends in
+a backslash continues onto the next line, so a `WorkingDirectory=` ending in `\`
+swallowed the `KillMode=process` line under it. The generator appends a trailing space
+in that case — systemd strips surrounding whitespace before expanding the value, so the
+path is unchanged and the next directive survives.
+
+The same two-layer mistake is possible in every format this plugin writes, and it is why
+each generator is exercised against the real parser (`systemd-analyze verify`, `plutil`,
+`desktop-file-validate`, and a `gio launch` for the XDG entry) rather than only against
+its own expectations.
+
+### A `.desktop` line has two parsers, in order
+
+The XDG entry is the one format that is genuinely read twice, and the first reader is
+easy to forget. `GKeyFile` consumes the line — `\n`, `\t`, `\r`, `\s` and `\\` are its
+escapes, and **a backslash that is none of those makes it refuse the key outright** —
+and only then does the desktop session split `Exec=` with `g_shell_parse_argv` and
+unquote each word. So a value is escaped for the key file *and* for the shell, and the
+key-file layer runs first.
+
+Escaping only for the shell therefore failed in a way that is invisible to
+`desktop-file-validate`, which reports such a file as clean: a lone `\` anywhere in a
+`Path=` or `Exec=` word (`C:\Users\…`, or any POSIX directory whose name has one) made
+`g_key_file_get_string` fail with "Key file contains key … which has a value that cannot
+be interpreted", the entry never loaded, and a `\$`, `` \` `` or `\"` did the same. A
+backslash run was also lossy, because the key-file layer ate half of it: `a\b` came back
+as `ab`. And since `desktop-file-validate` is not the loader, the entry failing to start
+was the first sign.
+
+`desktopValueEscape` is that missing first layer, `desktopValue` applies it to the plain
+keys (`Path=`, `Name=`, `Comment=`), and `Exec=` applies it on top of its shell quoting.
+Every ownership check reads the escaped marker too, or a marker carrying a backslash would
+be written escaped and searched for raw — and the plugin would call its own entry foreign.
+
 ## Enabling autostart hands the panel over
 
 An install alone proves nothing. The panel the plugin started keeps running, so nothing shows whether

package/lib/index.js

@@ -450,14 +450,16 @@ function systemdExecWord(value) {
 }
 function systemdText(value) {
   assertNoControl(value, "unit setting");
-  return replaceAll(value, [["\\", "\\\\"], ["%", "%%"]]);
+  const escaped = value.split("%").join("%%");
+  return escaped.endsWith("\\") ? `${escaped} ` : escaped;
 }
 function systemdPath(value, what = "path") {
   assertAbsolute(value, what);
   assertNoControl(value, what);
   if (value.includes('"'))
     throw new Error(`${what} must not contain a double quote: ${JSON.stringify(value)}`);
-  return replaceAll(value, [["\\", "\\\\"], ["%", "%%"]]);
+  const escaped = value.split("%").join("%%");
+  return escaped.endsWith("\\") ? `${escaped} ` : escaped;
 }
 function systemdEnvLine(key, value) {
   assertEnvKey(key);
@@ -478,14 +480,25 @@ function assertXmlCommentSafe(value) {
   return value;
 }
 var DESKTOP_RESERVED = /[\s"'\\><~|&;$*?#()`]/;
+function desktopValueEscape(value) {
+  assertNoControl(value, "desktop value");
+  return value.split("\\").join("\\\\");
+}
 function desktopWord(value) {
   assertNoControl(value, "desktop Exec word");
   const escaped = replaceAll(value, [["\\", "\\\\"], ['"', '\\"'], ["`", "\\`"], ["$", "\\$"], ["%", "%%"]]);
-  return DESKTOP_RESERVED.test(value) || escaped !== value ? `"${escaped}"` : value;
+  const word = DESKTOP_RESERVED.test(value) || escaped !== value ? `"${escaped}"` : value;
+  return desktopValueEscape(word);
 }
 function desktopExec(program, args) {
   return [program, ...args].map(desktopWord).join(" ");
 }
+function desktopValue(key, value) {
+  assertNoControl(value, `desktop ${key}`);
+  if (key.includes("=") || key.includes("\n"))
+    throw new Error(`desktop key ${JSON.stringify(key)} is not valid`);
+  return `${key}=${desktopValueEscape(value)}`;
+}
 function windowsArg(value) {
   assertNoControl(value, "windows argument");
   if (value !== "" && !/[\s"]/.test(value))
@@ -1504,18 +1517,21 @@ function validate3(spec) {
   for (const key of Object.keys(spec.env))
     assertEnvKey(key);
 }
+function fileMarker(spec) {
+  return desktopValueEscape(assertMarker(spec.marker));
+}
 function xdgDesktopEntry(spec) {
   validate3(spec);
   return `${[
     "[Desktop Entry]",
     "Type=Application",
-    `Name=${spec.label}`,
-    `Comment=home-hosted daemon, managed by ${spec.marker}`,
+    desktopValue("Name", spec.label),
+    desktopValue("Comment", `home-hosted daemon, managed by ${spec.marker}`),
     `Exec=${desktopExec(spec.command, spec.args)}`,
-    `Path=${spec.cwd}`,
+    desktopValue("Path", spec.cwd),
     "Terminal=false",
     "X-GNOME-Autostart-enabled=true",
-    `X-HomeHosted-Marker=${spec.marker}`,
+    desktopValue("X-HomeHosted-Marker", spec.marker),
     ""
   ].join("\n")}`;
 }
@@ -1547,7 +1563,7 @@ function createXdgAutostartProvider(ctx) {
     async status(spec) {
       try {
         const file = pathOf(spec);
-        const own = inspectOwned(file, assertMarker(spec.marker));
+        const own = inspectOwned(file, fileMarker(spec));
         if (own.exists && !own.owned)
           return { state: "not-installed", unitPath: file, detail: own.reason ?? "foreign file", commands: [] };
         if (!own.owned || own.text === null)
@@ -1569,10 +1585,10 @@ function createXdgAutostartProvider(ctx) {
         validate3(spec);
         const file = pathOf(spec);
         fs5.mkdirSync(path4.dirname(file), { recursive: true });
-        const write = writeOwned(file, spec.marker, xdgDesktopEntry(spec), 420);
+        const write = writeOwned(file, fileMarker(spec), xdgDesktopEntry(spec), 420);
         if (write.refusal)
           return failed(write.refusal);
-        const text = inspectOwned(file, spec.marker).text;
+        const text = inspectOwned(file, fileMarker(spec)).text;
         const enabled = text !== null && desktopFlag(text, "X-GNOME-Autostart-enabled") !== "false" && desktopFlag(text, "Hidden") !== "true";
         if (!enabled)
           return failed(`${file} was written but does not read back as enabled`, { changed: write.changed });
@@ -1590,10 +1606,10 @@ function createXdgAutostartProvider(ctx) {
     async uninstall(spec) {
       try {
         const file = pathOf(spec);
-        const own = inspectOwned(file, spec.marker);
+        const own = inspectOwned(file, fileMarker(spec));
         if (own.exists && !own.owned)
           return failed(own.reason ?? "foreign file");
-        const remove = removeOwned(file, spec.marker);
+        const remove = removeOwned(file, fileMarker(spec));
         if (remove.refusal)
           return failed(remove.refusal);
         return {
@@ -2468,6 +2484,9 @@ function migrationRefusal(home) {
 var ConfigLayoutError = class extends Error {
   name = "ConfigLayoutError";
 };
+var ConfigPatchError = class extends Error {
+  name = "ConfigPatchError";
+};
 function readConfig(home, workspace = DEFAULT_WORKSPACE) {
   const refusal = migrationRefusal(home);
   if (refusal !== null)
@@ -2478,8 +2497,15 @@ function readConfig(home, workspace = DEFAULT_WORKSPACE) {
     const exists = fs8.existsSync(file);
     return { raw: null, exists, error: exists ? "the workspace config file could not be parsed" : null };
   }
+  if (!isRecordValue(raw))
+    return { raw: null, exists: true, error: "the workspace config file does not contain a JSON object" };
   if (!Array.isArray(raw.servers) && raw.servers !== void 0)
     return { raw: null, exists: true, error: "the workspace config file has a servers field that is not an array" };
+  if (Array.isArray(raw.servers)) {
+    const index = raw.servers.findIndex((entry) => !isRecordValue(entry));
+    if (index >= 0)
+      return { raw: null, exists: true, error: `the workspace config file has an entry at servers[${index}] that is not an object` };
+  }
   return { raw, exists: true, error: null };
 }
 function writeConfig(home, raw, writtenBy = "dsh-home-hosted", workspace = DEFAULT_WORKSPACE) {
@@ -2499,7 +2525,9 @@ function readGlobalSettings(home) {
     const exists = fs8.existsSync(file);
     return { raw: null, exists, error: exists ? "the panel settings file could not be parsed" : null };
   }
-  if (raw.control !== void 0 && (typeof raw.control !== "object" || raw.control === null || Array.isArray(raw.control)))
+  if (!isRecordValue(raw))
+    return { raw: null, exists: true, error: "the panel settings file does not contain a JSON object" };
+  if (raw.control !== void 0 && !isRecordValue(raw.control))
     return { raw: null, exists: true, error: "the panel settings file has a control field that is not an object" };
   return { raw, exists: true, error: null };
 }
@@ -2513,7 +2541,7 @@ function setControl(home, patch, writtenBy = "dsh-home-hosted") {
   const read = readGlobalSettings(home);
   if (read.error !== null)
     throw new ConfigLayoutError(read.error);
-  writeGlobalSettings(home, { ...read.raw ?? {}, control: { ...read.raw?.control ?? {}, ...patch } }, writtenBy);
+  writeGlobalSettings(home, patchControl(read.raw ?? {}, patch), writtenBy);
 }
 function refuseUnmigrated(home) {
   const refusal = migrationRefusal(home);
@@ -2532,17 +2560,61 @@ function upsertEntry(raw, entry) {
     servers.push(entry);
   return { ...raw, servers };
 }
+var SERVER_MERGE_KEYS = /* @__PURE__ */ new Set(["restart", "health", "stop"]);
+var CONTROL_MERGE_KEYS = /* @__PURE__ */ new Set(["auth", "tls"]);
+function isRecordValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeGroup(target, patch) {
+  const merged = { ...target };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === void 0)
+      continue;
+    if (value === null) {
+      delete merged[key];
+      continue;
+    }
+    if (isRecordValue(value) && isRecordValue(merged[key])) {
+      merged[key] = mergeGroup(merged[key], value);
+      continue;
+    }
+    merged[key] = value;
+  }
+  return merged;
+}
 function patchEntry(raw, id, patch) {
+  for (const key of SERVER_MERGE_KEYS) {
+    if (patch[key] === null)
+      throw new ConfigPatchError(`${key} must be an object (was null): the panel refuses to boot a config that carries it`);
+  }
   const servers = (raw.servers ?? []).map((entry) => {
     if (entry.id !== id)
       return entry;
-    const merged = { ...entry, ...patch };
-    if (patch.stop !== void 0 && typeof entry.stop === "object" && entry.stop !== null)
-      merged.stop = { ...entry.stop, ...patch.stop };
+    const merged = { ...entry };
+    for (const [key, value] of Object.entries(patch)) {
+      if (value === void 0)
+        continue;
+      if (SERVER_MERGE_KEYS.has(key) && isRecordValue(value) && isRecordValue(merged[key]))
+        merged[key] = mergeGroup(merged[key], value);
+      else
+        merged[key] = value;
+    }
     return merged;
   });
   return { ...raw, servers };
 }
+function patchControl(raw, patch) {
+  const control = { ...raw.control ?? {} };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === void 0)
+      continue;
+    if (CONTROL_MERGE_KEYS.has(key) && isRecordValue(value) && isRecordValue(control[key]))
+      control[key] = mergeGroup(control[key], value);
+    else
+      control[key] = value;
+  }
+  return { ...raw, control };
+}
 function removeEntry(raw, id) {
   return { ...raw, servers: (raw.servers ?? []).filter((entry) => entry.id !== id) };
 }
@@ -4167,6 +4239,9 @@ ${result.stderr}`.trim();
 }
 
 // src/home-hosted/panel.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 var PanelError = class extends Error {
   constructor(message, code, status = null, detail = void 0) {
     super(message);
@@ -4200,6 +4275,32 @@ var PanelClient = class {
     const { workspaceId, ...rest } = raw;
     return { ...rest, workspace: workspaceId ?? workspace ?? this.workspace ?? "" };
   }
+  /**
+   * A `POST`/`PATCH` answer.
+   *
+   * The real panel answers the stored entry *flat* here — no `config` wrapper, no
+   * `workspaceId`, no live status — while `GET` answers a view. Both are accepted:
+   * a body that already carries a `config` object is a view, and anything else is
+   * the entry itself. Reading a flat entry as a view is what made `created.config`
+   * `undefined`, so the shape is decided here rather than assumed.
+   *
+   * A flat entry carries no live status, so it is reported as `unknown`: the panel
+   * has not said. Callers that need one re-read the list.
+   */
+  written(raw, workspace) {
+    const record = raw;
+    if (isRecord2(record.config))
+      return this.view(raw, workspace);
+    const { workspaceId, id, ...config } = record;
+    return {
+      id: typeof id === "string" ? id : "",
+      workspace: typeof workspaceId === "string" ? workspaceId : workspace ?? this.workspace ?? "",
+      status: "unknown",
+      pid: null,
+      url: null,
+      config
+    };
+  }
   ws(path17, workspace) {
     const id = workspace ?? this.workspace;
     if (id === null || id === void 0 || id.length === 0)
@@ -4249,11 +4350,11 @@ var PanelClient = class {
   }
   async createServer(entry, workspace) {
     const answer2 = await this.request("POST", this.ws("/api/servers", workspace), entry);
-    return this.view(answer2.server, workspace);
+    return this.written(answer2.server, workspace);
   }
   async updateServer(id, patch, workspace) {
     const answer2 = await this.request("PATCH", this.ws(`/api/servers/${encodeURIComponent(id)}`, workspace), patch);
-    return this.view(answer2.server, workspace);
+    return this.written(answer2.server, workspace);
   }
   async deleteServer(id, workspace) {
     await this.request("DELETE", this.ws(`/api/servers/${encodeURIComponent(id)}`, workspace));
@@ -4410,7 +4511,7 @@ var HomeHostedError = class extends Error {
     this.name = "HomeHostedError";
   }
 };
-function isRecordValue(value) {
+function isRecordValue2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function foreignView(entry, workspace) {
@@ -4909,7 +5010,7 @@ var HomeHostedService = class extends Service {
     const raw = readJson(this.snapshotsFile);
     if (raw === null)
       return {};
-    if (raw.version === 2 && isRecordValue(raw.entries))
+    if (raw.version === 2 && isRecordValue2(raw.entries))
       return raw.workspace === this.managedWorkspace() ? raw.entries : {};
     return this.managedWorkspace() === DEFAULT_WORKSPACE ? raw : {};
   }
@@ -5798,6 +5899,10 @@ var HomeHostedService = class extends Service {
         const target = await this.targetHome(input.home);
         const id = String(input.id);
         const patch = input.patch ?? {};
+        for (const key of ["restart", "health", "stop"]) {
+          if (patch[key] === null)
+            throw new HomeHostedError(`${key} must be an object (was null)`, "INVALID_PATCH");
+        }
         const workspace = this.callWorkspace(input, target.home, target.foreign);
         if (!target.foreign)
           return await (await this.requireClient()).updateServer(id, patch, workspace);