@synopackageland/cli 0.10.2 → 0.10.4

package/dist/runtime/executor-policy-check.js

@@ -1,22 +1,19 @@
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { PINNED_GO_HINT, PINNED_GO_TOOLCHAIN } from '../build-spk/go-toolchain.js';
 import { sdkBackend } from '../standalone/manifest.js';
 import { executorPolicy, executorPolicyText } from './executor-policy.js';
 import { requiredSdk } from './sdk-source.js';
-/** The executor subcommand that validates a policy on stdin as load() does (SDK 0.10.2 and later). */
+/** The executor subcommand that validates a policy on stdin as load() does. */
 const CHECK_POLICY = 'check-policy';
 /**
  * Why the SDK executor would refuse the policy, such as `invalid policy: policy root`;
- * undefined when it accepts it or its SDK predates check-policy. The executor is
+ * undefined when it accepts it. The executor is
  * built for this host from executorDir, so its own rules decide, not a copy in the CLI.
  */
 export function executorPolicyRefusal(executorDir, pkg, policyText, env = process.env) {
-    const main = join(executorDir, 'main.go');
-    if (!existsSync(main) || !readFileSync(main, 'utf8').includes(`"${CHECK_POLICY}"`))
-        return undefined;
     const dir = mkdtempSync(join(tmpdir(), 'synopkgland-check-policy-'));
     try {
         const binary = join(dir, 'executor');
@@ -38,7 +35,8 @@ export function executorPolicyRefusal(executorDir, pkg, policyText, env = proces
 }
 /** Where in dsm-package.yaml each executor refusal comes from. */
 const POLICY_FIX = [
-    [/policy (root|stop|purge)/, 'fix root.programs (schema, run, job), root.stop or uninstall.purge in dsm-package.yaml'],
+    [/policy (start|stop|purge): .*cannot also declare run or job/, 'root.start, root.stop and uninstall.purge name a program of their own: give them another program name in root.programs, one without run or job, and keep run and job on the session program'],
+    [/policy (root|start|stop|purge)/, 'fix root.programs (schema, run, job), root.start, root.stop or uninstall.purge in dsm-package.yaml'],
     [/policy (scope|operation|destination|move|lifetime)/, 'fix capabilities.delegate in dsm-package.yaml'],
     [/policy portal/, 'fix portal in dsm-package.yaml'],
     [/policy entry/, 'fix entry in dsm-package.yaml'],

package/dist/runtime/executor-policy.d.ts

@@ -32,6 +32,8 @@ export interface ExecutorPolicy {
     purge?: string;
     /** The root entry the executor runs when the package stops or upgrades. */
     stop?: string;
+    /** The root entry the executor runs once after each install or upgrade; a lifecycle step only. */
+    start?: string;
     root: Record<string, RootPolicyEntry>;
     /** Root programs get a directory only root can read, kept across upgrades. */
     root_state?: true;

package/dist/runtime/executor-policy.js

@@ -50,6 +50,7 @@ export function executorPolicy(m, arch) {
     return { v: 1, package: m.package, app: `SYNO.SDS.${m.package}.Instance`, ...(m.entry ? { entry: m.entry } : {}), ...(d ? { scope: d.scope } : {}),
         ...(d?.lifetime ? { destinations: [...d.destinations].sort(), lifetime: d.lifetime } : {}),
         operations: [...new Set(operations)].sort(), ...(portal ? { portal } : {}), ...(purge ? { purge } : {}), ...(settings?.stop ? { stop: settings.stop } : {}),
+        ...(settings?.start ? { start: settings.start } : {}),
         root, ...(settings?.state ? { root_state: true } : {}) };
 }
 /** A script without settings keeps the bare digest; a binary pins the bytes built for this architecture. */
@@ -72,18 +73,21 @@ function executorPortal(m) {
         throw new Error(`[EXECUTOR_POLICY] ${problem}`);
     return entry;
 }
+/** A root entry a session may run or start; the executor refuses it as a lifecycle step. */
+const sessionEntry = (entry) => typeof entry !== 'string' && (entry.run !== undefined || entry.job !== undefined);
 /** Inventory rejects malformed extensions even if a caller recomputes every pin. */
 export function validExecutorPolicy(value, pkg) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
     const p = value;
-    if (Object.keys(p).some(key => !['v', 'package', 'app', 'entry', 'scope', 'destinations', 'lifetime', 'operations', 'portal', 'purge', 'stop', 'root', 'root_state'].includes(key))
+    if (Object.keys(p).some(key => !['v', 'package', 'app', 'entry', 'scope', 'destinations', 'lifetime', 'operations', 'portal', 'purge', 'stop', 'start', 'root', 'root_state'].includes(key))
         || p.v !== 1 || p.package !== pkg || p.app !== `SYNO.SDS.${pkg}.Instance`
         || 'entry' in p && p.entry !== 'admin-only' && p.entry !== 'app-privilege'
         || !Array.isArray(p.operations) || !p.operations.includes('status') || new Set(p.operations).size !== p.operations.length
         || !p.root || typeof p.root !== 'object' || Array.isArray(p.root)
         || 'purge' in p && (typeof p.purge !== 'string' || !Object.hasOwn(p.root, p.purge))
         || 'stop' in p && (typeof p.stop !== 'string' || !Object.hasOwn(p.root, p.stop))
+        || 'start' in p && (typeof p.start !== 'string' || !Object.hasOwn(p.root, p.start) || sessionEntry(p.root[p.start]))
         || 'root_state' in p && p.root_state !== true
         || Object.entries(p.root).some(([name, entry]) => !ROOT_PROGRAM_NAME.test(name) || rootEntryProblem(entry) !== undefined))
         return false;

package/dist/runtime/root-programs.d.ts

@@ -19,6 +19,8 @@ export interface RootProgramSettings {
 /** dsm-package.yaml `root`: settings of root/ programs, the stop step and the root state directory. */
 export interface RootSettings {
     programs?: Record<string, RootProgramSettings>;
+    /** The program the executor runs once after each install or upgrade. */
+    start?: string;
     stop?: string;
     state?: true;
 }

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

@@ -4,6 +4,10 @@ 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";
+/** 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. */
 export interface SdkSource {
     version: string;

package/dist/runtime/sdk-source.js

@@ -8,6 +8,13 @@ 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';
+/** 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);
+    return major === floorMajor && minor === floorMinor && patch < floorPatch;
+}
 /** How each backend declares the SDK. */
 export const SDK_DEPENDENCY = {
     go: `add \`require ${SDK_MODULE} v<version>\` to backend/go.mod.`,

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

@@ -0,0 +1,23 @@
+/** The SDK's timeouts on the call chain to the executor (spec/protocol/v1, Timeouts). */
+export declare const SDK_TIMEOUTS_FILE: string;
+/** The waits the CLI generates into an App: its request default, the window's margin, and root.run's needs. */
+export interface SdkTimeouts {
+    /** The request deadline unless the App sets backend.timeout_seconds. */
+    requestDefaultSeconds: number;
+    /** How long the window waits past the request deadline. */
+    browserMarginMs: number;
+    /** A root.run program's timeout_s unless root.programs sets it. */
+    rootRunDefaultSeconds: number;
+    /** How much longer than a program's timeout_s a request awaiting root.run must last. */
+    rootRunRequestMarginSeconds: number;
+}
+/** What an App without the SDK waits. */
+export declare const NO_SDK_TIMEOUTS: SdkTimeouts;
+/** The timeouts of the SDK checkout or module at goDir. */
+export declare function sdkTimeouts(goDir: string): SdkTimeouts;
+/**
+ * The timeouts of the SDK an App's backend requires. A backend without the
+ * SDK, or one whose SDK cannot be resolved or is older than the CLI supports
+ * (sdkProblems and the API permissions report that), gets NO_SDK_TIMEOUTS.
+ */
+export declare function appSdkTimeouts(backend: object, env?: NodeJS.ProcessEnv): SdkTimeouts;

package/dist/runtime/sdk-timeouts.js

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { appSdkVersion, sdkBelowFloor, sdkSource } from './sdk-source.js';
+/** The SDK's timeouts on the call chain to the executor (spec/protocol/v1, Timeouts). */
+export const SDK_TIMEOUTS_FILE = join('spec', 'protocol', 'v1', 'timeouts.json');
+/** What an App without the SDK waits. */
+export const NO_SDK_TIMEOUTS = { requestDefaultSeconds: 60, browserMarginMs: 2000, rootRunDefaultSeconds: 20, rootRunRequestMarginSeconds: 20 };
+const read = new Map();
+/** The timeouts of the SDK checkout or module at goDir. */
+export function sdkTimeouts(goDir) {
+    const cached = read.get(goDir);
+    if (cached)
+        return cached;
+    const spec = JSON.parse(readFileSync(join(goDir, SDK_TIMEOUTS_FILE), 'utf8'));
+    const timeouts = {
+        requestDefaultSeconds: spec.request.default_s,
+        browserMarginMs: spec.browser.margin_ms,
+        rootRunDefaultSeconds: spec.executor.root_run_program_default_s,
+        // The executor answers root.run this long after the program's timeout, and its client waits margin_s more.
+        rootRunRequestMarginSeconds: spec.executor.root_run_answer_s - spec.executor.root_run_program_max_s + spec.margin_s,
+    };
+    read.set(goDir, timeouts);
+    return timeouts;
+}
+/**
+ * The timeouts of the SDK an App's backend requires. A backend without the
+ * SDK, or one whose SDK cannot be resolved or is older than the CLI supports
+ * (sdkProblems and the API permissions report that), gets NO_SDK_TIMEOUTS.
+ */
+export function appSdkTimeouts(backend, env = process.env) {
+    if (backend.kind === 'binary')
+        return NO_SDK_TIMEOUTS;
+    let goDir;
+    try {
+        const version = appSdkVersion(backend);
+        if (!version || sdkBelowFloor(version))
+            return NO_SDK_TIMEOUTS;
+        goDir = sdkSource(version, env).goDir;
+    }
+    catch {
+        return NO_SDK_TIMEOUTS;
+    }
+    return sdkTimeouts(goDir);
+}

package/dist/skill.js

@@ -10,6 +10,7 @@ const SKILL_CATALOG = [
     { id: "portal", file: "reference/portal.md", when: "Needs a DSM Application Portal alias link" },
     { id: "ui-vue", file: "reference/ui-vue.md", when: "Write or check a Vue UI" },
     { id: "ui-json", file: "reference/ui-json.md", when: "Generate or check a JSON UI" },
+    { id: "lifecycle", file: "reference/lifecycle.md", when: "Add work to install, upgrade, uninstall, start or stop (dsm-scripts/)" },
     { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
     { id: "diagnose", file: "reference/diagnose.md", when: "check/deploy/Open failed" },
 ];

package/dist/standalone/app-scripts.d.ts

@@ -0,0 +1,26 @@
+import { LIFECYCLE_SCRIPTS } from "../spk/dsm-spec.js";
+import type { StandaloneError } from "./manifest.js";
+/** The project folder whose files carry DSM's own script names; `scripts/` stays free for the App's tools. */
+export declare const APP_SCRIPTS_DIR = "dsm-scripts";
+/** Where the SPK carries them: next to the generated scripts, so postuninst still finds them after the payload is gone. */
+export declare const APP_SCRIPTS_SPK_DIR = "scripts/app";
+export type AppScriptName = (typeof LIFECYCLE_SCRIPTS)[number];
+/**
+ * The project's `dsm-scripts/<name>` files, one per DSM lifecycle script name.
+ * prereplace/postreplace are refused: DSM runs them only for
+ * install_replace_packages, which the SDK never declares.
+ */
+export declare function readAppScripts(root: string, fail: (error: StandaloneError) => void): AppScriptName[] | undefined;
+/** Wraps the SDK's script so it runs in a subshell, then calls the App's script of the same name. */
+export declare function composeAppScript(name: string, sdkScript: string): string;
+/** The SDK script inside `script`, or undefined when the App wrapper was edited. */
+export declare function sdkScriptOf(name: string, script: string): {
+    sdk: string;
+    app: boolean;
+} | undefined;
+/**
+ * inspect: checks every App wrapper and App script, then writes the bare SDK
+ * script back into the extracted `scripts/` so the fixed-lifecycle checks
+ * compare the SDK steps alone. Returns the App scripts DSM will reach.
+ */
+export declare function unwrapAppScripts(scriptsDir: string, findings: string[]): AppScriptName[];

package/dist/standalone/app-scripts.js

@@ -0,0 +1,141 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { LIFECYCLE_SCRIPTS } from "../spk/dsm-spec.js";
+/** The project folder whose files carry DSM's own script names; `scripts/` stays free for the App's tools. */
+export const APP_SCRIPTS_DIR = "dsm-scripts";
+/** Where the SPK carries them: next to the generated scripts, so postuninst still finds them after the payload is gone. */
+export const APP_SCRIPTS_SPK_DIR = "scripts/app";
+/**
+ * The project's `dsm-scripts/<name>` files, one per DSM lifecycle script name.
+ * prereplace/postreplace are refused: DSM runs them only for
+ * install_replace_packages, which the SDK never declares.
+ */
+export function readAppScripts(root, fail) {
+    const dir = join(root, APP_SCRIPTS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return undefined;
+    }
+    const names = [];
+    for (const name of entries.filter(entry => !entry.startsWith(".")).sort()) {
+        const path = `${APP_SCRIPTS_DIR}/${name}`;
+        if (!LIFECYCLE_SCRIPTS.includes(name)) {
+            fail({ code: "APP_SCRIPT_UNKNOWN", message: `${path} is not a DSM package script name; use one of ${LIFECYCLE_SCRIPTS.join(", ")}.` });
+            continue;
+        }
+        const stat = lstatSync(join(dir, name));
+        if (!stat.isFile()) {
+            fail({ code: "APP_SCRIPT_INVALID", message: `${path} must be a regular file, not a symlink or directory.` });
+            continue;
+        }
+        if (!(stat.mode & 0o100)) {
+            fail({ code: "APP_SCRIPT_NOT_EXECUTABLE", message: `${path} is not executable; run chmod +x ${path}.` });
+            continue;
+        }
+        if (!readFileSync(join(dir, name)).subarray(0, 2).equals(Buffer.from("#!"))) {
+            fail({ code: "APP_SCRIPT_NO_SHEBANG", message: `${path} must start with #! (for example #!/bin/sh); DSM runs it directly.` });
+            continue;
+        }
+        names.push(name);
+    }
+    return names.length ? names : undefined;
+}
+const SHEBANG = "#!/bin/sh\n";
+const SDK_OPEN = "synopkgland_sdk() (\n";
+const SDK_CLOSE = ")\n";
+/** Hooks that tear down: the App script runs first, while the SDK's services still exist. */
+const APP_FIRST = new Set(["preupgrade", "preuninst"]);
+function head(name) {
+    return `${SHEBANG}# synopkgland: the SDK steps run in synopkgland_sdk; the App's dsm-scripts/${name} runs from scripts/app/${name}.\n${SDK_OPEN}`;
+}
+/**
+ * Exit codes keep DSM's meaning. The SDK step is never skipped once it is
+ * due: start-stop-status stop always stops the SDK even when the App's stop
+ * fails, and a failed App start stops the SDK again, because DSM then treats
+ * the package as stopped and must not leave its ingress or workers running.
+ */
+function tail(name) {
+    const app = `synopkgland_app="$(dirname "$0")/app/${name}"\n`;
+    if (APP_FIRST.has(name))
+        return `${SDK_CLOSE}${app}"$synopkgland_app" "$@" || exit $?\nsynopkgland_sdk "$@"\n`;
+    if (name !== "start-stop-status")
+        return `${SDK_CLOSE}${app}synopkgland_sdk "$@" || exit $?\nexec "$synopkgland_app" "$@"\n`;
+    return `${SDK_CLOSE}${app}case "$1" in
+  start)
+    synopkgland_sdk "$@" || exit $?
+    "$synopkgland_app" "$@" && exit 0
+    synopkgland_result=$?
+    synopkgland_sdk stop
+    exit "$synopkgland_result" ;;
+  stop|prestop)
+    synopkgland_result=0
+    "$synopkgland_app" "$@" || synopkgland_result=$?
+    synopkgland_sdk "$@" || exit $?
+    exit "$synopkgland_result" ;;
+  restart)
+    "$0" stop || exit $?
+    exec "$0" start ;;
+  *)
+    synopkgland_sdk "$@" || exit $?
+    exec "$synopkgland_app" "$@" ;;
+esac
+`;
+}
+/** Wraps the SDK's script so it runs in a subshell, then calls the App's script of the same name. */
+export function composeAppScript(name, sdkScript) {
+    if (!sdkScript.startsWith(SHEBANG))
+        throw new Error(`SDK script ${name} must start with ${SHEBANG.trim()}`);
+    return head(name) + sdkScript.slice(SHEBANG.length) + tail(name);
+}
+/** The SDK script inside `script`, or undefined when the App wrapper was edited. */
+export function sdkScriptOf(name, script) {
+    if (!script.startsWith(`${SHEBANG}# synopkgland: the SDK steps`))
+        return { sdk: script, app: false };
+    const start = head(name), end = tail(name);
+    if (!script.startsWith(start) || !script.endsWith(end) || script.length < start.length + end.length)
+        return undefined;
+    return { sdk: SHEBANG + script.slice(start.length, script.length - end.length), app: true };
+}
+/**
+ * inspect: checks every App wrapper and App script, then writes the bare SDK
+ * script back into the extracted `scripts/` so the fixed-lifecycle checks
+ * compare the SDK steps alone. Returns the App scripts DSM will reach.
+ */
+export function unwrapAppScripts(scriptsDir, findings) {
+    const appDir = join(scriptsDir, "app");
+    const appFiles = new Set(existsSync(appDir) ? readdirSync(appDir) : []);
+    const called = [];
+    for (const name of LIFECYCLE_SCRIPTS) {
+        const path = join(scriptsDir, name);
+        if (!existsSync(path))
+            continue;
+        const found = sdkScriptOf(name, readFileSync(path, "utf8"));
+        if (!found) {
+            findings.push(`scripts/${name} wraps an App script but differs from the wrapper synopkgland build writes.`);
+            continue;
+        }
+        if (!found.app)
+            continue;
+        if (!appFiles.has(name))
+            findings.push(`scripts/${name} calls scripts/app/${name}, which is missing.`);
+        else
+            called.push(name);
+        writeFileSync(path, found.sdk);
+    }
+    for (const name of [...appFiles].sort()) {
+        const path = join(appDir, name);
+        if (!called.includes(name)) {
+            findings.push(`scripts/app/${name} is not called by a generated lifecycle script.`);
+            continue;
+        }
+        const stat = lstatSync(path);
+        if (!stat.isFile() || (stat.mode & 0o777) !== 0o755)
+            findings.push(`scripts/app/${name} must be a regular file with mode 0755.`);
+        else if (!readFileSync(path).subarray(0, 2).equals(Buffer.from("#!")))
+            findings.push(`scripts/app/${name} does not start with #!.`);
+    }
+    return called;
+}

package/dist/standalone/bridge-app.d.ts

@@ -17,6 +17,8 @@ export declare function stageScriptApp(m: StandaloneManifest, work: string): Pro
  * (spec/bridge/v1 SDKs). Returns the methods, sorted.
  */
 export declare function describeMethods(command: string, args: string[], cwd: string, env: Record<string, string>, timeoutMs?: number): Promise<string[]>;
+/** The Python SDK package of an SDK release or checkout (its root directory). */
+export declare function copyPythonSdk(sdkRoot: string, target: string): void;
 /** The Node SDK as npm would install it: its package.json and its compiled dist/. */
 export declare function copyNodeSdk(source: string, target: string): void;
 /** Copies an App tree: regular files and directories only, without dot entries and Python bytecode. */

package/dist/standalone/bridge-app.js

@@ -24,7 +24,7 @@ export async function stageScriptApp(m, work) {
     if (backend.kind === "python") {
         const vendor = join(dir, PYTHON_VENDOR_DIR, PYTHON_SDK);
         rmSync(vendor, { recursive: true, force: true });
-        copyAppTree(join(sdk.goDir, "python", PYTHON_SDK), vendor);
+        copyPythonSdk(sdk.goDir, vendor);
     }
     else {
         const modules = join(dir, "node_modules", NODE_SDK_PACKAGE);
@@ -91,6 +91,14 @@ export function describeMethods(command, args, cwd, env, timeoutMs = DESCRIBE_TI
         });
     });
 }
+/** The Python SDK package of an SDK release or checkout (its root directory). */
+export function copyPythonSdk(sdkRoot, target) {
+    const source = join(sdkRoot, "python", PYTHON_SDK);
+    if (!existsSync(join(source, "__init__.py"))) {
+        throw new StandaloneBuildError("STANDALONE_PYTHON_SDK_MISSING", `The SDK has no Python SDK: ${source}. Point SYNOPKGLAND_SDK_DIR at a syno-pkg-land-sdk checkout that has python/${PYTHON_SDK}, or use an SDK release that ships it.`);
+    }
+    copyAppTree(source, target);
+}
 /** The Node SDK as npm would install it: its package.json and its compiled dist/. */
 export function copyNodeSdk(source, target) {
     if (!existsSync(join(source, "dist/index.js"))) {

package/dist/standalone/bridge-backend.d.ts

@@ -23,7 +23,7 @@ export interface BridgeBackend {
     transfers?: Record<string, "upload" | "download">;
     /** The upload limit; absent, the runtime's 16 GiB. */
     maxUploadBytes?: number;
-    /** The request deadline in seconds; absent, DEFAULT_REQUEST_TIMEOUT_SECONDS. */
+    /** The request deadline in seconds; absent, the SDK's request default. */
     timeoutSeconds?: number;
 }
 export declare function isBridgeBackend(backend: {

package/dist/standalone/build.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { goModulePath, privateSdkHint, SDK_MODULE } from "../runtime/sdk-source.js";
+import { goModulePath, privateSdkHint, SDK_MODULE, sdkSource } from "../runtime/sdk-source.js";
 import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -16,6 +16,7 @@ import { checkJobs, commitOutputs, forEachArch } from "./arch-jobs.js";
 import { isBridgeBackend } from "./bridge-backend.js";
 import { requestTimeoutSeconds } from "./request-timeout.js";
 import { buildBridge, prepareBridge } from "./bridge-build.js";
+import { portalCatalogs } from "./portal-window.js";
 /** Argv only, never a shell; output streams to the terminal except stderr, which is also kept, and captured stdout. */
 export const runCommand = (command, args, options) => new Promise((done) => {
     const child = spawn(command, args, {
@@ -109,7 +110,9 @@ export async function buildStandalone(options) {
             const { cgi: cgiPath, worker: backgroundWorker, app } = await backendFor(builtManifest, arch, archWork, run, bridge);
             const outputPath = join(stage, `${manifest.package}-${manifest.spkVersion}-${arch}.spk`);
             const daemonControl = await buildDaemonControl(manifest, arch, archWork, run);
-            await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, daemonControl, backgroundWorker, executor, app });
+            // A portal needs the executor, so the executor's SDK carries the panel text.
+            const portalText = manifest.portal && executor ? portalCatalogs(sdkSource(executor.sdk).goDir) : undefined;
+            await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, daemonControl, backgroundWorker, executor, app, portalText });
             return outputPath;
         }));
         return { outputs, warnings: [...warnings] };

package/dist/standalone/dsm-window.d.ts

@@ -1,8 +1,14 @@
 import type { EntryMode, StandaloneManifest } from "./manifest.js";
+import { type PortalCatalogs } from "./portal-window.js";
 import { type AppTitle } from "../build-spk/ui-texts.js";
 import { type PackageIcons } from "../build-spk/dsm-icons.js";
 /** Same path the generated wrapper POSTs to, and the payload location of the CGI. */
 export declare const CGI_PAYLOAD_PATH = "ui/cgi/api.cgi";
+/**
+ * Relative to the page, as loadApp's assets and DSM's own WebAPI calls are: an
+ * Application Portal alias (https://nas/<alias>/) routes only its own paths,
+ * and /webman/... there answers 403.
+ */
 export declare function cgiUrl(packageId: string): string;
 /**
  * `createI18n(dsmLang, catalogs)` → `{ locale, t }`, plain ES5 so it runs in
@@ -19,8 +25,12 @@ export declare function windowScriptName(manifest: Pick<StandaloneManifest, "bui
 /** The launcher fields an entry mode fixes; inspect checks a built SPK against them. */
 export declare function entryLauncherAccess(entry: EntryMode): Record<string, unknown>;
 export declare function appTitle(manifest: StandaloneManifest): AppTitle;
-/** `ui/config`: registers the DSM main-menu app and its window class. */
-export declare function renderUiConfig(manifest: StandaloneManifest, icons?: PackageIcons): string;
+/**
+ * `ui/config`: registers the DSM main-menu app and its window class. A portal
+ * App's launcher also carries the Login Portal style and its icon as the
+ * login page icon (DSM shows `loginIcon`, never `icon`, there).
+ */
+export declare function renderUiConfig(manifest: StandaloneManifest, icons?: PackageIcons, loginStyle?: Record<string, string>): string;
 /**
  * The DSM AppWindow that hosts the project's UI. It loads app/app.js and
  * app/app.css once, then calls the app's mount(root, ctx). `ctx.call(method,
@@ -31,5 +41,6 @@ export declare function renderUiConfig(manifest: StandaloneManifest, icons?: Pac
  * launch owns the whole page: `ctx.fullPage` tells the app to lay out full-page
  * (and add a device-width viewport), and `ctx.appIcon` is the package icon a
  * full-page shell shows beside the name, where a DSM window has a title bar.
+ * A portal App's `ctx.portal` shows `portalText`, the SDK's panel text.
  */
-export declare function renderWindowScript(manifest: StandaloneManifest, assetVersion: string, icons?: PackageIcons): string;
+export declare function renderWindowScript(manifest: StandaloneManifest, assetVersion: string, icons?: PackageIcons, portalText?: PortalCatalogs): string;

package/dist/standalone/dsm-window.js

@@ -3,18 +3,22 @@ import { DSM_LANGS } from "./i18n.js";
 import { PASSWORD_CONFIRM, ROOT_PANEL, ROOT_RUNTIME, rootPanelCatalogs } from "./root-window.js";
 import { HOST_ADAPTER_RUNTIME } from "./host-adapter.js";
 import { permitsOrdinaryUsers } from "./api-permissions.js";
-import { PORTAL_RUNTIME } from "./portal-window.js";
+import { portalRuntime } from "./portal-window.js";
 import { portalByExecutor } from "../build-spk/dsm-version.js";
 import { uiTitleFields } from "../build-spk/ui-texts.js";
 import { packageIcons, windowIconFile, windowIconTemplate } from "../build-spk/dsm-icons.js";
 import { DEFAULT_WINDOW, FULL_PAGE_MIN_WIDTH } from "./window-size.js";
 import { requestTimeoutSeconds } from "./request-timeout.js";
+import { appSdkTimeouts } from "../runtime/sdk-timeouts.js";
 /** Same path the generated wrapper POSTs to, and the payload location of the CGI. */
 export const CGI_PAYLOAD_PATH = "ui/cgi/api.cgi";
-/** The SDK's clientTimeout(requestTimeout) waits this much past the backend deadline. */
-const CLIENT_TIMEOUT_MARGIN = 2000;
+/**
+ * Relative to the page, as loadApp's assets and DSM's own WebAPI calls are: an
+ * Application Portal alias (https://nas/<alias>/) routes only its own paths,
+ * and /webman/... there answers 403.
+ */
 export function cgiUrl(packageId) {
-    return `/webman/3rdparty/${packageId}/cgi/api.cgi`;
+    return `webman/3rdparty/${packageId}/cgi/api.cgi`;
 }
 const LOCALE_BY_DSM_LANG = Object.fromEntries(Object.entries(DSM_LANGS).map(([locale, lang]) => [lang, locale]));
 /**
@@ -81,8 +85,12 @@ function displayNameCatalogs(manifest) {
     }
     return catalogs;
 }
-/** `ui/config`: registers the DSM main-menu app and its window class. */
-export function renderUiConfig(manifest, icons = packageIcons(manifest.icon)) {
+/**
+ * `ui/config`: registers the DSM main-menu app and its window class. A portal
+ * App's launcher also carries the Login Portal style and its icon as the
+ * login page icon (DSM shows `loginIcon`, never `icon`, there).
+ */
+export function renderUiConfig(manifest, icons = packageIcons(manifest.icon), loginStyle) {
     const icon = windowIconTemplate(icons);
     const ns = `SYNO.SDS.${manifest.package}`;
     const titleFields = uiTitleFields(appTitle(manifest));
@@ -95,6 +103,7 @@ export function renderUiConfig(manifest, icons = packageIcons(manifest.icon)) {
                 appWindow: `${ns}.MainWindow`,
                 allowMultiInstance: false,
                 ...launcherAccess(manifest),
+                ...(loginStyle ? { loginIcon: icon, loginStyle } : {}),
                 depend: [`${ns}.MainWindow`],
             },
             [`${ns}.MainWindow`]: {
@@ -117,21 +126,25 @@ export function renderUiConfig(manifest, icons = packageIcons(manifest.icon)) {
  * launch owns the whole page: `ctx.fullPage` tells the app to lay out full-page
  * (and add a device-width viewport), and `ctx.appIcon` is the package icon a
  * full-page shell shows beside the name, where a DSM window has a title bar.
+ * A portal App's `ctx.portal` shows `portalText`, the SDK's panel text.
  */
-export function renderWindowScript(manifest, assetVersion, icons = packageIcons(manifest.icon)) {
+export function renderWindowScript(manifest, assetVersion, icons = packageIcons(manifest.icon), portalText) {
     const pkg = manifest.package;
     const ns = `SYNO.SDS.${pkg}`;
     const p = JSON.stringify(pkg);
     const root = manifest.executor ? renderRootParts(ns, manifest) : undefined;
     const size = manifest.ui.window ?? DEFAULT_WINDOW;
     const requestTimeout = requestTimeoutSeconds(manifest.backend) * 1000;
+    const clientMargin = appSdkTimeouts(manifest.backend).browserMarginMs;
+    if (manifest.portal && !portalText)
+        throw new Error("A portal App's window needs the SDK's portal panel text.");
     return `/* Generated by synopkgland build. Edit your UI in the project's ui folder. */
 Ext.ns(${JSON.stringify(ns)});
 
 // The SDK's clientTimeout: past the backend's request deadline
 // (ctx.requestTimeout, from backend.timeout_seconds), so its request_timeout
 // reply arrives first. options.signal aborts the fetch, for a page the user leaves.
-${ns}.call = function (method, params, options, requestTimeout) {
+${ns}.callOnce = function (method, params, options, requestTimeout) {
   var signal = options && options.signal;
   var canceled = { code: "request_canceled", message: "The request was canceled" };
   if (signal && signal.aborted) {
@@ -151,7 +164,7 @@ ${ns}.call = function (method, params, options, requestTimeout) {
   var leave = function () { stop(canceled); };
   var timer = setTimeout(function () {
     stop({ code: "request_timeout", message: "The NAS did not answer in time" });
-  }, (requestTimeout || ${requestTimeout}) + ${CLIENT_TIMEOUT_MARGIN});
+  }, (requestTimeout || ${requestTimeout}) + ${clientMargin});
   if (signal) signal.addEventListener("abort", leave);
   var done = function () {
     clearTimeout(timer);
@@ -178,6 +191,39 @@ ${ns}.call = function (method, params, options, requestTimeout) {
   });
 };
 
+// APP_STOPPED, APP_STARTING and EXECUTOR_STARTING mean the executor op was not
+// 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.
+${ns}.retryCodes = ["APP_STOPPED", "APP_STARTING", "EXECUTOR_STARTING"];
+${ns}.call = function (method, params, options, requestTimeout) {
+  var signal = options && options.signal;
+  var left = 30000;
+  var delay = 500;
+  var attempt = function () {
+    return ${ns}.callOnce(method, params, options, requestTimeout).catch(function (error) {
+      if (left <= 0 || !error || ${ns}.retryCodes.indexOf(error.code) < 0) throw error;
+      var wait = Math.min(delay, left);
+      left -= wait;
+      delay = Math.min(delay * 2, 8000);
+      return new Promise(function (resolve, reject) {
+        var leave = function () {
+          clearTimeout(timer);
+          reject({ code: "request_canceled", message: "The request was canceled" });
+        };
+        var timer = setTimeout(function () {
+          if (signal) signal.removeEventListener("abort", leave);
+          resolve(attempt());
+        }, wait);
+        if (signal && signal.aborted) leave();
+        else if (signal) signal.addEventListener("abort", leave);
+      });
+    });
+  };
+  return attempt();
+};
+
 ${ns}.messages = ${JSON.stringify(manifest.i18n?.catalogs ?? { en: {} })};
 ${ns}.createI18n = (function () {
 ${I18N_RUNTIME}
@@ -201,7 +247,7 @@ ${ns}.sessionUser = function () {
   return { name: typeof session.user === "string" ? session.user : "", isAdmin: session.is_admin === true };
 };
 
-${root ? root.definitions : ""}${manifest.portal ? renderPortalDefinition(ns) : ""}${ns}.loadApp = function (done) {
+${root ? root.definitions : ""}${manifest.portal ? renderPortalDefinition(ns, portalText) : ""}${ns}.loadApp = function (done) {
   var apps = window.DsmPackageApps || {};
   if (apps[${p}]) {
     done(apps[${p}]);
@@ -321,9 +367,9 @@ ${root ? root.mount : ""}    ${ns}.loadApp(function (app) {
 });
 `;
 }
-function renderPortalDefinition(ns) {
+function renderPortalDefinition(ns, text) {
     return `${ns}.createPortalAccess = (function () {
-${PORTAL_RUNTIME}
+${portalRuntime(text)}
   return createPortalAccess;
 })();