@synopackageland/cli 0.41.9 → 0.41.11

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.41.11 (2026-10-30)
+
+- Pre-pull inspected Compose image references on the NAS with byte progress, a
+  configurable 20-minute no-progress watchdog and image/registry/cause diagnostics.
+  Keep the shared tolerant install budget and never replay timed-out writes.
+- Uninstall broken packages directly, tolerate only their pre-existing install
+  failure while waiting for removal, and preserve new DSM worker failures.
+- Accept explicit DSM denial signals for admin-only window smoke; add optional
+  `preReady.clickIfVisible` for one-click upstream interstitials.
+- Force IPv4 and noninteractive SSH tunnels with bounded connection and shutdown.
+- Add `logs --json`, DSM worker messages and masked, timestamped last pull errors.
+  Clarify that smoke needs e2e/web/Chromium but no AI provider peers.
+
+## 0.41.10 (2026-10-30)
+
+- Give DSM reads/login three minutes and SPK upload, install/upgrade and package
+  start/stop requests ten minutes by default, configurable through `DSM_*`
+  timeout variables.
+- After an install/upgrade response timeout, keep polling the requested version
+  and running state within a shared 30-minute install budget, with progress on
+  stderr. Preserve DSM failures and distinguish an exhausted budget from a
+  failed installation; never replay the install request.
+- Apply the same tolerant polling and progress to stop/uninstall, with a shared
+  configurable 30-minute budget and no write replay after response timeouts.
+- Load the optional AI provider only when `magpieAgent()` is called, so DSM
+  smoke suites import without `@ai-sdk/openai` or `ai` installed.
+- Share Compose registry-mirror configuration with `images pin`; verify returned
+  manifest bytes against the registry digest before writing the pin.
+
 ## 0.41.9 (2026-10-30)
 
 - Accept self-signed DSM and redirected gateway certificates by default in the

package/README.md

@@ -223,7 +223,8 @@ not change how the App runs or its privilege tier. See `synopkgland skill show b
 
 `@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`).
+(optional peers). Smoke needs `e2e`, `@e2e-dev/web` and its Chromium browser;
+`ai` and `@ai-sdk/openai` are needed only when calling `magpieAgent()`.
 
 `dsmTarget()` uses Chromium and accepts self-signed DSM and gateway HTTPS
 certificates by default, including redirects from an HTTP DSM URL. It configures
@@ -276,12 +277,19 @@ import { appOpenSmoke } from '@synopackageland/cli/e2e';
 appOpenSmoke({ ready: '[data-app-ready]' });
 ```
 
+Declare an optional one-click upstream interstitial in the smoke config, for example
+`preReady: {clickIfVisible: {text: 'Continue on this device'}, timeout: 5000}`.
+It runs before the ready wait for permitted users; absent controls are skipped,
+and click failures remain failures. Denied and anonymous tests do not run it.
+
 `ready` is an app-content CSS selector or `{text: 'Exact text'}`. The helper
 reads `dsm-package.yaml` (`app` overrides its filename) and derives the launcher
 and entry using the packaging defaults. `entry` overrides a configured Portal
 alias or ingress URL. Three tests cover administrator (A), normal user (N),
 and a fresh anonymous browser context (X). A must reach `ready`. For
-`entry: admin-only`, N must see the SDK gateway's access-denied page, with
+`entry: admin-only`, N must see the SDK gateway's access-denied page or an explicit
+DSM denial/launcher privilege signal without an App window. A timeout alone is
+not proof of denial. Both paths require
 the `ready` and App content markers absent from the DOM. Set `content` to
 an App shell selector or text marker when it differs from `ready`, for example
 `appOpenSmoke({ready: '[data-app-ready]', content: '#app'})`.
@@ -446,6 +454,15 @@ installation; official protected ACL/project control and bridge readback remain
 blocked. No SSO Server or wrapper container is added. Linux tests do not prove
 DSM readiness; inspect lists explicit acceptance blockers.
 
+`images pin` and the Compose planner share the build-host mirror configuration:
+`SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS='{"docker.io":"https://mirror.example.com"}'`.
+Each mirror must be an HTTPS origin. Image names retain their original registry;
+manifest bytes are hashed and checked against the registry's digest before pinning.
+
+`appOpenSmoke` and `dsmTarget` need only the optional `e2e` and `@e2e-dev/web`
+peers. The optional `@ai-sdk/openai` provider is loaded when `magpieAgent()` is
+called; install it and `ai` only for AI agent runs.
+
 ## Control installed Apps
 
 Use `synopkgland host add nas --url https://nas.example:5001 --username alice`
@@ -468,6 +485,48 @@ certificate checks. Strict failures use `HOST_TLS_UNTRUSTED` or `HOST_CERT_CHANG
 are sent only over a connection whose certificate was inspected. Public package
 feeds and SPK downloads retain normal HTTPS verification.
 
+DSM API requests tolerate slow NAS storage and startup. These environment
+variables also work in `.env`; each accepts integer seconds from 1 to 86400:
+
+| Variable | Default | Budget |
+| --- | ---: | --- |
+| `DSM_REQUEST_TIMEOUT_SECONDS` | 180 | One DSM read, login or other API request |
+| `DSM_OPERATION_TIMEOUT_SECONDS` | 600 | One SPK upload, install/upgrade compound, or package start/stop request |
+| `DSM_INSTALL_TIMEOUT_SECONDS` | 1800 | Per-package state check, pre-pull, upload, install/upgrade and startup together, in `install` and `deploy` |
+| `DSM_UNINSTALL_TIMEOUT_SECONDS` | 1800 | State check, stop and uninstall together |
+| `DSM_POLL_INTERVAL_SECONDS` | 5 | Package-state polling and progress interval |
+| `DSM_IMAGE_PULL_STALL_TIMEOUT_SECONDS` | 1200 | No increase in NAS pull bytes; status heartbeats do not reset this budget |
+
+For example, set `DSM_INSTALL_TIMEOUT_SECONDS=3600` for an hour per package.
+Container Apps pre-pull their inspected, locked image references on the NAS before
+SPK upload. An exact local repository digest skips the registry pull; an image
+configuration ID or a remote update digest is not sufficient proof. Progress includes bytes; failures name the image, requested registry
+and daemon cause/endpoint when DSM provides them. Configure a reachable mirror,
+trust an inspecting CA in Container Manager, or use `images pin` and preload the
+pinned image. Pinning alone does not download layers onto the NAS. Pull tasks
+are not cancelled or replayed when their response is lost or a budget expires.
+Broken packages skip stop during uninstall; their existing install error does not
+block removal, while new uninstall errors still fail clearly.
+
+`logs --json` emits the usual single JSON envelope, including DSM `worker_msg`,
+status details and the last reported Compose error. A locally retained pre-pull
+failure includes its source and timestamp; it is scoped to NAS origin and package
+and cleared after a successful pre-pull. An unavailable lower-level cause stays
+unknown; a generic `install_corruption` does not prove a registry failure.
+
+An install/upgrade response timeout does not cancel DSM's work: the CLI keeps
+checking for the requested version **and running state**, without replaying the
+write. Progress continues on stderr, including with `--json`. A DSM failure
+reports `DSM_INSTALL_FAILED` and its reported details; an exhausted overall
+budget reports `DSM_INSTALL_TIMEOUT` and warns that DSM may still be working.
+Uninstall also keeps checking after stop/uninstall response or status timeouts,
+without replaying either write. Its exhausted budget reports `DSM_UNINSTALL_TIMEOUT`.
+Check Package Center before retrying. A timed-out same-version reinstall also
+needs an observed state transition before the old running instance can count
+as completion. Upload timeouts are reported separately because no install
+request has been sent yet. Explicit `ctl --timeout` budgets still take priority
+for `ctl` calls; App command/job/transfer deadlines retain their existing defaults.
+
 `ctl` preserves these process exit codes, including with `--json`:
 
 | Exit code | Meaning and examples |

package/dist/cli.js

@@ -694,6 +694,7 @@ async function runCliWithin(argv) {
     });
     program
         .command("logs")
+        .option("--json", "Print a single JSON object")
         .description("Status diagnosis: DSM package status and masked diagnostics; does not stream application logs")
         .option("--host <name>", "Registered NAS host")
         .option("--dev", "Development Package Identity")
@@ -714,10 +715,7 @@ async function runCliWithin(argv) {
             });
         if (!result.ok)
             throw failure("NOT_INSTALLED", "The package is not installed. Run synopkgland deploy --host first.");
-        for (const line of result.lines)
-            stdout(line);
-        if (result.diagnostics)
-            stdout(JSON.stringify(result.diagnostics, null, 2));
+        emit('logs', result, [...result.lines, ...(result.diagnostics ? [JSON.stringify(result.diagnostics, null, 2)] : [])].join('\n'));
     });
     const skill = program
         .command("skill")

package/dist/compose/registry-mirrors.d.ts

@@ -0,0 +1,3 @@
+/** Build-host registry policy shared by image pinning and SDK Compose planning. */
+export declare function composeRegistryMirrors(env?: NodeJS.ProcessEnv): Record<string, string> | undefined;
+export declare function registryBaseUrl(registry: string, mirrors?: Record<string, string> | undefined): string;

package/dist/compose/registry-mirrors.js

@@ -0,0 +1,38 @@
+/** Build-host registry policy shared by image pinning and SDK Compose planning. */
+export function composeRegistryMirrors(env = process.env) {
+    const raw = env.SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS;
+    if (raw === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS must be a JSON object of registry HTTPS origins');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('SYNOPKGLAND_COMPOSE_REGISTRY_MIRRORS must be a JSON object of registry HTTPS origins');
+    const mirrors = {};
+    for (const [registry, origin] of Object.entries(value)) {
+        let url;
+        try {
+            url = new URL(typeof origin === 'string' ? origin : '');
+        }
+        catch {
+            throw new Error('Registry mirror must be an HTTPS origin');
+        }
+        if (url.protocol !== 'https:' || !url.hostname || url.username || url.password || url.search || url.hash || url.pathname !== '/')
+            throw new Error('Registry mirror must be an HTTPS origin');
+        mirrors[registry] = url.origin;
+    }
+    return mirrors;
+}
+export function registryBaseUrl(registry, mirrors = composeRegistryMirrors()) {
+    const domain = registry === 'index.docker.io' ? 'docker.io' : registry;
+    if (mirrors && Object.hasOwn(mirrors, domain))
+        return mirrors[domain];
+    if (domain === 'docker.io')
+        return 'https://registry-1.docker.io';
+    const host = registry.startsWith('[') ? registry.slice(0, registry.indexOf(']') + 1) : registry.split(':')[0];
+    return `${['localhost', '127.0.0.1', '::1', '[::1]'].includes(host) ? 'http' : 'https'}://${registry}`;
+}

package/dist/e2e/app-open.d.ts

@@ -16,6 +16,11 @@ export interface AppOpenSmokeOptions {
     admin?: string;
     normal?: string;
     timeout?: number;
+    /** Optional one-click upstream interstitial; only used on entries expected ready. */
+    preReady?: {
+        clickIfVisible: SmokeMarker;
+        timeout?: number;
+    };
 }
 export interface SmokeEntry {
     package: string;

package/dist/e2e/dsm.d.ts

@@ -194,6 +194,8 @@ export declare function normalSmokeSkip(user?: string, env?: Env): string | unde
 /** Checks rendered errors as well as HTTP errors; ready alone never proves success. */
 export declare function assertSmokePage(page: Page, ready: SmokeMarker, anonymous?: boolean, publicLogin?: SmokeMarker): Promise<void>;
 /** A denied entry must show the SDK denial page and contain no App markers. */
-export declare function assertSmokeAccess(page: Page, root: Page | Locator, options: Pick<AppOpenSmokeOptions, 'ready' | 'content'>, expectation: 'ready' | 'denied', timeout: number): Promise<void>;
+export declare function assertSmokeAccess(page: Page, root: Page | Locator, options: Pick<AppOpenSmokeOptions, 'ready' | 'content' | 'preReady'>, expectation: 'ready' | 'denied', timeout: number): Promise<void>;
+/** A window may be denied by DSM before any App frame is created. */
+export declare function assertDsmWindowDenied(page: Page, appId: string, options: Pick<AppOpenSmokeOptions, 'ready' | 'content'>, dialogs: string[], timeout: number, dialogStart?: number): Promise<void>;
 /** Registers A (admin), N (manifest entry policy), X (fresh anonymous context). */
 export declare function appOpenSmoke(options: AppOpenSmokeOptions): void;

package/dist/e2e/dsm.js

@@ -19,7 +19,7 @@ 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 { createRequire } from "node:module";
 import { readSmokeEntry } from "./app-open.js";
 export { deriveSmokeEntry } from "./app-open.js";
 import { surfaceOf, test, web } from "@e2e-dev/web";
@@ -52,10 +52,18 @@ export function tunnelArgs(env = process.env) {
     const target = env.DSM_E2E_SSH?.trim();
     if (!target)
         throw new Error("DSM_E2E_SSH is required to open a NAS tunnel; set it to user@nas.example (using your NAS host).");
-    return ["-N", "-o", "BatchMode=yes", "-o", "ExitOnForwardFailure=yes",
+    const timeout = tunnelTimeoutMs(env);
+    return ["-4", "-n", "-N", "-o", "BatchMode=yes", "-o", `ConnectTimeout=${Math.max(1, Math.ceil(timeout / 1000))}`,
+        "-o", "ConnectionAttempts=1", "-o", "ExitOnForwardFailure=yes",
         ...forwards(env).flatMap(([local, remote]) => ["-L", `127.0.0.1:${local}:127.0.0.1:${remote}`]),
         target];
 }
+function tunnelTimeoutMs(env) {
+    const value = Number(env.DSM_E2E_TUNNEL_TIMEOUT_MS ?? '15000');
+    if (!Number.isSafeInteger(value) || value < 1 || value > 86400000)
+        throw new Error('DSM_E2E_TUNNEL_TIMEOUT_MS must be a positive timeout of at most 86400000 ms.');
+    return value;
+}
 /** A loopback port nothing listens on now, for a tunnel that names none. */
 export function freePort() {
     return new Promise((accept, reject) => {
@@ -70,6 +78,7 @@ export function freePort() {
 function portOpen(port) {
     return new Promise(accept => {
         const socket = connect({ host: "127.0.0.1", port });
+        socket.setTimeout(500, () => { socket.destroy(); accept(false); });
         socket.once("connect", () => { socket.destroy(); accept(true); });
         socket.once("error", () => accept(false));
     });
@@ -97,13 +106,19 @@ export async function runWithTunnel(command, outer = process.env) {
     }
     const ssh = spawn(env.DSM_E2E_SSH_BIN || "ssh", args, { stdio: ["ignore", "ignore", "inherit"] });
     let sshExited = false;
+    let sshError;
+    ssh.once('error', error => { sshError = error; sshExited = true; });
     ssh.once("exit", () => { sshExited = true; });
     try {
-        const deadline = Date.now() + Number(env.DSM_E2E_TUNNEL_TIMEOUT_MS || "15000");
+        const deadline = Date.now() + tunnelTimeoutMs(env);
         for (const waiting of ports) {
             while (!(await portOpen(waiting))) {
-                if (sshExited || Date.now() > deadline)
-                    throw new Error(`The SSH tunnel to ${args.at(-1)} did not open on port ${waiting}.`);
+                if (sshError)
+                    throw new Error(`SSH tunnel spawn failed: ${sshError.message}`, { cause: sshError });
+                if (sshExited)
+                    throw new Error(`SSH tunnel exited before port ${waiting} opened; check the IPv4 host, SSH key and BatchMode authentication.`);
+                if (Date.now() >= deadline)
+                    throw new Error(`SSH tunnel connect timed out after ${tunnelTimeoutMs(env)} ms on port ${waiting}; check IPv4 resolution, routing and SSH key authentication.`);
                 await new Promise(accept => setTimeout(accept, 100));
             }
         }
@@ -134,7 +149,13 @@ export async function runWithTunnel(command, outer = process.env) {
         if (!sshExited) {
             const closed = new Promise(accept => ssh.once("exit", accept));
             ssh.kill("SIGTERM");
-            await closed;
+            const kill = setTimeout(() => ssh.kill('SIGKILL'), 500);
+            try {
+                await closed;
+            }
+            finally {
+                clearTimeout(kill);
+            }
         }
     }
 }
@@ -222,9 +243,21 @@ export function llmSettings(env = process.env) {
 }
 /** The `agents.default` entry of e2e.config.ts: model plus the effort sent with every request. */
 export function magpieAgent(env = process.env) {
+    // Keep the synchronous config API; load the optional ESM provider only when
+    // an agent is requested (Node 22.12+ supports require(esm)). Smoke tests do
+    // not need the AI SDK or any model provider installed.
+    let provider;
+    try {
+        provider = createRequire(import.meta.url)('@ai-sdk/openai');
+    }
+    catch (error) {
+        if (!['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'].includes(error.code ?? ''))
+            throw error;
+        throw new Error('magpieAgent requires optional @ai-sdk/openai and ai; install them to run AI agents.', { cause: error });
+    }
     const settings = llmSettings(env);
     return {
-        model: createOpenAI({ baseURL: settings.baseURL, apiKey: settings.apiKey }).chat(settings.model),
+        model: provider.createOpenAI({ baseURL: settings.baseURL, apiKey: settings.apiKey }).chat(settings.model),
         providerOptions: { openai: { reasoningEffort: settings.reasoningEffort } },
     };
 }
@@ -635,6 +668,19 @@ export async function assertSmokePage(page, ready, anonymous = false, publicLogi
 /** A denied entry must show the SDK denial page and contain no App markers. */
 export async function assertSmokeAccess(page, root, options, expectation, timeout) {
     if (expectation === 'ready') {
+        if (options.preReady) {
+            const step = marker(root, options.preReady.clickIfVisible);
+            try {
+                await step.waitFor({ state: 'visible', timeout: Math.min(options.preReady.timeout ?? 5000, timeout) });
+            }
+            catch (error) {
+                // An absent optional interstitial is fine; a closed page or transport error is not.
+                if (!(error instanceof Error) || !/timeout|not visible/i.test(error.message))
+                    throw error;
+            }
+            if (await step.isVisible())
+                await step.click({ timeout });
+        }
         await marker(root, options.ready).waitFor({ state: 'visible', timeout });
         await assertSmokePage(page, options.ready);
         return;
@@ -649,6 +695,52 @@ export async function assertSmokeAccess(page, root, options, expectation, timeou
         throw new Error('Denied app smoke reached a server error page.');
     }
 }
+/** A window may be denied by DSM before any App frame is created. */
+export async function assertDsmWindowDenied(page, appId, options, dialogs, timeout, dialogStart = 0) {
+    const deadline = Date.now() + timeout;
+    do {
+        if (await dsmLoginVisible(page))
+            throw new Error('Denied app smoke reached a login gate.');
+        if (await marker(page, options.ready).count() || await marker(page, options.content ?? options.ready).count())
+            throw new Error('Denied app smoke exposed app content or its ready marker.');
+        const signal = await page.evaluate(async (id) => {
+            const sds = window.SYNO?.SDS;
+            const instance = sds?.AppMgr?.getByAppName?.(id)?.[0];
+            const appWindow = instance?.window;
+            let privileges = sds?.AppPrivilege;
+            if (!privileges) {
+                const body = new URLSearchParams({ api: 'SYNO.Core.Desktop.Initdata', method: 'get_user_service', version: '1' });
+                if (sds?.Session?.SynoToken)
+                    body.set('SynoToken', sds.Session.SynoToken);
+                const response = await fetch('/webapi/entry.cgi', { method: 'POST', body, signal: AbortSignal.timeout(3000) }).then(r => r.json()).catch(() => undefined);
+                if (response?.success === true)
+                    privileges = response.data?.AppPrivilege;
+            }
+            return { normal: sds?.Session?.is_admin === false,
+                windowId: appWindow?.isVisible?.() ? appWindow.el?.dom?.id : null,
+                privilegeKnown: Boolean(privileges && typeof privileges === 'object' && !Array.isArray(privileges)),
+                allowed: privileges?.[id] === true };
+        }, appId);
+        if (!signal.normal)
+            throw new Error('Denied window smoke requires an explicit normal-user DSM session.');
+        if (signal.windowId) {
+            await assertSmokeAccess(page, page.locator(`#${signal.windowId}`), options, 'denied', Math.max(1, deadline - Date.now()));
+            return;
+        }
+        if (await page.locator('body').innerText().then(text => /(?:^|\n)\s*(?:50[0-9]\b|internal server error|bad gateway|service unavailable)/i.test(text)))
+            throw new Error('Denied window smoke reached a server error page.');
+        const denial = dialogs.slice(dialogStart).some(text => /not authorized|access denied|permission denied|no permission|not permitted|\u6c92\u6709\u6b0a\u9650|\u65e0\u6743|\u7121\u6b0a|\u6743\u9650\u4e0d\u8db3|\u6b0a\u9650\u4e0d\u8db3/i.test(text));
+        if (denial)
+            return;
+        if (Date.now() >= deadline) {
+            if (signal.privilegeKnown && !signal.allowed)
+                return;
+            break;
+        }
+        await new Promise(resolve => setTimeout(resolve, Math.min(100, deadline - Date.now())));
+    } while (true);
+    throw new Error('No App window appeared, but DSM supplied no explicit denial or launcher privilege signal.');
+}
 /** Registers A (admin), N (manifest entry policy), X (fresh anonymous context). */
 export function appOpenSmoke(options) {
     const entry = readSmokeEntry(options);
@@ -678,6 +770,16 @@ export function appOpenSmoke(options) {
                 failures.push(r.status()); };
             page.on('response', response);
             try {
+                if (entry.window && expectation === 'denied') {
+                    const dialogs = await handleDialogs(browser);
+                    const start = dialogs.length;
+                    await openDesktop(app);
+                    await page.evaluate(id => window.SYNO.SDS.AppLaunch(id), entry.appId);
+                    await assertDsmWindowDenied(page, entry.appId, options, dialogs, timeout, start);
+                    if (failures.length)
+                        throw new Error(`App smoke received HTTP ${failures.join(', ')}.`);
+                    return;
+                }
                 const root = entry.window ? await openApp(app, entry.appId, timeout, browser)
                     : (await handleDialogs(browser), await openPath(app, new URL(entry.entry, dsmUrl()).href), dsmPage());
                 await assertSmokeAccess(page, root, options, expectation, timeout);

package/dist/error-registry.js

@@ -5,6 +5,14 @@ export const ERROR_REGISTRY = {
     HOST_TLS_UNTRUSTED: { "code": "HOST_TLS_UNTRUSTED", "description": "Strict TLS: the NAS certificate failed CA, hostname or validity verification", "suggestion": "Check the CA file, NAS hostname and certificate validity, or omit strict TLS" },
     HOST_DNS_FAILED: { "code": "HOST_DNS_FAILED", "description": "The NAS hostname could not be resolved", "suggestion": "Check the registered hostname and DNS" },
     HOST_CONNECTION_REFUSED: { "code": "HOST_CONNECTION_REFUSED", "description": "The NAS refused the connection", "suggestion": "Check the DSM port and NAS availability" },
+    CONTAINER_PULL_FAILED: { code: 'CONTAINER_PULL_FAILED', description: 'NAS image pull failed or its outcome is unknown', suggestion: 'Check the image and registry detail; configure a mirror, trust the CA, or pin and preload the image' },
+    CONTAINER_PULL_STALLED: { code: 'CONTAINER_PULL_STALLED', description: 'NAS image download stopped making byte progress', suggestion: 'Check the registry mirror; inspect Container Manager before retrying or adjust DSM_IMAGE_PULL_STALL_TIMEOUT_SECONDS' },
+    CONTAINER_PULL_TIMEOUT: { code: 'CONTAINER_PULL_TIMEOUT', description: 'The overall install budget expired during image pull', suggestion: 'Inspect Container Manager before retrying or increase DSM_INSTALL_TIMEOUT_SECONDS' },
+    DSM_UNINSTALL_TIMEOUT: { code: 'DSM_UNINSTALL_TIMEOUT', description: 'The overall stop/uninstall budget was exhausted; DSM may still be working', suggestion: 'Check Package Center before retrying or increase DSM_UNINSTALL_TIMEOUT_SECONDS' },
+    DSM_UNINSTALL_FAILED: { code: 'DSM_UNINSTALL_FAILED', description: 'DSM reported a package stop or uninstall failure', suggestion: 'Check the reported DSM error and Package Center log' },
+    DSM_TIMEOUT_INVALID: { code: 'DSM_TIMEOUT_INVALID', description: 'A DSM timeout budget is invalid', suggestion: 'Use whole seconds from 1 to 86400 for DSM timeout variables' },
+    DSM_INSTALL_TIMEOUT: { code: 'DSM_INSTALL_TIMEOUT', description: 'The overall install/start budget was exhausted; DSM may still be working', suggestion: 'Check Package Center before retrying or increase DSM_INSTALL_TIMEOUT_SECONDS' },
+    DSM_INSTALL_FAILED: { code: 'DSM_INSTALL_FAILED', description: 'DSM reported a package installation or startup failure', suggestion: 'Check the reported DSM error and Package Center log' },
     HOST_TIMEOUT: { "code": "HOST_TIMEOUT", "description": "The NAS request timed out", "suggestion": "Check connection and firewall; inspect state before retrying writes" },
     CTL_HOST_REQUIRED: { "code": "CTL_HOST_REQUIRED", "description": "Select a registered NAS host", "suggestion": "Run synopkgland host add, select --host, or set host default" },
     CTL_NOT_AUTHENTICATED: { "code": "CTL_NOT_AUTHENTICATED", "description": "The DSM session is absent or expired", "suggestion": "Run synopkgland host login <name>" },

package/dist/host/catalog-install.d.ts

@@ -32,19 +32,24 @@ export interface UploadedCatalogPackage {
 }
 export declare function packageStateFromRecord(value: unknown): InstalledPackageState;
 export declare function packageStateFromListPayload(payload: unknown, packageId: string): InstalledPackageState | undefined;
-export declare function fetchInstalledPackageState(dsmOrigin: string, cookieHeader: string, packageId: string): Promise<InstalledPackageState | undefined>;
-export declare function waitForInstalledVersion(readState: () => InstalledPackageState | undefined | Promise<InstalledPackageState | undefined>, options: {
+export declare function fetchInstalledPackageState(dsmOrigin: string, cookieHeader: string, packageId: string, timeoutMs?: number): Promise<InstalledPackageState | undefined>;
+export interface InstallWaitOptions {
     packageId: string;
     expectedVersion?: string;
     deadlineMs?: number;
     pollMs?: number;
-}): Promise<void>;
+    requireRunning?: boolean;
+    requireTransition?: boolean;
+    onProgress?: (message: string) => void;
+}
+export declare function waitForInstalledVersion(readState: (remainingMs: number) => InstalledPackageState | undefined | Promise<InstalledPackageState | undefined>, options: InstallWaitOptions): Promise<void>;
 export interface UninstallPackageOptions {
     dsmOrigin: string;
     cookieHeader: string;
     packageId: string;
     deadlineMs?: number;
     pollMs?: number;
+    onProgress?: (message: string) => void;
 }
 export declare function uninstallPackageFromDsm(options: UninstallPackageOptions): Promise<void>;
 export declare function catalogInstallationRequests(entry: Pick<CatalogPackageEntry, "package" | "version" | "size" | "beta" | "link" | "md5" | "qinst" | "deppkgs" | "breakpkgs" | "replacepkgs">, installed: boolean, sid: string, volumePath?: string): {
@@ -64,6 +69,10 @@ export interface LocalSpkInstallOptions {
     version: string;
     profileName?: string;
     extraValues?: Record<string, string>;
+    deadlineMs?: number;
+    pollMs?: number;
+    onProgress?: (message: string) => void;
+    containerImages?: string[];
 }
 export declare function installPackageFromLocalSpk(options: LocalSpkInstallOptions): Promise<void>;
 export {};