@synopackageland/cli 0.15.3 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.16.0 (2026-10-19)
+
+- Pin SDK/templates 0.16.0; generated Shared Folder flows use the shared SDK readback and settings components.
+- Add the upstream-fork recipe/init/check workflow, Container Manager preflight and architecture-matched storage initializer packaging while preserving official images.
+- Remove internal deployment details from published content and scan actual npm tarballs before release.
+
+## 0.15.4 (2026-10-18)
+
+- Fix Compose import and undeclared SDK defaults after CLI-only patch releases. Resolve the SDK from the exactly pinned templates' Go module instead of assuming the CLI and SDK share a patch version; daemon-control defaults use the same source.
+- Preserve explicit Compose and identity-gateway SDK declarations. Add subprocess regressions with differing CLI/SDK versions and no SDK source override, plus release smoke coverage for real Compose imports and headless manifests.
+- Keep templates/SDK pinned to 0.15.2 and every executor/lifecycle digest entry unchanged. Upgrade from CLI 0.15.3 to 0.15.4 to restore `init -t compose --from`; SDK/helper bytes do not change and no new administrator reapproval requirement is introduced.
+
+繁中摘要：修正 CLI 與 SDK patch 版本不同時，Compose 匯入／未宣告 SDK 的預設路徑下載不存在 SDK tag 的問題；改由固定 templates 的 Go module 讀取 SDK pin，daemon-control 預設值亦同步。保留明確 SDK 宣告的優先順序，新增無 source override 的版本拆分回歸測試與正式產物 smoke。templates／SDK 保持 0.15.2，全部 executor／lifecycle digest 不變；請由 CLI 0.15.3 升級至 0.15.4，不新增管理員重新核准要求。
+
 ## 0.15.3 (2026-10-18)
 
 - Pin templates and SDK fixtures/examples to 0.15.2, including UI 0.12.0 scaffolds, concise UI copy/tokens and delegate DTO contract checks.
@@ -166,8 +180,8 @@ only its protocol README's wording, and nothing in the CLI depends on it.
 
 - `ctx.call` rejects `APP_STOPPED` at once: a stopped package waits for the
   user to start it in Package Center, so the SDK's stopped copy shows within a
-  page's next read instead of 30 s later (Download Hub 29.3 s, t-0527; Reclaim
-  showed its old content or loading, t-0528). `APP_STARTING` and
+  page's next read instead of 30 s later (Download Hub 29.3 s; Reclaim
+  showed its old content or loading). `APP_STARTING` and
   `EXECUTOR_STARTING` repeat for 4 s of waiting (0.5, 1, 2, 0.5 s), so a short
   start still shows the page nothing and the SDK's starting copy follows a
   longer one within its own 4 s recheck. `executor.control`, which the window's
@@ -217,7 +231,7 @@ e2e 新增 `openUntilLoaded`（`signIn` 遇 `net::ERR_ABORTED` 最多重開約 3
   the newest one it read (`lastStatus()`); a `status()` asked for while a read
   runs shares it. The SDK's `PortalSettings` starts from it, so a settings
   page no longer moves when its placeholder rows become the real section
-  (Reclaim: 100 px, t-0520).
+  (Reclaim: 100 px).
 
 ## 0.10.6 (2026-10-15)
 
@@ -236,7 +250,7 @@ digest 與 0.10.5 相同；SDK 下限維持 0.10.5。e2e 新增 `openPath`、`ha
 
 - `signIn`, `openDesktop` and `openPortal` open their page once more when
   the first navigation fails with `net::ERR_ABORTED`, which about one run in
-  ten met as DSM's desktop navigated on its own (t-0499, t-0500); any other
+  ten met as DSM's desktop navigated on its own; any other
   failure, or a second abort, still fails. The helper is exported as
   `openPath(app, path)`.
 - The DSM window's `status()` answers a pinned executor that reports
@@ -322,7 +336,7 @@ digest 與 0.10.4 相同；新增 `@synopackageland/cli/e2e`。
   `authorization.status`, `executor.status`) while the package is stopped or
   starting: they reject with the code at once, and SDK 0.10.5's panels show the
   stopped or starting package and check again on their own. A page no longer
-  shows nothing for the first seconds after an upgrade (6.7 s in t-0503). Calls
+  shows nothing for the first seconds after an upgrade (6.7 s in the regression test). Calls
   that change something, approvals and controls among them, still repeat for up
   to 30 s. `ctx.executor.status()` for a user who is not an administrator says
   the package is stopped or starting instead of `admin_required`.
@@ -354,12 +368,12 @@ before its timeout.
 - The window approval of an upgrade (outdated tasks) makes 11 scheduler calls
   instead of 12: the outdated boot task is deleted by the approval's own first
   EventScheduler get, made moments before the password, instead of a second
-  get (2.9 s on the test NAS in t-0484). The control task is still read again by id
+  get (2.9 s on the test NAS in the regression test). The control task is still read again by id
   before its delete (spec/scheduler/v1). A fresh approval stays at 8.
   繁中：升級核准的排程呼叫由 12 降為 11（boot 任務不再於刪除前重讀）。
 - A scope approval reads the executor's selection back every second at most
   (it backed off to 2 s), so the window sees the landed scope within a second
-  of `scope.confirm` (the Dialog closed 4.8 s after it in t-0482). Removing
+  of `scope.confirm` (the Dialog closed 4.8 s after it in the regression test). Removing
   the temporary selection task still lists Task Scheduler first, as
   spec/scheduler/v1 requires of a delete.
   繁中：範圍核准讀回間隔上限 2 s → 1 s，confirmed 後 1 s 內看到結果。
@@ -368,7 +382,7 @@ before its timeout.
   before any request: the pinned, running executor reads `ready`; anything
   else stays `blocked` with `admin_required`. Task Scheduler is still read only
   for administrators. A user no longer sees an approved executor as waiting
-  for approval (t-0482 F7).
+  for approval.
   繁中：非管理員的 `ctx.executor.status()` 會向 App 的 `executor.status` 詢問，已核准且
   執行中即為 `ready`，不再一律回 `admin_required`。
 

package/README.md

@@ -61,6 +61,9 @@ children's `GOPRIVATE`, `GONOPROXY` and `GONOSUMDB`, preserving existing environ
 `https://github.com/synopackageland/syno-pkg-land-sdk` (check with `git ls-remote`);
 a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
+CLI-only patch releases can differ from the SDK patch. Compose import and SDK defaults
+read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
+
 `init` and `add` read their templates from `@synopackageland/templates`, an exact-pinned
 dependency. For development against local checkouts, set `SYNOPKGLAND_TEMPLATES_DIR` to a
 templates checkout and `SYNOPKGLAND_SDK_DIR` to an SDK checkout; SPKs built with

package/assets/init-compose.md

@@ -0,0 +1,33 @@
+# Compose App development
+
+Run `synopkgland skill list`, then `synopkgland skill show orchestrator`,
+`synopkgland skill show compose` and `synopkgland skill show upstream-fork`.
+Prefer `check --json`, `build --json`, `inspect <spk> --json` for reviewable results.
+
+Never write `AppPortal.json` or `@appconf` directly, or relay QuickConnect.
+Compose has no native Application Portal alias; use its supported web entry.
+
+Use dsm-package.yaml schema 2. Keep upstream Compose bytes unchanged; declare DSM
+policy in compose.files and compose.web. Never use file/targets/address_env or
+identity_gateway.upstream: the SDK planner derives ingress.
+
+## Compose health and launch
+
+Select compose.web.health.path and its actual expected 2xx status before
+check/build. Redirects are not followed; a 302 to login is unhealthy. check is
+static, not an HTTP or arbitrary-UID/storage probe. Test the selected official image as
+the package UID, including writable volumes, first setup and upgrade.
+Omitted ui.launch means new-page via the SDK standalone launcher, without
+Application Portal. Headless Apps omit compose.web and have no launcher.
+Compose ctl is unsupported.
+
+Use supported upstream config files, environment, argv or reverse proxy for
+login/settings. For integrated upstream Apps, select supported trusted-header authentication or disable upstream login behind the DSM admin gate; or use the existing SDK 0.16.0 token adapter: OpenList uses mode: token, access: dsm-admins and entry: admin-only. Its unmodified admin token CLI supplies a package-private 0600 credential; the gateway injects Authorization server-side after DSM admission, without delivering it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own credentials. Verify each App adapter and DSM admission separately.
+Containers use the package account and a dedicated bridge; they do not inherit
+an interactive user's NAS ACL. Do not use root/chown during any App lifecycle
+phase. Preserve licenses and dependency/source provenance. Read the CLI skill
+reference/compose.md and reference/upstream-fork.md for the full recipe.
+
+Public npm access does not grant anonymous Go SDK access. Obtain authorised
+source/cache access or a matching SYNOPKGLAND_SDK_DIR checkout first. Never copy
+credentials into the App. Do not install, publish or modify NAS data without task authorization.

package/assets/init-upstream/build-source.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Native App payload hook. SPL_UPSTREAM_SOURCE is the merged fork root.
+# Stage official release binaries only after verifying pinned SHA-256 values
+# (the OpenList route), or compile the merged source with a source build hook.
+# Stage daemon.targets under synology/; pin toolchains/dependencies for builds.
+# Keep upstream source unchanged.
+# Every App lifecycle phase uses the package UID. Do not add root/chown hooks.
+echo 'SOURCE_BUILD_REQUIRED: implement the native synology/build-source.sh.' >&2
+exit 2

package/assets/init-upstream/update-image.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Use the CLI's existing OCI registry resolver; never build or publish an image.
+import {mkdtempSync, readFileSync, writeFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {spawnSync} from 'node:child_process';
+const [tag] = process.argv.slice(2);
+const match = /^v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(tag ?? '');
+if (!match) throw new Error('Use the selected stable upstream tag.');
+const config = JSON.parse(readFileSync(new URL('./upstream-recipe.json', import.meta.url), 'utf8'));
+if (config.kind !== 'official-image' || !['tag', 'version'].includes(config.imageTag)) throw new Error('Invalid official image recipe.');
+const imageTag = config.imageTag === 'version' ? match[1] : tag;
+const reference = `${config.repository}:${imageTag}`;
+const temp = mkdtempSync(join(tmpdir(), 'synopkgland-image-pin-'));
+try {
+  // images pin edits only compose.yaml; use a bounded temporary project so the
+  // App's base Compose and upstream source remain unchanged on lookup failure.
+  writeFileSync(join(temp, 'dsm-package.yaml'), 'schema: 2\n');
+  writeFileSync(join(temp, 'compose.yaml'), JSON.stringify({services: {[config.service]: {image: reference}}}, null, 2) + '\n');
+  const result = spawnSync('synopkgland', ['--project', temp, 'images', 'pin'], {stdio: 'inherit'});
+  if (result.error || result.status !== 0) throw new Error('Official image digest lookup failed; no Compose override was changed.');
+  const pinned = JSON.parse(readFileSync(join(temp, 'compose.yaml'), 'utf8'));
+  const image = pinned.services[config.service].image;
+  if (!image.startsWith(`${reference}@sha256:`) || !/@sha256:[0-9a-f]{64}$/.test(image)) throw new Error('Registry lookup did not produce the selected tag plus digest.');
+  writeFileSync(new URL('./compose.image.yaml', import.meta.url), JSON.stringify(pinned, null, 2) + '\n');
+} finally {rmSync(temp, {recursive: true, force: true});}

package/assets/init-upstream/upgrade.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# One explicit stable tag; no latest guessing, push, image publication or NAS access.
+set -euo pipefail
+packaging=$(cd -- "$(dirname -- "$0")" && pwd)
+repo=$(cd -- "$packaging/.." && pwd)
+cd "$repo"
+[[ $# == 2 && $1 =~ ^v?(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]] || {
+  echo 'Usage: bash synology/upgrade.sh <[v]X.Y.Z> <increasing-build-number>' >&2; exit 2;
+}
+[[ $(git rev-parse --show-toplevel) == "$repo" ]] || { echo 'Run inside a source fork.' >&2; exit 2; }
+[[ -z $(git status --porcelain --untracked-files=normal) ]] || { echo 'Commit changes before upgrading.' >&2; exit 2; }
+git remote get-url upstream >/dev/null
+node "$packaging/version.mjs" "$1" "$2" --validate
+# Fetch the named remote tag into a private ref: a local tag can never substitute for it.
+git fetch --no-tags upstream "+refs/tags/$1:refs/synopkgland/selected-upstream"
+commit=$(git rev-parse 'refs/synopkgland/selected-upstream^{commit}')
+[[ -z $(git ls-tree "$commit" -- synology) ]] || { echo 'Upstream owns synology/; choose another integration layout.' >&2; exit 2; }
+previous=$(git describe --tags --abbrev=0 --match '[0-9]*' --match 'v[0-9]*' HEAD 2>/dev/null || true)
+if [[ -f "$packaging/upstream-source.json" ]]; then
+  previous=$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.argv[1])).commit)' "$packaging/upstream-source.json")
+fi
+if [[ -n $previous ]]; then
+  git merge-base --is-ancestor "$previous" "$commit" || { echo 'Refusing upstream downgrade/divergent history.' >&2; exit 2; }
+  [[ -z $(git diff "$previous" HEAD -- . ':(exclude)synology') ]] || { echo 'Wrapper changed upstream files outside synology/.' >&2; exit 2; }
+else
+  # First adoption must already be based on the selected source tag.
+  git merge-base --is-ancestor "$commit" HEAD
+  [[ -z $(git diff "$commit" HEAD -- . ':(exclude)synology') ]] || { echo 'Initial fork must preserve upstream source.' >&2; exit 2; }
+fi
+git merge --no-ff --no-edit "$commit"
+[[ -z $(git diff "$commit" HEAD -- . ':(exclude)synology') ]] || { echo 'Upstream files differ after merge; resolve before building.' >&2; exit 2; }
+kind=$(node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(process.argv[1])).kind)' "$packaging/upstream-recipe.json")
+if [[ $kind == official-image ]]; then
+  node "$packaging/update-image.mjs" "$1"
+elif [[ $kind != native-source ]]; then
+  echo 'Unknown upstream recipe kind.' >&2; exit 2
+fi
+node "$packaging/version.mjs" "$1" "$2"
+node -e 'const fs=require("fs");fs.writeFileSync(process.argv[1],JSON.stringify({tag:process.argv[2],commit:process.argv[3],build:Number(process.argv[4])},null,2)+"\n")' "$packaging/upstream-source.json" "$1" "$commit" "$2"
+export SPL_UPSTREAM_SOURCE="$repo"
+export SPL_UPSTREAM_TAG="$1"
+export SPL_UPSTREAM_COMMIT="$commit"
+cd "$packaging"
+if [[ $kind == native-source ]]; then bash ./build-source.sh; fi
+synopkgland check --json
+synopkgland build --json
+# Review version/provenance and commit synology/ before the next upgrade.

package/assets/init-upstream/version.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Stable tag -> DSM version. Keep all wrapper-owned changes under synology/.
+import {readFileSync, writeFileSync} from 'node:fs';
+const [tag, build, mode] = process.argv.slice(2);
+const match = /^v?((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/.exec(tag ?? '');
+const file = new URL('./dsm-package.yaml', import.meta.url);
+const source = readFileSync(file, 'utf8');
+const current = /^build: (\d+)\s*$/m.exec(source);
+if (!match || !/^[1-9][0-9]{0,3}$/.test(build ?? '') || !current || Number(build) <= Number(current[1]))
+  throw new Error('Use a stable [v]X.Y.Z tag and an increasing packaging build (1–9999).');
+if (!/^version: .+$/m.test(source)) throw new Error('Missing scaffold version.');
+if (mode !== '--validate') writeFileSync(file, source.replace(/^version: .+$/m, `version: ${match[1]}`).replace(/^build: \d+\s*$/m, `build: ${Number(build)}`));

package/dist/cli.js

@@ -421,6 +421,10 @@ export async function runCli(argv) {
         .option("-t, --template <name>", `Template: ${listTemplates().join(" | ")}`)
         .option("--package <id>", "INFO.package (defaults to the directory name)")
         .option("--name <display>", "Display name")
+        .option("--upstream-image <repository>", "compose fork: official image repository; upgrade pins its matching tag and index digest")
+        .option("--upstream-fork", "Create only synology/ inside an upstream source fork (compose or native-go)")
+        .option("--health-path <path>", "compose: actual readiness endpoint; redirects are not followed")
+        .option("--health-status <status>", "compose: expected 2xx readiness status (no default)", Number)
         .option("--ui <vue|plain>", `Native UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} by default (vue); plain uses ui/app.js`)
         .option("--with <caps>", `Capabilities (comma-separated): ${CAPABILITY_NAMES.join(",")}`)
         .option("--from <compose.yaml>", "compose: import an existing Compose; omit to create an example")
@@ -430,7 +434,7 @@ export async function runCli(argv) {
         .option("--shared-folder-permission <ro|rw>", "Package account permission, defaults to rw")
         .option("--min-dsm <version>", `Minimum DSM version (native templates and binary default to ${DEFAULT_MIN_DSM}, compose to ${CONTAINER_MIN_DSM})`)
         .argument("[dir]", "Target directory", ".")
-        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses synology-app.yaml; --from imports compose.yaml.\nQuick start: synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
+        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses dsm-package.yaml schema 2; --from imports compose.yaml.\nQuick start: synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
         .action((dir, options, command) => {
         if (command.parent?.opts().project)
             throw failure("CLI_OPTION_INVALID", "--project does not apply to init.");
@@ -440,6 +444,10 @@ export async function runCli(argv) {
             throw failure("INIT_TEMPLATE_UNKNOWN", `Unknown template: ${options.template}`);
         const targetDir = resolve(dir);
         initFromTemplate(options.template, targetDir, {
+            upstreamFork: options.upstreamFork,
+            upstreamImage: options.upstreamImage,
+            healthPath: options.healthPath,
+            healthStatus: options.healthStatus,
             packageId: options.package,
             displayName: options.name,
             minDsm: options.minDsm,
@@ -457,7 +465,13 @@ export async function runCli(argv) {
                     permission: options.sharedFolderPermission,
                 },
         });
-        stdout(`Created the ${options.template} project at ${targetDir}`);
+        stdout(`Created the ${options.template} project at ${options.upstreamFork ? join(targetDir, "synology") : targetDir}`);
+        if (options.template === "compose")
+            stdout("Select actual compose.web.health path/status before check/build. Redirects are not followed; check does not probe runtime health.");
+        if (options.upstreamFork) {
+            stdout("Read synology/AGENTS.md; configure the official image recipe or the native source hook, then run bash synology/upgrade.sh <upstream-tag> <build-number>.");
+            return;
+        }
         const next = initNextSteps(options.template, dir, existsSync(join(targetDir, "frontend", "package.json")), Boolean(process.env.SYNOPKGLAND_SDK_DIR));
         if (next)
             stdout(next);

package/dist/e2e/dsm.d.ts

@@ -105,7 +105,7 @@ type SessionPage = {
 /**
  * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
  * e2e secrets, so e2e masks them in its report and output, as a request's
- * Playwright call log carries them (t-0498). Returns how many were registered.
+ * Playwright call log carries them. Returns how many were registered.
  */
 export declare function registerDsmSecrets(page?: SessionPage, ledger?: SecretLedger): Promise<number>;
 /**
@@ -136,7 +136,7 @@ export declare function dsmSessionLive(page: Pick<SessionPage, "evaluate">): Pro
 /**
  * `app.open(path)`, once more after net::ERR_ABORTED: about one first
  * navigation in ten was aborted as DSM's desktop navigated on its own, and the
- * next one loaded (t-0499, t-0500). Any other failure, or a second abort, is
+ * next one loaded. Any other failure, or a second abort, is
  * thrown.
  */
 export declare function openPath(app: Pick<App, "open">, path: string): Promise<void>;

package/dist/e2e/dsm.js

@@ -135,7 +135,7 @@ export async function runWithTunnel(command, outer = process.env) {
 // ---- Secrets in output ----------------------------------------------------
 // e2e redacts only the secrets its config declares. A Playwright call log in a
 // run error lists a request's headers, DSM's session cookie among them, and e2e
-// writes it to the report and stdout (t-0498). A value runs to a quote, a
+// writes it to the report and stdout. A value runs to a quote, a
 // backslash or a line end, so a JSON string's escapes end it too.
 const mask = "***";
 // A Cookie or Set-Cookie header, and in it DSM's session (id, _SSID) and device (did) cookies.
@@ -324,7 +324,7 @@ async function e2eSecretLedger() {
 /**
  * Registers the signed-in session's cookies (id, did, _SSID) and SynoToken as
  * e2e secrets, so e2e masks them in its report and output, as a request's
- * Playwright call log carries them (t-0498). Returns how many were registered.
+ * Playwright call log carries them. Returns how many were registered.
  */
 export async function registerDsmSecrets(page = dsmPage(), ledger) {
     const target = ledger ?? await e2eSecretLedger();
@@ -410,7 +410,7 @@ function accountFile(user, env) {
 /**
  * `app.open(path)`, once more after net::ERR_ABORTED: about one first
  * navigation in ten was aborted as DSM's desktop navigated on its own, and the
- * next one loaded (t-0499, t-0500). Any other failure, or a second abort, is
+ * next one loaded. Any other failure, or a second abort, is
  * thrown.
  */
 export async function openPath(app, path) {

package/dist/error-registry.js

@@ -1,7 +1,11 @@
 import { COMPOSE_ERRORS } from "./standalone/compose-errors.js";
 export const ERROR_REGISTRY = {
     ...COMPOSE_ERRORS,
+    INIT_HEALTH_INVALID: { code: "INIT_HEALTH_INVALID", description: "The Compose readiness selection is invalid.", suggestion: "Supply both --health-path and --health-status with the actual endpoint and expected 2xx response; redirects are not followed." },
+    INIT_UPSTREAM_IMAGE_REQUIRED: { code: "INIT_UPSTREAM_IMAGE_REQUIRED", description: "The official upstream image repository was not selected.", suggestion: "Use init --upstream-fork --upstream-image <official-repository> for Compose." },
+    INIT_UPSTREAM_IMAGE_INVALID: { code: "INIT_UPSTREAM_IMAGE_INVALID", description: "The upstream image repository is invalid.", suggestion: "Supply the official repository without a tag or digest; upgrade.sh selects the matching release and resolves its digest." },
     CTL_TRUST_REQUIRED: { "code": "CTL_TRUST_REQUIRED", "description": "App description access requires approval.", "suggestion": "Run synopkgland ctl list with explicit host and approve the candidate batch." },
+    COMPOSE_HEALTH_REQUIRED: { code: "COMPOSE_HEALTH_REQUIRED", description: "Compose web readiness was not selected.", suggestion: "Set compose.web.health.path and expected 2xx status for the actual App; redirects are not followed." },
     CTL_UNSUPPORTED_BACKEND: { "code": "CTL_UNSUPPORTED_BACKEND", "description": "Automatic descriptions require a native SDK backend.", "suggestion": "Disable ctl for binary/Compose wrappers or implement the public contract separately." },
     CTL_DESCRIBE_REQUIRED: { "code": "CTL_DESCRIBE_REQUIRED", "description": "The Go backend has no build-only registry exporter.", "suggestion": "Update the native template and implement --describe using api.DescribeRoutes." },
     CTL_DESCRIBE_FAILED: { "code": "CTL_DESCRIBE_FAILED", "description": "The backend registry export failed.", "suggestion": "Check the backend --describe output and build diagnostics." },

package/dist/host/share-permission.d.ts

@@ -10,7 +10,7 @@
  * extra_values directly, and share permission can change after install.
  *
  * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
- * before changing the predicate: on the test NAS, `newadmin` has is_writable=false on
+ * before changing the predicate: on the test NAS, `fixtureadmin` has is_writable=false on
  * its own row for `pkgland-p0b` and still writes there, because the
  * `administrators` group row carries the grant. A user-row-only check rejects
  * the only configuration with live proof behind it.

package/dist/host/share-permission.js

@@ -10,7 +10,7 @@
  * extra_values directly, and share permission can change after install.
  *
  * The rows are SYNO.Core.Share.Permission v1 output verbatim. Read the tests
- * before changing the predicate: on the test NAS, `newadmin` has is_writable=false on
+ * before changing the predicate: on the test NAS, `fixtureadmin` has is_writable=false on
  * its own row for `pkgland-p0b` and still writes there, because the
  * `administrators` group row carries the grant. A user-row-only check rejects
  * the only configuration with live proof behind it.

package/dist/init-upstream.d.ts

@@ -0,0 +1,7 @@
+export interface ForkRecipeOptions {
+    upstreamImage?: string;
+    from?: string;
+}
+export declare function validateForkRecipe(template: 'compose' | 'native-go', options: ForkRecipeOptions): void;
+/** CLI-owned packaging recipe; upstream files and history stay untouched. */
+export declare function writeForkScaffold(packaging: string, template: 'compose' | 'native-go', options: ForkRecipeOptions): void;

package/dist/init-upstream.js

@@ -0,0 +1,64 @@
+import { cpSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+import { API_PERMISSIONS_FILE } from './standalone/api-permissions.js';
+import { parseImageReference } from './images/pin.js';
+export function validateForkRecipe(template, options) {
+    if (template === 'native-go' && options.upstreamImage)
+        throw new Error('[INIT_OPTIONS_UNSUPPORTED] Native forks stage official release binaries or use a source build hook; image options apply only to compose.');
+    if (template !== 'compose')
+        return;
+    if (!options.upstreamImage)
+        throw new Error('[INIT_UPSTREAM_IMAGE_REQUIRED] Compose forks use official images: supply --upstream-image <official-repository>.');
+    const parsed = parseImageReference(options.upstreamImage);
+    if (!parsed || parsed.explicitTag || parsed.digest || !/^[a-z0-9][a-z0-9._:/-]*$/.test(options.upstreamImage) || options.upstreamImage.includes('//'))
+        throw new Error('[INIT_UPSTREAM_IMAGE_INVALID] Supply the official image repository without a tag or digest; upgrade.sh selects the matching upstream release tag.');
+}
+/** CLI-owned packaging recipe; upstream files and history stay untouched. */
+export function writeForkScaffold(packaging, template, options) {
+    const official = template === 'compose';
+    const assets = fileURLToPath(new URL('../assets/init-upstream/', import.meta.url));
+    for (const file of ['upgrade.sh', 'version.mjs', official ? 'update-image.mjs' : 'build-source.sh'])
+        cpSync(join(assets, file), join(packaging, file));
+    const manifest = join(packaging, 'dsm-package.yaml');
+    const doc = parseDocument(readFileSync(manifest, 'utf8'));
+    const service = official ? (doc.toJS().compose.web?.service ?? 'web') : undefined;
+    const recipe = official
+        ? { kind: 'official-image', repository: options.upstreamImage, service, imageTag: 'tag' }
+        : { kind: 'native-source' };
+    writeFileSync(join(packaging, 'upstream-recipe.json'), JSON.stringify(recipe, null, 2) + '\n');
+    doc.set('entry', 'admin-only');
+    if (official) {
+        doc.setIn(['identity_gateway', 'access'], 'dsm-admins');
+        if (!options.from) {
+            const path = join(packaging, 'compose.yaml');
+            const base = parseDocument(readFileSync(path, 'utf8'));
+            base.deleteIn(['services', service, 'command']);
+            base.setIn(['services', service, 'image'], `${options.upstreamImage}:SELECT_UPSTREAM_TAG`);
+            writeFileSync(path, String(base));
+        }
+        doc.setIn(['compose', 'files'], [...doc.toJS().compose.files, 'compose.image.yaml']);
+        writeFileSync(join(packaging, 'compose.image.yaml'), JSON.stringify({ services: { [service]: { image: `${options.upstreamImage}:SELECT_UPSTREAM_TAG` } } }, null, 2) + '\n');
+    }
+    if (!official) {
+        const path = join(packaging, 'backend', API_PERMISSIONS_FILE.go);
+        const policy = JSON.parse(readFileSync(path, 'utf8'));
+        for (const method of Object.keys(policy.methods))
+            policy.methods[method] = 'administrators';
+        writeFileSync(path, JSON.stringify(policy, null, 2) + '\n');
+    }
+    writeFileSync(manifest, String(doc));
+    const guidance = `
+## Integrating an existing open-source App
+
+Keep the upstream fork/history and remote upstream. All wrapper-owned files belong in synology/; never edit upstream files or treat the App as an SDK component. Read synopkgland skill show upstream-fork.
+
+Commit the scaffold, then run bash synology/upgrade.sh <upstream-tag> <build-number>. It fetches the exact tag, verifies ancestry/untouched upstream files, merges, derives version/provenance, checks and builds. Commit synology/ before upgrading again. It does not publish or touch a NAS.
+
+${official ? 'Default: use the upstream official image. upgrade.sh updates its release tag and resolves an OCI index/manifest digest through synopkgland images pin, writing only synology/compose.image.yaml. Container Manager downloads that pinned official image at install. Configure upstream-recipe.json repository/service and imageTag: tag (exact upstream tag) or version (strip v only when upstream image naming requires it). Review multi-architecture support and upstream source/license correspondence. The SELECT_UPSTREAM_TAG placeholder must be replaced by a successful upgrade before check/build.' : 'Native App: implement build-source.sh as the native payload hook; it deliberately fails until implemented. Stage official release binaries pinned by SHA-256 (the OpenList route), or compile the merged source with a source build hook. Verify the release digest before staging architecture-specific daemon.targets; keep the SDK management shell separate.'}
+
+Use DSM administrator identity without an additional App password, an OIDC/SSO server or upstream source changes. Prefer supported trusted-header/proxy auth (FreshRSS), otherwise disable upstream login/enable guest behind the administrator-only gateway after a bounded first bootstrap (Uptime Kuma disableAuth). The third shipped pattern is the existing SDK 0.16.0 token adapter: mode: token, access: dsm-admins, entry: admin-only. OpenList obtains its native API token with the unmodified admin token CLI while stopped, stores it package-private 0600 under a 0700 directory, and the gateway injects Authorization server-side after DSM admission; packaging never delivers it to the browser. All DSM admins share one upstream admin; token reset requires package restart; WebDAV keeps its own native credentials. The upstream admin token/settings APIs remain unchanged. Verify actual DSM admission/revocation separately. Use supported config, environment, argv or proxy adapters. Every App lifecycle phase runs as the package UID. For upstream fixed-UID data directories, currently provide a synology/ startup adapter or writable path without root/chown; replace it with the framework ownership mechanism when available. Preserve licenses and the full source/component inventory.
+`;
+    writeFileSync(join(packaging, 'AGENTS.md'), readFileSync(join(packaging, 'AGENTS.md'), 'utf8') + guidance);
+}

package/dist/init.d.ts

@@ -16,6 +16,10 @@ export interface InitOptions {
     ui?: "plain" | "vue";
     with?: string[];
     from?: string;
+    upstreamFork?: boolean;
+    upstreamImage?: string;
+    healthPath?: string;
+    healthStatus?: number;
     /** native-go: `install.sharedFolder` (select from the NAS, or create one). key defaults to "shared", permission to "rw". */
     sharedFolder?: {
         mode: "select" | "create";

package/dist/init.js

@@ -1,3 +1,4 @@
+import { validateForkRecipe, writeForkScaffold } from "./init-upstream.js";
 import { goChildEnv } from "./runtime/go-env.js";
 import { spawnSync } from "node:child_process";
 import { parse, parseDocument } from "yaml";
@@ -112,6 +113,30 @@ function isTemplateBuildArtifact(path) {
     return (name === "node_modules" || name === "dist" || name === ".go-results.json");
 }
 export function initFromTemplate(template, targetDir, options = {}) {
+    if (options.upstreamFork) {
+        if (template !== "compose" && template !== "native-go")
+            throw new Error("[INIT_OPTIONS_UNSUPPORTED] --upstream-fork supports compose or native-go.");
+        validateForkRecipe(template, options);
+        const packaging = join(targetDir, "synology");
+        if (existsSync(packaging))
+            throw new Error("[INIT_TARGET_NOT_EMPTY] synology/ already exists.");
+        initFromTemplate(template, packaging, {
+            ...options,
+            packageId: options.packageId ?? defaultPackageId(targetDir),
+            displayName: options.displayName ?? defaultDisplayName(targetDir),
+            upstreamFork: false,
+            upstreamImage: undefined,
+        });
+        writeForkScaffold(packaging, template, options);
+        return;
+    }
+    if (options.upstreamImage)
+        throw new Error("[INIT_OPTIONS_UNSUPPORTED] Image recipe options require --upstream-fork.");
+    const hasHealth = options.healthPath !== undefined || options.healthStatus !== undefined;
+    if (hasHealth && (template !== "compose" || typeof options.healthPath !== "string" ||
+        !/^\/(?!\/)[^\s#\\]*$/.test(options.healthPath) || !Number.isInteger(options.healthStatus) ||
+        options.healthStatus < 200 || options.healthStatus > 299))
+        throw new Error("[INIT_HEALTH_INVALID] Compose health needs both --health-path /actual-endpoint and --health-status 2xx; redirects are not followed.");
     if (!isTemplateName(template))
         throw new Error(`[INIT_TEMPLATE_UNKNOWN] Unknown template: ${template}`);
     const requested = capabilityNames(options.with ?? []);
@@ -261,6 +286,18 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     if (template === "compose" && options.from)
         importCompose(options.from, targetDir);
+    if (template === "compose") {
+        const path = join(targetDir, "dsm-package.yaml");
+        const doc = parseDocument(readFileSync(path, "utf8"));
+        if (doc.hasIn(["compose", "web"])) {
+            doc.deleteIn(["compose", "web", "health"]);
+            if (hasHealth)
+                doc.setIn(["compose", "web", "health"], { path: options.healthPath, status: options.healthStatus });
+        }
+        writeFileSync(path, String(doc));
+        const guidance = readFileSync(new URL("../assets/init-compose.md", import.meta.url), "utf8");
+        writeFileSync(join(targetDir, "AGENTS.md"), guidance);
+    }
     if (template === "binary") {
         mkdirSync(join(targetDir, "prebuilt"), { recursive: true });
         for (const [arch, goarch] of [
@@ -356,7 +393,6 @@ function importCompose(from, targetDir) {
     if (candidates.length === 1)
         doc.setIn(["compose", "web"], {
             ...candidates[0],
-            health: { path: "/", status: 200 },
         });
     else {
         doc.deleteIn(["compose", "web"]);

package/dist/runtime/dsm-version.d.ts

@@ -1,6 +1,6 @@
 /** Self-contained: the same function is embedded in the DSM window. True only
  * when DSM refused a request because this method version is unavailable, the
- * one refusal that may be retried with an older version. DSM 7.1.1 (t-0234)
+ * one refusal that may be retried with an older version. DSM 7.1.1
  * returns 104 for a version above maxVersion and 103 for a method absent at an
  * existing version. Accepts the numeric code and the window's dsm_ form. */
 export declare function versionUnsupported(code: unknown): boolean;

package/dist/runtime/dsm-version.js

@@ -1,6 +1,6 @@
 /** Self-contained: the same function is embedded in the DSM window. True only
  * when DSM refused a request because this method version is unavailable, the
- * one refusal that may be retried with an older version. DSM 7.1.1 (t-0234)
+ * one refusal that may be retried with an older version. DSM 7.1.1
  * returns 104 for a version above maxVersion and 103 for a method absent at an
  * existing version. Accepts the numeric code and the window's dsm_ form. */
 export function versionUnsupported(code) {

package/dist/runtime/executor-digests.json

@@ -1,27 +1,5 @@
 {
-    "0.15.0": {
-        "x86_64": "efe409287770f6b70e7f8465e8767eeb2413b9ab8775020cf4dffb1555d7bf1f",
-        "aarch64": "d68c9889ed2391e918b9c278679ea0a01cd04425528c11090700a3b6341fc543",
-        "armv7": "9149a05efb9f2d7d86a400707099b3d657382b1c0dbad6588be8c500e90445cc",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.15.1": {
-        "x86_64": "4f47fb43f6e60dbad064afb0bbec96dd009fa046670e2c4b590b128a855cb404",
-        "aarch64": "c903b09ad657a838f0c62b6688e65e9094572b22b969770fca92fcc3640a5364",
-        "armv7": "8178d90de7ea720530bb9496e50ed118086b0e57382d84675aadc68f482d219f",
-        "lifecycle": {
-            "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
-            "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",
-            "armv7": "cafc97c89f5645c14a8cf31d6d9f258394ed6f2d086478a7aebd04d57c274b4e"
-        },
-        "goToolchain": "go1.26.9"
-    },
-    "0.15.2": {
+    "0.16.0": {
         "x86_64": "4f47fb43f6e60dbad064afb0bbec96dd009fa046670e2c4b590b128a855cb404",
         "aarch64": "c903b09ad657a838f0c62b6688e65e9094572b22b969770fca92fcc3640a5364",
         "armv7": "8178d90de7ea720530bb9496e50ed118086b0e57382d84675aadc68f482d219f",

package/dist/skill.js

@@ -14,6 +14,7 @@ const SKILL_CATALOG = [
         file: "reference/compose.md",
         when: "Upstream Compose with the SDK planner, fixed identity and support boundary",
     },
+    { id: "upstream-fork", file: "reference/upstream-fork.md", when: "Package an upstream source fork without changing upstream files" },
     {
         id: "wrap",
         file: "reference/wrap.md",

package/dist/standalone/build.js

@@ -10,7 +10,7 @@ import { resolveMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM,
 import { checkCgiBinary } from "./binary.js";
 import { loadStandaloneManifest, } from "./manifest.js";
 import { assembleStandaloneSpk, StandaloneBuildError } from "./spk.js";
-import { buildComposeControl, lockComposeImages, dsmComposeProblem, } from "./compose.js";
+import { buildComposeControl, buildComposeStorageInit, lockComposeImages, dsmComposeProblem, } from "./compose.js";
 import { buildDaemonControl } from "./daemon.js";
 import { buildIdentityGateway } from "./identity-gateway.js";
 import { buildExecutor } from "../runtime/executor-build.js";
@@ -148,6 +148,7 @@ export async function buildStandalone(options) {
             const daemonControl = await buildDaemonControl(manifest, arch, archWork, run);
             const identityGateway = await buildIdentityGateway(manifest, arch, archWork, run);
             const composeControl = await buildComposeControl(manifest, arch, archWork, run);
+            const composeStorageInit = await buildComposeStorageInit(manifest, arch, archWork, run);
             // A portal needs the executor, so the executor's SDK carries the panel text.
             const portalText = manifest.portal && executor
                 ? portalCatalogs(sdkSource(executor.sdk).goDir)
@@ -160,6 +161,7 @@ export async function buildStandalone(options) {
                 daemonControl,
                 identityGateway,
                 composeControl,
+                composeStorageInit,
                 backgroundWorker,
                 executor,
                 app,

package/dist/standalone/compose-errors.js

@@ -1,5 +1,20 @@
 /** SDK planner errors accepted at this versioned tool boundary. */
 export const COMPOSE_ERRORS = {
+    COMPOSE_STORAGE_INIT_INVALID: {
+        code: "COMPOSE_STORAGE_INIT_INVALID",
+        description: "The container storage initialization declaration is invalid.",
+        suggestion: "Declare private subdirectories on writable mounts and explicit upstream entrypoint/command argv; keep the service nonroot. The SDK initializer is supplied by the SPK.",
+    },
+    COMPOSE_STORAGE_NOT_WRITABLE: {
+        code: "COMPOSE_STORAGE_NOT_WRITABLE",
+        description: "The package UID cannot initialize or write its private container data.",
+        suggestion: "Use a writable mount base with a package-owned private subtree; inspect ownership, permissions, read-only storage, quota and free space. Do not add root or chown hooks.",
+    },
+    COMPOSE_STORAGE_COMMAND_INVALID: {
+        code: "COMPOSE_STORAGE_COMMAND_INVALID",
+        description: "The application command after storage preflight cannot be executed.",
+        suggestion: "Declare the actual upstream executable and arguments. Keep the upstream official image unchanged; the SPK supplies the SDK initializer.",
+    },
     COMPOSE_SUBNET_STATE_INVALID: {
         code: "COMPOSE_SUBNET_STATE_INVALID",
         description: "The private ingress history is invalid or has foreign ownership.",