dsh-home-hosted 0.7.2 → 0.7.4

package/lib/types/boot/escape.d.ts

@@ -36,14 +36,31 @@ export declare function shellCommand(program: string, args: string[]): string;
  */
 export declare function systemdExecWord(value: string): string;
 /**
- * A single-line free-text setting such as `Description=` (specifiers only).
+ * A single-line free-text setting such as `Description=`.
+ *
+ * systemd reads these **verbatim** — unlike `ExecStart=`, it does not unescape
+ * `\\` or `$` there — so doubling a backslash puts a backslash *into* the value.
+ * Only two things need care: `%` starts a specifier, and a value that *ends* in a
+ * backslash splices the following line onto this directive, because the
+ * continuation rule applies to the raw line whatever the setting. A trailing
+ * space is the one encoding that leaves both the value and the next directive
+ * intact.
  */
 export declare function systemdText(value: string): string;
 /**
- * A path setting (`WorkingDirectory=`). systemd does not unquote these, but it
- * does expand `%` specifiers (an unknown one is fatal, verified with
- * `systemd-analyze verify`), and a trailing `\` continues the line into the next
- * directive. So both are escaped rather than passed raw.
+ * A path setting (`WorkingDirectory=`).
+ *
+ * Measured against real systemd (`systemctl show -p WorkingDirectory --value`):
+ * the value is taken **verbatim**, so a backslash is a backslash and must not be
+ * doubled — doubling turned a directory named `a\b` into a path that does not
+ * exist, and the unit failed with `status=200/CHDIR`. `%` still expands as a
+ * specifier, and an unknown one (`%i` in a system unit) is fatal, so it is
+ * escaped. The remaining hazard is a *trailing* backslash, which continues the
+ * directive onto the next line and swallows it; a trailing space absorbs that
+ * without changing the path.
+ *
+ * A double quote is refused rather than quoted: systemd does not unquote these
+ * settings, so a quoted form is simply a path with a quote in it.
  */
 export declare function systemdPath(value: string, what?: string): string;
 /** `Environment=KEY=value`, quoted as one assignment when the value needs it. */
@@ -52,9 +69,37 @@ export declare function xmlEscape(value: string): string;
 export declare function xmlUnescape(value: string): string;
 /** A marker inside an XML comment may not contain `--`. */
 export declare function assertXmlCommentSafe(value: string): string;
+/**
+ * Escape one value for the **key-file** layer of a `.desktop` file.
+ *
+ * This is a separate layer from `Exec=`'s own quoting, and it runs *first*:
+ * GLib reads the line with `GKeyFile`, which consumes `\n`, `\t`, `\r`, `\s`
+ * and `\\` before anything else sees the value. A `\` that is not one of those
+ * escapes makes `g_key_file_get_string` fail outright — "Key file contains key
+ * … which has a value that cannot be interpreted" — so the whole entry becomes
+ * unloadable, and `desktop-file-validate` happily accepts the file.
+ *
+ * That is why every backslash is doubled here: after the key-file layer the
+ * value is byte-identical to what the next layer was handed. Only `\\` may
+ * appear in the file — a bare `\` is always invalid.
+ */
+export declare function desktopValueEscape(value: string): string;
+/**
+ * Quote one `Exec=` word for the desktop-entry parser.
+ *
+ * Two layers, in order: `desktopValueEscape` for the key file, then the shell
+ * quoting below for `g_shell_parse_argv`, which is what actually splits the
+ * value into words and unquotes each one.
+ */
 export declare function desktopWord(value: string): string;
 export declare function desktopExec(program: string, args: string[]): string;
-/** A `Key=value` line in a `.desktop` file; the marker is written verbatim. */
+/**
+ * A `Key=value` line in a `.desktop` file.
+ *
+ * The value is key-file escaped, because a `.desktop` line has no shell to
+ * quote for: `Path=`/`Name=`/`Comment=` are read as plain strings, and a
+ * backslash in any of them is a key-file escape rather than data.
+ */
 export declare function desktopValue(key: string, value: string): string;
 /** Quote one argv word the way `CreateProcess`/`cmd` parse a command line. */
 export declare function windowsArg(value: string): string;

package/lib/types/home-hosted/config-file.d.ts

@@ -23,6 +23,10 @@ export interface SettingsReadResult {
 export declare class ConfigLayoutError extends Error {
     name: string;
 }
+/** A patch the panel's own schema would reject, refused rather than written. */
+export declare class ConfigPatchError extends Error {
+    name: string;
+}
 /** One workspace's entries. A not-yet-migrated root is reported, never parsed. */
 export declare function readConfig(home: string, workspace?: string): ConfigReadResult;
 /**
@@ -47,7 +51,25 @@ export declare function setControl(home: string, patch: Record<string, unknown>,
 export declare function findEntry(raw: RawConfig, id: string): ServerEntry | null;
 /** Insert or replace one entry, preserving every other key in the file. */
 export declare function upsertEntry(raw: RawConfig, entry: ServerEntry): RawConfig;
+/**
+ * Apply one entry patch, merging the nested groups the panel merges.
+ *
+ * Only the keys `patch` names are touched; everything else in the entry — and
+ * every other entry in the file — is preserved.
+ *
+ * An explicit `null` for one of the three groups is **refused**, not written.
+ * The panel's patch schema declares them `.optional()` but not nullable, so the
+ * API answers 400; writing it here instead produced a config the panel then
+ * refused to boot from (`servers[0] ("a"): restart must be an object (was null)`)
+ * — a file this plugin wrote, that this plugin's own panel cannot start on. A
+ * `null` nested *inside* a group is fine: that is how an optional key is cleared.
+ */
 export declare function patchEntry(raw: RawConfig, id: string, patch: ServerEntryPatch): RawConfig;
-/** Patch a settings file's `control` block, as a pure value. */
+/**
+ * Patch a settings file's `control` block, as a pure value.
+ *
+ * `auth` and `tls` merge the way the panel's `CONTROL_MERGE_KEYS` says, so a
+ * patch naming one of them does not reset its siblings.
+ */
 export declare function patchControl(raw: GlobalSettings, patch: Record<string, unknown>): GlobalSettings;
 export declare function removeEntry(raw: RawConfig, id: string): RawConfig;

package/lib/types/home-hosted/panel.d.ts

@@ -39,6 +39,19 @@ export declare class PanelClient {
      * `workspace`. One mapping, so a caller never has to know both spellings.
      */
     private view;
+    /**
+     * 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.
+     */
+    private written;
     private ws;
     private request;
     listServers(workspace?: string): Promise<ServerEntryView[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-home-hosted",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "DeepSeek Harness (dsh) plugin: prompt your home servers into existence through home-hosted — Gitea, Jellyfin, anything — and manage the panel, the entries and boot autostart from dsh.",
   "type": "module",
   "license": "MIT",