@synopackageland/cli 0.10.4 → 0.10.5

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.10.5 (2026-10-15)
+
+Builds with SDK 0.10.5 and templates 0.10.5: `init` writes SDK v0.10.5 (Go
+module, Rust crate tag and `backend.sdk`), `@synopackageland/sdk` 0.10.5 and
+`@synopackageland/ui` 0.9.7, whose `Space` aligns its items to the start. The
+executor digest table adds SDK 0.10.5, whose executor and lifecycle digests
+equal 0.10.4, so an App rebuilt on it keeps its approval unless its own root
+programs change. New: the `@synopackageland/cli/e2e` module for real-NAS e2e
+suites.
+
+繁中摘要：搭配 SDK 0.10.5、templates 0.10.5（UI 0.9.7）；需要 SDK 0.10.5 以上；
+digest 與 0.10.4 相同；新增 `@synopackageland/cli/e2e`。
+
+- **Incompatible:** the CLI needs SDK 0.10.5 or later. `check` and `build` refuse an App
+  whose backend requires SDK 0.10.3 or 0.10.4 (`SDK_UNSUPPORTED`, naming 0.10.5); raise
+  the Go module, Cargo tag or `backend.sdk` and the frontend's `@synopackageland/sdk` to
+  0.10.5. The DSM window now answers the SDK's status reads at once while the package is
+  stopped or starting, and only SDK 0.10.5's panels show that state and check again;
+  SDK 0.10.4's would show the package as needing approval.
+
+  繁中摘要：CLI 需要 SDK 0.10.5 以上；App 若仍用 SDK 0.10.3／0.10.4，`check`／`build` 會以
+  `SDK_UNSUPPORTED` 拒絕。DSM 視窗的 status 讀取不再替 App 重試，只有 SDK 0.10.5 的面板會自行重試。
+- `@synopackageland/cli/e2e` (`src/e2e/dsm.ts`): DSM helpers for a package's
+  real-NAS suite on `e2e` 0.19 and `@e2e-dev/web` 0.14 (optional peers).
+  `dsmTarget`, `magpieAgent` (magpie GPT-6 Luna at max reasoning effort,
+  `E2E_LLM_*` override), `dsmLoginSetup` and `signIn` (a mode 600 saved profile,
+  restored while it still reaches the desktop), `openDesktop`, `openApp`,
+  `openPortal`, `dismissNotifications` and `runWithTunnel`
+  (`node dsm.js tunnel -- <command>`, an npm script such as `e2e:nas`). The file
+  is self-contained, so a package may copy it to `tests/e2e/support/dsm.ts`.
+  繁中：新增共用 DSM e2e 模組，App 可改為 import `@synopackageland/cli/e2e`。
+- `runWithTunnel` opens the tunnel on a free loopback port unless
+  `DSM_E2E_TUNNEL_PORT` names one, so parallel runs do not collide on 15000.
+- A saved DSM profile is reused by host, not port, and saved atomically, so
+  concurrent runs never leave it half written.
+- `dismissNotifications` waits up to `DSM_E2E_NOTIFICATION_WAIT_MS` (default
+  5000) for the cards DSM shows after the desktop (the admin's "Admin account
+  security" card, about 2 s later on DSM 7.4) and matches DSM 7.4's container.
+- `runWithTunnel` masks DSM's session cookies (`id`, `did`, `_SSID`),
+  `X-SYNO-TOKEN`, `SynoToken` and `_sid` as `***` in the command's stdout and
+  stderr and in the text files under `DSM_E2E_OUTPUT_DIR` (default `.e2e`), and
+  makes that directory private (directories 700, files 600). A Playwright call
+  log in a run error had carried the session cookie into `report.json` and the
+  run's output; e2e redacts only the secrets its config declares. Saved
+  sessions keep their cookies. `redactDsmSecrets` and `protectE2eOutput` are
+  exported for a package with its own runner. Before that, `signIn` and
+  `openDesktop` (and so `openApp`) register the session's cookies and
+  SynoToken as e2e secrets in the test's worker (`registerDsmSecrets`), so e2e
+  itself masks them in a run error, `report.json` and its output; e2e 0.19
+  keeps that ledger internal, so a later layout without it leaves the second
+  mask alone.
+  繁中：e2e 輸出與 log 遮蔽 DSM cookie／token，輸出目錄改為 700／600。
+- `ctx.call` no longer repeats the SDK's status reads (`delegate.status`,
+  `authorization.status`, `executor.status`) while the package is stopped or
+  starting: they reject with the code at once, and SDK 0.10.5's panels show the
+  stopped or starting package and check again on their own. A page no longer
+  shows nothing for the first seconds after an upgrade (6.7 s in t-0503). Calls
+  that change something, approvals and controls among them, still repeat for up
+  to 30 s. `ctx.executor.status()` for a user who is not an administrator says
+  the package is stopped or starting instead of `admin_required`.
+  繁中：status 類讀取遇停止／啟動中立即回傳該碼，交給 SDK 重試；核准等呼叫維持重試。
+
 ## 0.10.4 (2026-10-14)
 
 Builds with SDK 0.10.4 and templates 0.10.4: `init` writes SDK v0.10.4 (Go

package/README.md

@@ -121,6 +121,45 @@ declaring it changes the policy digest, so an administrator approves the App aga
 [CLI reference](https://www.varvis.me/docs/reference/cli/) and
 [error codes](https://www.varvis.me/docs/reference/errors/).
 
+## E2E helpers
+
+`@synopackageland/cli/e2e` holds the DSM helpers for a package's real-NAS
+suite on [`e2e`](https://www.npmjs.com/package/e2e) and `@e2e-dev/web`
+(optional peers, with `ai` and `@ai-sdk/openai`). The same file,
+`src/e2e/dsm.ts`, can be copied verbatim to `tests/e2e/support/dsm.ts`.
+
+```ts
+// e2e.config.ts
+import {dsmTarget, magpieAgent} from '@synopackageland/cli/e2e';
+export default {targets: [dsmTarget()], output: '.e2e/output', agents: {default: magpieAgent()}};
+
+// tests/e2e/dsm.setup.e2e.ts: signs in once (a private saved profile when it still works)
+import {dsmLoginSetup} from '@synopackageland/cli/e2e';
+dsmLoginSetup({session: 'dsm', user: 'admin'});
+
+// a test that declares {sessions: ['dsm']}
+import {dismissNotifications, openApp} from '@synopackageland/cli/e2e';
+const window = await openApp(app, 'SYNO.SDS.MyApp.Instance'); // closes DSM's notification cards first
+await dismissNotifications(); // when a card shows later
+```
+
+```json
+"scripts": {"e2e:nas": "node --env-file-if-exists=.env node_modules/@synopackageland/cli/dist/e2e/dsm.js tunnel -- e2e run"}
+```
+
+`runWithTunnel` (the `tunnel --` command) opens an SSH tunnel to the NAS
+(`DSM_E2E_SSH`, default `root@vt-nas.syno`) on a free loopback port and runs the
+command with `DSM_E2E_URL` set. It masks DSM's session cookies (`id`, `did`,
+`_SSID`), `X-SYNO-TOKEN`, `SynoToken` and `_sid` as `***` in the command's
+output and in the files under `DSM_E2E_OUTPUT_DIR` (default `.e2e`), and makes
+that directory private (700, files 600); saved sessions keep their cookies.
+Accounts come from mode 600 files named by `DSM_E2E_ACCOUNT_<USER>`.
+`signIn` and `openDesktop` also register those values as e2e secrets in the
+test's worker, so e2e masks them in its own report. A test that forwards
+requests with `context.route` and `route.fetch` should end with
+`await context.unrouteAll({behavior: 'ignoreErrors'})`: a request still in
+flight otherwise rejects into a run error that carries its headers.
+
 ## AI assistants
 
 Every project includes `AGENTS.md` and a `CLAUDE.md` pointer. Start with

package/dist/e2e/dsm.d.ts

@@ -0,0 +1,137 @@
+import { surfaceOf } from "@e2e-dev/web";
+type Env = Readonly<Record<string, string | undefined>>;
+type App = {
+    open(path?: string): Promise<unknown>;
+};
+type StorageState = {
+    cookies: unknown[];
+    origins: unknown[];
+};
+type Page = ReturnType<NonNullable<ReturnType<typeof surfaceOf>>["page"]>;
+type Locator = ReturnType<Page["locator"]>;
+/** The DSM URL the browser opens: DSM_E2E_URL, else the local end of the SSH tunnel. */
+export declare function dsmUrl(env?: Env): string;
+/** ssh arguments forwarding the loopback port DSM_E2E_TUNNEL_PORT (default 15000) to DSM's HTTP port on the NAS. */
+export declare function tunnelArgs(env?: Env): string[];
+/** A loopback port nothing listens on now, for a tunnel that names none. */
+export declare function freePort(): Promise<number>;
+/**
+ * Opens the SSH tunnel on DSM_E2E_TUNNEL_PORT, else on a free port, runs
+ * `command` with DSM_E2E_URL pointing at it, and closes the tunnel afterwards.
+ * The command's output reaches this process's stdout and stderr with DSM's
+ * secrets masked, and its e2e output directory, DSM_E2E_OUTPUT_DIR (default
+ * .e2e), is protected afterwards (see protectE2eOutput). Resolves to the
+ * command's exit code.
+ */
+export declare function runWithTunnel(command: readonly string[], outer?: Env): Promise<number>;
+/** `text` with DSM's session cookies, X-SYNO-TOKEN, SynoToken and _sid values replaced by ***. */
+export declare function redactDsmSecrets(text: string): string;
+/**
+ * Makes an e2e output directory private (directories 700, files 600) and masks
+ * DSM's secrets in its text files. A `sessions` directory keeps its contents:
+ * a saved session must restore the real cookies. Does nothing when `dir` is missing.
+ */
+export declare function protectE2eOutput(dir: string): void;
+/** magpie's GPT-6 Luna at max reasoning effort unless E2E_LLM_* says otherwise. */
+export declare function llmSettings(env?: Env): {
+    baseURL: string;
+    model: string;
+    apiKey: string;
+    reasoningEffort: string;
+};
+/** The `agents.default` entry of e2e.config.ts: model plus the effort sent with every request. */
+export declare function magpieAgent(env?: Env): {
+    model: import("@ai-sdk/provider").LanguageModelV4;
+    providerOptions: {
+        openai: {
+            reasoningEffort: string;
+        };
+    };
+};
+/**
+ * Reads one account from a private JSON file: `{username, password}` or
+ * `{users: {<user>: {username, password}}}`. Errors never include the values.
+ */
+export declare function readAccount(file: string, user: string): {
+    username: string;
+    password: string;
+};
+/** ~/.cache/synopkgland-e2e/<target>-<user>.json, or under DSM_E2E_PROFILE_DIR. */
+export declare function profilePath(target: string, user: string, env?: Env): string;
+/**
+ * The saved browser state for `url`'s DSM host, or null when there is none or
+ * it belongs to another host. The port does not count: DSM's cookies do not
+ * depend on it, so tunnels on different ports share one profile. A file
+ * without `url` (written by another tool) is reused when one of its cookies
+ * belongs to the DSM host.
+ */
+export declare function loadProfile(file: string, url: string): StorageState | null;
+/**
+ * Saves the browser state (a Playwright storage state plus `url`) mode 600 in
+ * a mode 700 directory, atomically: concurrent runs, even threads of one
+ * process, each write their own temporary file and rename it into place.
+ */
+export declare function saveProfile(file: string, url: string, state: StorageState): void;
+/** The `targets` entry of e2e.config.ts. */
+export declare function dsmTarget(name?: string): {
+    name: string;
+    engine: import("e2e/engine").EngineHandle;
+    app: {
+        url: string;
+    };
+};
+/** The active DSM tab of the current attempt. */
+export declare function dsmPage(): Page;
+type SecretLedger = {
+    register(name: string, value: string): void;
+};
+type SessionPage = {
+    context(): {
+        cookies(): Promise<{
+            name: string;
+            value: string;
+        }[]>;
+    };
+    evaluate(fn: () => unknown): Promise<unknown>;
+};
+/**
+ * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
+ * e2e secrets, so e2e masks them in its report and output, as a request's
+ * Playwright call log carries them (t-0498). Returns how many were registered.
+ */
+export declare function registerDsmSecrets(page?: SessionPage, ledger?: SecretLedger): Promise<number>;
+/** Waits until the DSM desktop and its signed-in taskbar are shown. */
+export declare function waitForDesktop(page?: Page): Promise<void>;
+/**
+ * Closes every DSM notification card; returns how many were closed. DSM shows
+ * them a moment after the desktop (the admin's "Admin account security" card
+ * about 2 s later on vt-nas), so it first waits up to
+ * DSM_E2E_NOTIFICATION_WAIT_MS (default 5000) for one.
+ */
+export declare function dismissNotifications(page?: Page, env?: Env): Promise<number>;
+/**
+ * Restores the saved profile of `user`; signs in with the account file only
+ * when that profile is missing or no longer reaches the desktop. Saves the
+ * resulting state and returns which path it took.
+ */
+export declare function signIn(app: App, user?: string, env?: Env): Promise<"restored" | "signed-in">;
+/**
+ * Registers the setup test that signs `user` in and saves the e2e session
+ * `session`. Tests then declare `{ session }` and start signed in.
+ */
+export declare function dsmLoginSetup(options?: {
+    session?: string;
+    user?: string;
+    timeout?: number;
+}): void;
+/** Shows the DSM desktop once per attempt: a no-op while it is already shown. */
+export declare function openDesktop(app: App): Promise<Page>;
+/**
+ * Opens the DSM app `appId` (for example SYNO.SDS.SynoPkgConnect.Instance) in
+ * its desktop window, or brings its open window to the front, and returns it
+ * once the app has rendered text into the window.
+ */
+export declare function openApp(app: App, appId: string, timeout?: number): Promise<Locator>;
+/** Opens an Application Portal page (for example /download-hub/) as the whole tab. */
+export declare function openPortal(app: App, path: string): Promise<Page>;
+export {};

package/dist/e2e/dsm.js

@@ -0,0 +1,450 @@
+// DSM helpers for package e2e suites on upstream `e2e` + `@e2e-dev/web`.
+// One self-contained file: a package may copy it verbatim to tests/e2e/support/dsm.ts.
+// It signs in once per run (a saved, private profile is restored when still valid),
+// opens DSM app windows and Application Portal pages, dismisses DSM notifications,
+// configures the magpie LLM, and runs a command through an SSH tunnel to the NAS
+// (on a free loopback port unless DSM_E2E_TUNNEL_PORT names one). DSM's session
+// cookies and tokens are masked in what that command prints and leaves in its
+// e2e output, which is made private (directories 700, files 600).
+//
+//   node tests/e2e/support/dsm.ts tunnel -- npx e2e run
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { connect, createServer } from "node:net";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createOpenAI } from "@ai-sdk/openai";
+import { surfaceOf, test, web } from "@e2e-dev/web";
+const safeName = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+const desktopSelector = "#sds-desktop";
+const signedInSelector = "#sds-taskbar-tray-item-user";
+const loginSelector = 'input[name="username"]';
+// ---- Connection -----------------------------------------------------------
+/** The DSM URL the browser opens: DSM_E2E_URL, else the local end of the SSH tunnel. */
+export function dsmUrl(env = process.env) {
+    return env.DSM_E2E_URL || `http://127.0.0.1:${env.DSM_E2E_TUNNEL_PORT || "15000"}/`;
+}
+/** ssh arguments forwarding the loopback port DSM_E2E_TUNNEL_PORT (default 15000) to DSM's HTTP port on the NAS. */
+export function tunnelArgs(env = process.env) {
+    const local = env.DSM_E2E_TUNNEL_PORT || "15000";
+    const remote = env.DSM_E2E_REMOTE_PORT || "5000";
+    return ["-N", "-o", "BatchMode=yes", "-o", "ExitOnForwardFailure=yes",
+        "-L", `127.0.0.1:${local}:127.0.0.1:${remote}`, env.DSM_E2E_SSH || "root@vt-nas.syno"];
+}
+/** A loopback port nothing listens on now, for a tunnel that names none. */
+export function freePort() {
+    return new Promise((accept, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const { port } = server.address();
+            server.close(() => accept(port));
+        });
+    });
+}
+function portOpen(port) {
+    return new Promise(accept => {
+        const socket = connect({ host: "127.0.0.1", port });
+        socket.once("connect", () => { socket.destroy(); accept(true); });
+        socket.once("error", () => accept(false));
+    });
+}
+/**
+ * Opens the SSH tunnel on DSM_E2E_TUNNEL_PORT, else on a free port, runs
+ * `command` with DSM_E2E_URL pointing at it, and closes the tunnel afterwards.
+ * The command's output reaches this process's stdout and stderr with DSM's
+ * secrets masked, and its e2e output directory, DSM_E2E_OUTPUT_DIR (default
+ * .e2e), is protected afterwards (see protectE2eOutput). Resolves to the
+ * command's exit code.
+ */
+export async function runWithTunnel(command, outer = process.env) {
+    if (!command.length)
+        throw new Error("runWithTunnel needs a command to run.");
+    const port = Number(outer.DSM_E2E_TUNNEL_PORT || await freePort());
+    const env = { ...outer, DSM_E2E_TUNNEL_PORT: String(port) };
+    if (await portOpen(port))
+        throw new Error(`Port ${port} is already in use; set DSM_E2E_TUNNEL_PORT or close it before opening the tunnel.`);
+    const ssh = spawn(env.DSM_E2E_SSH_BIN || "ssh", tunnelArgs(env), { stdio: ["ignore", "ignore", "inherit"] });
+    let sshExited = false;
+    ssh.once("exit", () => { sshExited = true; });
+    try {
+        const deadline = Date.now() + Number(env.DSM_E2E_TUNNEL_TIMEOUT_MS || "15000");
+        while (!(await portOpen(port))) {
+            if (sshExited || Date.now() > deadline)
+                throw new Error(`The SSH tunnel to ${tunnelArgs(env).at(-1)} did not open on port ${port}.`);
+            await new Promise(accept => setTimeout(accept, 100));
+        }
+        // Piped output loses the terminal, not its colours.
+        const color = process.stdout.isTTY && env.FORCE_COLOR === undefined ? { FORCE_COLOR: "1" } : {};
+        const child = spawn(command[0], command.slice(1), {
+            stdio: ["inherit", "pipe", "pipe"], env: { ...env, ...color, DSM_E2E_URL: dsmUrl({ ...env, DSM_E2E_URL: undefined }) },
+        });
+        redactLines(child.stdout, process.stdout);
+        redactLines(child.stderr, process.stderr);
+        const forward = (signal) => child.kill(signal);
+        process.on("SIGINT", forward);
+        process.on("SIGTERM", forward);
+        try {
+            // "close" waits for the output pipes, so every line is through before the files are protected.
+            return await new Promise((accept, reject) => {
+                child.once("error", reject);
+                child.once("close", (code, signal) => accept(code ?? (signal ? 128 : 1)));
+            });
+        }
+        finally {
+            process.off("SIGINT", forward);
+            process.off("SIGTERM", forward);
+            protectE2eOutput(resolve(env.DSM_E2E_OUTPUT_DIR || ".e2e"));
+        }
+    }
+    finally {
+        if (!sshExited) {
+            const closed = new Promise(accept => ssh.once("exit", accept));
+            ssh.kill("SIGTERM");
+            await closed;
+        }
+    }
+}
+// ---- Secrets in output ----------------------------------------------------
+// e2e redacts only the secrets its config declares. A Playwright call log in a
+// run error lists a request's headers, DSM's session cookie among them, and e2e
+// writes it to the report and stdout (t-0498). A value runs to a quote, a
+// backslash or a line end, so a JSON string's escapes end it too.
+const mask = "***";
+// A Cookie or Set-Cookie header, and in it DSM's session (id, _SSID) and device (did) cookies.
+const cookieHeader = /(\bcookie"?\s*[:=]\s*"?)([^"\\\r\n]*)/gi;
+const sessionCookieNames = ["id", "did", "_SSID"];
+const sessionCookie = new RegExp(`(^|;\\s*)(${sessionCookieNames.join("|")})=[^;\\s]*`, "gi");
+// The X-SYNO-TOKEN header, a SynoToken parameter or field, and a web API's _sid parameter.
+const tokenValue = /(\b(?:x-syno-token|synotoken)"?\s*[:=]\s*"?)[^"\\\s,;&}]+/gi;
+const sidParameter = /([?&]_sid=)[^&"\\\s]+/gi;
+/** `text` with DSM's session cookies, X-SYNO-TOKEN, SynoToken and _sid values replaced by ***. */
+export function redactDsmSecrets(text) {
+    return text
+        .replace(cookieHeader, (_match, header, cookies) => header + cookies.replace(sessionCookie, `$1$2=${mask}`))
+        .replace(tokenValue, `$1${mask}`)
+        .replace(sidParameter, `$1${mask}`);
+}
+function redactLines(from, to) {
+    let pending = "";
+    from.setEncoding("utf8");
+    from.on("data", (chunk) => {
+        const text = pending + chunk;
+        const end = text.lastIndexOf("\n") + 1;
+        pending = text.slice(end);
+        if (end)
+            to.write(redactDsmSecrets(text.slice(0, end)));
+    });
+    from.on("end", () => { if (pending)
+        to.write(redactDsmSecrets(pending)); });
+}
+/**
+ * Makes an e2e output directory private (directories 700, files 600) and masks
+ * DSM's secrets in its text files. A `sessions` directory keeps its contents:
+ * a saved session must restore the real cookies. Does nothing when `dir` is missing.
+ */
+export function protectE2eOutput(dir) {
+    protectTree(dir, true);
+}
+function protectTree(dir, redact) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    chmodSync(dir, 0o700);
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            protectTree(path, redact && entry.name !== "sessions");
+        else if (entry.isFile()) {
+            chmodSync(path, 0o600);
+            if (redact)
+                redactFile(path);
+        }
+    }
+}
+function redactFile(file) {
+    const content = readFileSync(file);
+    if (content.includes(0))
+        return;
+    const text = content.toString("utf8");
+    const masked = redactDsmSecrets(text);
+    if (masked !== text)
+        writeFileSync(file, masked, { mode: 0o600 });
+}
+// ---- LLM ------------------------------------------------------------------
+/** magpie's GPT-6 Luna at max reasoning effort unless E2E_LLM_* says otherwise. */
+export function llmSettings(env = process.env) {
+    return {
+        baseURL: env.E2E_LLM_BASE_URL || "http://127.0.0.1:3425/v1",
+        model: env.E2E_LLM_MODEL || "codex/gpt-6-luna",
+        apiKey: env.E2E_LLM_API_KEY || "magpie-local",
+        reasoningEffort: env.E2E_LLM_REASONING_EFFORT || "max",
+    };
+}
+/** The `agents.default` entry of e2e.config.ts: model plus the effort sent with every request. */
+export function magpieAgent(env = process.env) {
+    const settings = llmSettings(env);
+    return {
+        model: createOpenAI({ baseURL: settings.baseURL, apiKey: settings.apiKey }).chat(settings.model),
+        providerOptions: { openai: { reasoningEffort: settings.reasoningEffort } },
+    };
+}
+// ---- Accounts and profiles ------------------------------------------------
+function requirePrivate(file, what) {
+    if (statSync(file).mode & 0o077)
+        throw new Error(`The ${what} ${file} must have mode 600.`);
+}
+/**
+ * Reads one account from a private JSON file: `{username, password}` or
+ * `{users: {<user>: {username, password}}}`. Errors never include the values.
+ */
+export function readAccount(file, user) {
+    requirePrivate(file, "account file");
+    const content = JSON.parse(readFileSync(file, "utf8"));
+    const account = content.users ? content.users[user] : content;
+    if (typeof account?.username !== "string" || !account.username || typeof account.password !== "string" || !account.password) {
+        throw new Error(`The account file has no username/password for ${user}.`);
+    }
+    return { username: account.username, password: account.password };
+}
+/** ~/.cache/synopkgland-e2e/<target>-<user>.json, or under DSM_E2E_PROFILE_DIR. */
+export function profilePath(target, user, env = process.env) {
+    if (!safeName.test(target) || !safeName.test(user))
+        throw new Error("The profile target and user must be simple names.");
+    return join(env.DSM_E2E_PROFILE_DIR || join(homedir(), ".cache/synopkgland-e2e"), `${target}-${user}.json`);
+}
+/**
+ * The saved browser state for `url`'s DSM host, or null when there is none or
+ * it belongs to another host. The port does not count: DSM's cookies do not
+ * depend on it, so tunnels on different ports share one profile. A file
+ * without `url` (written by another tool) is reused when one of its cookies
+ * belongs to the DSM host.
+ */
+export function loadProfile(file, url) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    requirePrivate(file, "profile");
+    const { url: savedUrl, savedAt: _savedAt, ...profile } = JSON.parse(raw);
+    const cookies = profile.cookies ?? [];
+    const host = new URL(url).hostname;
+    const sameHost = savedUrl === undefined ? cookies.some(cookie => cookie.domain === host) : new URL(savedUrl).hostname === host;
+    return sameHost ? { ...profile, cookies, origins: profile.origins ?? [] } : null;
+}
+/**
+ * Saves the browser state (a Playwright storage state plus `url`) mode 600 in
+ * a mode 700 directory, atomically: concurrent runs, even threads of one
+ * process, each write their own temporary file and rename it into place.
+ */
+export function saveProfile(file, url, state) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(file), 0o700);
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ ...state, url, savedAt: new Date().toISOString() }) + "\n", { mode: 0o600 });
+    renameSync(temporary, file);
+}
+// ---- Browser --------------------------------------------------------------
+const engine = web({
+    viewport: { width: Number(process.env.DSM_E2E_VIEWPORT_WIDTH || 1280), height: Number(process.env.DSM_E2E_VIEWPORT_HEIGHT || 800) },
+});
+/** The `targets` entry of e2e.config.ts. */
+export function dsmTarget(name = "dsm") {
+    return { name, engine, app: { url: dsmUrl() } };
+}
+function surface() {
+    const live = surfaceOf(engine);
+    if (!live)
+        throw new Error("The DSM web engine is unavailable.");
+    return live;
+}
+/** The active DSM tab of the current attempt. */
+export function dsmPage() {
+    return surface().page();
+}
+async function desktopOrLogin(page, timeout = 30_000) {
+    return Promise.race([
+        page.locator(desktopSelector).waitFor({ state: "visible", timeout }).then(() => "desktop"),
+        page.locator(loginSelector).waitFor({ state: "visible", timeout }).then(() => "login"),
+    ]);
+}
+/**
+ * e2e's ledger of the secrets this process has seen, which a worker's run
+ * errors and output are redacted with. e2e 0.19 keeps it internal and lets a
+ * config declare only secrets known up front, so it is reached by its file;
+ * under another layout there is none and runWithTunnel's masking remains.
+ */
+async function e2eSecretLedger() {
+    try {
+        const { processSecrets } = await import(new URL("run/secrecy.js", import.meta.resolve("e2e")).href);
+        return typeof processSecrets?.register === "function" ? processSecrets : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
+ * e2e secrets, so e2e masks them in its report and output, as a request's
+ * Playwright call log carries them (t-0498). Returns how many were registered.
+ */
+export async function registerDsmSecrets(page = dsmPage(), ledger) {
+    const target = ledger ?? await e2eSecretLedger();
+    if (!target)
+        return 0;
+    const cookies = (await page.context().cookies()).filter(c => sessionCookieNames.includes(c.name) && c.value);
+    const token = await page.evaluate(() => window.SYNO?.SDS?.Session?.SynoToken).catch(() => undefined);
+    const values = cookies.map(c => [`dsm.${c.name}`, c.value]);
+    if (typeof token === "string" && token)
+        values.push(["dsm.SynoToken", token]);
+    for (const [name, value] of values)
+        target.register(name, value);
+    return values.length;
+}
+/** Waits until the DSM desktop and its signed-in taskbar are shown. */
+export async function waitForDesktop(page = dsmPage()) {
+    await page.locator(desktopSelector).waitFor({ state: "visible", timeout: 60_000 });
+    await page.locator(signedInSelector).waitFor({ state: "visible", timeout: 15_000 });
+}
+// DSM 7.4: .v-notification-container > .v-notification-panel.show > i.close-btn.
+const notificationCloseSelector = ".v-notification-container .v-notification-panel .close-btn, .v-notification-panel.show .close-btn";
+/**
+ * Closes every DSM notification card; returns how many were closed. DSM shows
+ * them a moment after the desktop (the admin's "Admin account security" card
+ * about 2 s later on vt-nas), so it first waits up to
+ * DSM_E2E_NOTIFICATION_WAIT_MS (default 5000) for one.
+ */
+export async function dismissNotifications(page = dsmPage(), env = process.env) {
+    const close = page.locator(notificationCloseSelector).first();
+    const wait = Number(env.DSM_E2E_NOTIFICATION_WAIT_MS ?? "5000");
+    if (!await close.waitFor({ state: "visible", timeout: wait }).then(() => true, () => false))
+        return 0;
+    let closed = 0;
+    while (closed < 20 && await close.isVisible().catch(() => false)) {
+        const card = await close.elementHandle();
+        await close.click();
+        // A closing card stays visible while it fades out; a detached one counts as hidden.
+        await card?.waitForElementState("hidden", { timeout: 2_000 }).catch(() => { });
+        closed++;
+    }
+    return closed;
+}
+function accountFile(user, env) {
+    const key = `DSM_E2E_ACCOUNT_${user.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+    const file = env[key];
+    if (!file)
+        throw new Error(`Set ${key} to the account file for ${user} (mode 600).`);
+    return resolve(file);
+}
+/**
+ * Restores the saved profile of `user`; signs in with the account file only
+ * when that profile is missing or no longer reaches the desktop. Saves the
+ * resulting state and returns which path it took.
+ */
+export async function signIn(app, user = "admin", env = process.env) {
+    const url = dsmUrl(env);
+    const file = profilePath(env.DSM_E2E_TARGET || "vt-nas", user, env);
+    const context = surface().context();
+    const profile = loadProfile(file, url);
+    if (profile)
+        await context.setStorageState(profile);
+    await app.open("/");
+    const page = dsmPage();
+    let outcome = "restored";
+    if (!profile || await desktopOrLogin(page) === "login") {
+        if (profile)
+            await app.open("/");
+        const account = readAccount(accountFile(user, env), user);
+        await page.locator(loginSelector).fill(account.username);
+        await page.keyboard.press("Enter");
+        const password = page.locator('input[type="password"]:visible');
+        await password.fill(account.password);
+        await password.press("Enter");
+        outcome = "signed-in";
+    }
+    await waitForDesktop(page);
+    await registerDsmSecrets(page);
+    saveProfile(file, url, await context.storageState());
+    return outcome;
+}
+/**
+ * Registers the setup test that signs `user` in and saves the e2e session
+ * `session`. Tests then declare `{ session }` and start signed in.
+ */
+export function dsmLoginSetup(options = {}) {
+    const name = options.session ?? "dsm";
+    const user = options.user ?? "admin";
+    test.setup(`DSM sign-in as ${user}`, { sessions: [name], timeout: options.timeout ?? 120_000 }, async ({ app, session }) => {
+        await signIn(app, user);
+        await session.save(name);
+    });
+}
+/** Shows the DSM desktop once per attempt: a no-op while it is already shown. */
+export async function openDesktop(app) {
+    // A restored session leaves no page open until the attempt's first app.open.
+    const current = (() => { try {
+        return dsmPage();
+    }
+    catch {
+        return undefined;
+    } })();
+    if (current && await current.locator(desktopSelector).isVisible().catch(() => false))
+        return current;
+    await app.open("/");
+    const page = dsmPage();
+    if (await desktopOrLogin(page) === "login")
+        throw new Error("The DSM session is signed out; declare the session that dsmLoginSetup saves.");
+    await waitForDesktop(page);
+    await registerDsmSecrets(page);
+    await dismissNotifications(page);
+    return page;
+}
+/**
+ * Opens the DSM app `appId` (for example SYNO.SDS.SynoPkgConnect.Instance) in
+ * its desktop window, or brings its open window to the front, and returns it
+ * once the app has rendered text into the window.
+ */
+export async function openApp(app, appId, timeout = 30_000) {
+    const page = await openDesktop(app);
+    await page.evaluate(id => window.SYNO.SDS.AppLaunch(id), appId);
+    const handle = await page.waitForFunction(id => {
+        const instance = (window.SYNO.SDS.AppMgr.getByAppName(id) || [])[0];
+        const appWindow = instance?.window;
+        return appWindow?.isVisible?.() && appWindow.el?.dom?.id;
+    }, appId, { timeout });
+    const id = await handle.jsonValue();
+    // The window frame shows before the app renders into it.
+    await page.waitForFunction(windowId => document.getElementById(windowId)?.querySelector(".x-window-body")?.innerText.trim(), id, { timeout });
+    return page.locator(`#${id}`);
+}
+/** Opens an Application Portal page (for example /download-hub/) as the whole tab. */
+export async function openPortal(app, path) {
+    if (!path.startsWith("/") || path.startsWith("//"))
+        throw new Error("openPortal takes a same-origin path such as /download-hub/.");
+    await app.open(path);
+    const page = dsmPage();
+    await page.waitForLoadState("load");
+    return page;
+}
+// ---- Command line ---------------------------------------------------------
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const [verb, separator, ...command] = process.argv.slice(2);
+    if (verb !== "tunnel" || separator !== "--" || !command.length) {
+        console.error("usage: node dsm.ts tunnel -- <command...>");
+        process.exit(2);
+    }
+    runWithTunnel(command).then(code => process.exit(code), error => { console.error(error.message); process.exit(1); });
+}

package/dist/runtime/executor-digests.json

@@ -53,5 +53,16 @@
             "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
         },
         "goToolchain": "go1.26.9"
+    },
+    "0.10.5": {
+        "x86_64": "4ba7040761a719e74d6b047ef68b9415e658ebb8b373b69555b8c307524e26ba",
+        "aarch64": "ba80b389e3291419389b66be7b0a0e1085d3dfec55c9c651fecae427279bb3d5",
+        "armv7": "49474467b9c9a7f31b30b5053b70eb4f71a95f2c06fbf3566e8de8f16972a299",
+        "lifecycle": {
+            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
+            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
+            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
+        },
+        "goToolchain": "go1.26.9"
     }
 }

package/dist/runtime/sdk-source.d.ts

@@ -4,8 +4,12 @@ export declare const EXECUTOR_MODULE = "github.com/synopackageland/syno-pkg-land
 /** The thin Rust App crate (spec/bridge/v1), a git dependency on a release tag of the SDK repository. */
 export declare const SDK_CRATE = "syno-pkg-land-app";
 export declare const SDK_GIT_URL = "https://github.com/synopackageland/syno-pkg-land-sdk";
-/** The oldest SDK this CLI supports in its minor line; older patches lack spec/protocol/v1/timeouts.json. */
-export declare const SDK_FLOOR = "0.10.3";
+/**
+ * The oldest SDK this CLI supports in its minor line. The DSM window answers
+ * the SDK's status reads at once while the package is stopped or starting,
+ * which only SDK 0.10.5's panels retry on their own.
+ */
+export declare const SDK_FLOOR = "0.10.5";
 /** Whether version is an SDK patch older than SDK_FLOOR in the floor's minor line. */
 export declare function sdkBelowFloor(version: string): boolean;
 /** Where one SDK version's Go client and executor sources are read from. */

package/dist/runtime/sdk-source.js

@@ -8,8 +8,12 @@ export const EXECUTOR_MODULE = `${SDK_MODULE}/executor`;
 /** The thin Rust App crate (spec/bridge/v1), a git dependency on a release tag of the SDK repository. */
 export const SDK_CRATE = 'syno-pkg-land-app';
 export const SDK_GIT_URL = `https://${SDK_MODULE}`;
-/** The oldest SDK this CLI supports in its minor line; older patches lack spec/protocol/v1/timeouts.json. */
-export const SDK_FLOOR = '0.10.3';
+/**
+ * The oldest SDK this CLI supports in its minor line. The DSM window answers
+ * the SDK's status reads at once while the package is stopped or starting,
+ * which only SDK 0.10.5's panels retry on their own.
+ */
+export const SDK_FLOOR = '0.10.5';
 /** Whether version is an SDK patch older than SDK_FLOOR in the floor's minor line. */
 export function sdkBelowFloor(version) {
     const [major, minor, patch] = version.split('.').map(Number), [floorMajor, floorMinor, floorPatch] = SDK_FLOOR.split('.').map(Number);

package/dist/standalone/dsm-window.js

@@ -195,11 +195,14 @@ ${ns}.callOnce = function (method, params, options, requestTimeout) {
 // sent: the package is stopped, or starting. The call repeats on its own, half a
 // second, then doubling up to 8 s, for 30 s of waiting in all; each attempt keeps
 // its own deadline. Past that it rejects with the last refusal, and leaving the
-// page during a wait rejects request_canceled at once.
+// page during a wait rejects request_canceled at once. The SDK's status reads
+// are not repeated: its panels show the stopped or starting package and check
+// again on their own, and a page waiting here shows nothing (t-0503 R1).
 ${ns}.retryCodes = ["APP_STOPPED", "APP_STARTING", "EXECUTOR_STARTING"];
+${ns}.statusReads = ["delegate.status", "authorization.status", "executor.status"];
 ${ns}.call = function (method, params, options, requestTimeout) {
   var signal = options && options.signal;
-  var left = 30000;
+  var left = ${ns}.statusReads.indexOf(method) < 0 ? 30000 : 0;
   var delay = 500;
   var attempt = function () {
     return ${ns}.callOnce(method, params, options, requestTimeout).catch(function (error) {

package/dist/standalone/root-window.js

@@ -330,12 +330,16 @@ export const ROOT_RUNTIME = `function createRootAccess(options) {
   function publish(result) { listeners.forEach(function (listener) { listener(result); }); return result; }
   // TaskScheduler answers administrators only. Anyone else reads the approved
   // executor through the App's executor.status, which answers every user: the
-  // pinned, running executor is ready; otherwise an administrator is needed.
+  // pinned, running executor is ready; a stopped or starting package says so,
+  // as an administrator's status does; otherwise an administrator is needed.
+  var lifecycleCodes = ["APP_STOPPED", "APP_STARTING", "EXECUTOR_STARTING"];
   function userStatus() {
     var needed = block({tasks: {}}, fail("admin_required"));
     return options.call("executor.status", {}).then(function (status) {
       return pinned(status) ? {state: "ready", tasks: {}, executor: status} : needed;
-    }, function () { return needed; });
+    }, function (e) {
+      return e && lifecycleCodes.indexOf(e.code) >= 0 ? block({tasks: {}}, fail(e.code, "the executor status request failed.")) : needed;
+    });
   }
   return {
     status: function () { return (isAdmin() ? read().then(function (verified) { return health(verified, 0); }) : userStatus()).then(publish); },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -25,17 +25,41 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@synopackageland/templates": "0.10.4",
+    "@synopackageland/templates": "0.10.5",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "tar": "^7.4.3",
     "yaml": "^2.7.0"
   },
   "devDependencies": {
+    "@ai-sdk/openai": "^4.0.91",
+    "@e2e-dev/web": "^0.14.0",
     "@types/node": "^22.13.10",
+    "ai": "^7.0.137",
+    "e2e": "^0.19.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2"
   },
+  "peerDependencies": {
+    "@ai-sdk/openai": ">=4",
+    "@e2e-dev/web": ">=0.14",
+    "ai": ">=7",
+    "e2e": ">=0.19"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@e2e-dev/web": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "e2e": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -52,6 +76,7 @@
   "exports": {
     "./dist/*": "./dist/*",
     "./package.json": "./package.json",
-    "./native-layout": "./dist/standalone/native-layout.js"
+    "./native-layout": "./dist/standalone/native-layout.js",
+    "./e2e": "./dist/e2e/dsm.js"
   }
 }