@synopackageland/cli 0.8.0 → 0.9.0

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,13 @@
+{
+    "0.9.0": {
+        "x86_64": "e009eb882e79e001fa8e6faf43e58525948c132f01f873562353284e5ac53b69",
+        "aarch64": "f9b84fb9b4a945abf28af6efe1bee0e11067dd0cc5ae26e53f8a949175d519a9",
+        "armv7": "05b670757c9a6cdea17596769ddd471c0563c044af75a564e1570caac8e37bd2",
+        "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>;

package/dist/runtime/executor-tasks.js

@@ -1,6 +1,5 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { templatesRoot } from '../template-paths.js';
 export function validateTaskScript(script, limit) {
     if (script.includes('%'))
         throw new Error('[EXECUTOR_TASK_PERCENT] Task scripts must not contain percent characters.');
@@ -8,14 +7,17 @@ export function validateTaskScript(script, limit) {
         throw new Error('[EXECUTOR_TASK_LENGTH] Task script exceeds DSM byte limit.');
     return script;
 }
-/** Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes. */
-export function executorTasks(pins) {
+/**
+ * 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 function executorTasks(pins, executorDir) {
     if (!/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(pins.package))
         throw new Error('[EXECUTOR_PACKAGE] Invalid package identity.');
     if (!/^[a-f0-9]{64}$/.test(pins.policyDigest))
         throw new Error('[EXECUTOR_DIGEST] Invalid sha256 pin.');
     return ['boot', 'control'].map(kind => {
-        const script = readFileSync(join(templatesRoot(), '_executor', 'internal', 'taskscript', `${kind}.sh`), 'utf8')
+        const script = readFileSync(join(executorDir, 'internal', 'taskscript', `${kind}.sh`), 'utf8')
             .replaceAll('@PACKAGE@', pins.package).replaceAll('@POLICY_DIGEST@', pins.policyDigest);
         return { kind, name: `${pins.package} executor ${kind}`, header: `#!/bin/sh\n# synopkgland executor ${kind}\n`, script: validateTaskScript(script, kind === 'boot' ? 1024 : 6000) };
     });

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

@@ -0,0 +1,31 @@
+export declare const SDK_PACKAGE = "@synopackageland/sdk";
+export declare const SDK_MODULE = "github.com/synopackageland/syno-pkg-land-sdk";
+export declare const EXECUTOR_MODULE = "github.com/synopackageland/syno-pkg-land-sdk/executor";
+/** Where one SDK version's Go client and executor sources are read from. */
+export interface SdkSource {
+    version: string;
+    goDir: string;
+    executorDir: string;
+    local: boolean;
+}
+/** The SDK version an App requires: `require github.com/synopackageland/syno-pkg-land-sdk vX.Y.Z` in backend/go.mod, the only version source. */
+export declare function sdkRequirement(backendDir: string): string | undefined;
+/** The App's own Go module path, the prefix of every `-X` that targets its packages. */
+export declare function goModulePath(backendDir: string): string | undefined;
+/**
+ * The module directories of one SDK version. SYNOPKGLAND_SDK_DIR names a
+ * local sdk checkout (development and gates only); otherwise both modules
+ * come from `go mod download` of exactly that version.
+ */
+export declare function sdkSource(version: string, env?: NodeJS.ProcessEnv, download?: (spec: string) => string): SdkSource;
+/** The module cache directory of module@version; the cache is read-only, so builds copy it first. */
+export declare function goModDownload(spec: string, env?: NodeJS.ProcessEnv): string;
+/** The SDK an App builds its executor with; delegate and rootOps cannot build without one. */
+export declare function requiredSdk(backendDir: string, env?: NodeJS.ProcessEnv, download?: (spec: string) => string): SdkSource;
+/**
+ * The SDK repositories are private: Go must fetch them with git, not from
+ * proxy.golang.org and sum.golang.org. Says which of the two is missing.
+ */
+export declare function privateSdkHint(env?: NodeJS.ProcessEnv): string;
+/** Whether a comma-separated GOPRIVATE-style glob list matches a module path or one of its prefixes, as go does. */
+export declare function goPrivateCovers(patterns: string, modulePath: string): boolean;

package/dist/runtime/sdk-source.js

@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const SDK_PACKAGE = '@synopackageland/sdk';
+export const SDK_MODULE = 'github.com/synopackageland/syno-pkg-land-sdk';
+export const EXECUTOR_MODULE = `${SDK_MODULE}/executor`;
+/** The SDK version an App requires: `require github.com/synopackageland/syno-pkg-land-sdk vX.Y.Z` in backend/go.mod, the only version source. */
+export function sdkRequirement(backendDir) {
+    const module = SDK_MODULE.replaceAll('.', '\\.');
+    return new RegExp(`^\\s*(?:require\\s+)?${module}\\s+v(\\S+)`, 'm').exec(goMod(backendDir))?.[1];
+}
+/** The App's own Go module path, the prefix of every `-X` that targets its packages. */
+export function goModulePath(backendDir) {
+    return /^\s*module\s+(\S+)/m.exec(goMod(backendDir))?.[1];
+}
+/** backend/go.mod without comments; empty when the backend has none. */
+function goMod(backendDir) {
+    try {
+        return readFileSync(join(backendDir, 'go.mod'), 'utf8').replace(/\/\/.*$/gm, '');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The module directories of one SDK version. SYNOPKGLAND_SDK_DIR names a
+ * local sdk checkout (development and gates only); otherwise both modules
+ * come from `go mod download` of exactly that version.
+ */
+export function sdkSource(version, env = process.env, download = (spec) => goModDownload(spec, env)) {
+    const dir = env.SYNOPKGLAND_SDK_DIR;
+    if (dir)
+        return { version, goDir: dir, executorDir: join(dir, 'executor'), local: true };
+    return { version, goDir: download(`${SDK_MODULE}@v${version}`), executorDir: download(`${EXECUTOR_MODULE}@v${version}`), local: false };
+}
+const downloaded = new Map();
+/** The module cache directory of module@version; the cache is read-only, so builds copy it first. */
+export function goModDownload(spec, env = process.env) {
+    const key = [spec, env.GOPROXY, env.GOMODCACHE, env.GOPATH].join('\0');
+    const cached = downloaded.get(key);
+    if (cached)
+        return cached;
+    const result = spawnSync('go', ['mod', 'download', '-json', spec], { cwd: tmpdir(), env: { ...env, GOWORK: 'off', GOFLAGS: '' }, encoding: 'utf8' });
+    let info = {};
+    try {
+        info = JSON.parse(result.stdout);
+    }
+    catch { /* reported below */ }
+    if (result.error || result.status !== 0 || !info.Dir) {
+        throw new Error(`[SDK_DOWNLOAD_FAILED] go mod download ${spec} failed: ${info.Error ?? result.stderr ?? result.error?.message}${privateSdkHint(env)}`);
+    }
+    downloaded.set(key, info.Dir);
+    return info.Dir;
+}
+/** The SDK an App builds its executor with; delegate and rootOps cannot build without one. */
+export function requiredSdk(backendDir, env = process.env, download) {
+    const version = sdkRequirement(backendDir);
+    if (!version)
+        throw new Error(`[SDK_REQUIRED] capabilities.delegate and rootOps need the SDK: add \`require ${SDK_MODULE} v<version>\` to backend/go.mod.`);
+    return download ? sdkSource(version, env, download) : sdkSource(version, env);
+}
+/**
+ * The SDK repositories are private: Go must fetch them with git, not from
+ * proxy.golang.org and sum.golang.org. Says which of the two is missing.
+ */
+export function privateSdkHint(env = process.env) {
+    const result = spawnSync('go', ['env', '-json', 'GONOPROXY', 'GONOSUMDB'], { cwd: tmpdir(), env: { ...env, GOFLAGS: '' }, encoding: 'utf8' });
+    let goEnv = {};
+    try {
+        goEnv = JSON.parse(result.stdout);
+    }
+    catch { /* treated as not covered */ }
+    if (goPrivateCovers(goEnv.GONOPROXY ?? '', SDK_MODULE) && goPrivateCovers(goEnv.GONOSUMDB ?? '', SDK_MODULE)) {
+        return ` GOPRIVATE covers the SDK, so Go fetches it with git: check that \`git ls-remote https://${SDK_MODULE}\` works with your git credential.`;
+    }
+    return ' The SDK repositories are private, and Go looks up modules outside GOPRIVATE on proxy.golang.org and sum.golang.org.'
+        + ' Set GOPRIVATE=github.com/synopackageland/* (for example `go env -w GOPRIVATE=github.com/synopackageland/*`) and give git a credential for github.com.';
+}
+/** Whether a comma-separated GOPRIVATE-style glob list matches a module path or one of its prefixes, as go does. */
+export function goPrivateCovers(patterns, modulePath) {
+    const elements = modulePath.split('/');
+    return patterns.split(',').map(glob => glob.trim().replace(/\/+$/, '')).filter(Boolean).some(glob => {
+        const prefix = elements.slice(0, glob.split('/').length).join('/');
+        return globRegExp(glob).test(prefix);
+    });
+}
+/** path.Match syntax: `*` and `?` never cross a slash. */
+function globRegExp(glob) {
+    const body = glob.replace(/[.+^${}()|\\]/g, '\\$&').replaceAll('*', '[^/]*').replaceAll('?', '[^/]');
+    return new RegExp(`^${body}$`);
+}

package/dist/standalone/api-permissions.d.ts

@@ -1,5 +1,6 @@
 import type { Capabilities } from "./manifest.js";
 export declare const API_PERMISSIONS_FILE = "internal/api/permissions.json";
+type SdkPermissions = Record<string, Record<string, ApiPermission>>;
 export declare const MAX_PERMISSIONS_BYTES = 65536;
 export declare const MAX_PERMISSION_METHODS = 1024;
 export type ApiPermission = "administrators" | "authenticated" | "public";
@@ -13,6 +14,7 @@ export declare function readApiPermissions(backendDir: string, capabilities?: Ca
     policy: ApiPermissions;
     digest: string;
     sdkDigest: string;
+    sdk: SdkPermissions;
 };
 /**
  * `entry: admin-only` makes administrators the floor of every route. App
@@ -20,9 +22,10 @@ export declare function readApiPermissions(backendDir: string, capabilities?: Ca
  * capability added are raised, except the public login ceremony of
  * `identity: standalone`, which admits no one by itself.
  */
-export declare function floorAtAdministrators(policy: ApiPermissions): {
+export declare function floorAtAdministrators(policy: ApiPermissions, sdkPermissions: SdkPermissions): {
     policy: ApiPermissions;
     widened: string[];
 };
 /** Launcher access is derived from the same API policy; no second setting. */
 export declare function permitsOrdinaryUsers(policy?: ApiPermissions): boolean;
+export {};

package/dist/standalone/api-permissions.js

@@ -1,10 +1,11 @@
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { templatesRoot } from "../template-paths.js";
+import { sdkRequirement, sdkSource } from "../runtime/sdk-source.js";
 import { parseDocument } from "yaml";
 export const API_PERMISSIONS_FILE = "internal/api/permissions.json";
-const SDK_PERMISSIONS_TEMPLATE = "native-go/backend/internal/api/sdk-permissions.json";
+/** SDK-owned routes per capability, in the Go module of the SDK version the App requires. */
+const SDK_PERMISSIONS_FILE = "api/sdk-permissions.json";
 export const MAX_PERMISSIONS_BYTES = 65536;
 export const MAX_PERMISSION_METHODS = 1024;
 export function parseApiPermissions(raw) {
@@ -38,15 +39,9 @@ export function readApiPermissions(backendDir, capabilities = {}) {
         throw new Error("permissions must be a regular bounded JSON file");
     const raw = readFileSync(file);
     const policy = parseApiPermissions(raw);
-    const sdkRaw = readFileSync(join(templatesRoot(), SDK_PERMISSIONS_TEMPLATE));
-    const sdkFile = join(backendDir, 'internal/api/sdk-permissions.json');
-    if (existsSync(sdkFile)) {
-        const sdkStat = lstatSync(sdkFile);
-        if (!sdkStat.isFile() || sdkStat.size !== sdkRaw.length || !readFileSync(sdkFile).equals(sdkRaw)) {
-            throw new Error('SDK route policy differs from the CLI policy; restore the SDK-owned file');
-        }
-    }
-    const sdk = readSdkPermissions();
+    const version = sdkRequirement(backendDir);
+    const sdkRaw = version ? readFileSync(join(sdkSource(version).goDir, SDK_PERMISSIONS_FILE)) : Buffer.from("{}");
+    const sdk = JSON.parse(sdkRaw.toString("utf8"));
     for (const methods of Object.values(sdk))
         for (const method of Object.keys(methods)) {
             if (Object.hasOwn(policy.methods, method))
@@ -56,7 +51,7 @@ export function readApiPermissions(backendDir, capabilities = {}) {
         if (capabilities[capability] || ['rootOps', 'files'].includes(capability) && capabilities.delegate)
             Object.assign(policy.methods, methods);
     }
-    return { policy, sdkDigest: createHash("sha256").update(sdkRaw).digest("hex"), digest: createHash("sha256").update(raw).digest("hex") };
+    return { policy, sdk, sdkDigest: createHash("sha256").update(sdkRaw).digest("hex"), digest: createHash("sha256").update(raw).digest("hex") };
 }
 /**
  * `entry: admin-only` makes administrators the floor of every route. App
@@ -64,16 +59,13 @@ export function readApiPermissions(backendDir, capabilities = {}) {
  * capability added are raised, except the public login ceremony of
  * `identity: standalone`, which admits no one by itself.
  */
-export function floorAtAdministrators(policy) {
-    const sdk = new Set(Object.values(readSdkPermissions()).flatMap(methods => Object.keys(methods)));
+export function floorAtAdministrators(policy, sdkPermissions) {
+    const sdk = new Set(Object.values(sdkPermissions).flatMap(methods => Object.keys(methods)));
     const methods = Object.fromEntries(Object.entries(policy.methods)
         .map(([method, permission]) => [method, sdk.has(method) && permission === "public" ? permission : "administrators"]));
     const widened = Object.entries(policy.methods).filter(([method, permission]) => !sdk.has(method) && permission !== "administrators").map(([method]) => method);
     return { policy: { ...policy, methods }, widened };
 }
-function readSdkPermissions() {
-    return JSON.parse(readFileSync(join(templatesRoot(), SDK_PERMISSIONS_TEMPLATE), 'utf8'));
-}
 /** Launcher access is derived from the same API policy; no second setting. */
 export function permitsOrdinaryUsers(policy) {
     return policy !== undefined && Object.values(policy.methods).some(permission => permission !== "administrators");

package/dist/standalone/build.d.ts

@@ -33,4 +33,5 @@ export declare function runnerFor(run: CommandRunner | undefined, jobs: number,
 /** `build` for a Standalone Package: build the UI, compile the CGI, pack one SPK per arch. */
 export declare function buildStandalone(options: StandaloneBuildOptions): Promise<{
     outputs: string[];
+    warnings: string[];
 }>;

package/dist/standalone/build.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { goModulePath, privateSdkHint, SDK_MODULE } from "../runtime/sdk-source.js";
 import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -92,12 +93,14 @@ export async function buildStandalone(options) {
     await buildUi(manifest, options.run ?? runCommand);
     const outDir = options.outDir ?? join(options.root, "dist");
     const work = mkdtempSync(join(tmpdir(), "syno-standalone-build-"));
+    const warnings = new Set();
     try {
         const outputs = await commitOutputs(outDir, (stage) => forEachArch(arches, jobs, async (arch) => {
             const run = runnerFor(options.run, jobs, arch);
             const archWork = join(work, arch);
             mkdirSync(archWork);
             const executor = await buildExecutor(manifest, arch, archWork, run);
+            executor?.warnings.forEach(warning => warnings.add(warning));
             const builtManifest = executor ? { ...manifest, executor } : manifest;
             const cgiPath = await backendFor(builtManifest, arch, archWork, run);
             const problem = checkCgiBinary(manifest.backend.kind === "go" ? archWork : manifest.root, cgiPath, arch);
@@ -110,7 +113,7 @@ export async function buildStandalone(options) {
             await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, daemonControl, backgroundWorker, executor });
             return outputPath;
         }));
-        return { outputs };
+        return { outputs, warnings: [...warnings] };
     }
     finally {
         rmSync(work, { recursive: true, force: true });
@@ -140,6 +143,9 @@ async function backendFor(manifest, arch, work, run) {
     if (readApiPermissions(backend.dir, manifest.capabilities).digest !== manifest.apiPermissionsDigest || readApiPermissions(backend.dir, manifest.capabilities).sdkDigest !== manifest.apiSDKPermissionsDigest) {
         throw new StandaloneBuildError("STANDALONE_API_PERMISSIONS_CHANGED", "API permissions changed during build; check and rebuild.");
     }
+    const module = goModulePath(backend.dir);
+    if (!module)
+        throw new StandaloneBuildError("STANDALONE_GO_BUILD_FAILED", `${join(backend.dir, "go.mod")} 沒有 module 行；backend 必須是一個 Go module。`);
     const out = join(work, `api-${arch}.cgi`);
     const ldflags = [
         "-s",
@@ -147,8 +153,8 @@ async function backendFor(manifest, arch, work, run) {
         "-buildid=",
         `-X main.packageID=${manifest.package}`,
         `-X main.version=${manifest.spkVersion}`,
-        `-X dsmapp/internal/api.expectedPermissionsDigest=${manifest.apiPermissionsDigest}`,
-        `-X dsmapp/internal/api.expectedSDKPermissionsDigest=${manifest.apiSDKPermissionsDigest}`,
+        `-X ${module}/internal/api.expectedPermissionsDigest=${manifest.apiPermissionsDigest}`,
+        `-X ${SDK_MODULE}/api.expectedSDKPermissionsDigest=${manifest.apiSDKPermissionsDigest}`,
         ...delegateBuildFlags(manifest),
         ...(manifest.executor ? [`-X main.executorDigest=${manifest.executor.executorDigest}`, `-X main.policyDigest=${manifest.executor.policyDigest}`] : []),
         ...(manifest.capabilities.identity ? [`-X main.identity=${manifest.capabilities.identity}`] : []),
@@ -164,7 +170,8 @@ async function backendFor(manifest, arch, work, run) {
         throw new StandaloneBuildError("STANDALONE_GO_MISSING", "找不到 go 指令。請安裝 Go 1.25 以上版本（https://go.dev/dl/），或改用 backend.binary 打包既有執行檔。");
     }
     if (result.status !== 0) {
-        throw new StandaloneBuildError("STANDALONE_GO_BUILD_FAILED", `go build（${arch}）失敗。\n${result.stderr}`);
+        const fetchingSdk = result.stderr.includes(`${SDK_MODULE}@`) ? privateSdkHint() : "";
+        throw new StandaloneBuildError("STANDALONE_GO_BUILD_FAILED", `go build（${arch}）失敗。\n${result.stderr}${fetchingSdk}`);
     }
     return out;
 }