@synopackageland/cli 0.9.6 → 0.10.0

package/dist/runtime/executor-policy.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { MOVE_FROM_STAGING, DELEGATE_EXTENSION_OPERATIONS } from './delegate-contract.js';
 import { portalByExecutor } from '../build-spk/dsm-version.js';
 import { portalEntryProblem } from '../portal/alias.js';
+import { ROOT_JOB_OPERATIONS, ROOT_PROGRAM_NAME, rootEntryProblem, rootOperations } from './root-programs.js';
 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'];
@@ -25,7 +26,7 @@ export const sha256 = (data) => createHash('sha256').update(data).digest('hex');
 /** The exact policy file bytes whose sha256 is the policy pin. */
 export const executorPolicyText = (policy) => JSON.stringify(policy) + '\n';
 /** Version-independent, sorted policy. Only §2.4 operation IDs are admitted. */
-export function executorPolicy(m) {
+export function executorPolicy(m, arch) {
     if (m.capabilities.delegate && !validDelegate(m.capabilities.delegate))
         throw new Error('[EXECUTOR_POLICY] Invalid delegate operations or scope.');
     const portal = executorPortal(m);
@@ -38,16 +39,28 @@ export function executorPolicy(m) {
             operations.push(...DELEGATE_EXTENSION_OPERATIONS);
     }
     const root = {};
+    const settings = m.capabilities.rootOps ? m.rootPrograms : undefined;
     if (m.capabilities.rootOps) {
-        operations.push('root.run');
         for (const op of [...m.rootOps ?? []].sort((a, b) => a.name.localeCompare(b.name, 'en')))
-            root[op.name] = sha256(op.body);
+            root[op.name] = rootEntry(op, settings?.programs?.[op.name], arch);
+        operations.push(...rootOperations(root));
     }
     const d = m.capabilities.delegate;
     const purge = m.capabilities.rootOps ? m.uninstall?.purge.root : undefined;
     return { v: 1, package: m.package, app: `SYNO.SDS.${m.package}.Instance`, ...(m.entry ? { entry: m.entry } : {}), ...(d ? { scope: d.scope } : {}),
         ...(d?.lifetime ? { destinations: [...d.destinations].sort(), lifetime: d.lifetime } : {}),
-        operations: [...new Set(operations)].sort(), ...(portal ? { portal } : {}), ...(purge ? { purge } : {}), root };
+        operations: [...new Set(operations)].sort(), ...(portal ? { portal } : {}), ...(purge ? { purge } : {}), ...(settings?.stop ? { stop: settings.stop } : {}),
+        root, ...(settings?.state ? { root_state: true } : {}) };
+}
+/** A script without settings keeps the bare digest; a binary pins the bytes built for this architecture. */
+function rootEntry(op, settings, arch) {
+    const digest = op.body !== undefined ? sha256(op.body) : arch && op.binary?.[arch]?.digest;
+    if (!digest)
+        throw new Error(`[EXECUTOR_POLICY] Root program ${op.name} has no binary for ${arch ?? 'an unnamed architecture'}.`);
+    if (!settings)
+        return digest;
+    return { digest, kind: op.body !== undefined ? 'script' : 'binary', ...(settings.schema ? { schema: settings.schema } : {}),
+        ...(settings.run ? { run: settings.run } : {}), ...(settings.job ? { job: settings.job } : {}) };
 }
 /** The entry the executor registers: a portal App whose os_min_ver is below DSM 7.2. */
 function executorPortal(m) {
@@ -64,14 +77,20 @@ export function validExecutorPolicy(value, pkg) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
     const p = value;
-    if (Object.keys(p).some(key => !['v', 'package', 'app', 'entry', 'scope', 'destinations', 'lifetime', 'operations', 'portal', 'purge', 'root'].includes(key))
+    if (Object.keys(p).some(key => !['v', 'package', 'app', 'entry', 'scope', 'destinations', 'lifetime', 'operations', 'portal', 'purge', 'stop', 'root', 'root_state'].includes(key))
         || p.v !== 1 || p.package !== pkg || p.app !== `SYNO.SDS.${pkg}.Instance`
         || 'entry' in p && p.entry !== 'admin-only' && p.entry !== 'app-privilege'
         || !Array.isArray(p.operations) || !p.operations.includes('status') || new Set(p.operations).size !== p.operations.length
         || !p.root || typeof p.root !== 'object' || Array.isArray(p.root)
-        || 'purge' in p && (typeof p.purge !== 'string' || !Object.hasOwn(p.root, p.purge)))
+        || 'purge' in p && (typeof p.purge !== 'string' || !Object.hasOwn(p.root, p.purge))
+        || 'stop' in p && (typeof p.stop !== 'string' || !Object.hasOwn(p.root, p.stop))
+        || 'root_state' in p && p.root_state !== true
+        || Object.entries(p.root).some(([name, entry]) => !ROOT_PROGRAM_NAME.test(name) || rootEntryProblem(entry) !== undefined))
+        return false;
+    const rootOps = rootOperations(p.root);
+    if (![...ROOT_JOB_OPERATIONS, 'root.run'].every(op => p.operations.includes(op) === rootOps.includes(op)))
         return false;
-    const base = ['status', 'root.run', 'delegate.create', 'delegate.list', 'delegate.revoke'];
+    const base = ['status', 'root.run', ...ROOT_JOB_OPERATIONS, 'delegate.create', 'delegate.list', 'delegate.revoke'];
     if (p.operations.some(op => ![...base, ...FILE_OPERATIONS, ...FILE_TASK_OPERATIONS, ...DELEGATE_EXTENSION_OPERATIONS, ...PORTAL_OPERATIONS].includes(op)))
         return false;
     if (!PORTAL_OPERATIONS.every(op => p.operations.includes(op) === (p.portal !== undefined)) || p.portal !== undefined && !validPortalEntry(p.portal, pkg))
@@ -83,7 +102,7 @@ export function validExecutorPolicy(value, pkg) {
         ...('lifetime' in p ? { lifetime: p.lifetime } : {}), ...('destinations' in p ? { destinations: p.destinations } : {}) };
     if (!validDelegate(capability))
         return false;
-    const expected = executorPolicy({ package: pkg, capabilities: { delegate: capability, ...(p.operations.includes('root.run') ? { rootOps: true } : {}) } }).operations;
+    const expected = [...executorPolicy({ package: pkg, capabilities: { delegate: capability } }).operations, ...rootOps];
     const declared = p.operations.filter(op => !PORTAL_OPERATIONS.includes(op));
     return expected.length === declared.length && expected.every(op => declared.includes(op));
 }

package/dist/runtime/root-programs.d.ts

@@ -0,0 +1,47 @@
+import type { ExecutorPolicy } from './executor-policy.js';
+export interface RootRunLimits {
+    timeout_s?: number;
+    max_output?: number;
+}
+export interface RootJobLimits {
+    timeout_s?: number;
+    grace_s?: number;
+    max_concurrent?: number;
+    nice?: number;
+}
+/** A `root.programs.<name>` setting in dsm-package.yaml. */
+export interface RootProgramSettings {
+    kind?: 'script' | 'binary';
+    schema?: Record<string, unknown>;
+    run?: RootRunLimits;
+    job?: RootJobLimits;
+}
+/** dsm-package.yaml `root`: settings of root/ programs, the stop step and the root state directory. */
+export interface RootSettings {
+    programs?: Record<string, RootProgramSettings>;
+    stop?: string;
+    state?: true;
+}
+/** A policy root entry: a bare digest is a script root.run may run with the defaults. */
+export type RootPolicyEntry = string | {
+    digest: string;
+    kind: 'script' | 'binary';
+    schema?: Record<string, unknown>;
+    run?: RootRunLimits;
+    job?: RootJobLimits;
+};
+export declare const ROOT_JOB_OPERATIONS: readonly ["root.start", "root.jobs.list", "root.jobs.get", "root.jobs.stop"];
+export declare const ROOT_PROGRAM_NAME: RegExp;
+/** The operations a policy's root entries need: root.run for any it may run, the job ops for any with job. */
+export declare function rootOperations(root: Record<string, RootPolicyEntry>): string[];
+/**
+ * Why the App's SDK executor cannot run this policy: one from before root
+ * program entries refuses a policy with them, and the package would not start.
+ */
+export declare function rootProgramsUnsupported(policy: ExecutorPolicy, executorDir: string): string | undefined;
+/** Why the run or job limits are outside the executor's bounds; undefined when they are within. */
+export declare function rootLimitsProblem(value: unknown, which: 'run' | 'job'): string | undefined;
+/** Why a params schema is outside the executor's closed JSON Schema subset; undefined when it is inside. */
+export declare function rootSchemaProblem(schema: unknown, depth?: number): string | undefined;
+/** Why a policy root entry would make the executor refuse the policy; undefined when it would not. */
+export declare function rootEntryProblem(entry: unknown): string | undefined;

package/dist/runtime/root-programs.js

@@ -0,0 +1,153 @@
+/**
+ * Root programs as the executor's policy declares them (protocol: Root
+ * programs, Root jobs, Package stop step, Root state directory). The bounds
+ * and the params schema subset are the executor's; a policy outside them
+ * makes the executor refuse to start.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const ROOT_JOB_OPERATIONS = ['root.start', 'root.jobs.list', 'root.jobs.get', 'root.jobs.stop'];
+export const ROOT_PROGRAM_NAME = /^[a-z][a-z0-9_]{0,31}$/;
+const RUN_BOUNDS = { timeout_s: [1, 120], max_output: [1, 64 * 1024 * 1024] };
+const JOB_BOUNDS = { timeout_s: [1, 604800], grace_s: [1, 60], max_concurrent: [1, 4], nice: [0, 19] };
+const SCHEMA_TYPES = ['object', 'array', 'string', 'integer', 'number', 'boolean'];
+const STRING_KEYWORDS = ['pattern', 'minLength', 'maxLength'];
+const NUMBER_KEYWORDS = ['minimum', 'maximum'];
+const ARRAY_KEYWORDS = ['items', 'minItems', 'maxItems'];
+const OBJECT_KEYWORDS = ['properties', 'required', 'additionalProperties'];
+const PARAM_KEY = /^[a-z0-9_]{1,64}$/;
+/** RE2, which the executor compiles patterns with, has no lookaround and no backreferences. */
+const NOT_RE2 = /\(\?<?[=!]|\\[1-9]|\\k</;
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const integer = (value) => typeof value === 'number' && Number.isInteger(value);
+/** The operations a policy's root entries need: root.run for any it may run, the job ops for any with job. */
+export function rootOperations(root) {
+    const entries = Object.values(root);
+    return [
+        ...(entries.some(entry => typeof entry === 'string' || entry.run) ? ['root.run'] : []),
+        ...(entries.some(entry => typeof entry !== 'string' && entry.job) ? ROOT_JOB_OPERATIONS : []),
+    ];
+}
+/** A file only executors that read root program entries, stop and root_state have (SDK 0.10). */
+const ROOT_PROGRAMS_SOURCE = 'stop_step.go';
+/**
+ * Why the App's SDK executor cannot run this policy: one from before root
+ * program entries refuses a policy with them, and the package would not start.
+ */
+export function rootProgramsUnsupported(policy, executorDir) {
+    const uses = Object.values(policy.root).some(entry => typeof entry !== 'string') || policy.stop !== undefined || policy.root_state !== undefined;
+    if (!uses || existsSync(join(executorDir, ROOT_PROGRAMS_SOURCE)))
+        return undefined;
+    return 'root.programs, root.stop and root.state need an SDK whose executor supports root program settings (root programs beyond root.run, stop and root_state); this SDK\'s executor does not. Use an SDK with this feature, or remove the root settings from dsm-package.yaml.';
+}
+/** Why the run or job limits are outside the executor's bounds; undefined when they are within. */
+export function rootLimitsProblem(value, which) {
+    const bounds = which === 'run' ? RUN_BOUNDS : JOB_BOUNDS;
+    if (!record(value))
+        return `${which} must be an object`;
+    for (const [key, limit] of Object.entries(value)) {
+        const range = bounds[key];
+        if (!range)
+            return `${which}.${key} is not one of ${Object.keys(bounds).join(', ')}`;
+        if (!integer(limit) || limit < range[0] || limit > range[1])
+            return `${which}.${key} must be an integer from ${range[0]} to ${range[1]}`;
+    }
+    return undefined;
+}
+/** Why a params schema is outside the executor's closed JSON Schema subset; undefined when it is inside. */
+export function rootSchemaProblem(schema, depth = 0) {
+    if (!record(schema) || depth > 8)
+        return 'a schema is an object nested at most 8 levels';
+    const type = schema.type;
+    if (typeof type !== 'string' || !SCHEMA_TYPES.includes(type))
+        return `type must be one of ${SCHEMA_TYPES.join(', ')}`;
+    const allowed = ['type', 'enum', ...{ string: STRING_KEYWORDS, integer: NUMBER_KEYWORDS, number: NUMBER_KEYWORDS, boolean: [], array: ARRAY_KEYWORDS, object: OBJECT_KEYWORDS }[type]];
+    const other = Object.keys(schema).find(key => !allowed.includes(key));
+    if (other)
+        return `${type} schema cannot have ${other}`;
+    for (const key of ['minLength', 'maxLength', 'minItems', 'maxItems'])
+        if (key in schema && !integer(schema[key]))
+            return `${key} must be an integer`;
+    for (const key of NUMBER_KEYWORDS)
+        if (key in schema && typeof schema[key] !== 'number')
+            return `${key} must be a number`;
+    if ('pattern' in schema) {
+        const pattern = schema.pattern;
+        if (typeof pattern !== 'string' || NOT_RE2.test(pattern))
+            return 'pattern must be an RE2 regular expression (no lookaround or backreferences)';
+        try {
+            new RegExp(pattern, 'u');
+        }
+        catch {
+            return `pattern ${pattern} does not compile`;
+        }
+    }
+    if (type === 'array') {
+        if (!('items' in schema))
+            return 'array schema needs items';
+        const items = rootSchemaProblem(schema.items, depth + 1);
+        if (items)
+            return `items: ${items}`;
+    }
+    if (type === 'object') {
+        if (schema.additionalProperties !== false)
+            return 'every object schema sets additionalProperties: false';
+        if ('enum' in schema)
+            return 'object schema cannot have enum';
+        const properties = schema.properties ?? {};
+        if (!record(properties))
+            return 'properties must be an object';
+        for (const [key, property] of Object.entries(properties)) {
+            if (!PARAM_KEY.test(key))
+                return `property ${key} must match [a-z0-9_]{1,64}`;
+            const problem = rootSchemaProblem(property, depth + 1);
+            if (problem)
+                return `${key}: ${problem}`;
+        }
+        const required = schema.required ?? [];
+        if (!Array.isArray(required) || required.some(key => typeof key !== 'string' || !Object.hasOwn(properties, key)))
+            return 'required must name properties';
+    }
+    if ('enum' in schema && (!Array.isArray(schema.enum) || schema.enum.some(value => !matchesType(value, type))))
+        return `enum values must be ${type}s`;
+    return undefined;
+}
+function matchesType(value, type) {
+    switch (type) {
+        case 'string': return typeof value === 'string';
+        case 'integer': return integer(value);
+        case 'number': return typeof value === 'number';
+        case 'boolean': return typeof value === 'boolean';
+        case 'array': return Array.isArray(value);
+        default: return false;
+    }
+}
+/** Why a policy root entry would make the executor refuse the policy; undefined when it would not. */
+export function rootEntryProblem(entry) {
+    if (typeof entry === 'string')
+        return /^[a-f0-9]{64}$/.test(entry) ? undefined : 'digest must be 64 lowercase hex digits';
+    if (!record(entry))
+        return 'an entry is a digest or an object';
+    const other = Object.keys(entry).find(key => !['digest', 'kind', 'schema', 'run', 'job'].includes(key));
+    if (other)
+        return `an entry cannot have ${other}`;
+    if (typeof entry.digest !== 'string' || !/^[a-f0-9]{64}$/.test(entry.digest))
+        return 'digest must be 64 lowercase hex digits';
+    if (entry.kind !== 'script' && entry.kind !== 'binary')
+        return 'kind is script or binary';
+    if ('schema' in entry) {
+        if (!record(entry.schema) || entry.schema.type !== 'object')
+            return 'schema must be an object schema';
+        const problem = rootSchemaProblem(entry.schema);
+        if (problem)
+            return `schema: ${problem}`;
+    }
+    for (const which of ['run', 'job']) {
+        if (which in entry) {
+            const problem = rootLimitsProblem(entry[which], which);
+            if (problem)
+                return problem;
+        }
+    }
+    return undefined;
+}

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

@@ -1,8 +1,8 @@
 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";
-/** The Rust SDK crate, a git dependency on a release tag of the SDK repository. */
-export declare const SDK_CRATE = "syno-pkg-land-sdk";
+/** The thin Rust App crate (spec/bridge/v1), a git dependency on a release tag of the SDK repository. */
+export declare const SDK_CRATE = "syno-pkg-land-app";
 export declare const SDK_GIT_URL = "https://github.com/synopackageland/syno-pkg-land-sdk";
 /** Where one SDK version's Go client and executor sources are read from. */
 export interface SdkSource {
@@ -13,10 +13,11 @@ export interface SdkSource {
 }
 /** How each backend declares the SDK. */
 export declare const SDK_DEPENDENCY: Record<SdkBackend['kind'], string>;
-/** The App backend whose dependency files name its SDK version. */
+/** The App backend whose dependency files, or for python and node whose `sdk`, name its SDK version. */
 export interface SdkBackend {
-    kind: 'go' | 'rust';
+    kind: 'go' | 'rust' | 'python' | 'node';
     dir: string;
+    sdk?: string;
 }
 /** The SDK version an App requires, read from its backend's dependency files. */
 export declare function appSdkVersion(backend: SdkBackend): string | undefined;

package/dist/runtime/sdk-source.js

@@ -5,16 +5,20 @@ 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 Rust SDK crate, a git dependency on a release tag of the SDK repository. */
-export const SDK_CRATE = 'syno-pkg-land-sdk';
+/** The thin Rust App crate (spec/bridge/v1), a git dependency on a release tag of the SDK repository. */
+export const SDK_CRATE = 'syno-pkg-land-app';
 export const SDK_GIT_URL = `https://${SDK_MODULE}`;
 /** How each backend declares the SDK. */
 export const SDK_DEPENDENCY = {
     go: `add \`require ${SDK_MODULE} v<version>\` to backend/go.mod.`,
-    rust: `add \`${SDK_CRATE} = { git = "${SDK_GIT_URL}", tag = "v<version>" }\` to backend/Cargo.toml and commit Cargo.lock.`,
+    rust: `add \`${SDK_CRATE} = { git = "${SDK_GIT_URL}", tag = "v<version>" }\` to the App's Cargo.toml and commit Cargo.lock.`,
+    python: 'set backend.sdk: <version> in dsm-package.yaml.',
+    node: 'set backend.sdk: <version> in dsm-package.yaml.',
 };
 /** The SDK version an App requires, read from its backend's dependency files. */
 export function appSdkVersion(backend) {
+    if (backend.kind === 'python' || backend.kind === 'node')
+        return backend.sdk;
     return backend.kind === 'go' ? sdkRequirement(backend.dir) : cargoSdkRequirement(backend.dir);
 }
 /**
@@ -37,7 +41,7 @@ function cargoSdkRequirement(backendDir) {
     const tag = new RegExp(`^source = "git\\+${SDK_GIT_URL.replaceAll('.', '\\.')}\\?tag=v(\\d+\\.\\d+\\.\\d+)#[0-9a-f]{40}"$`, 'm');
     const version = sdk.length === 1 ? tag.exec(sdk[0])?.[1] : undefined;
     if (!version)
-        throw new Error(`[SDK_TAG_REQUIRED] backend/Cargo.lock must pin one ${SDK_CRATE} from a release tag: { git = "${SDK_GIT_URL}", tag = "vX.Y.Z" } in Cargo.toml, then cargo update -p ${SDK_CRATE}.`);
+        throw new Error(`[SDK_TAG_REQUIRED] Cargo.lock must pin one ${SDK_CRATE} from a release tag: { git = "${SDK_GIT_URL}", tag = "vX.Y.Z" } in Cargo.toml, then cargo update -p ${SDK_CRATE}.`);
     return version;
 }
 /** The SDK version a Go backend requires: `require github.com/synopackageland/syno-pkg-land-sdk vX.Y.Z` in backend/go.mod, its only version source. */

package/dist/skill.js

@@ -2,16 +2,16 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const SKILL_CATALOG = [
-    { id: "orchestrator", file: "SKILL.md", when: "永遠先讀" },
-    { id: "create", file: "reference/create.md", when: "從零或一句話開始" },
-    { id: "wrap", file: "reference/wrap.md", when: "已有 Compose 或要補契約" },
-    { id: "identity", file: "reference/identity.md", when: "需要 DSM 登入者" },
-    { id: "files", file: "reference/files.md", when: "需要 NAS 檔案" },
-    { id: "portal", file: "reference/portal.md", when: "需要 DSM Application Portal 別名連結" },
-    { id: "ui-vue", file: "reference/ui-vue.md", when: "編寫／檢查 Vue UI" },
-    { id: "ui-json", file: "reference/ui-json.md", when: "產生／檢查 JSON UI" },
-    { id: "deploy", file: "reference/deploy.md", when: "要放到 NAS" },
-    { id: "diagnose", file: "reference/diagnose.md", when: "check／deploy／Open 失敗" },
+    { id: "orchestrator", file: "SKILL.md", when: "Read first" },
+    { id: "create", file: "reference/create.md", when: "Start from nothing or a one-liner" },
+    { id: "wrap", file: "reference/wrap.md", when: "Existing Compose, or adding a contract" },
+    { id: "identity", file: "reference/identity.md", when: "Needs a DSM sign-in" },
+    { id: "files", file: "reference/files.md", when: "Needs NAS files" },
+    { id: "portal", file: "reference/portal.md", when: "Needs a DSM Application Portal alias link" },
+    { id: "ui-vue", file: "reference/ui-vue.md", when: "Write or check a Vue UI" },
+    { id: "ui-json", file: "reference/ui-json.md", when: "Generate or check a JSON UI" },
+    { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
+    { id: "diagnose", file: "reference/diagnose.md", when: "check/deploy/Open failed" },
 ];
 export function resolveSkillsRoot() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -24,7 +24,7 @@ export function resolveSkillsRoot() {
             return candidate;
         }
     }
-    throw new Error("找不到 Skill Pack。請重新安裝 @synopackageland/cli。");
+    throw new Error("Skill Pack not found. Reinstall @synopackageland/cli.");
 }
 export function listSkills() {
     return [...SKILL_CATALOG];
@@ -32,11 +32,11 @@ export function listSkills() {
 export function skillPath(id) {
     const entry = SKILL_CATALOG.find((item) => item.id === id);
     if (!entry) {
-        throw new Error(`未知 skill：${id}`);
+        throw new Error(`Unknown skill: ${id}`);
     }
     const path = join(resolveSkillsRoot(), entry.file);
     if (!existsSync(path)) {
-        throw new Error(`Skill 檔案不存在：${entry.file}`);
+        throw new Error(`Skill file does not exist: ${entry.file}`);
     }
     return path;
 }
@@ -45,7 +45,7 @@ export function readSkill(id) {
 }
 export function formatSkillList() {
     const root = resolveSkillsRoot();
-    const lines = [`Skill Pack：${root}`, ""];
+    const lines = [`Skill Pack: ${root}`, ""];
     for (const entry of SKILL_CATALOG) {
         lines.push(`${entry.id}\t${entry.when}\t${entry.file}`);
     }

package/dist/spk/check-info.js

@@ -15,7 +15,7 @@ export function parseInfo(text, findings) {
             return;
         const match = /^([A-Za-z0-9_]+)=(.*)$/.exec(line);
         if (!match) {
-            findings?.add("SPK_INFO_LINE_INVALID", `INFO 第 ${index + 1} 行不是 key="value"：${line.slice(0, 60)}`, "INFO");
+            findings?.add("SPK_INFO_LINE_INVALID", `INFO line ${index + 1} is not key="value": ${line.slice(0, 60)}`, "INFO");
             return;
         }
         const [, key, raw] = match;
@@ -23,13 +23,13 @@ export function parseInfo(text, findings) {
         if (raw.startsWith('"')) {
             const quoted = /^"((?:[^"\\]|\\.)*)"\s*$/.exec(raw);
             if (!quoted) {
-                findings?.add("SPK_INFO_VALUE_UNTERMINATED", `INFO 第 ${index + 1} 行 ${key} 的引號沒有結束。`, "INFO");
+                findings?.add("SPK_INFO_VALUE_UNTERMINATED", `INFO line ${index + 1} has an unterminated value quote for ${key}.`, "INFO");
                 return;
             }
             value = quoted[1].replace(/\\(.)/g, "$1");
         }
         if (fields.has(key))
-            findings?.add("SPK_INFO_FIELD_DUPLICATE", `INFO 重複設定 ${key}；只有一個值會生效。`, "INFO");
+            findings?.add("SPK_INFO_FIELD_DUPLICATE", `INFO sets ${key} twice; only one value takes effect.`, "INFO");
         fields.set(key, value);
     });
     return fields;
@@ -45,19 +45,19 @@ function compareOsVer(a, b) {
 function checkVersion(version, findings) {
     const parts = version.split(/[._-]/);
     if (parts.some((part) => !/^\d+$/.test(part) || Number(part) > MAX_VERSION_PART)) {
-        findings.add("SPK_INFO_VERSION_INVALID", `INFO version「${version}」只能是以 .、-、_ 分隔的數字（每段 0–2147483647），例如 1.2.3-0001。`, "INFO");
+        findings.add("SPK_INFO_VERSION_INVALID", `INFO version "${version}" must be numbers separated by . - _ (each segment 0-2147483647), for example 1.2.3-0001.`, "INFO");
     }
     else if (!version.includes("-")) {
-        findings.add("SPK_INFO_VERSION_NO_BUILD", `INFO version「${version}」沒有 -<build> 編號；指南格式為 [feature number]-[build number]，例如 ${version}-0001。`, "INFO");
+        findings.add("SPK_INFO_VERSION_NO_BUILD", `INFO version "${version}" has no -<build> number; the guide format is [feature number]-[build number], for example ${version}-0001.`, "INFO");
     }
 }
 function checkArch(field, value, findings) {
     const tokens = value.split(/\s+/).filter(Boolean);
     for (const token of tokens.filter((t) => !ARCH_ELF_MACHINE.has(t))) {
-        findings.add("SPK_INFO_ARCH_UNKNOWN", `INFO ${field} 含有指南 Appendix A 與已知 DSM 7 平台都沒有的值「${token}」。`, "INFO");
+        findings.add("SPK_INFO_ARCH_UNKNOWN", `INFO ${field} has a value that is in neither the guide's Appendix A nor the known DSM 7 platforms: "${token}".`, "INFO");
     }
     if (field === "arch" && tokens.includes("noarch") && tokens.length > 1) {
-        findings.add("SPK_INFO_ARCH_NOARCH_MIXED", `INFO arch「${value}」同時有 noarch 與其他值；noarch 已代表所有平台。`, "INFO");
+        findings.add("SPK_INFO_ARCH_NOARCH_MIXED", `INFO arch "${value}" has noarch together with other values; noarch already covers every platform.`, "INFO");
     }
 }
 function checkTranslations(key, findings) {
@@ -65,7 +65,7 @@ function checkTranslations(key, findings) {
     if (!match)
         return false;
     if (!LANGUAGES.has(match[2])) {
-        findings.add("SPK_INFO_LANG_UNKNOWN", `INFO ${key} 的語言碼「${match[2]}」不在指南的清單（${INFO_LANGUAGES.join("、")}）。`, "INFO");
+        findings.add("SPK_INFO_LANG_UNKNOWN", `The language code of INFO ${key} is "${match[2]}", not in the guide list (${INFO_LANGUAGES.join(", ")}).`, "INFO");
     }
     return true;
 }
@@ -73,14 +73,14 @@ function checkTranslations(key, findings) {
 export function checkInfoFields(fields, payloadPath, findings) {
     for (const key of REQUIRED_INFO_FIELDS) {
         if (!fields.get(key))
-            findings.add("SPK_INFO_FIELD_REQUIRED", `INFO 缺少必填欄位 ${key}。`, "INFO");
+            findings.add("SPK_INFO_FIELD_REQUIRED", `INFO is missing required field ${key}.`, "INFO");
     }
     if (!fields.get("displayname")) {
-        findings.add("SPK_INFO_DISPLAYNAME_MISSING", "INFO 沒有 displayname；Package Center 會顯示 package 值。", "INFO");
+        findings.add("SPK_INFO_DISPLAYNAME_MISSING", "INFO has no displayname; Package Center shows the package value.", "INFO");
     }
     const pkg = fields.get("package");
     if (pkg && /[:/><|=]/.test(pkg)) {
-        findings.add("SPK_INFO_PACKAGE_INVALID", `INFO package「${pkg}」不能含有 : / > < | =。`, "INFO");
+        findings.add("SPK_INFO_PACKAGE_INVALID", `INFO package "${pkg}" cannot contain : / > < | =.`, "INFO");
     }
     const version = fields.get("version");
     if (version)
@@ -90,10 +90,10 @@ export function checkInfoFields(fields, payloadPath, findings) {
         if (!value)
             continue;
         if (!OS_VER.test(value)) {
-            findings.add("SPK_INFO_OS_VER_INVALID", `INFO ${key}「${value}」不是 <major>.<minor>-<build>（例如 7.0-40000）。`, "INFO");
+            findings.add("SPK_INFO_OS_VER_INVALID", `INFO ${key} "${value}" is not <major>.<minor>-<build> (for example 7.0-40000).`, "INFO");
         }
         else if (key === "os_min_ver" && compareOsVer(value, DSM7_MIN_VER) < 0) {
-            findings.add("SPK_INFO_OS_MIN_VER_LOW", `INFO os_min_ver「${value}」低於 ${DSM7_MIN_VER}；DSM 7 套件應至少為 ${DSM7_MIN_VER}。`, "INFO");
+            findings.add("SPK_INFO_OS_MIN_VER_LOW", `INFO os_min_ver "${value}" is below ${DSM7_MIN_VER}; a DSM 7 package should be at least ${DSM7_MIN_VER}.`, "INFO");
         }
     }
     for (const key of ["arch", "exclude_arch"]) {
@@ -103,21 +103,21 @@ export function checkInfoFields(fields, payloadPath, findings) {
     }
     for (const [key, value] of fields) {
         if (BOOLEAN_FIELDS.has(key) && value !== "yes" && value !== "no") {
-            findings.add("SPK_INFO_BOOLEAN_INVALID", `INFO ${key}「${value}」只能是 "yes" 或 "no"。`, "INFO");
+            findings.add("SPK_INFO_BOOLEAN_INVALID", `INFO ${key} "${value}" can only be "yes" or "no".`, "INFO");
         }
         if (!checkTranslations(key, findings) && !KNOWN_FIELDS.has(key)) {
-            findings.add("SPK_INFO_FIELD_UNKNOWN", `INFO ${key} 不是指南列出的欄位；DSM 不會使用它。`, "INFO");
+            findings.add("SPK_INFO_FIELD_UNKNOWN", `INFO ${key} is not a field the guide lists; DSM does not use it.`, "INFO");
         }
     }
     const adminport = fields.get("adminport");
     if (adminport !== undefined && (!/^\d+$/.test(adminport) || Number(adminport) > 65536)) {
-        findings.add("SPK_INFO_ADMINPORT_INVALID", `INFO adminport「${adminport}」必須是 0–65536 的整數。`, "INFO");
+        findings.add("SPK_INFO_ADMINPORT_INVALID", `INFO adminport "${adminport}" must be an integer from 0 to 65536.`, "INFO");
     }
     const checksum = fields.get("checksum");
     if (checksum && payloadPath) {
         const actual = createHash("md5").update(readFileSync(payloadPath)).digest("hex");
         if (checksum.toLowerCase() !== actual) {
-            findings.add("SPK_INFO_CHECKSUM_MISMATCH", `INFO checksum「${checksum}」不是 package.tgz 的 MD5（${actual}）。`, "INFO");
+            findings.add("SPK_INFO_CHECKSUM_MISMATCH", `INFO checksum "${checksum}" is not the MD5 of package.tgz (${actual}).`, "INFO");
         }
     }
 }

package/dist/spk/check-metadata.js

@@ -22,22 +22,22 @@ function checkScripts({ files, modes }, findings) {
         const body = files.get(path);
         if (!body) {
             if (name === "start-stop-status")
-                findings.add("SPK_SCRIPT_MISSING", `缺少 ${path}；DSM 用它啟動、停止與查詢套件狀態。`, path);
+                findings.add("SPK_SCRIPT_MISSING", `${path} is missing; DSM uses it to start, stop and query the package status.`, path);
             else if (LIFECYCLE_SCRIPTS.includes(name))
-                findings.add("SPK_SCRIPT_HOOK_MISSING", `缺少 ${path}；指南把它列為必備，沒有事要做時寫 #!/bin/sh 與 exit 0。`, path);
+                findings.add("SPK_SCRIPT_HOOK_MISSING", `${path} is missing; the guide lists it as required, so write #!/bin/sh with exit 0 when there is nothing to do.`, path);
             continue;
         }
         if (!executable(modes.get(path)))
-            findings.add("SPK_SCRIPT_NOT_EXECUTABLE", `${path} 沒有執行權限（mode ${(modes.get(path) ?? 0).toString(8)}）；打包前 chmod 755。`, path);
+            findings.add("SPK_SCRIPT_NOT_EXECUTABLE", `${path} is not executable (mode ${(modes.get(path) ?? 0).toString(8)}); chmod 755 it before packaging.`, path);
         const head = body.subarray(0, 4).toString("latin1");
         if (!head.startsWith("#!") && head !== "\x7fELF")
-            findings.add("SPK_SCRIPT_NO_INTERPRETER", `${path} 開頭沒有 #!（例如 #!/bin/sh）。`, path);
+            findings.add("SPK_SCRIPT_NO_INTERPRETER", `${path} does not start with #! (for example #!/bin/sh).`, path);
     }
 }
 function checkPrivilege(files, findings) {
     const path = "conf/privilege";
     if (!files.has(path)) {
-        findings.add("SPK_PRIVILEGE_MISSING", "缺少 conf/privilege；DSM 7 起每個套件都必須明確宣告執行身分。", path);
+        findings.add("SPK_PRIVILEGE_MISSING", "conf/privilege is missing; from DSM 7 every package must declare its run identity explicitly.", path);
         return;
     }
     const privilege = parseJson(files.get(path));
@@ -47,11 +47,11 @@ function checkPrivilege(files, findings) {
         : [];
     const values = isRecord(privilege) ? [runAs(privilege.defaults), ...listed] : [];
     if (!isRecord(privilege) || values.some((value) => typeof value !== "string" || !RUN_AS.includes(value))) {
-        findings.add("SPK_PRIVILEGE_INVALID", 'conf/privilege 必須是 JSON 物件，有 defaults.run-as，且每個 run-as 是 "package" 或 "root"。', path);
+        findings.add("SPK_PRIVILEGE_INVALID", 'conf/privilege must be a JSON object with defaults.run-as, and every run-as must be "package" or "root".', path);
         return;
     }
     if (values.includes("root"))
-        findings.add("SPK_PRIVILEGE_ROOT", "conf/privilege 要求以 root 執行；DSM 7 第三方套件應以 package 帳號執行。", path);
+        findings.add("SPK_PRIVILEGE_ROOT", "conf/privilege requires running as root; a DSM 7 third-party package should run as the package account.", path);
 }
 function checkConf({ files, modes }, findings) {
     checkPrivilege(files, findings);
@@ -59,27 +59,27 @@ function checkConf({ files, modes }, findings) {
     if (files.has(resourcePath)) {
         const resource = parseJson(files.get(resourcePath));
         if (!isRecord(resource))
-            findings.add("SPK_RESOURCE_INVALID", "conf/resource 不是 JSON 物件。", resourcePath);
+            findings.add("SPK_RESOURCE_INVALID", "conf/resource is not a JSON object.", resourcePath);
         else
             for (const id of Object.keys(resource).filter((key) => !WORKERS.has(key))) {
-                findings.add("SPK_RESOURCE_UNKNOWN", `conf/resource 的「${id}」不是指南列出的 resource worker。`, resourcePath);
+                findings.add("SPK_RESOURCE_UNKNOWN", `conf/resource "${id}" is not a resource worker the guide lists.`, resourcePath);
             }
     }
     const names = new Set([...modes.keys()].filter((path) => path.startsWith("conf/")).map((path) => path.split("/")[1]).filter(Boolean));
     for (const name of [...names].filter((n) => !CONF.has(n)))
-        findings.add("SPK_CONF_UNKNOWN", `conf/${name} 不是 DSM 讀取的設定檔。`, `conf/${name}`);
+        findings.add("SPK_CONF_UNKNOWN", `conf/${name} is not a config file DSM reads.`, `conf/${name}`);
 }
 function checkIcons(files, findings) {
     for (const [name, size] of PACKAGE_ICONS) {
         const png = files.get(name);
         if (!png) {
-            findings.add("SPK_ICON_MISSING", `缺少 ${name}（${size}×${size} PNG）。`, name);
+            findings.add("SPK_ICON_MISSING", `${name} is missing (a ${size}x${size} PNG).`, name);
         }
         else if (png.length < 24 || !png.subarray(0, 8).equals(PNG_SIGNATURE) || png.toString("latin1", 12, 16) !== "IHDR") {
-            findings.add("SPK_ICON_INVALID", `${name} 不是 PNG。`, name);
+            findings.add("SPK_ICON_INVALID", `${name} is not a PNG.`, name);
         }
         else if (png.readUInt32BE(16) !== size || png.readUInt32BE(20) !== size) {
-            findings.add("SPK_ICON_SIZE", `${name} 是 ${png.readUInt32BE(16)}×${png.readUInt32BE(20)}，指南要求 ${size}×${size}。`, name);
+            findings.add("SPK_ICON_SIZE", `${name} is ${png.readUInt32BE(16)}x${png.readUInt32BE(20)}; the guide requires ${size}x${size}.`, name);
         }
     }
 }
@@ -87,14 +87,14 @@ function checkWizards({ files, modes }, findings) {
     for (const path of [...modes.keys()].filter((p) => p.startsWith("WIZARD_UIFILES/") && files.has(p))) {
         const name = path.slice("WIZARD_UIFILES/".length);
         if (!WIZARD_NAME.test(name)) {
-            findings.add("SPK_WIZARD_UNKNOWN", `${path} 不是 install／upgrade／uninstall_uifile[_<lang>][.sh]；DSM 不會讀它。`, path);
+            findings.add("SPK_WIZARD_UNKNOWN", `${path} is not install/upgrade/uninstall_uifile[_<lang>][.sh]; DSM does not read it.`, path);
         }
         else if (name.endsWith(".sh")) {
             if (!executable(modes.get(path)))
-                findings.add("SPK_WIZARD_SCRIPT_NOT_EXECUTABLE", `${path} 沒有執行權限；DSM 執行它來產生精靈。`, path);
+                findings.add("SPK_WIZARD_SCRIPT_NOT_EXECUTABLE", `${path} is not executable; DSM runs it to generate the wizard.`, path);
         }
         else if (!Array.isArray(parseJson(files.get(path)))) {
-            findings.add("SPK_WIZARD_INVALID", `${path} 不是 JSON 陣列（每個元素是一個精靈步驟）。`, path);
+            findings.add("SPK_WIZARD_INVALID", `${path} is not a JSON array (each element is a wizard step).`, path);
         }
     }
 }
@@ -105,9 +105,9 @@ export function checkMetadata(outer, findings) {
     checkWizards(outer, findings);
     const license = outer.files.get("LICENSE");
     if (license && license.length >= MAX_LICENSE_BYTES)
-        findings.add("SPK_LICENSE_TOO_LARGE", `LICENSE 有 ${license.length} bytes；指南要求小於 1 MB。`, "LICENSE");
+        findings.add("SPK_LICENSE_TOO_LARGE", `LICENSE is ${license.length} bytes; the guide requires less than 1 MB.`, "LICENSE");
     const signature = outer.files.get("syno_signature.asc");
     if (signature && !signature.toString("latin1").includes("-----BEGIN PGP SIGNATURE-----")) {
-        findings.add("SPK_SIGNATURE_INVALID", "syno_signature.asc 不是 ASCII-armored PGP 簽章。", "syno_signature.asc");
+        findings.add("SPK_SIGNATURE_INVALID", "syno_signature.asc is not an ASCII-armored PGP signature.", "syno_signature.asc");
     }
 }