@synopackageland/cli 0.19.0 → 0.19.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.19.1 (2026-10-20)
+
+- Record SDK 0.19.1 executor and lifecycle digests for the executor fix that accepts `deadline_ms` on delegated `webapi.call`; SDK 0.19.0 digests remain. Executor Apps rebuilt with SDK 0.19.1 require one administrator reapproval after upgrading.
+- Compare upgrade approval requirements with a baseline SPK: `build --baseline` and `inspect --baseline` report root program digests, policy differences, task template changes and executor-only handoff eligibility.
+- Retain templates 0.19.0 (SDK 0.19.0) and UI 0.12.5.
+
 ## 0.19.0 (2026-10-20)
 
 - Align the CLI SDK minor line and templates at 0.19.0; retain UI 0.12.5.

package/README.md

@@ -119,6 +119,19 @@ window's approval waits for it, while a status read answers `executor_starting`
 SDK's panels check again on their own. The program cannot declare `run` or `job`, and
 declaring it changes the policy digest, so an administrator approves the App again.
 
+Before releasing an executor App, compare it with the previous released SPK of
+that package and architecture. Include the resulting summary in release notes:
+
+```sh
+synopkgland build --arch x86_64 --baseline previous.spk --json
+synopkgland inspect current.spk --baseline previous.spk
+```
+
+The summary covers root program digests, permission/parameter differences, task
+template changes and executor-only handover eligibility. Without a comparable
+baseline, approval retention is unknown. Eligibility still requires live protected
+runtime and exact DSM task readback. See [the approval guide](skills/reference/approval-upgrades.md).
+
 ## Commands
 
 | Command | Purpose |

package/dist/cli.js

@@ -33,6 +33,7 @@ import { buildNativeLayout, isNativeLayout, loadNativeLayout, LAYOUT_ARCHES, } f
 import { buildStandalone, runnerFor } from "./standalone/build.js";
 import { checkJobs, commitOutputs, forEachArch, } from "./standalone/arch-jobs.js";
 import { checkReproducible } from "./reproducible.js";
+import { spkApprovalDiff, formatApprovalDiff } from "./runtime/approval-diff.js";
 import { inspectAnySpk } from "./spk/inspect.js";
 function failure(code, message, hint = "Fix the configuration and retry; use --help to see command usage.") {
     return Object.assign(new Error(codedMessage(code, message)), { code, hint });
@@ -389,16 +390,18 @@ export async function runCli(argv) {
     });
     program
         .command("inspect <spk>")
+        .option("--baseline <spk>", "Compare approval requirements with the previous SPK")
         .description("Inspect any SPK against the DSM 7 package format without installing; for a synopkgland-built SPK also check the build contract and root privilege requirements")
         .option("--json", "Print a single JSON object")
-        .action(async (input) => {
+        .action(async (input, options) => {
         const spk = resolve(input);
         if (existsSync(spk) && statSync(spk).isDirectory())
             throw failure("SPK_INSPECTION_FAILED", `${spk} is a directory; inspect checks .spk files.`, "Use synopkgland check to inspect project settings.");
         const report = await inspectAnySpk(spk);
         if (!report.dsm.ok || report.findings.length)
             throw Object.assign(failure("SPK_INSPECTION_FAILED", formatSpkChecks(report).join("\n"), "Fix the SPK by error code and repackage; see reference/errors for the codes; do not install an SPK that fails inspection."), { report: { spk, ...report } });
-        emit("inspect", { spk, ...report }, formatSpkReport(spk, report));
+        const approval = await spkApprovalDiff(spk, options.baseline && resolve(options.baseline), report);
+        emit("inspect", { spk, ...report, approval }, formatSpkReport(spk, report) + "\n" + formatApprovalDiff(approval));
     });
     const images = program.command("images").description("Container image tools");
     images
@@ -624,6 +627,7 @@ export async function runCli(argv) {
     skill.command("show <id>").action((id) => stdout(readSkill(id)));
     program
         .command("build")
+        .option("--baseline <spk>", "Compare approval requirements with the previous SPK (one matching architecture)")
         .description("Build an SPK from synology-app.yaml or dsm-package.yaml")
         .option("--json", "Print a single JSON object")
         .option("-o, --output <path>", "Output SPK; use with a single --arch")
@@ -684,13 +688,15 @@ export async function runCli(argv) {
                         outDir: undefined,
                     }),
             });
+        const approval = await Promise.all(outputs.map(async (output) => ({ output, ...await spkApprovalDiff(output, options.baseline && resolve(options.baseline)) })));
         const lines = [
+            ...approval.map(item => item.output + "\n" + formatApprovalDiff(item)),
             ...outputs.map((output) => `Built ${output}`),
             ...(reproducible ? reproducibleLines(reproducible) : []),
         ];
         if (reproducible && !reproducible.identical)
             throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "Find the payload files that differ between builds (timestamps, random paths, unpinned dependencies) and retry after fixing them."), { report: { outputs, reproducible } });
-        emit("build", { outputs, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
+        emit("build", { outputs, approval, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
     });
     if (json)
         console.log = (...args) => console.error(...args);

package/dist/error-registry.js

@@ -11,6 +11,7 @@ export const ERROR_REGISTRY = {
     CTL_DESCRIBE_FAILED: { "code": "CTL_DESCRIBE_FAILED", "description": "The backend registry export failed.", "suggestion": "Check the backend --describe output and build diagnostics." },
     CTL_COMMAND_UNREGISTERED: { "code": "CTL_COMMAND_UNREGISTERED", "description": "A command references an unregistered backend method.", "suggestion": "Correct ctl.commands bindings or register the backend method." },
     CTL_DESCRIPTOR_INVALID: { "code": "CTL_DESCRIPTOR_INVALID", "description": "The generated API description violates the public contract.", "suggestion": "Correct ctl.commands and rebuild the private synopkgland-api.json." },
+    APPROVAL_BASELINE_INVALID: { code: "APPROVAL_BASELINE_INVALID", description: "The --baseline SPK failed inspection, so approval retention cannot be compared.", suggestion: "Pass the previous released SPK of the same package and architecture, unmodified; inspect it to see each finding." },
     CTL_DECLARATION_INVALID: { "code": "CTL_DECLARATION_INVALID", "description": "The ctl declaration is invalid.", "suggestion": "Check ctl.enabled, aliases and explicit commands in dsm-package.yaml." },
     ...{
         LAUNCHER_PORTAL_MISMATCH: {

package/dist/runtime/approval-diff.d.ts

@@ -0,0 +1,37 @@
+import type { ExecutorPolicy } from './executor-policy.js';
+import { type SpkReport } from '../spk/inspect.js';
+export interface ApprovalInventory {
+    package: string;
+    arch: string;
+    executorDigest: string;
+    policyDigest: string;
+    anchored: boolean;
+    policy: ExecutorPolicy;
+    tasks: Array<{
+        kind: string;
+        name: string;
+        script: string;
+    }>;
+}
+export interface ApprovalDifference {
+    retention: 'unknown' | 'eligible' | 'required';
+    permissions: 'unknown' | 'unchanged' | 'expanded' | 'review-required';
+    executor_only: boolean;
+    task_template_changed: boolean | null;
+    old_policy_digest?: string;
+    new_policy_digest?: string;
+    root_programs: Array<{
+        name: string;
+        old: string | null;
+        new: string | null;
+    }>;
+    policy_changes: Array<{
+        path: string;
+        old: unknown;
+        new: unknown;
+    }>;
+    reason: string;
+}
+export declare function approvalDiff(old: ApprovalInventory | undefined, next: ApprovalInventory | undefined): ApprovalDifference;
+export declare function spkApprovalDiff(current: string, baseline?: string, report?: SpkReport): Promise<ApprovalDifference>;
+export declare function formatApprovalDiff(d: ApprovalDifference): string;

package/dist/runtime/approval-diff.js

@@ -0,0 +1,56 @@
+import { inspectAnySpk } from '../spk/inspect.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => JSON.stringify(k) + ':' + canonical(v)).join(',') + '}';
+    return JSON.stringify(value) ?? 'null';
+}
+function authority(policy) {
+    const p = structuredClone(policy);
+    p.root = Object.fromEntries(Object.entries(policy.root).map(([name, entry]) => [name, typeof entry === 'string' ? {} : Object.fromEntries(Object.entries(entry).filter(([key]) => key !== 'digest'))]));
+    return p;
+}
+function changes(a, b, path = '', out = []) {
+    if (canonical(a) === canonical(b))
+        return out;
+    if (a && b && typeof a === 'object' && typeof b === 'object' && !Array.isArray(a) && !Array.isArray(b)) {
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort())
+            changes(a[key], b[key], path + '/' + key.replaceAll('~', '~0').replaceAll('/', '~1'), out);
+    }
+    else
+        out.push({ path, old: a ?? null, new: b ?? null });
+    return out;
+}
+const rootDigests = (p) => Object.fromEntries(Object.entries(p.root).map(([name, e]) => [name, typeof e === 'string' ? e : e.digest]));
+export function approvalDiff(old, next) {
+    const unknown = { retention: 'unknown', permissions: 'unknown', executor_only: false, task_template_changed: null, root_programs: [], policy_changes: [], reason: 'Cannot determine whether approval can be retained: a valid, matching baseline SPK and executor inventory are required.' };
+    if (!old || !next || old.package !== next.package || old.arch !== next.arch)
+        return unknown;
+    const a = rootDigests(old.policy), b = rootDigests(next.policy);
+    const root_programs = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort().filter(name => a[name] !== b[name]).map(name => ({ name, old: a[name] ?? null, new: b[name] ?? null }));
+    const policy_changes = changes(authority(old.policy), authority(next.policy));
+    const expanded = next.policy.operations.some(op => !old.policy.operations.includes(op)) || Object.keys(next.policy.root).some(name => !(name in old.policy.root));
+    const templates = (i) => i.tasks.map(t => ({ kind: t.kind, name: t.name, script: t.script.replaceAll(i.policyDigest, '@POLICY_DIGEST@') })).sort((a, b) => a.kind < b.kind ? -1 : 1);
+    const task_template_changed = canonical(templates(old)) !== canonical(templates(next));
+    const eligible = old.policyDigest === next.policyDigest && !task_template_changed && (old.executorDigest === next.executorDigest || next.anchored);
+    return { retention: eligible ? 'eligible' : 'required', permissions: expanded ? 'expanded' : policy_changes.length ? 'review-required' : 'unchanged', executor_only: eligible && old.executorDigest !== next.executorDigest, task_template_changed, old_policy_digest: old.policyDigest, new_policy_digest: next.policyDigest, root_programs, policy_changes, reason: eligible ? 'Approval can be retained if the installed protected runtime and exact DSM task readback still match this baseline.' : 'Administrator reapproval is required for the changed payload, policy, executor anchor or task definitions.' };
+}
+function inventory(r) {
+    if (!r.dsm.ok || r.findings.length || !r.executor || !r.package || !r.arch)
+        return;
+    return { package: r.package, arch: r.arch, ...r.executor, anchored: true }; // inspect verifies the INFO anchor and every root payload digest.
+}
+export async function spkApprovalDiff(current, baseline, report) {
+    if (!baseline)
+        return approvalDiff(undefined, undefined);
+    const next = inventory(report ?? await inspectAnySpk(current));
+    const old = await inspectAnySpk(baseline);
+    if (!old.dsm.ok || old.findings.length)
+        throw new Error('[APPROVAL_BASELINE_INVALID] Baseline SPK failed inspection: ' + [...old.findings, ...old.dsm.errors.map(e => e.message)].join('; '));
+    return approvalDiff(inventory(old), next);
+}
+export function formatApprovalDiff(d) {
+    const short = (s) => s?.slice(0, 12) ?? '—';
+    return ['Approval: ' + d.reason, 'Permissions: ' + d.permissions, ...d.root_programs.map(p => `Root program ${p.name}: ${short(p.old)} → ${short(p.new)}`), ...d.policy_changes.map(c => `Policy ${c.path}: ${JSON.stringify(c.old)} → ${JSON.stringify(c.new)}`), `Task template: ${d.task_template_changed === null ? 'unknown' : d.task_template_changed ? 'changed' : 'unchanged'}`, `Executor-only handover: ${d.executor_only ? 'eligible under the INFO anchor' : 'not established'}`].join('\n');
+}

package/dist/runtime/executor-digests.json

@@ -9,5 +9,16 @@
             "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
         },
         "goToolchain": "go1.26.9"
+    },
+    "0.19.1": {
+        "x86_64": "e27cfeb85fed221b06f9c58166f02c0f701a724308cd17c96a43a843a0b5c4aa",
+        "aarch64": "908db00cbd37d072f6ffc339e7bca24da5efb8cddd4befcbad02c7398beb7191",
+        "armv7": "a0f35d62ec80a1bf3fb49f5e2d1a5f7576eda569a6fd0695084cec6cb8e100bc",
+        "lifecycle": {
+            "x86_64": "9bb53301670b43cdcd6e21cebac99ab7abd82962d874f32423a81e6cb49d4972",
+            "aarch64": "38fe873c86eb102c850baa1f304114a83a31d1df72defd22792bc37610fec9bb",
+            "armv7": "256fb348b275da7ac5728a3cb7cb7c65660de0d5c2c59430ab4f5ade1b0a3681"
+        },
+        "goToolchain": "go1.26.9"
     }
 }

package/dist/standalone/root-window.js

@@ -359,9 +359,14 @@ export const ROOT_RUNTIME = `function createRootAccess(options) {
   // here, and that first status serves the health check. Approval and
   // control read back on their own.
   function checked(status) { return pinned(status) && !!status.tasks && status.tasks.state === "ready"; }
+  function approvalExplanation(verified, status) {
+    var diff = status && status.approval;
+    if (verified.state === "needs-admin-approval" && diff && options.pins && diff.package === options.pins.package && diff.new_policy_digest === options.pins.policyDigest && diff.new_executor_digest === options.pins.executorDigest && (diff.old_policy_digest !== diff.new_policy_digest || diff.task_template_changed)) verified.approval = diff;
+    return verified;
+  }
   function adminStatus() {
     var asked = options.call("executor.status", {});
-    function verify() { return read().then(function (verified) { return health(verified, 0, asked); }); }
+    function verify() { return read().then(function (verified) { return health(verified, 0, asked); }).then(function (verified) { return asked.then(function (status) { return approvalExplanation(verified, status); }, function () { return verified; }); }); }
     return asked.then(function (status) {
       return checked(status) ? {state: "ready", tasks: {boot: {state: "ready"}, control: {state: "ready"}}, executor: status} : verify();
     }, verify);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -5,6 +5,8 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
+Before releasing an executor App, read [reference/approval-upgrades.md](reference/approval-upgrades.md). Run build/inspect with the previous released SPK as `--baseline` and include the approval difference in release notes. Without a comparable baseline, retention is unknown.
+
 Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
 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.

package/skills/reference/approval-upgrades.md

@@ -0,0 +1,36 @@
+# Approval changes before release
+
+Run the current CLI against the previous released SPK for the same package and
+architecture before releasing an executor App:
+
+```sh
+synopkgland build --arch x86_64 --baseline previous-x86_64.spk --json
+synopkgland inspect current-x86_64.spk --baseline previous-x86_64.spk
+synopkgland inspect current-x86_64.spk --baseline previous-x86_64.spk --json
+```
+
+`inspect` returns `data.approval`; `build` returns one entry per output in
+`data.approval`. Put the human summary in release notes. Optionally copy that
+same summary into the manifest's `metadata.changelog`, which the existing build writes to INFO for Package Center.
+Do not assume DSM automatically opens an App after upgrading it.
+
+The summary names root programs and their old/new SHA-256 prefixes, policy
+permission/parameter paths, and task template changes. Task template comparison
+removes only the policy pin; a policy pin change still requires approval.
+`unchanged` means the policy excluding root digests is identical. Added root
+programs or operations are `expanded`; other permission/parameter changes are
+`review-required`, because arbitrary schema and scope changes cannot generally
+be proven to narrow permissions. Program bytes can change behavior even when
+the declared policy is unchanged.
+
+`eligible` is conditional: the live protected runtime must still match the
+baseline and DSM must read back the exact approved tasks. An executor-only
+handover additionally needs the new executor's valid INFO anchor. This offline
+summary does not grant approval. With no baseline, an incompatible package or
+architecture, or no executor inventory, retention is `unknown`; never promise
+that approval will be retained. Invalid baselines fail inspection.
+
+The SDK approval screen reads root-produced diagnostics through executor.status,
+then uses the existing PasswordConfirm and exact task readback. Older protected
+runtimes without diagnostic support show an explicit unknown explanation. No App
+option supplies an approved baseline or permission claim.