@synopackageland/cli 0.8.0 → 0.9.1

package/dist/init.js

@@ -3,8 +3,10 @@ import { isMap, isScalar, parse, parseDocument, stringify } from "yaml";
 import { capabilityNames, capabilitySettings } from "./capabilities.js";
 import { MOVE_FROM_STAGING } from './runtime/delegate-contract.js';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { basename, join, relative } from "node:path";
+import { basename, join, relative, resolve } from "node:path";
+import { SDK_MODULE, SDK_PACKAGE } from "./runtime/sdk-source.js";
 import { templatesRoot } from "./template-paths.js";
+import { borrowedTarget, capabilityOverlays } from "./capability-overlays.js";
 import { resolveMinDsm, assertContainerMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast } from "./build-spk/dsm-version.js";
 import { readSharedFolder } from "./standalone/shared-folder.js";
 const TEMPLATE_NAMES = [
@@ -35,20 +37,8 @@ export function nativeCapabilitySettings(names) {
         };
     return settings;
 }
-/**
- * native-go --with root-ops: files laid over the native-go template, and the
- * files they replace.
- */
-const ROOT_OVERLAY = "native-go-root-ops";
-const ROOT_REPLACED = ["backend/internal/app/root_none.go"];
-/** native-go --with jobs: overlay with the routes, the UI panel and the docs. */
-const BACKGROUND_OVERLAY = "native-go-jobs";
-const BACKGROUND_REPLACED = ["backend/internal/app/background_none.go"];
-/** Templates whose identity is filled in at init (placeholders in these files). */
-const SUBSTITUTED = {
-    "native-go": ["dsm-package.yaml", "README.md"],
-    "binary": ["dsm-package.yaml", "ui/app.js"],
-};
+/** Templates whose identity is filled in at init: every generated file may carry a placeholder. */
+const IDENTIFIED = ["native-go", "binary"];
 const PACKAGE_ID = /^[A-Za-z][A-Za-z0-9]{1,63}$/;
 /** npm never publishes files named .gitignore, so templates ship them as `gitignore`. */
 const RENAMED = { gitignore: ".gitignore" };
@@ -105,8 +95,9 @@ export function initFromTemplate(template, targetDir, options = {}) {
         throw new Error("[INIT_OPTIONS_UNSUPPORTED] --from 只適用於 compose。");
     if (caps.length && template !== "native-go")
         throw new Error("[CAPABILITY_UNSUPPORTED] binary／compose 不支援 --with 能力。");
-    const background = caps.includes("jobs") || caps.includes("delegate");
-    const executor = caps.includes("root-ops") || caps.includes("delegate");
+    const localSdk = template === "native-go" && process.env.SYNOPKGLAND_SDK_DIR ? resolve(process.env.SYNOPKGLAND_SDK_DIR) : undefined;
+    if (localSdk)
+        assertLocalSdkReady(localSdk, resolvedUi(template, options) === "vue");
     const source = join(templatesRoot(), template);
     if (!existsSync(source)) {
         throw new Error(`找不到模板：${template}`);
@@ -121,20 +112,14 @@ export function initFromTemplate(template, targetDir, options = {}) {
     if (rootExample && minDsm !== undefined && !isDsmAtLeast(minDsm, DEFAULT_MIN_DSM)) {
         throw new Error(`[MIN_DSM_INVALID] root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
     }
-    const overlays = [
-        ...(rootExample ? [ROOT_OVERLAY] : []),
-        ...(ui === "vue" ? ["native-go-vue"] : []),
-        ...(background ? [BACKGROUND_OVERLAY] : []),
-        ...(caps.includes("login") && existsSync(join(templatesRoot(), "native-go-identity")) ? ["native-go-identity"] : []),
-        ...(caps.includes("files") && existsSync(join(templatesRoot(), "native-go-files")) ? ["native-go-files"] : []),
-        ...(caps.includes("delegate") ? ["native-go-delegate"] : []),
-    ].map(name => join(templatesRoot(), name));
+    const capability = capabilityOverlays(caps);
+    const overlays = [...(ui === "vue" ? ["native-go-vue"] : []), ...capability.overlays].map(name => join(templatesRoot(), name));
     // Shared legal resources also live in the CLI package; only the template
     // terms are an unconditional part of a generated project.
     const shared = join(templatesRoot(), "_shared");
     const sharedFiles = ["LICENSES/TEMPLATE.txt", "AGENTS.md", "CLAUDE.md"];
     const files = [...templateFiles(source), ...sharedFiles, ...overlays.flatMap(root => templateFiles(root)),
-        ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : [])];
+        ...capability.borrowed.map(borrowedTarget), ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : [])];
     const collisions = files.map(targetName).filter((file) => existsSync(join(targetDir, file)));
     if (collisions.length > 0) {
         throw new Error(`[INIT_TARGET_NOT_EMPTY] ${targetDir} 已有 ${collisions.join(", ")}；init 不會覆蓋既有檔案。請改用空目錄。`);
@@ -149,35 +134,25 @@ export function initFromTemplate(template, targetDir, options = {}) {
     for (const dir of (ui === "vue" ? ["frontend"] : [])) {
         cpSync(join(shared, "third-party-notices.mjs"), join(targetDir, dir, "third-party-notices.mjs"));
     }
-    if (rootExample)
-        ROOT_REPLACED.forEach(file => rmSync(join(targetDir, file)));
-    if (caps.includes("delegate") && !rootExample) {
-        cpSync(join(templatesRoot(), ROOT_OVERLAY, "backend/internal/app/executor.go"), join(targetDir, "backend/internal/app/executor.go"));
-        cpSync(join(templatesRoot(), ROOT_OVERLAY, "backend/internal/app/executor_test.go"), join(targetDir, "backend/internal/app/executor_test.go"));
-        ROOT_REPLACED.forEach(file => rmSync(join(targetDir, file), { force: true }));
-    }
+    for (const path of capability.borrowed)
+        cpSync(join(templatesRoot(), path), join(targetDir, borrowedTarget(path)));
+    for (const file of capability.removed)
+        rmSync(join(targetDir, file));
     if (caps.includes("delegate")) {
-        rmSync(join(targetDir, "backend/internal/app/delegate_none.go"));
         const path = join(targetDir, "backend/internal/api/permissions.json");
         const policy = JSON.parse(readFileSync(path, "utf8"));
         policy.methods["app.status"] = "authenticated";
         writeFileSync(path, JSON.stringify(policy, null, 2) + "\n");
     }
-    if (background)
-        BACKGROUND_REPLACED.forEach(file => rmSync(join(targetDir, file)));
     for (const [from, to] of Object.entries(RENAMED)) {
         if (files.includes(from)) {
             renameSync(join(targetDir, from), join(targetDir, to));
         }
     }
-    for (const file of new Set([...(SUBSTITUTED[template] ?? []), ...overlays.flatMap(root => templateFiles(root))])) {
-        const path = join(targetDir, targetName(file));
-        let text = readFileSync(path, "utf8");
-        for (const [token, value] of Object.entries(substitutions)) {
-            text = text.replaceAll(token, value);
-        }
-        writeFileSync(path, text);
-    }
+    for (const file of files.map(targetName))
+        substitute(join(targetDir, file), substitutions);
+    if (localSdk)
+        useLocalSdk(targetDir, localSdk);
     if (minDsm) {
         const manifest = join(targetDir, template !== "compose" ? "dsm-package.yaml" : "synology-app.yaml");
         writeFileSync(manifest, readFileSync(manifest, "utf8").replace(/^os_min_ver:.*$/m, `os_min_ver: "${minDsm}"`));
@@ -189,20 +164,6 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     if (ui !== "vue")
         rmSync(join(targetDir, "frontend"), { recursive: true, force: true });
-    if (background) {
-        const routeTest = join(targetDir, "backend/internal/app/routes_test.go");
-        writeFileSync(routeTest, readFileSync(routeTest, "utf8").replace('want := ""', 'want := sampleOutcome[r.Method()]'));
-    }
-    if (executor) {
-        const path = join(targetDir, "backend/internal/app/routes_test.go");
-        writeFileSync(path, readFileSync(path, "utf8").replace('if strings.HasPrefix(r.Method(), "jobs.") {', 'if r.Method() == "root.run" { want = "session_required" }\n\t\tif strings.HasPrefix(r.Method(), "jobs.") {'));
-    }
-    if (background && ui === "vue") {
-        const app = join(targetDir, "frontend/src/App.vue");
-        writeFileSync(app, readFileSync(app, "utf8")
-            .replace("import AppShell from './shell/AppShell.vue'\n", "import AppShell from './shell/AppShell.vue'\nimport BackgroundPanel from './background/BackgroundPanel.vue'\n")
-            .replace("   <!-- BACKGROUND_PANEL -->", "   <BackgroundPanel v-if=\"app\" :key=\"app.user\" :ctx=\"ctx\" />"));
-    }
     if (template !== "compose") {
         const path = join(targetDir, "dsm-package.yaml");
         const raw = parse(readFileSync(path, "utf8"));
@@ -262,6 +223,39 @@ function sharedFolderYaml(options) {
     }
     return `\ninstall:\n  sharedFolder:\n${Object.entries(folder).map(([k, v]) => `    ${k}: ${v}\n`).join("")}`;
 }
+/**
+ * A local sdk checkout must hold the Go module, and for a Vue frontend the
+ * built ts package: npm installs a file: package as it is, without its build.
+ */
+function assertLocalSdkReady(sdkDir, vue) {
+    if (!existsSync(join(sdkDir, "go.mod"))) {
+        throw new Error(`[SDK_DIR_NOT_READY] SYNOPKGLAND_SDK_DIR=${sdkDir} 沒有 go.mod；請指向 syno-pkg-land-sdk 的 checkout。`);
+    }
+    const ts = join(sdkDir, "ts");
+    if (vue && !existsSync(join(ts, "dist"))) {
+        throw new Error(`[SDK_DIR_NOT_READY] ${ts} 尚未建置；前端安裝本機 SDK 時 npm 不會替它 build。請先執行 (cd ${ts} && npm ci && npm run build)，SDK 原始碼改動後也要重新 build。`);
+    }
+}
+/** SYNOPKGLAND_SDK_DIR: the project builds against a local sdk checkout instead of the released version. */
+function useLocalSdk(targetDir, sdkDir) {
+    const goMod = join(targetDir, "backend/go.mod");
+    writeFileSync(goMod, `${readFileSync(goMod, "utf8")}\nreplace ${SDK_MODULE} => ${sdkDir}\n`);
+    const frontend = join(targetDir, "frontend/package.json");
+    if (!existsSync(frontend))
+        return;
+    const pkg = JSON.parse(readFileSync(frontend, "utf8"));
+    pkg.dependencies[SDK_PACKAGE] = `file:${join(sdkDir, "ts")}`;
+    writeFileSync(frontend, JSON.stringify(pkg, null, 2) + "\n");
+}
+/** Fill the placeholders of one generated file; files without one, or removed by an overlay, stay untouched. */
+function substitute(path, substitutions) {
+    if (!existsSync(path))
+        return;
+    const original = readFileSync(path, "utf8");
+    const text = Object.entries(substitutions).reduce((current, [token, value]) => current.replaceAll(token, value), original);
+    if (text !== original)
+        writeFileSync(path, text);
+}
 function substitutionsFor(template, targetDir, options) {
     const ui = resolvedUi(template, options);
     const caps = capabilityNames(options.with ?? []);
@@ -274,7 +268,7 @@ function substitutionsFor(template, targetDir, options) {
     }
     if (options.ui !== undefined && !["plain", "vue"].includes(options.ui))
         throw new Error("[INIT_UI_INVALID] --ui 只接受 plain 或 vue。");
-    if (!SUBSTITUTED[template]) {
+    if (!IDENTIFIED.includes(template)) {
         if (options.from && options.displayName !== undefined)
             validDisplayName(options.displayName);
         return {};

package/dist/portal/alias.d.ts

@@ -1,4 +1,3 @@
-import type { AppContract } from "../types.js";
 /**
  * DSM Application Portal alias: `https://<nas>/<alias>/` opens the App after
  * DSM sign-in. DSM itself only refuses empty aliases (4100), synoman
@@ -12,6 +11,12 @@ export declare const PORTAL_ALIAS_MAX = 64;
  * of Synology Apps, as observed on DSM 7.4-90069. DSM stays the authority.
  */
 export declare const RESERVED_PORTAL_ALIASES: readonly string[];
+/**
+ * A portal needs the executor tier: DSM removes the alias files on uninstall
+ * but leaves nginx serving the alias, and only the root executor purge can
+ * reload it. A no-privilege App never runs anything as root.
+ */
+export declare const PORTAL_REQUIRES_EXECUTOR = "portal \u9700\u8981 executor \u5C64\u7D1A\uFF08capabilities.rootOps \u6216 delegate\uFF09\uFF1A\u89E3\u9664\u5B89\u88DD\u5F8C DSM \u4E0D\u6703 reload nginx\uFF0C\u767B\u5165\u5165\u53E3\u5225\u540D\u8981\u7531 root executor \u6E05\u9664\u3002\u6C92\u6709 executor \u7684 App \u8ACB\u79FB\u9664 portal\uFF0C\u6539\u7531\u7BA1\u7406\u54E1\u5728 DSM \u624B\u52D5\u8A2D\u5B9A\u53CD\u5411\u4EE3\u7406\u3002";
 export interface PortalDeclaration {
     alias: string;
 }
@@ -20,6 +25,3 @@ export declare function isPortalAlias(value: unknown): value is string;
 export declare function defaultPortalAlias(packageId: string): string;
 /** `{}` or `{alias}`; undefined for any other shape. */
 export declare function readPortalDeclaration(value: unknown, packageId: string): PortalDeclaration | undefined;
-/** A Compose App reaches the portal only as a DSM window behind the DSM-authenticated gateway. */
-export declare function contractPortalSupported(contract: AppContract): boolean;
-export declare function resolvedContractPortal(contract: AppContract): PortalDeclaration | undefined;

package/dist/portal/alias.js

@@ -1,5 +1,4 @@
 import { createHash } from "node:crypto";
-import { readWebIntegration, resolvedWebLaunch, usesAuthGateway } from "../contract/web-launch.js";
 /**
  * DSM Application Portal alias: `https://<nas>/<alias>/` opens the App after
  * DSM sign-in. DSM itself only refuses empty aliases (4100), synoman
@@ -16,6 +15,12 @@ export const RESERVED_PORTAL_ALIASES = [
     "dsfile", "indexdb", "mobile", "oauth", "scripts", "sharing", "ssdp", "synosdsjslib", "synohdpack", "webapi", "webman",
     "calendar", "chatplus", "contacts", "drive", "file", "photo", "sso", "synologymeet",
 ];
+/**
+ * A portal needs the executor tier: DSM removes the alias files on uninstall
+ * but leaves nginx serving the alias, and only the root executor purge can
+ * reload it. A no-privilege App never runs anything as root.
+ */
+export const PORTAL_REQUIRES_EXECUTOR = "portal 需要 executor 層級（capabilities.rootOps 或 delegate）：解除安裝後 DSM 不會 reload nginx，登入入口別名要由 root executor 清除。沒有 executor 的 App 請移除 portal，改由管理員在 DSM 手動設定反向代理。";
 export function isPortalAlias(value) {
     return typeof value === "string" && PORTAL_ALIAS_PATTERN.test(value) && !RESERVED_PORTAL_ALIASES.includes(value);
 }
@@ -36,13 +41,3 @@ export function readPortalDeclaration(value, packageId) {
         return { alias: defaultPortalAlias(packageId) };
     return isPortalAlias(alias) ? { alias } : undefined;
 }
-/** A Compose App reaches the portal only as a DSM window behind the DSM-authenticated gateway. */
-export function contractPortalSupported(contract) {
-    return resolvedWebLaunch(contract) === "dsm-window" && usesAuthGateway(contract);
-}
-export function resolvedContractPortal(contract) {
-    const portal = readWebIntegration(contract)?.portal;
-    if (portal === undefined || !contractPortalSupported(contract))
-        return undefined;
-    return readPortalDeclaration(portal, String(contract.package ?? ""));
-}

package/dist/portal/package.d.ts

@@ -1,6 +1,5 @@
 import type { Translate } from "../build-spk/wizard-i18n.js";
 import type { InstallWizardStep } from "../build-spk/install-wizard.js";
-import type { AppContract } from "../types.js";
 /** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
 export declare const PORTAL_JSON_RELPATH = "etc/portal.json";
 export declare const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
@@ -16,8 +15,6 @@ export interface PortalPackage {
     /** Default alias; the wizard answer replaces it. */
     alias: string;
 }
-/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
-export declare function contractPortal(contract: AppContract): PortalPackage | undefined;
 export declare function portalResource(): Record<string, unknown>;
 /** Every field of DSM's own app.d files; the worker refuses a partial file (synopkg start 272). */
 export declare function renderPortalJson(portal: PortalPackage): string;

package/dist/portal/package.js

@@ -1,4 +1,4 @@
-import { PORTAL_ALIAS_MAX, PORTAL_ALIAS_PATTERN, RESERVED_PORTAL_ALIASES, resolvedContractPortal } from "./alias.js";
+import { PORTAL_ALIAS_MAX, PORTAL_ALIAS_PATTERN, RESERVED_PORTAL_ALIASES } from "./alias.js";
 /** Package payload paths DSM's app-portal worker copies to /usr/syno/etc/www/app.d at start. */
 export const PORTAL_JSON_RELPATH = "etc/portal.json";
 export const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
@@ -6,12 +6,6 @@ export const PORTAL_MUSTACHE_RELPATH = "etc/portal.mustache";
 export const PORTAL_INSTALL_KEY = "portal_alias";
 /** Package-owned install draft, never DSM's saved portal configuration. */
 export const PORTAL_DRAFT = "portal-install.json";
-/** A Compose portal opens the App's `.url` entry of ui/config, keyed by the package id. */
-export function contractPortal(contract) {
-    const portal = resolvedContractPortal(contract);
-    const packageId = String(contract.package);
-    return portal && { appId: packageId, application: String(contract.displayname ?? packageId), alias: portal.alias };
-}
 export function portalResource() {
     return { "web-config": { "app-portal": { "json-relpath": PORTAL_JSON_RELPATH, "mustache-relpath": PORTAL_MUSTACHE_RELPATH } } };
 }

package/dist/reproducible.js

@@ -9,9 +9,9 @@ import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { extractSpk, walkFiles } from "./build-spk/generator.js";
 import { invalid, readReproducible } from "./reproducible-config.js";
+import { CLI_VERSION } from "./cli-version.js";
 export { readReproducible, validateReproducible } from "./reproducible-config.js";
 export const FINGERPRINT_RECORD = "reproducible-fingerprint.json";
-const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function insideProject(root, path) {
     const rel = relative(realpathSync(root), realpathSync(path));

package/dist/runtime/delegate-contract.d.ts

@@ -37,9 +37,22 @@ export interface MoveFromStaging {
     delegation_id: string;
     job_id: string;
     staging: string;
+    /**
+     * File name, or folders below the destination and a file name, for example
+     * `Album/CD1/01.flac`. Missing folders are created as the user, at most
+     * `DELEGATE_LIMITS.maxDestinationFolders` deep and `maxDestinationBytes` long.
+     */
     name: string;
     size: number;
+    /**
+     * When the name is taken: `fail` (default) refuses with `destination-exists`,
+     * `overwrite` atomically replaces a regular file the user can write, `rename`
+     * publishes `name (n).ext` (n up to 99) and the receipt reports that path.
+     */
+    conflict?: DelegateConflictPolicy;
 }
+export declare const DELEGATE_CONFLICT_POLICIES: readonly ["fail", "overwrite", "rename"];
+export type DelegateConflictPolicy = typeof DELEGATE_CONFLICT_POLICIES[number];
 export interface OperationRef {
     delegation_id: string;
     job_id: string;
@@ -76,4 +89,6 @@ export declare const DELEGATE_LIMITS: {
     readonly maxOperationBytes: number;
     readonly maxAuditBytes: number;
     readonly revalidateSeconds: 5;
+    readonly maxDestinationFolders: 16;
+    readonly maxDestinationBytes: 1024;
 };

package/dist/runtime/delegate-contract.js

@@ -7,6 +7,7 @@ export const DELEGATE_EXTENSION_OPERATIONS = [
 export const DELEGATE_OPERATION_STATES = [
     'queued', 'copying', 'committed', 'canceled', 'interrupted', 'uncertain',
 ];
+export const DELEGATE_CONFLICT_POLICIES = ['fail', 'overwrite', 'rename'];
 export const DELEGATE_ROUTES = {
     'delegate.example.export': 'authenticated',
     'delegate.destination': 'authenticated',
@@ -24,4 +25,5 @@ export const DELEGATE_LIMITS = {
     maxFileBytes: 16 * 1024 ** 3, maxQueued: 16, maxActive: 1,
     maxCopySeconds: 86400, maxOperationBytes: 10 * 1024 ** 2,
     maxAuditBytes: 50 * 1024 ** 2, revalidateSeconds: 5,
+    maxDestinationFolders: 16, maxDestinationBytes: 1024,
 };

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

@@ -3,6 +3,7 @@ import type { CommandRunner } from '../standalone/build.js';
 import type { StandaloneManifest } from '../standalone/manifest.js';
 import { type ExecutorPolicy } from './executor-policy.js';
 import { type ExecutorPins, type ExecutorTask } from './executor-tasks.js';
+import { type ExecutorDigestTable } from './executor-source.js';
 export interface ExecutorArtifact extends ExecutorPins {
     binary: string;
     lifecycleBinary: string;
@@ -10,8 +11,20 @@ export interface ExecutorArtifact extends ExecutorPins {
     policyText: string;
     tasks: ExecutorTask[];
     implementation: 'executor';
+    /** The SDK version the executor was built from; inspect regenerates the tasks from it. */
+    sdk: string;
+    warnings: string[];
 }
-export declare function buildExecutor(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): Promise<ExecutorArtifact | undefined>;
+export interface ExecutorSourceOptions {
+    env?: NodeJS.ProcessEnv;
+    download?: (spec: string) => string;
+    digests?: ExecutorDigestTable;
+}
+/**
+ * Build the executor and lifecycle helper from the App's SDK version: a copy of
+ * the module directory, `go build .` and `./cmd/lifecycle` inside it.
+ */
+export declare function buildExecutor(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner, options?: ExecutorSourceOptions): Promise<ExecutorArtifact | undefined>;
 export declare function executorPlan(a: ExecutorArtifact): {
     package: string;
     executorDigest: string;
@@ -19,4 +32,5 @@ export declare function executorPlan(a: ExecutorArtifact): {
     policy: ExecutorPolicy;
     tasks: ExecutorTask[];
     implementation: "executor";
+    sdk: string;
 };

package/dist/runtime/executor-build.js

@@ -1,28 +1,51 @@
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { templatesRoot } from '../template-paths.js';
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem } from '../build-spk/go-toolchain.js';
 import { StandaloneBuildError } from '../standalone/spk.js';
 import { checkCgiBinary } from '../standalone/binary.js';
 import { executorPolicy, executorPolicyText, sha256 } from './executor-policy.js';
 import { executorTasks } from './executor-tasks.js';
-export async function buildExecutor(m, arch, work, run) {
+import { copyModule, verifyExecutorDigests } from './executor-source.js';
+import { requiredSdk } from './sdk-source.js';
+/** CLI-owned build flags; the release digest table is computed the same way, so they must not change within an SDK minor. */
+const GO_BUILD = ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o'];
+function failure(error) {
+    const message = error.message;
+    const code = /^\[([A-Z0-9_]+)\]/.exec(message)?.[1] ?? 'EXECUTOR_BUILD_FAILED';
+    return new StandaloneBuildError(code, message.replace(/^\[[A-Z0-9_]+\] /, ''));
+}
+/**
+ * Build the executor and lifecycle helper from the App's SDK version: a copy of
+ * the module directory, `go build .` and `./cmd/lifecycle` inside it.
+ */
+export async function buildExecutor(m, arch, work, run, options = {}) {
     if (!m.capabilities.delegate && !m.capabilities.rootOps)
         return undefined;
+    let sdk;
+    try {
+        sdk = requiredSdk(m.backend.kind === 'go' ? m.backend.dir : m.root, options.env, options.download);
+    }
+    catch (error) {
+        throw failure(error);
+    }
     const dir = join(work, `executor-${arch}`);
     mkdirSync(dir);
-    const source = join(templatesRoot(), '_executor');
-    if (!existsSync(join(source, 'go.mod')))
-        throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', 'Executor sources are missing.');
+    const source = join(dir, 'source');
+    try {
+        copyModule(sdk.executorDir, source);
+    }
+    catch (error) {
+        throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Executor sources of SDK ${sdk.version} are missing: ${error.message}`);
+    }
     const binary = join(dir, 'executor');
-    const result = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', binary, '.'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
+    const result = await run('go', [...GO_BUILD, binary, '.'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
     if (result.missing || result.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Executor build failed (${arch}). ${PINNED_GO_HINT}\n${result.stderr}`);
     const problem = checkCgiBinary(work, binary, arch);
     if (problem)
         throw new StandaloneBuildError(problem.code, problem.message);
     const lifecycleBinary = join(dir, 'lifecycle');
-    const lifecycleResult = await run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
+    const lifecycleResult = await run('go', [...GO_BUILD, lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
     if (lifecycleResult.missing || lifecycleResult.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Lifecycle helper build failed (${arch}). ${PINNED_GO_HINT}\n${lifecycleResult.stderr}`);
     const lifecycleProblem = checkCgiBinary(work, lifecycleBinary, arch);
@@ -31,10 +54,18 @@ export async function buildExecutor(m, arch, work, run) {
     const toolchainProblem = pinnedGoProblem(binary) ?? pinnedGoProblem(lifecycleBinary);
     if (toolchainProblem)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', toolchainProblem);
+    const executorDigest = sha256(readFileSync(binary));
+    let warnings;
+    try {
+        warnings = verifyExecutorDigests(sdk, arch, { executor: executorDigest, lifecycle: sha256(readFileSync(lifecycleBinary)) }, options.digests);
+    }
+    catch (error) {
+        throw failure(error);
+    }
     const policy = executorPolicy(m), policyText = executorPolicyText(policy);
-    const pins = { package: m.package, executorDigest: sha256(readFileSync(binary)), policyDigest: sha256(policyText) };
-    return { ...pins, binary, lifecycleBinary, policy, policyText, tasks: executorTasks(pins), implementation: 'executor' };
+    const pins = { package: m.package, executorDigest, policyDigest: sha256(policyText) };
+    return { ...pins, binary, lifecycleBinary, policy, policyText, tasks: executorTasks(pins, sdk.executorDir), implementation: 'executor', sdk: sdk.version, warnings };
 }
 export function executorPlan(a) {
-    return { package: a.package, executorDigest: a.executorDigest, policyDigest: a.policyDigest, policy: a.policy, tasks: a.tasks, implementation: a.implementation };
+    return { package: a.package, executorDigest: a.executorDigest, policyDigest: a.policyDigest, policy: a.policy, tasks: a.tasks, implementation: a.implementation, sdk: a.sdk };
 }

package/dist/runtime/executor-digests.json

@@ -0,0 +1,24 @@
+{
+    "0.9.0": {
+        "x86_64": "e009eb882e79e001fa8e6faf43e58525948c132f01f873562353284e5ac53b69",
+        "aarch64": "f9b84fb9b4a945abf28af6efe1bee0e11067dd0cc5ae26e53f8a949175d519a9",
+        "armv7": "05b670757c9a6cdea17596769ddd471c0563c044af75a564e1570caac8e37bd2",
+        "lifecycle": {
+            "x86_64": "819459580135e016184ad80c258350d57194d6134e8aa4cf1caf5237085b1004",
+            "aarch64": "5abcfc21403e84a0af15d972bcb819ac6fedfd9aaf5898ddc8c4bb06130f9f59",
+            "armv7": "b65a14f0fc77a1d3221c7dc6781eb66059aa200956b094d58a62bd1cad10f116"
+        },
+        "goToolchain": "go1.26.9"
+    },
+    "0.9.1": {
+        "x86_64": "5d75af3ce1de5b1d3ef5d89e062be1651a8e8b84edbca9903eb1a0b81d122fb5",
+        "aarch64": "b0e1f8174bf53eb435616ae0faf39ac929b515056f0b2fad5a6c264a1ff7f6e2",
+        "armv7": "17db613a4bdb181e0aa0f127822bfc13d7473fa846aadfbac3344b7c17700a84",
+        "lifecycle": {
+            "x86_64": "819459580135e016184ad80c258350d57194d6134e8aa4cf1caf5237085b1004",
+            "aarch64": "5abcfc21403e84a0af15d972bcb819ac6fedfd9aaf5898ddc8c4bb06130f9f59",
+            "armv7": "b65a14f0fc77a1d3221c7dc6781eb66059aa200956b094d58a62bd1cad10f116"
+        },
+        "goToolchain": "go1.26.9"
+    }
+}

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

@@ -8,6 +8,7 @@ export interface ExecutorInspection {
     policyDigest: string;
     policy: ExecutorPolicy;
     implementation: string;
+    sdk: string;
     tasks: Array<ExecutorTask & {
         state: 'unknown' | 'ready' | 'needs-admin-approval' | 'blocked';
     }>;

package/dist/runtime/executor-inspect.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { validExecutorPolicy, sha256 } from './executor-policy.js';
 import { parseDocument } from 'yaml';
 import { executorTasks } from './executor-tasks.js';
+import { sdkSource } from './sdk-source.js';
 import { familyOfArchToken } from '../build-spk/dsm-arch.js';
 import { ELF_MACHINE } from '../standalone/binary.js';
 /** INFO key that anchors the executor digest; Package Center writes INFO as root. */
@@ -27,10 +28,12 @@ export function inspectExecutor(dir, pkg, arch) {
                 throw new Error('Root script digest mismatch.');
         }
         const executorDigest = sha256(binary), policyDigest = sha256(text);
-        const tasks = executorTasks({ package: pkg, policyDigest });
+        if (typeof plan.sdk !== 'string' || !/^\d+\.\d+\.\d+$/.test(plan.sdk))
+            throw new Error('Executor setup does not name its SDK version.');
+        const tasks = executorTasks({ package: pkg, policyDigest }, sdkSource(plan.sdk).executorDir);
         if (plan.package !== pkg || plan.executorDigest !== executorDigest || plan.policyDigest !== policyDigest || JSON.stringify(plan.policy) !== JSON.stringify(policy) || JSON.stringify(plan.tasks) !== JSON.stringify(tasks) || plan.implementation !== 'executor')
             throw new Error('Executor pins or task binding mismatch.');
-        return { executor: { executorDigest, policyDigest, policy, implementation: plan.implementation, tasks: tasks.map(task => ({ ...task, state: 'unknown' })) }, findings: [] };
+        return { executor: { executorDigest, policyDigest, policy, implementation: plan.implementation, sdk: plan.sdk, tasks: tasks.map(task => ({ ...task, state: 'unknown' })) }, findings: [] };
     }
     catch (e) {
         return { findings: ['Executor inventory invalid: ' + e.message] };

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

@@ -1,6 +1,8 @@
 import type { RootOp } from '../standalone/root-ops.js';
 import type { EntryMode } from '../standalone/manifest.js';
-export declare const FILE_OPERATIONS: readonly ["files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write"];
+export declare const FILE_OPERATIONS: readonly ["files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write", "files.read", "files.rename", "files.copy", "files.move", "files.delete"];
+/** Started File Station tasks are followed with these; they are implied, never declared. */
+export declare const FILE_TASK_OPERATIONS: readonly ["files.taskStatus", "files.taskCancel"];
 export interface DelegateCapability {
     operations: string[];
     scope: string;

package/dist/runtime/executor-policy.js

@@ -1,6 +1,9 @@
 import { createHash } from 'node:crypto';
 import { MOVE_FROM_STAGING, DELEGATE_EXTENSION_OPERATIONS } from './delegate-contract.js';
-export const FILE_OPERATIONS = ['files.list', 'files.info', 'files.createFolder', 'files.checkPermission', 'files.write'];
+export const FILE_OPERATIONS = ['files.list', 'files.info', 'files.createFolder', 'files.checkPermission', 'files.write', 'files.read', 'files.rename', 'files.copy', 'files.move', 'files.delete'];
+/** Started File Station tasks are followed with these; they are implied, never declared. */
+export const FILE_TASK_OPERATIONS = ['files.taskStatus', 'files.taskCancel'];
+const TASK_STARTING_OPERATIONS = ['files.copy', 'files.move', 'files.delete'];
 export function validDelegate(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -24,6 +27,8 @@ export function executorPolicy(m) {
     const operations = ['status'];
     if (m.capabilities.delegate) {
         operations.push('delegate.create', 'delegate.list', 'delegate.revoke', ...m.capabilities.delegate.operations);
+        if (m.capabilities.delegate.operations.some(op => TASK_STARTING_OPERATIONS.includes(op)))
+            operations.push(...FILE_TASK_OPERATIONS);
         if (m.capabilities.delegate.lifetime === 'until-revoked')
             operations.push(...DELEGATE_EXTENSION_OPERATIONS);
     }
@@ -50,7 +55,7 @@ export function validExecutorPolicy(value, pkg) {
         || !p.root || typeof p.root !== 'object' || Array.isArray(p.root))
         return false;
     const base = ['status', 'root.run', 'delegate.create', 'delegate.list', 'delegate.revoke'];
-    if (p.operations.some(op => ![...base, ...FILE_OPERATIONS, ...DELEGATE_EXTENSION_OPERATIONS].includes(op)))
+    if (p.operations.some(op => ![...base, ...FILE_OPERATIONS, ...FILE_TASK_OPERATIONS, ...DELEGATE_EXTENSION_OPERATIONS].includes(op)))
         return false;
     const delegated = p.operations.some(op => op.startsWith('files.') || op.startsWith('delegate.'));
     if (!delegated)

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

@@ -0,0 +1,21 @@
+import type { NativeArchFamily } from '../build-spk/dsm-arch.js';
+import type { SdkSource } from './sdk-source.js';
+type ArchDigests = Record<NativeArchFamily, string>;
+/** Released SDK versions: the sha256 of the executor and lifecycle helper built from them, per architecture. */
+export type ExecutorDigestTable = Record<string, ArchDigests & {
+    lifecycle: ArchDigests;
+    goToolchain: string;
+}>;
+export declare const SHIPPED_EXECUTOR_DIGESTS: ExecutorDigestTable;
+/** Copy a module directory (the module cache is read-only) so the build owns a writable tree. */
+export declare function copyModule(source: string, target: string): void;
+/**
+ * A released SDK's executor is only shipped when its bytes equal the digest
+ * table; a local SDK checkout (SYNOPKGLAND_SDK_DIR) is built unverified.
+ * Returns the warnings to show.
+ */
+export declare function verifyExecutorDigests(sdk: SdkSource, arch: NativeArchFamily, built: {
+    executor: string;
+    lifecycle: string;
+}, table?: ExecutorDigestTable): string[];
+export {};

package/dist/runtime/executor-source.js

@@ -0,0 +1,35 @@
+import { chmodSync, cpSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import EXECUTOR_DIGESTS from './executor-digests.json' with { type: 'json' };
+export const SHIPPED_EXECUTOR_DIGESTS = EXECUTOR_DIGESTS;
+/** Copy a module directory (the module cache is read-only) so the build owns a writable tree. */
+export function copyModule(source, target) {
+    cpSync(source, target, { recursive: true });
+    const writable = (path) => {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            return;
+        chmodSync(path, stat.mode | 0o200);
+        if (stat.isDirectory())
+            for (const name of readdirSync(path))
+                writable(join(path, name));
+    };
+    writable(target);
+}
+/**
+ * A released SDK's executor is only shipped when its bytes equal the digest
+ * table; a local SDK checkout (SYNOPKGLAND_SDK_DIR) is built unverified.
+ * Returns the warnings to show.
+ */
+export function verifyExecutorDigests(sdk, arch, built, table = SHIPPED_EXECUTOR_DIGESTS) {
+    if (sdk.local)
+        return [`[EXECUTOR_DIGEST_UNVERIFIED] executor built from the local SDK checkout SYNOPKGLAND_SDK_DIR (${arch}, sha256 ${built.executor}); the digest table was not checked. Do not publish this SPK.`];
+    const expected = table[sdk.version];
+    if (!expected)
+        throw new Error(`[EXECUTOR_DIGEST_MISMATCH] This CLI has no recorded executor digest for SDK ${sdk.version}; it knows ${Object.keys(table).join(', ') || 'no released SDK'}.`);
+    if (expected[arch] !== built.executor)
+        throw new Error(`[EXECUTOR_DIGEST_MISMATCH] SDK ${sdk.version} executor (${arch}) built to sha256 ${built.executor}, not the released ${expected[arch]}.`);
+    if (expected.lifecycle[arch] !== built.lifecycle)
+        throw new Error(`[EXECUTOR_DIGEST_MISMATCH] SDK ${sdk.version} lifecycle helper (${arch}) built to sha256 ${built.lifecycle}, not the released ${expected.lifecycle[arch]}.`);
+    return [];
+}

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

@@ -11,7 +11,10 @@ export interface ExecutorTask {
     script: string;
 }
 export declare function validateTaskScript(script: string, limit: number): string;
-/** Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes. */
-export declare function executorTasks(pins: Pick<ExecutorPins, 'package' | 'policyDigest'>): ExecutorTask[];
+/**
+ * Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes.
+ * The task scripts come from the SDK executor module the App builds with.
+ */
+export declare function executorTasks(pins: Pick<ExecutorPins, 'package' | 'policyDigest'>, executorDir: string): ExecutorTask[];
 export declare function bootDefinition(task: ExecutorTask): Record<string, unknown>;
 export declare function controlDefinition(task: ExecutorTask): Record<string, unknown>;