@synopackageland/cli 0.41.5 → 0.41.7

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.41.7 (2026-10-30)
+
+- Allow `webapi` raw profiles to set `raw_max_bytes` up to 10 GiB
+  (10737418240 bytes), matching SDK/App 0.38.3 and executor/v0.38.3. The limit
+  shipped in 0.41.6 without a changelog entry. Larger raw downloads need SDK
+  0.38.3; templates ~0.35.5 still pin SDK 0.38.2. Raising a profile limit
+  requires administrator approval and fresh user consent.
+
+## 0.41.6
+
+- Share administrator, permitted normal-user and fresh anonymous app-open smoke tests through `@synopackageland/cli/e2e`, with manifest-derived entry URLs and explicit missing-account skips.
+- Scaffold the smoke test, runner config and npm script from templates; document the existing credential/profile/tunnel path.
+
 ## 0.41.5
 
 - Generate dedicated shared folders and guarded existing-folder choices, retain upgrade selections, validate required HTTPS settings before Next, and enable cold sign-in resume for all gateway modes. Pin templates 0.35.3 and SDK 0.38.2.

package/README.md

@@ -88,7 +88,7 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-CLI 0.41.5 uses templates ~0.35.3, whose default SDK pin is 0.38.2. Compose import and SDK defaults
+CLI 0.41.7 uses templates ~0.35.5, whose default SDK pin is 0.38.2. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -99,7 +99,7 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.41.5 depends on `~0.35.3`: npm installation or
+`@synopackageland/templates`. CLI 0.41.7 depends on `~0.35.5`: npm installation or
 update can select the latest templates patch in the 0.35 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
@@ -223,8 +223,7 @@ 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`). The same file,
-`src/e2e/dsm.ts`, can be copied verbatim to `tests/e2e/support/dsm.ts`.
+(optional peers, with `ai` and `@ai-sdk/openai`).
 
 ```ts
 // e2e.config.ts
@@ -263,6 +262,31 @@ 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.
 
+### App-open smoke
+
+Every template includes `npm run e2e:smoke` and a small test. Run `npm install`
+at the project root and `npx @e2e-dev/web install chromium` once before using it:
+
+```ts
+import { appOpenSmoke } from '@synopackageland/cli/e2e';
+appOpenSmoke({ ready: '[data-app-ready]' });
+```
+
+`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 with
+Application Privileges (N), and a fresh anonymous browser context (X).
+N explicitly skips when neither `DSM_E2E_ACCOUNT_NORMAL` nor its saved profile
+exists; `normal` selects another named account/profile. A defaults to `admin`.
+An expired saved profile needs its account file to sign in again and fails if
+unavailable. Invalid configured account files fail instead of being skipped.
+Use the same `DSM_E2E_*` account, target and SSH settings described above.
+The anonymous test requires a DSM gate and refuses ready app content or error
+pages. Only entries the manifest declares upstream-authenticated may provide
+`publicLogin` (a selector or text marker for their own login page).
+The smoke never installs packages or changes accounts/privileges.
+
 ## AI assistants
 
 Every project includes `AGENTS.md` and a `CLAUDE.md` pointer. Start with

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

@@ -0,0 +1,27 @@
+export type SmokeMarker = string | {
+    selector: string;
+} | {
+    text: string;
+};
+export interface AppOpenSmokeOptions {
+    /** Manifest filename; defaults to dsm-package.yaml in the project root. */
+    app?: string;
+    /** Override the manifest-derived entry, e.g. a configured Portal alias. */
+    entry?: string;
+    ready: SmokeMarker;
+    /** Required only for an entry the manifest declares upstream-authenticated. */
+    publicLogin?: SmokeMarker;
+    admin?: string;
+    normal?: string;
+    timeout?: number;
+}
+export interface SmokeEntry {
+    package: string;
+    appId: string;
+    entry: string;
+    window: boolean;
+    upstreamAuthenticated: boolean;
+}
+/** Uses the same launch defaults and legacy web entry resolver as packaging. */
+export declare function deriveSmokeEntry(raw: any, entry?: string): SmokeEntry;
+export declare function readSmokeEntry(options: Pick<AppOpenSmokeOptions, 'app' | 'entry'>): SmokeEntry;

package/dist/e2e/app-open.js

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import { parse } from 'yaml';
+import { resolveAppLaunch } from '../contract/app-launch.js';
+import { trustedAppEntryPath } from '../contract/web-launch.js';
+function safeEntry(entry) {
+    const url = new URL(entry, 'https://dsm.example');
+    if ((!entry.startsWith('/') && !/^https?:\/\//.test(entry)) || entry.startsWith('//') ||
+        /[\\\r\n]/.test(entry) || !['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+        throw new Error('Smoke entry must be a same-origin path or an HTTP(S) URL without credentials.');
+    }
+    return entry;
+}
+/** Uses the same launch defaults and legacy web entry resolver as packaging. */
+export function deriveSmokeEntry(raw, entry) {
+    if (!raw || typeof raw.package !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(raw.package)) {
+        throw new Error('Smoke requires a package id in dsm-package.yaml.');
+    }
+    const native = raw.schema === 2;
+    const gateway = raw.identity_gateway;
+    const web = Boolean(gateway || raw.compose || (!native && raw.adminport));
+    if ((!native && !raw.adminport) || (raw.ui === false && !gateway))
+        throw new Error('This package has no app entry to smoke test.');
+    const appId = native ? `SYNO.SDS.${raw.package}.Instance` : raw.package;
+    const launch = resolveAppLaunch(native ? raw.ui?.launch : raw.integration?.web?.launch, web);
+    if (!launch)
+        throw new Error('Invalid app launch mode in manifest.');
+    const window = launch === 'dsm-window' && !raw.console && raw.ui !== false && !raw.compose && !raw.daemon?.ingress;
+    const derived = raw.daemon?.ingress?.path ?? (gateway
+        ? `/webman/3rdparty/${raw.package}/sso/open.cgi`
+        : native ? `/?launchApp=${encodeURIComponent(appId)}`
+            : trustedAppEntryPath(raw));
+    const selected = safeEntry(entry ?? derived);
+    const pathname = new URL(selected, 'https://dsm.example').pathname;
+    // The menu CGI always checks DSM, even when the upstream listener is public.
+    const menuEntry = `/webman/3rdparty/${raw.package}/sso/open.cgi`;
+    const upstreamAuthenticated = (gateway?.upstream_access === 'public' && pathname !== menuEntry) ||
+        (!native && raw.integration?.web?.access === 'public') ||
+        (gateway?.upstream_auth_paths ?? []).some((prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`));
+    return { package: raw.package, appId, entry: selected, window: entry ? false : window, upstreamAuthenticated };
+}
+export function readSmokeEntry(options) {
+    return deriveSmokeEntry(parse(readFileSync(options.app ?? 'dsm-package.yaml', 'utf8')), options.entry);
+}

package/dist/e2e/dsm.d.ts

@@ -1,3 +1,5 @@
+import { type AppOpenSmokeOptions, type SmokeMarker } from "./app-open.js";
+export { deriveSmokeEntry, type AppOpenSmokeOptions, type SmokeMarker } from "./app-open.js";
 import { surfaceOf } from "@e2e-dev/web";
 type Env = Readonly<Record<string, string | undefined>>;
 type App = {
@@ -187,4 +189,9 @@ export declare function waitForPortal(page?: Page): Promise<void>;
  * tab. With the `browser` fixture, native dialogs are accepted and recorded (see handleDialogs).
  */
 export declare function openPortal(app: App, path: string, browser?: DialogBrowser): Promise<Page>;
-export {};
+/** Missing normal accounts are skipped; malformed configured files still fail. */
+export declare function normalSmokeSkip(user?: string, env?: Env): string | undefined;
+/** 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>;
+/** Registers A (admin), N (permitted normal user), X (fresh anonymous context). */
+export declare function appOpenSmoke(options: AppOpenSmokeOptions): void;

package/dist/e2e/dsm.js

@@ -14,12 +14,14 @@ import { sessionFetch } from "../nas/transport.js";
 import { canonicalOrigin } from "../nas/transport.js";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { chmodSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, 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 { readSmokeEntry } from "./app-open.js";
+export { deriveSmokeEntry } from "./app-open.js";
 import { surfaceOf, test, web } from "@e2e-dev/web";
 const safeName = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
 const desktopSelector = "#sds-desktop";
@@ -576,6 +578,129 @@ export async function openPortal(app, path, browser) {
     await waitForPortal(page);
     return page;
 }
+// ---- Minimal app-open smoke -----------------------------------------------
+/** Missing normal accounts are skipped; malformed configured files still fail. */
+export function normalSmokeSkip(user = "normal", env = process.env) {
+    const key = `DSM_E2E_ACCOUNT_${user.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+    if (env[key])
+        return undefined;
+    const file = profilePath(env.DSM_E2E_TARGET || "dsm", user, env);
+    if (existsSync(file) && loadProfile(file, dsmUrl(env)))
+        return undefined;
+    return `Normal-user smoke requires ${key} (mode 600) or a saved ${user} profile with app permission.`;
+}
+function marker(root, value) {
+    return typeof value === "string" ? root.locator(value).first()
+        : "selector" in value ? root.locator(value.selector).first() : root.getByText(value.text, { exact: true }).first();
+}
+const dsmGate = loginSelector;
+async function dsmLoginVisible(page) {
+    if (await page.locator('[data-error-code="dsm_sign_in_required"], [data-i18n="gateway.sign_in"]').first().isVisible())
+        return true;
+    if (await page.getByText(signInText).first().isVisible() &&
+        await page.locator('a, button, form, input').first().isVisible())
+        return true;
+    if (!await page.locator(dsmGate).first().isVisible())
+        return false;
+    const url = new URL(page.url());
+    // An upstream username field is not proof of a DSM gate. Alias pages also
+    // carry DSM's login root; ordinary upstream forms cannot stand in for it.
+    return (url.origin === new URL(dsmUrl()).origin && (url.pathname === '/' || url.pathname.startsWith('/webman/'))) ||
+        await page.locator('#sds-login, #sds-login-vue').first().isVisible();
+}
+const signInText = /sign in to DSM|log in to DSM|\u767b\u5165 DSM|\u767b\u5f55 DSM/i;
+const errorText = /(?:^|\n)\s*(?:[45]0[0-9]\b|internal server error|bad gateway|service unavailable|gateway timeout|not found|access denied|you are not authorized)/i;
+/** Checks rendered errors as well as HTTP errors; ready alone never proves success. */
+export async function assertSmokePage(page, ready, anonymous = false, publicLogin) {
+    if (await page.locator('body').innerText().then(text => errorText.test(text)))
+        throw new Error('App smoke reached an error page.');
+    if (anonymous) {
+        if (await marker(page, ready).isVisible())
+            throw new Error('Anonymous app smoke exposed app content.');
+        if (publicLogin) {
+            if (!await marker(page, publicLogin).isVisible())
+                throw new Error('Declared upstream login is not visible.');
+        }
+        else if (!await dsmLoginVisible(page)) {
+            throw new Error('Anonymous app smoke did not reach the DSM login gate.');
+        }
+    }
+    else if (await dsmLoginVisible(page) || await page.getByText(signInText).first().isVisible()) {
+        throw new Error('Signed-in app smoke reached a login gate.');
+    }
+}
+/** Registers A (admin), N (permitted normal user), X (fresh anonymous context). */
+export function appOpenSmoke(options) {
+    const entry = readSmokeEntry(options);
+    if (entry.upstreamAuthenticated && !options.publicLogin) {
+        throw new Error('An upstream-authenticated smoke entry requires publicLogin.');
+    }
+    if (!entry.upstreamAuthenticated && options.publicLogin) {
+        throw new Error('publicLogin requires a manifest-declared upstream-authenticated entry.');
+    }
+    const timeout = options.timeout ?? 90_000;
+    const normal = options.normal ?? 'normal';
+    const admin = options.admin ?? 'admin';
+    if (normal === admin)
+        throw new Error('Normal smoke must use a separate named profile.');
+    for (const [role, user] of [['A administrator', admin], ['N normal user', normal]]) {
+        test(`${entry.package}: app opens — ${role}`, {
+            timeout, skip: user === normal ? normalSmokeSkip(normal) : undefined,
+        }, async ({ app, browser }) => {
+            await signIn(app, user);
+            const page = dsmPage();
+            const isAdmin = await page.evaluate(() => window.SYNO?.SDS?.Session?.is_admin);
+            if (isAdmin !== (user === admin))
+                throw new Error('Smoke account does not have the expected DSM administrator role.');
+            const failures = [];
+            const response = (r) => { if (r.status() >= 500)
+                failures.push(r.status()); };
+            page.on('response', response);
+            try {
+                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 marker(root, options.ready).waitFor({ state: 'visible', timeout });
+                await assertSmokePage(page, options.ready);
+                if (failures.length)
+                    throw new Error(`App smoke received HTTP ${failures.join(', ')}.`);
+            }
+            finally {
+                page.off('response', response);
+            }
+        });
+    }
+    test(`${entry.package}: app opens — X signed out`, { timeout }, async ({ app }) => {
+        // The runner owns an attempt context; a separate one cannot inherit sessions,
+        // storage, routes or service workers from setup tests or global hooks.
+        await openPath(app, '/');
+        const browser = surface().context().browser();
+        if (!browser)
+            throw new Error('Anonymous smoke requires a browser that supports a fresh context.');
+        const context = await browser.newContext({ ignoreHTTPSErrors: true });
+        try {
+            const page = await context.newPage();
+            const failures = [];
+            page.on('response', r => { if (r.status() >= 500)
+                failures.push(r.status()); });
+            const response = await page.goto(new URL(entry.entry, dsmUrl()).href);
+            if (response && response.status() >= 400 &&
+                (response.status() !== 401 || !response.headers()['content-type']?.includes('text/html'))) {
+                throw new Error(`Anonymous app entry returned HTTP ${response.status()}.`);
+            }
+            const login = options.publicLogin && marker(page, options.publicLogin);
+            if (login)
+                await login.waitFor({ state: 'visible', timeout });
+            else
+                await page.locator(`${dsmGate}, [data-error-code="dsm_sign_in_required"], [data-i18n="gateway.sign_in"]`).or(page.getByText(signInText)).first().waitFor({ state: 'visible', timeout });
+            await assertSmokePage(page, options.ready, true, options.publicLogin);
+            if (failures.length)
+                throw new Error(`Anonymous app smoke received HTTP ${failures.join(', ')}.`);
+        }
+        finally {
+            await context.close();
+        }
+    });
+}
 // ---- Command line ---------------------------------------------------------
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
     const [verb, separator, ...command] = process.argv.slice(2);

package/dist/init.js

@@ -207,6 +207,7 @@ export function initFromTemplate(template, targetDir, options = {}) {
         "AGENTS.md",
         "CLAUDE.md",
         ...sharedScripts,
+        ...["package.json", "e2e.config.ts", "tests/e2e/smoke.e2e.ts"].filter(file => existsSync(join(shared, file))),
     ];
     const files = [
         ...templateFiles(source),

package/dist/runtime/webapi-profile.js

@@ -8,7 +8,7 @@ export function validWebAPIProfiles(value) {
     for (const [name, p] of Object.entries(value)) {
         if (!/^[a-z][a-z0-9_-]{0,63}$/.test(name) || name === 'home' || !record(p) || Object.keys(p).some(k => !['purpose', 'apis', 'raw_max_bytes'].includes(k)) || typeof p.purpose !== 'string' || !p.purpose.trim() || Buffer.byteLength(p.purpose) > 1024 || /[\x00-\x1f\x7f]/.test(p.purpose) || !record(p.apis) || !Object.keys(p.apis).length)
             return false;
-        if (p.raw_max_bytes !== undefined && (!Number.isSafeInteger(p.raw_max_bytes) || Number(p.raw_max_bytes) < 0 || Number(p.raw_max_bytes) > 2147483648))
+        if (p.raw_max_bytes !== undefined && (!Number.isSafeInteger(p.raw_max_bytes) || Number(p.raw_max_bytes) < 0 || Number(p.raw_max_bytes) > 10737418240))
             return false;
         for (const [api, methods] of Object.entries(p.apis)) {
             if (!/^SYNO\.[A-Za-z][A-Za-z0-9]*(\.[A-Za-z][A-Za-z0-9]*)*$/.test(api) || api.toLowerCase().split('.').slice(1).some(x => blocked.has(x)) || !record(methods) || !Object.keys(methods).length)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.41.5",
+  "version": "0.41.7",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.35.3",
+    "@synopackageland/templates": "~0.35.5",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.35.3`. A templates patch needs only a
+The CLI installs templates through `~0.35.5`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -26,7 +26,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK/App 0.38.2 and CLI 0.41.5 for App entry enforcement. Declare every App method
+Use SDK/App 0.38.3 and CLI 0.41.7 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -307,3 +307,16 @@ Headless Compose 不產生 launcher。health 必須選實際 endpoint 與 2xx st
 readiness 不跟隨 redirect，check 不會發 HTTP。Compose 不支援 ctl。
 
 For controlling installed Apps or designing task-level AI commands, read [reference/ctl.md](reference/ctl.md). Use ctl host list, register/renew explicitly, discover all commands, and always name the host when agents may operate multiple NAS machines.
+
+## App-open smoke
+
+Every generated project has `tests/e2e/smoke.e2e.ts` and `npm run e2e:smoke`.
+Use `appOpenSmoke` from `@synopackageland/cli/e2e`; keep one content-specific
+`ready` selector or text marker. It derives the manifest entry and launcher,
+reuses the existing DSM credentials/profiles/tunnel, and registers administrator,
+normal-user and fresh anonymous tests. Configure `DSM_E2E_ACCOUNT_ADMIN` and
+`DSM_E2E_ACCOUNT_NORMAL` as private account files; a missing normal profile and
+credentials is a reported skip. Grant Application Privileges before running.
+Override `app` for a manifest filename or `entry` for a configured URL.
+Only a manifest-declared upstream-authenticated entry may use `publicLogin`.
+Keep `.env` and `.e2e/` untracked; never add NAS details to source.

package/skills/reference/install.md

@@ -1,6 +1,6 @@
 # Native installation settings
 
-Use SDK/App 0.38.2, CLI 0.41.5 and templates 0.35.3. Configure installation through the manifest and generated wizard; do not add App ACL writers, root hooks or independent port state.
+Use SDK/App 0.38.3, CLI 0.41.7 and templates 0.35.5. Configure installation through the manifest and generated wizard; do not add App ACL writers, root hooks or independent port state.
 
 ```yaml
 install: