@synopackageland/cli 0.6.1 → 0.7.1

package/README.md

@@ -1,107 +1,99 @@
 # Syno Package Land CLI
 
-Create independent DSM packages by selecting a runtime and declaring the work your app needs.
+`synopkgland` builds Synology DSM packages (SPK). Pick a template, declare what your app needs,
+and the CLI checks, builds and installs the package.
 
-```sh
-synopkgland init -t native-go --with files,jobs,login --package MyApp ./my-app
-(cd my-app/frontend && npm ci)
-synopkgland --project ./my-app check --json
-synopkgland --project ./my-app build --arch x86_64 --json
-synopkgland inspect ./my-app/dist/MyApp-0.1.0-0001-x86_64.spk --json
-synopkgland --project ./my-app deploy --dry-run --arch x86_64 --json
-# When installation on this configured NAS profile is intended:
-synopkgland --project ./my-app deploy --host my-nas --arch x86_64 --json
-synopkgland --project ./my-app status --host my-nas --json
-```
-
-Native-go needs Go 1.25+ and defaults to Vue; install frontend dependencies before building. Use Node 22.19+ for the documented workflow. `--ui plain` skips the frontend npm build but cannot use standalone login. Binary packages a static Linux CGI that owns authentication. Compose imports an upstream project with `init -t compose --from ./compose.yaml`, or creates an example when the import option is omitted.
-
-## Capabilities and authorization
-
-| Class | Declaration | Execution, limits and administrator action |
-| --- | --- | --- |
-| A | Base private settings/data; `--with jobs` | Package-account work bound to trusted username/UID; ordinary users can submit and access their own jobs without admin setup. Private copies do not retain source authority. |
-| B | `--with files` | Caller-session metadata, TreeView/DataGrid file tree, shared NasPicker, streaming upload/download. File Station enforces the caller's permissions; no capability setup. |
-| I | `--with login` | Same-host DSM cookie reuse, including another port, or HTTPS DSM account/password/OTP fallback. App session at most 15 minutes; sensitive operations revalidate live DSM cookie/UID. Vue required. |
-| C | `--with delegate` | One-time admin executor setup, revocable subject/job/operation/scope/expiry grants; DSM runner and uid-dropped writes enforce the user's own permissions. |
-| R | `--with root-ops` | Fixed root/*.sh, administrator only. Shares one-time digest-locked executor setup with C; every root request independently verifies an active administrator. |
-
-An App session identifies the person but does not create File Station authority. Files without a live DSM cookie return `dsm_session_required`; sensitive business methods may return `session_revalidation_required`. Sign in to DSM on the same hostname. P2 scope is a usage restriction, not the permission boundary; per-operation account/AppPriv checks must reject disabled accounts and denied application access. Digest-locked boot tasks restore the executor after reboot; complete integrated lifecycle acceptance remains pending.
-
-Generated native-go/binary require schema 2 `dsm-package.yaml`, with `backend: {kind: go, dir: backend}` or `backend: {kind: binary, files: {x86_64: prebuilt/api-x86_64}}`. Capability values are `files: session`, `jobs: true` (or `{worker: sha256-v1}`), `identity: standalone`, `rootOps: true`, `delegate: {operations: [files.write], scope: home}` inside `capabilities`. Jobs and daemon are mutually exclusive. Binary/compose do not support files/jobs/login/delegate; current rootOps also requires Go. Business route access comes from `backend/internal/api/permissions.json`; SDK-owned route policy cannot be overridden.
-
-See the [delegate guide](../../website/src/content/docs/docs/guides/delegate.md) ([繁體中文](../../website/src/content/docs/zh-tw/docs/guides/delegate.md)) and [administrator lifecycle checks](../../website/src/content/docs/docs/concepts/lifecycle.md) ([繁體中文](../../website/src/content/docs/zh-tw/docs/concepts/lifecycle.md)) for exact operations, errors and cleanup.
-
-## Add capabilities and inspect readiness
+Full documentation: <https://www.varvis.me/docs/> ([繁體中文](https://www.varvis.me/zh-tw/docs/)).
 
-`add files jobs login` updates the manifest and SDK-owned overlays while preserving App-owned handlers/pages. A differing overlay or modified SDK placeholder causes `ADD_FILE_CONFLICT`; review the listed paths. Already-declared capabilities are a no-op. Pristine SDK stubs and the generated route-policy test scaffold may be replaced only while matching the bundled base.
+## Install
 
-`check`, `build`, `inspect`, `deploy` and `status` support `--json`. Stdout contains one object; progress uses stderr; errors contain stable `code`, `message`, `hint`. `status --host <profile>` reports package state, Open URL and per-capability ready/needs-admin-approval/unsupported/blocked reasons. Installation success is separate from approval and runtime caller permissions. `logs` currently reads DSM package status diagnostics; it does not stream App/worker/executor logs and has no follow flag.
-
-## Containers and distribution
-
-Compose retains its separate synology-app.yaml contract. `--share MEDIA_SHARE=photos`, `--run-as RUN_AS=alice` and `--param APP_MODE=prod` supply installation answers. Retain upstream container target paths. Fixed UID/GID mounts govern service access; upstream authentication remains explicit. The DSM gateway controls entry and does not supply a general per-user files capability. `dev`, `test` and `images pin` are Compose tools.
+```sh
+npm install -g @synopackageland/cli --registry=https://registry.npmjs.org
+```
 
-`--dev` selects container development identities. Deploy uploads directly to the selected DSM host, never to a catalog. There is no release, signing or public-submit command.
+Native Go apps need Go 1.25+ and npm. The CLI is tested on Node.js 22.19.
 
-Uninstall requests executor purge and verified own-task removal. If automatic cleanup is unavailable or skipped, an administrator must inspect surviving tasks and protected state. The Delete App Data checkbox does not prove complete deletion: retained DSM directories, account/group and symlink artifacts need readback. Full device lifecycle acceptance and DSM-update persistence remain separate.
+## Quick start
 
-See the bilingual website CLI and schema reference for the complete command/flag inventory; website tests compare it to this CLI's help output.
+```sh
+synopkgland init -t native-go --with files,jobs,login --package MyApp my-app
+cd my-app
+(cd frontend && npm ci)
+synopkgland check --json
+synopkgland build --arch x86_64 --json
+synopkgland inspect dist/MyApp-0.1.0-0001-x86_64.spk --json
+synopkgland deploy --host my-nas --arch x86_64 --json
+synopkgland status --host my-nas --json
+```
 
-## AI authoring guidance
+`deploy --dry-run` prints the deployment plan without connecting to a NAS. You can also install
+the SPK with Package Center's Manual Install.
 
-Every scaffold includes AGENTS.md and a CLAUDE.md pointer. Start with
-`synopkgland skill list`, read `synopkgland skill show orchestrator`, then the
-relevant skill. `synopkgland skill path` locates the bundled reference files.
-For UI work, read `synopkgland skill show ui-vue` for direct Vue components and
-`synopkgland skill show ui-json` for optional JSON specs. Both use the installed
-UI contracts; the Vue template does not require JSON. Follow AGENTS.md's local
-check/build/inspect workflow and obtain authorization before connecting to NAS.
+## Templates
 
-For UI discovery, run `npx --no syno-pkg-land-ui catalog --json` and
-`npx --no syno-pkg-land-ui describe Button --json` from the installed frontend.
-Read its prompt and exported Vue docs/types before choosing component APIs.
-Use `syno-pkg-land-ui` directly in npm scripts; keep AI guidance version-independent.
+| Template | Use it for | Manifest |
+| --- | --- | --- |
+| `native-go` | A Go backend with a Vue UI (or `--ui plain`) | `dsm-package.yaml` |
+| `binary` | A static Linux program you build yourself | `dsm-package.yaml` |
+| `compose` | An existing Docker Compose app (`--from compose.yaml`) | `synology-app.yaml` |
 
-For an empty directory or one-off discovery, select the package explicitly:
+Existing native products with their own payload layout use `backend: {kind: native}` in
+`dsm-package.yaml`.
 
-```sh
-npx -y -p @synopackageland/ui syno-pkg-land-ui catalog
-```
+## Capabilities
 
-The render output defaults to `syno-pkg-land-ui-render`; use `--out shots` to
-choose an artifact directory.
+Add them with `init --with …` or later with `synopkgland add <capability…>`.
 
+| Capability | What the app can do | Who approves |
+| --- | --- | --- |
+| `files` | Browse, read and write NAS files as the signed-in DSM user | Nobody; File Station applies that user's permissions |
+| `jobs` | Run background jobs and schedules as the package | Nobody |
+| `login` | Sign users in with their DSM account, without the DSM desktop | Nobody; requires HTTPS for password sign-in |
+| `delegate` | Move files into a user's chosen folder while the user is offline | An administrator, once |
+| `root-ops` | Run fixed `root/*.sh` scripts for administrators | An administrator, once |
+| `portal` | Open the app from its own Application Portal alias | An administrator sets the alias; needs DSM 7.3.2-86009+ |
+
+Delegate is implemented; its default operation is `files.moveFromStaging`.
+Device lifecycle acceptance on real hardware is still pending for delegate and root operations.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `init` | Create a project from a template |
+| `add` | Add capabilities or `portal` to a project |
+| `check` | Validate the manifest, capability combinations and Compose file |
+| `build` | Build the SPK for one or more architectures |
+| `inspect` | Inspect an SPK without installing it |
+| `deploy` | Build and install on a NAS |
+| `status` | Show package state, Open URL and capability readiness |
+| `logs` | Show package status diagnostics |
+| `dev`, `test`, `images` | Run, test and pin images for Compose projects |
+| `skill` | Read the bundled guidance for AI assistants |
+
+`--json` prints one JSON object on stdout: `{ok: true, command, data}` on success and
+`{ok: false, code, message, hint}` on failure. See the
+[CLI reference](https://www.varvis.me/docs/reference/cli/) and
+[error codes](https://www.varvis.me/docs/reference/errors/).
+
+## AI assistants
+
+Every project includes `AGENTS.md` and a `CLAUDE.md` pointer. Start with
+`synopkgland skill list` and `synopkgland skill show orchestrator`. For UI work, read
+`synopkgland skill show ui-vue` (Vue components) or `synopkgland skill show ui-json`
+(JSON specs). From an installed frontend, `npx --no syno-pkg-land-ui catalog --json` lists the
+UI components and `npx --no syno-pkg-land-ui describe Button --json` describes one.
 
 ## Licensing
 
-The CLI and original templates are MIT licensed, Copyright (c) 2026 synopkgland.
-Third-party components retain their own terms.
-Generated projects keep these template terms in `LICENSES/TEMPLATE.txt`.
-`init` does not create an app-level `LICENSE` or select a license for your work:
-choose your own terms and copyright holder in the project root `LICENSE`.
-Retain the template and dependency notices when distributing derived code.
-
-SPKs place legal material under the installed payload's `LICENSES/` directory:
-`TEMPLATE.txt`, optional developer `APP.txt`, Go's `GO-LICENSE`/`GO-PATENTS`,
-`GO-THIRD_PARTY_NOTICES.txt`, and the Vue `ui/` notice tree.
-
-Vue builds generate full notices plus `inventory.json` from the installed,
-locked production dependency tree. Missing text or a version mismatch fails the
-build. Run `npm ci` in the generated frontend before building.
-
-Keep `backend/THIRD_PARTY_NOTICES.txt` current if you change Go modules.
-The supplied notice inventory covers the pinned template dependencies and Go
-runtime; arbitrary developer binaries, Go module additions, container images,
-custom UI bundles and upstream applications need their own notice inventory.
-
-### Existing native products
-
-Schema 2 also supports `backend: {kind: native}` with `layout` and `native` declarations.
-This preserves project-owned multi-executable payloads, metadata/conf, lifecycle hooks,
-checksum-pinned DSM toolkits and x86_64/aarch64/armv8/armv7 families. Lifecycle and
-systemd remain package-only; root task authorization is an explicit product responsibility.
-The separate `@synopackageland/cli/authorization-sdk` export provides the pinned-task
-host adapter and Vue authorization gate. Generated Go rootOps/delegate still use the executor.
-See the [native layout and migration guide](../../website/src/content/docs/docs/guides/native-layout.md)
-([繁體中文](../../website/src/content/docs/zh-tw/docs/guides/native-layout.md)).
+The CLI and its original templates are MIT licensed, Copyright (c) 2026 synopkgland.
+Third-party components keep their own terms.
+
+- Generated projects keep the template terms in `LICENSES/TEMPLATE.txt`. `init` does not choose a
+  license for your app: add your own `LICENSE`.
+- An SPK carries its legal notices under `LICENSES/` in the installed payload: `TEMPLATE.txt`,
+  an optional `APP.txt`, Go's license, patents and third-party notices, and the Vue UI notices.
+- Vue builds generate the UI notices from the installed, locked dependencies; run `npm ci` in
+  `frontend/` first. A missing notice or version mismatch fails the build.
+- Keep `backend/THIRD_PARTY_NOTICES.txt` current when you change Go modules. Your own binaries,
+  added modules, container images and upstream apps need their own notices.

package/dist/add.d.ts

@@ -1,4 +1,7 @@
-export declare function addCapabilities(root: string, requested: string[]): {
+type AddResult = {
     added: string[];
     unchanged: string[];
+    notes?: string[];
 };
+export declare function addCapabilities(root: string, requested: string[]): AddResult;
+export {};

package/dist/add.js

@@ -1,11 +1,11 @@
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, relative } from 'node:path';
-import { parseDocument } from 'yaml';
+import { isScalar, parseDocument } from 'yaml';
 import { capabilityNames, capabilitySettings } from './capabilities.js';
-import { initFromTemplate } from './init.js';
+import { initFromTemplate, nativeCapabilitySettings } from './init.js';
 import { templatesRoot } from './template-paths.js';
-import { DEFAULT_MIN_DSM, isDsmAtLeast } from './build-spk/dsm-version.js';
+import { DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_MIN_DSM } from './build-spk/dsm-version.js';
 import { loadStandaloneManifest } from './standalone/manifest.js';
 const overlays = {
     jobs: ['native-go-jobs'],
@@ -46,7 +46,43 @@ function safePath(root, file) {
     }
     return true;
 }
+/** Raise a lower os_min_ver to the floor a capability needs; a higher one stays. Returns the notice. */
+function raiseOsMinVer(doc, current, floor, capability) {
+    const osMinVer = doc.get('os_min_ver', true);
+    if (!isScalar(osMinVer) || isDsmAtLeast(current, floor))
+        return [];
+    osMinVer.value = floor;
+    return [`os_min_ver raised from ${current} to ${floor}: ${capability} needs DSM ${floor} or later.`];
+}
+function withNotes(result, notes) {
+    const all = [...(result.notes ?? []), ...notes];
+    return all.length ? { ...result, notes: all } : result;
+}
+/**
+ * `portal: {}` in dsm-package.yaml; the Go and binary starters already carry the UI and backend side.
+ * A lower os_min_ver is raised to PORTAL_MIN_DSM, the oldest DSM verified to install a portal.
+ */
+function addPortal(root, result) {
+    const loaded = loadStandaloneManifest(root);
+    if (!loaded.ok)
+        throw new Error(loaded.errors.map(e => `[${e.code}] ${e.message}`).join('\n'));
+    if (loaded.manifest.portal)
+        return { ...result, unchanged: [...result.unchanged, 'portal'] };
+    if (!safePath(root, 'dsm-package.yaml'))
+        throw new Error('[ADD_FILE_CONFLICT] 既有檔案與 SDK overlay 不同：dsm-package.yaml；請先移動或合併衝突，不會覆寫。');
+    const manifestPath = join(root, 'dsm-package.yaml');
+    const doc = parseDocument(readFileSync(manifestPath, 'utf8'));
+    doc.set('portal', doc.createNode({}, { flow: true }));
+    const notes = raiseOsMinVer(doc, loaded.manifest.os_min_ver, PORTAL_MIN_DSM, 'portal');
+    writeFileSync(manifestPath, String(doc));
+    return withNotes({ ...result, added: [...result.added, 'portal'] }, notes);
+}
 export function addCapabilities(root, requested) {
+    const wanted = [...new Set(requested.flatMap(value => value.split(',')).map(value => value.trim()))];
+    if (wanted.includes('portal')) {
+        const rest = wanted.filter(name => name !== 'portal');
+        return addPortal(root, rest.length ? addCapabilities(root, rest) : { added: [], unchanged: [] });
+    }
     const names = capabilityNames(requested);
     const loaded = loadStandaloneManifest(root);
     if (!loaded.ok)
@@ -59,8 +95,8 @@ export function addCapabilities(root, requested) {
     const added = names.filter(name => !unchanged.includes(name));
     if (!added.length)
         return { added, unchanged };
-    if ((added.includes('jobs') || added.includes('delegate')) && m.daemon)
-        throw new Error('[CAPABILITY_COMBINATION_INVALID] daemon 與 capabilities.jobs 互斥。');
+    if (m.daemon && added.includes('jobs') && !added.includes('delegate') && m.capabilities.delegate?.lifetime !== 'until-revoked')
+        throw new Error('[CAPABILITY_COMBINATION_INVALID] daemon 僅可與 until-revoked delegate 固定 worker 共存。');
     if (m.backend.dir !== join(root, 'backend'))
         throw new Error('[ADD_LAYOUT_UNSUPPORTED] SDK overlay 需要 backend.dir: backend。');
     const work = mkdtempSync(join(tmpdir(), 'synopkgland-add-'));
@@ -96,11 +132,10 @@ export function addCapabilities(root, requested) {
         if (conflicts.length)
             throw new Error(`[ADD_FILE_CONFLICT] 既有檔案與 SDK overlay 不同：${conflicts.join(', ')}；請先移動或合併衝突，不會覆寫。`);
         const doc = parseDocument(readFileSync(manifestPath, 'utf8'));
-        for (const [key, value] of Object.entries(capabilitySettings(added)))
+        for (const [key, value] of Object.entries(nativeCapabilitySettings(added)))
             doc.setIn(['capabilities', key], value);
-        // All semantic checks precede writes to the user's project.
-        if (added.includes('root-ops') && !isDsmAtLeast(m.os_min_ver, DEFAULT_MIN_DSM))
-            throw new Error('[STANDALONE_OS_MIN_VER_INVALID] rootOps 需要 DSM 7.1-42661 或以上。');
+        // rootOps needs DSM 7.1-42661 or later.
+        const notes = added.includes('root-ops') ? raiseOsMinVer(doc, m.os_min_ver, DEFAULT_MIN_DSM, 'root-ops') : [];
         for (const file of destinations) {
             const path = join(root, file);
             mkdirSync(dirname(path), { recursive: true });
@@ -108,15 +143,8 @@ export function addCapabilities(root, requested) {
         }
         for (const file of deletions)
             rmSync(join(root, file), { force: true });
-        if (added.includes('delegate')) {
-            const path = join(root, 'backend/internal/api/permissions.json');
-            const policy = JSON.parse(readFileSync(path, 'utf8'));
-            if (!Object.hasOwn(policy.methods, 'app.status'))
-                policy.methods['app.status'] = 'authenticated';
-            writeFileSync(path, JSON.stringify(policy, null, 2) + '\n');
-        }
         writeFileSync(manifestPath, String(doc));
-        return { added, unchanged };
+        return withNotes({ added, unchanged }, notes);
     }
     finally {
         rmSync(work, { recursive: true, force: true });

package/dist/build-spk/delegate-scope.d.ts

@@ -0,0 +1,6 @@
+import type { InstallWizardStep } from './install-wizard.js';
+import type { Translate } from './wizard-i18n.js';
+export declare function renderDelegateScopeSteps(t: Translate): InstallWizardStep[];
+/** Package-owned draft only. Preinst validates; postinst stores the same value.
+ * No shell evaluation of the share, no ACL changes, no protected-state access. */
+export declare function renderDelegateInstallDraft(pkg: string, validateOnly: boolean): string;

package/dist/build-spk/delegate-scope.js

@@ -0,0 +1,34 @@
+import { sharedFolderCombobox } from './share-combobox.js';
+export function renderDelegateScopeSteps(t) {
+    const box = sharedFolderCombobox(t, 'delegate_share');
+    box.desc = t('label.sharedFolder');
+    const item = box.subitems[0];
+    item.desc = t('label.sharedFolder');
+    item.validator = { allowBlank: true }; // Home works even on a NAS without local shares.
+    return [{ step_title: t('install.step'), items: [
+                { desc: t('consent.appOwnSpace') }, { desc: t('delegate.preselection') },
+                box, { type: 'multiselect', subitems: [{ key: 'delegate_home', desc: t('delegate.home'), defaultValue: false }] },
+            ] }];
+}
+/** Package-owned draft only. Preinst validates; postinst stores the same value.
+ * No shell evaluation of the share, no ACL changes, no protected-state access. */
+export function renderDelegateInstallDraft(pkg, validateOnly) {
+    return `if [ "\${SYNOPKG_PKG_STATUS:-}" != UPGRADE ]; then
+  case "\${delegate_home:-false}" in
+    true|1|yes|on) selected_scope=home ;;
+    *)
+      selected_share="\${delegate_share:-}"
+      case "$selected_share" in
+        ''|.|*..*|*/*|*'\\'*|*:*|*'"'*|*'%'*|*[[:cntrl:]]*|[hH][oO][mM][eE]|[hH][oO][mM][eE][sS]|[[:space:]]*|*[[:space:]]) echo "Select a shared folder or choose home." >&2; exit 1 ;;
+      esac
+      selected_scope="shared:$selected_share" ;;
+  esac
+${validateOnly ? '' : `  umask 077
+  draft_dir="\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}"
+  mkdir -p "$draft_dir"
+  draft_tmp="$draft_dir/.delegate-install.$$"
+  printf '{"schema":1,"scope":"%s"}\\n' "$selected_scope" > "$draft_tmp"
+  mv "$draft_tmp" "$draft_dir/delegate-install.json"
+`}fi
+`;
+}

package/dist/build-spk/dsm-arch.d.ts

@@ -1,7 +1,13 @@
-export declare const NATIVE_ARCH_FAMILIES: readonly ["x86_64", "aarch64"];
+export declare const NATIVE_ARCH_FAMILIES: readonly ["x86_64", "aarch64", "armv7"];
 export type NativeArchFamily = (typeof NATIVE_ARCH_FAMILIES)[number];
+/** DSM ships Container Manager for x86_64 and aarch64 only. */
+export declare const CONTAINER_ARCH_FAMILIES: readonly ["x86_64", "aarch64"];
+export type ContainerArchFamily = (typeof CONTAINER_ARCH_FAMILIES)[number];
 export declare const NATIVE_ARCH_PLATFORMS: Record<NativeArchFamily, readonly string[]>;
+/** The `go build` environment for a static Linux binary of this family. */
+export declare function goBuildEnv(family: NativeArchFamily): Record<string, string>;
 export declare function isNativeArchFamily(value: string): value is NativeArchFamily;
+export declare function isContainerArchFamily(value: string): value is ContainerArchFamily;
 /** `--arch x86_64,aarch64`: one or more families, in the given order, each once. */
 export declare function parseArchList(value: string): NativeArchFamily[];
 export declare function infoArchValue(family: NativeArchFamily): string;

package/dist/build-spk/dsm-arch.js

@@ -1,36 +1,32 @@
-export const NATIVE_ARCH_FAMILIES = ["x86_64", "aarch64"];
+import DSM_PLATFORMS from "./dsm-platforms.json" with { type: "json" };
+export const NATIVE_ARCH_FAMILIES = ["x86_64", "aarch64", "armv7"];
+/** DSM ships Container Manager for x86_64 and aarch64 only. */
+export const CONTAINER_ARCH_FAMILIES = ["x86_64", "aarch64"];
+/**
+ * INFO platforms per family: DSM's family members, then platforms listed
+ * explicitly. dsm-platforms.json is shared with package-source. armv7 omits
+ * armada370/375/xp and comcerto2k, which exist only on DSM 7.0/7.1, so DSM
+ * refuses the SPK there.
+ */
+const platformsOf = (family) => [...DSM_PLATFORMS[family].members, ...DSM_PLATFORMS[family].platformOnly];
 export const NATIVE_ARCH_PLATFORMS = {
-    x86_64: [
-        "apollolake",
-        "avoton",
-        "braswell",
-        "broadwell",
-        "broadwellnk",
-        "broadwellnkv2",
-        "broadwellntbap",
-        "bromolow",
-        "cedarview",
-        "denverton",
-        "epyc7002",
-        "epyc7003",
-        "epyc7003ntb",
-        "geminilake",
-        "geminilakenk",
-        "grantley",
-        "icelaked",
-        "kvmcloud",
-        "kvmx64",
-        "purley",
-        "r1000",
-        "r1000nk",
-        "v1000",
-        "v1000nk",
-    ],
-    aarch64: ["armada37xx", "rtd1296", "rtd1619b"],
+    x86_64: platformsOf("x86_64"),
+    aarch64: platformsOf("aarch64"),
+    armv7: platformsOf("armv7"),
 };
+const GOARCH = { x86_64: "amd64", aarch64: "arm64", armv7: "arm" };
+/** The `go build` environment for a static Linux binary of this family. */
+export function goBuildEnv(family) {
+    const env = { CGO_ENABLED: "0", GOOS: "linux", GOARCH: GOARCH[family] };
+    // GOARM=7 needs VFPv3, which every DSM armv7 platform has.
+    return family === "armv7" ? { ...env, GOARM: "7" } : env;
+}
 export function isNativeArchFamily(value) {
     return NATIVE_ARCH_FAMILIES.includes(value);
 }
+export function isContainerArchFamily(value) {
+    return CONTAINER_ARCH_FAMILIES.includes(value);
+}
 /** `--arch x86_64,aarch64`: one or more families, in the given order, each once. */
 export function parseArchList(value) {
     const families = [];

package/dist/build-spk/dsm-platforms.json

@@ -0,0 +1,42 @@
+{
+    "x86_64": {
+        "members": [
+            "apollolake",
+            "avoton",
+            "braswell",
+            "broadwell",
+            "broadwellnk",
+            "broadwellnkv2",
+            "broadwellntb",
+            "broadwellntbap",
+            "bromolow",
+            "cedarview",
+            "coffeelake",
+            "denverton",
+            "epyc7002",
+            "epyc7003",
+            "epyc7003ntb",
+            "geminilake",
+            "geminilakenk",
+            "grantley",
+            "icelaked",
+            "kvmcloud",
+            "kvmx64",
+            "purley",
+            "r1000",
+            "r1000nk",
+            "skylaked",
+            "v1000",
+            "v1000nk"
+        ],
+        "platformOnly": []
+    },
+    "aarch64": {
+        "members": ["armada37xx", "rtd1296", "rtd1619", "rtd1619b"],
+        "platformOnly": []
+    },
+    "armv7": {
+        "members": ["alpine", "alpine4k"],
+        "platformOnly": ["armada38x", "monaco"]
+    }
+}

package/dist/build-spk/dsm-version.d.ts

@@ -6,9 +6,20 @@ export declare const DEFAULT_MIN_DSM: string;
  * would install and then fail to start.
  */
 export declare const CONTAINER_MIN_DSM: string;
+/**
+ * DSM registers an Application Portal through the package's web-config
+ * app-portal resource. DSM 7.1.1-42962 refuses that resource in an unsigned
+ * package (error 320, "internal worker"); DSM 7.3.2-86009 and 7.4 install it.
+ * 7.2 and 7.3.0/7.3.1 are untested, so the floor is the oldest verified build.
+ */
+export declare const PORTAL_MIN_DSM = "7.3.2-86009";
+/** Why a portal package cannot declare `value`, and how to fix it; `field` names the portal key. */
+export declare function portalMinDsmMessage(value: string, field: string): string;
 /** `true` when `value` is not older than `floor`, comparing version parts then build. */
 export declare function isDsmAtLeast(value: string, floor: string): boolean;
 /** Container Apps cannot declare an os_min_ver below {@link CONTAINER_MIN_DSM}. */
 export declare function assertContainerMinDsm(value: string): void;
+/** A compose portal cannot be built for an os_min_ver below {@link PORTAL_MIN_DSM}. */
+export declare function assertPortalMinDsm(value: string): void;
 /** `--min-dsm`: a release (`7.1`) or a full `<version>-<build>` string (`7.2-69057`). */
 export declare function resolveMinDsm(value: string): string;

package/dist/build-spk/dsm-version.js

@@ -13,6 +13,17 @@ export const DEFAULT_MIN_DSM = FIRST_BUILD["7.1"];
  * would install and then fail to start.
  */
 export const CONTAINER_MIN_DSM = FIRST_BUILD["7.2.1"];
+/**
+ * DSM registers an Application Portal through the package's web-config
+ * app-portal resource. DSM 7.1.1-42962 refuses that resource in an unsigned
+ * package (error 320, "internal worker"); DSM 7.3.2-86009 and 7.4 install it.
+ * 7.2 and 7.3.0/7.3.1 are untested, so the floor is the oldest verified build.
+ */
+export const PORTAL_MIN_DSM = "7.3.2-86009";
+/** Why a portal package cannot declare `value`, and how to fix it; `field` names the portal key. */
+export function portalMinDsmMessage(value, field) {
+    return `${field} 需要 DSM ${PORTAL_MIN_DSM} 以上，os_min_ver 是「${value}」。DSM 7.1.1 以錯誤 320 拒裝帶 portal（web-config app-portal）的未簽章套件；DSM 7.3.2 與 7.4 已驗證可裝，7.2 未驗證。請把 os_min_ver 提高到 ${PORTAL_MIN_DSM} 以上，或移除 ${field}。`;
+}
 /** `true` when `value` is not older than `floor`, comparing version parts then build. */
 export function isDsmAtLeast(value, floor) {
     const [valueVersion, valueBuild] = value.split("-");
@@ -33,6 +44,12 @@ export function assertContainerMinDsm(value) {
         throw new Error(`[MIN_DSM_CONTAINER_FLOOR] 容器 App 需要 DSM ${CONTAINER_MIN_DSM} 以上（docker-project／Container Manager 從 DSM 7.2.1 才有），收到「${value}」。`);
     }
 }
+/** A compose portal cannot be built for an os_min_ver below {@link PORTAL_MIN_DSM}. */
+export function assertPortalMinDsm(value) {
+    if (!isDsmAtLeast(value, PORTAL_MIN_DSM)) {
+        throw new Error(`[CONTRACT_PORTAL_MIN_DSM] ${portalMinDsmMessage(value, "integration.web.portal")}`);
+    }
+}
 const FULL_VERSION = /^7\.\d+(\.\d+)?-\d+$/;
 /** `--min-dsm`: a release (`7.1`) or a full `<version>-<build>` string (`7.2-69057`). */
 export function resolveMinDsm(value) {

package/dist/build-spk/gateway.js

@@ -4,12 +4,12 @@ import { checkCgiBinary } from "../standalone/binary.js";
 import { runCommand } from "../standalone/build.js";
 import { resolvedWebAccess } from "../contract/web-launch.js";
 import { templatesRoot } from "../template-paths.js";
+import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem } from "./go-toolchain.js";
 export { gatewayEntryPath } from "../contract/web-launch.js";
 /** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
 export const GATEWAY_CGI_PAYLOAD = "ui/cgi/gateway.cgi";
 /** Readable copy of the baked-in configuration, for inspection; the CGI does not read it. */
 export const GATEWAY_CONFIG_PAYLOAD = "gateway.json";
-const GOARCH = { x86_64: "amd64", aarch64: "arm64" };
 const ACCESS = { "dsm-users": "users", "dsm-admins": "admins", "dsm-groups": "groups" };
 /** The access rule and container address the gateway enforces; undefined for an App without one. */
 export function gatewayConfig(contract, adminport) {
@@ -29,18 +29,22 @@ export function buildGatewayBinary(input) {
     const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${input.packageId}`, `-X 'main.configJSON=${JSON.stringify(input.config)}'`].join(" ");
     const result = (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
         cwd: join(templatesRoot(), "_gateway"),
-        env: { ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: GOARCH[input.arch] },
+        env: { ...process.env, ...pinnedGoBuildEnv(input.arch) },
     });
     if (result.missing) {
-        return { error: "GATEWAY_GO_MISSING", detail: "找不到 go 指令。DSM 驗證閘道需要 Go 1.24 以上版本（https://go.dev/dl/）才能建置。" };
+        return { error: "GATEWAY_GO_MISSING", detail: `找不到 go 指令。DSM 驗證閘道需要 Go 1.21 以上版本（https://go.dev/dl/）才能建置。${PINNED_GO_HINT}` };
     }
     if (result.status !== 0) {
-        return { error: "GATEWAY_BUILD_FAILED", detail: `go build（${input.arch}）失敗。\n${result.stderr}` };
+        return { error: "GATEWAY_BUILD_FAILED", detail: `go build（${input.arch}）失敗。${PINNED_GO_HINT}\n${result.stderr}` };
     }
     const problem = checkCgiBinary(input.work, out, input.arch);
     if (problem) {
         return { error: "GATEWAY_BUILD_FAILED", detail: problem.message };
     }
+    const toolchainProblem = pinnedGoProblem(out);
+    if (toolchainProblem) {
+        return { error: "GATEWAY_BUILD_FAILED", detail: toolchainProblem };
+    }
     return { binary: out };
 }
 /** Puts the CGI (mode 0755) and its readable configuration into the package payload. */