@synopackageland/cli 0.3.10 → 0.4.1

package/dist/standalone/lifecycle.js

@@ -0,0 +1,53 @@
+import { renderHelperStoppedCheck } from "./lifecycle-helper.js";
+/** Non-privileged hooks: precheck gates DSM management; no hook tears down root. */
+export function renderStandaloneScript(name, manifest) {
+    if (manifest.daemon)
+        return renderDaemonScript(name, manifest);
+    if (manifest.integration && ["preupgrade", "preuninst", "start-stop-status"].includes(name)) {
+        const check = renderHelperStoppedCheck(manifest.package);
+        if (name !== "start-stop-status")
+            return `#!/bin/sh\n${check}`;
+        return `#!/bin/sh
+case "$1" in
+  # Start the ordinary app even when integration is disabled or needs cleanup.
+  # No root enable/recover here; the administrator must explicitly approve it.
+  prestart|start|status) exit 0 ;;
+  prestop|stop)
+  # prestop is the management veto. stop runs inside ExecStop: its failure
+  # reports unsafe residue but cannot keep the DSM unit active.
+${check}    ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    if (name === "start-stop-status") {
+        return `#!/bin/sh
+case "$1" in
+  start|stop|status) exit 0 ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    return "#!/bin/sh\nexit 0\n";
+}
+function renderDaemonScript(name, manifest) {
+    const pkg = manifest.package;
+    const control = `"/var/packages/${pkg}/target/daemon/control"`;
+    const paths = `"\${SYNOPKG_PKGDEST:-/var/packages/${pkg}/target}" "\${SYNOPKG_PKGVAR:-/var/packages/${pkg}/var}"`;
+    const check = manifest.integration ? renderHelperStoppedCheck(pkg) : "";
+    if (["preupgrade", "preuninst"].includes(name))
+        return `#!/bin/sh\n${check}exec ${control} ${name === "preuninst" && manifest.daemon?.uninstall_args ? "uninstall" : "stop"} ${paths}\n`;
+    if (name !== "start-stop-status")
+        return "#!/bin/sh\nexit 0\n";
+    return `#!/bin/sh
+case "$1" in
+  prestart) exit 0 ;;
+  prestop)
+${check}    exit 0 ;;
+  start|status) exec ${control} "$1" ${paths} ;;
+  stop|restart)
+${check}    exec ${control} "$1" ${paths} ;;
+  *) exit 1 ;;
+esac
+`;
+}

package/dist/standalone/manifest.d.ts

@@ -0,0 +1,73 @@
+import { type NativeArchFamily } from "../build-spk/dsm-arch.js";
+import { type Catalogs, type Locale } from "./i18n.js";
+import { type RootOp } from "./root-ops.js";
+import { type Integration } from "./helper.js";
+import { type Daemon } from "./daemon.js";
+/**
+ * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
+ * runs as its own DSM package account with a CGI backend and a DSM window UI.
+ */
+export declare const STANDALONE_MANIFEST = "dsm-package.yaml";
+export type StandaloneBackend = {
+    kind: "go";
+    dir: string;
+    main: string;
+} | {
+    kind: "binary";
+    files: Partial<Record<NativeArchFamily, string>>;
+};
+export interface InfoText {
+    displayname?: string;
+    description?: string;
+}
+export interface StandaloneI18n {
+    /** UI messages per locale, embedded into the DSM window. */
+    catalogs?: Catalogs;
+    /** INFO `displayname_<dsm lang>` / `description_<dsm lang>`. */
+    info: Partial<Record<Locale, InfoText>>;
+}
+export interface StandaloneManifest {
+    root: string;
+    package: string;
+    version: string;
+    build: number;
+    /** INFO version: `<version>-<build, 4 digits>`. */
+    spkVersion: string;
+    displayname: string;
+    description: string;
+    maintainer: string;
+    os_min_ver: string;
+    arches: NativeArchFamily[];
+    backend: StandaloneBackend;
+    ui: {
+        dir: string;
+        build?: {
+            cwd: string;
+            command: string[];
+        };
+    };
+    i18n?: StandaloneI18n;
+    /** `none`: the package account only. `root`: adds DSM-approved root tasks. */
+    privilege: "none" | "root";
+    /** `root/<name>.sh`, present exactly when privilege is root. */
+    rootOps?: RootOp[];
+    integration?: Integration;
+    daemon?: Daemon;
+}
+export interface StandaloneError {
+    code: string;
+    message: string;
+}
+export type ManifestResult = {
+    ok: true;
+    manifest: StandaloneManifest;
+} | {
+    ok: false;
+    errors: StandaloneError[];
+};
+export declare function loadStandaloneManifest(root: string): ManifestResult;
+/**
+ * The nearest directory at or above `start` that holds dsm-package.yaml,
+ * unless a Managed Profile project (synology-app.yaml) is found first.
+ */
+export declare function findStandaloneRoot(start: string): string | null;

package/dist/standalone/manifest.js

@@ -0,0 +1,279 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { isNativeArchFamily } from "../build-spk/dsm-arch.js";
+import { checkGlossary, isLocale, loadCatalogs } from "./i18n.js";
+import { loadRootOps, ROOT_OPS_DIR } from "./root-ops.js";
+import { readIntegration } from "./helper.js";
+import { readDaemon } from "./daemon.js";
+/**
+ * `dsm-package.yaml`: a Standalone Package, i.e. an unsigned native SPK that
+ * runs as its own DSM package account with a CGI backend and a DSM window UI.
+ */
+export const STANDALONE_MANIFEST = "dsm-package.yaml";
+const KNOWN_FIELDS = new Set([
+    "schema", "package", "version", "build", "displayname", "description",
+    "maintainer", "os_min_ver", "arches", "backend", "ui", "privilege", "i18n", "integration", "daemon",
+]);
+const I18N_FIELDS = new Set(["messages", "glossary", "info"]);
+const INFO_TEXT_FIELDS = new Set(["displayname", "description"]);
+const PACKAGE_ID = /^[A-Za-z][A-Za-z0-9]{1,63}$/;
+const VERSION = /^\d+(\.\d+){0,3}$/;
+const OS_MIN_VER = /^\d+\.\d+(\.\d+)?-\d+$/;
+const GO_MAIN = /^\.\/[A-Za-z0-9_./-]*$/;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+class Collector {
+    root;
+    errors = [];
+    constructor(root) {
+        this.root = root;
+    }
+    fail(code, message) {
+        this.errors.push({ code, message });
+        return undefined;
+    }
+    /** A project-relative path that stays inside the project. */
+    path(value, field) {
+        if (typeof value !== "string" || value.trim() === "") {
+            return this.fail("STANDALONE_PATH_INVALID", `${field} 必須是專案內的相對路徑。`);
+        }
+        const resolved = resolve(this.root, value);
+        const rel = relative(this.root, resolved);
+        if (isAbsolute(value) || rel.startsWith("..") || isAbsolute(rel)) {
+            return this.fail("STANDALONE_PATH_OUTSIDE_PROJECT", `${field}「${value}」必須位於專案目錄內。`);
+        }
+        return resolved;
+    }
+    text(value, field) {
+        if (typeof value !== "string" || value.trim() === "" || /[\r\n"\\]/.test(value)) {
+            return this.fail("STANDALONE_TEXT_INVALID", `${field} 必須是單行、非空且不含 " 或 \\ 的文字。`);
+        }
+        return value;
+    }
+}
+export function loadStandaloneManifest(root) {
+    const file = join(root, STANDALONE_MANIFEST);
+    if (!existsSync(file)) {
+        return { ok: false, errors: [{ code: "STANDALONE_MANIFEST_MISSING", message: `找不到 ${STANDALONE_MANIFEST}。` }] };
+    }
+    let raw;
+    try {
+        raw = parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return { ok: false, errors: [{ code: "STANDALONE_MANIFEST_YAML", message: String(error) }] };
+    }
+    const c = new Collector(root);
+    if (!isRecord(raw)) {
+        c.fail("STANDALONE_MANIFEST_YAML", `${STANDALONE_MANIFEST} 必須是 YAML 物件。`);
+        return { ok: false, errors: c.errors };
+    }
+    const manifest = readManifest(raw, c);
+    return manifest && c.errors.length === 0 ? { ok: true, manifest } : { ok: false, errors: c.errors };
+}
+function readManifest(raw, c) {
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_FIELDS.has(key)) {
+            c.fail("STANDALONE_FIELD_UNKNOWN", `不支援的欄位「${key}」。Standalone Package 不接受自訂 lifecycle scripts 或 DSM conf。`);
+        }
+    }
+    if (raw.schema !== 1) {
+        c.fail("STANDALONE_SCHEMA_INVALID", "schema 必須是 1。");
+    }
+    const privilege = raw.privilege === "none" || raw.privilege === "root"
+        ? raw.privilege
+        : c.fail("STANDALONE_PRIVILEGE_UNSUPPORTED", "privilege 只接受 none（只用套件帳號）或 root（由 DSM 管理員核准的 root 工作）；請見 README「Root access」。");
+    const rootOps = privilege && readRootOps(privilege, c);
+    const packageId = typeof raw.package === "string" && PACKAGE_ID.test(raw.package)
+        ? raw.package
+        : c.fail("STANDALONE_PACKAGE_INVALID", "package 必須以英文字母開頭，只含英數字（2–64 字）。");
+    const version = typeof raw.version === "string" && VERSION.test(raw.version)
+        ? raw.version
+        : c.fail("STANDALONE_VERSION_INVALID", "version 必須是數字版本，例如 1.2.0（build 另外填）。");
+    const build = Number.isInteger(raw.build) && raw.build >= 1 && raw.build <= 9999
+        ? raw.build
+        : c.fail("STANDALONE_BUILD_INVALID", "build 必須是 1–9999 的整數。");
+    const osMinVer = typeof raw.os_min_ver === "string" && OS_MIN_VER.test(raw.os_min_ver)
+        ? raw.os_min_ver
+        : c.fail("STANDALONE_OS_MIN_VER_INVALID", "os_min_ver 格式為 <major>.<minor>-<build>，例如 7.2-64570。");
+    const displayname = c.text(raw.displayname, "displayname");
+    const description = c.text(raw.description, "description");
+    const maintainer = c.text(raw.maintainer, "maintainer");
+    const arches = readArches(raw.arches, c);
+    const backend = arches && readBackend(raw.backend, arches, c);
+    const daemon = arches && readDaemon(raw.daemon, c.root, arches, e => c.fail(e.code, e.message));
+    const integration = readIntegration(raw.integration, c.root, e => c.fail(e.code, e.message));
+    if (integration && (privilege !== "root" || backend?.kind !== "go" || rootOps?.some(op => op.name.startsWith("helper_")))) {
+        c.fail("STANDALONE_INTEGRATION_INVALID", "integration 需要 privilege: root 和 backend.go；helper_ 操作名稱保留給 generator。");
+    }
+    const ui = readUi(raw.ui, c);
+    const i18n = raw.i18n === undefined ? undefined : readI18n(raw.i18n, c);
+    if (!packageId || !version || !build || !osMinVer || !displayname || !description || !maintainer
+        || !arches || !backend || !ui || !privilege || (privilege === "root" && !rootOps)) {
+        return undefined;
+    }
+    return {
+        root: c.root,
+        package: packageId,
+        version,
+        build,
+        spkVersion: `${version}-${String(build).padStart(4, "0")}`,
+        displayname,
+        description,
+        maintainer,
+        os_min_ver: osMinVer,
+        arches,
+        backend,
+        ui,
+        ...(i18n ? { i18n } : {}),
+        privilege,
+        ...(rootOps ? { rootOps } : {}),
+        ...(integration ? { integration } : {}),
+        ...(daemon ? { daemon } : {}),
+    };
+}
+function readRootOps(privilege, c) {
+    const dir = join(c.root, ROOT_OPS_DIR);
+    if (privilege === "none") {
+        return existsSync(dir)
+            ? c.fail("STANDALONE_ROOT_OPS_UNUSED", `${ROOT_OPS_DIR}/ 只用在 privilege: root；privilege: none 的套件不會執行它。`)
+            : undefined;
+    }
+    const loaded = loadRootOps(dir);
+    if (!loaded.ok) {
+        loaded.errors.forEach((e) => c.fail(e.code, e.message));
+        return undefined;
+    }
+    return loaded.ops;
+}
+function readArches(value, c) {
+    const ok = Array.isArray(value)
+        && value.length > 0
+        && value.every((arch) => typeof arch === "string" && isNativeArchFamily(arch))
+        && new Set(value).size === value.length;
+    return ok
+        ? value
+        : c.fail("STANDALONE_ARCHES_INVALID", "arches 必須是不重複的 x86_64／aarch64 清單，至少一個。");
+}
+function readBackend(value, arches, c) {
+    if (!isRecord(value) || ("go" in value) === ("binary" in value)) {
+        return c.fail("STANDALONE_BACKEND_INVALID", "backend 必須恰好有 go 或 binary 其中之一。");
+    }
+    if ("go" in value) {
+        const go = value.go;
+        if (!isRecord(go) || typeof go.main !== "string" || !GO_MAIN.test(go.main) || go.main.includes("..")) {
+            return c.fail("STANDALONE_BACKEND_INVALID", "backend.go 需要 dir 與以 ./ 開頭的 main（例如 ./cmd/app）。");
+        }
+        const dir = c.path(go.dir, "backend.go.dir");
+        return dir ? { kind: "go", dir, main: go.main } : undefined;
+    }
+    const binary = value.binary;
+    if (!isRecord(binary)) {
+        return c.fail("STANDALONE_BACKEND_INVALID", "backend.binary 必須以架構為 key 指向 CGI 執行檔。");
+    }
+    const files = {};
+    for (const arch of arches) {
+        if (!(arch in binary)) {
+            c.fail("STANDALONE_BINARY_ARCH_MISSING", `arches 宣告了 ${arch}，但 backend.binary 沒有它的執行檔。`);
+            continue;
+        }
+        files[arch] = c.path(binary[arch], `backend.binary.${arch}`);
+    }
+    for (const key of Object.keys(binary)) {
+        if (!arches.includes(key)) {
+            c.fail("STANDALONE_BACKEND_INVALID", `backend.binary.${key} 不在 arches 內。`);
+        }
+    }
+    return Object.values(files).every(Boolean) ? { kind: "binary", files } : undefined;
+}
+function readUi(value, c) {
+    if (!isRecord(value)) {
+        return c.fail("STANDALONE_UI_INVALID", "ui 必須包含 dir。");
+    }
+    const dir = c.path(value.dir, "ui.dir");
+    if (value.build === undefined) {
+        return dir ? { dir } : undefined;
+    }
+    const build = value.build;
+    const command = isRecord(build) ? build.command : undefined;
+    if (!Array.isArray(command) || command.length === 0 || !command.every((arg) => typeof arg === "string" && arg !== "")) {
+        return c.fail("STANDALONE_UI_BUILD_INVALID", "ui.build.command 必須是 argv 字串陣列（不經 shell），例如 [npm, run, build]。");
+    }
+    const cwd = c.path(build.cwd, "ui.build.cwd");
+    return dir && cwd ? { dir, build: { cwd, command: command } } : undefined;
+}
+function readI18n(value, c) {
+    const invalid = (why) => c.fail("STANDALONE_I18N_INVALID", `i18n ${why}`);
+    if (!isRecord(value) || Object.keys(value).some((key) => !I18N_FIELDS.has(key))) {
+        return invalid("只接受 messages（訊息目錄）、glossary（用語表）與 info（各語言 INFO 文字）。");
+    }
+    const info = readInfoText(value.info, c);
+    if (value.messages === undefined) {
+        return value.glossary === undefined ? info && { info } : invalid("glossary 需要搭配 messages。");
+    }
+    const dir = c.path(value.messages, "i18n.messages");
+    const glossary = value.glossary === undefined ? undefined : c.path(value.glossary, "i18n.glossary");
+    if (!dir || (value.glossary !== undefined && !glossary)) {
+        return undefined;
+    }
+    const loaded = loadCatalogs(dir);
+    if (!loaded.ok) {
+        loaded.errors.forEach((e) => c.fail(e.code, e.message));
+        return undefined;
+    }
+    const drift = glossary ? checkGlossary(glossary, loaded.catalogs) : [];
+    drift.forEach((e) => c.fail(e.code, e.message));
+    return info && drift.length === 0 ? { catalogs: loaded.catalogs, info } : undefined;
+}
+function readInfoText(value, c) {
+    if (value === undefined) {
+        return {};
+    }
+    const invalid = (why) => c.fail("STANDALONE_I18N_INVALID", `i18n.info ${why}`);
+    if (!isRecord(value)) {
+        return invalid("必須以語言為 key，例如 zh-TW: { displayname, description }。");
+    }
+    const info = {};
+    for (const [locale, text] of Object.entries(value)) {
+        if (!isLocale(locale) || locale === "en") {
+            return invalid(`的「${locale}」不是支援的翻譯語言；英文寫在頂層 displayname / description。`);
+        }
+        if (!isRecord(text) || Object.keys(text).some((key) => !INFO_TEXT_FIELDS.has(key))) {
+            return invalid(`.${locale} 只接受 displayname 與 description。`);
+        }
+        const entry = {};
+        for (const field of INFO_TEXT_FIELDS) {
+            if (text[field] !== undefined) {
+                const checked = c.text(text[field], `i18n.info.${locale}.${field}`);
+                if (!checked) {
+                    return undefined;
+                }
+                entry[field] = checked;
+            }
+        }
+        info[locale] = entry;
+    }
+    return info;
+}
+/**
+ * The nearest directory at or above `start` that holds dsm-package.yaml,
+ * unless a Managed Profile project (synology-app.yaml) is found first.
+ */
+export function findStandaloneRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, "synology-app.yaml"))) {
+            return null;
+        }
+        if (existsSync(join(current, STANDALONE_MANIFEST))) {
+            return current;
+        }
+        const parent = resolve(current, "..");
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}

package/dist/standalone/reopen-events.d.ts

@@ -0,0 +1,2 @@
+/** Wrapper-owned subscriptions; no dependency on native event names or Ext. */
+export declare const REOPEN_EVENTS_RUNTIME = "\nfunction createReopenEvents() {\n  var active = true, handlers = [];\n  function subscribe(fn) {\n    if (!active || typeof fn !== \"function\") return function () {};\n    function handler() { if (active && fn) fn(); }\n    function unsubscribe() {\n      if (!fn) return;\n      fn = null;\n      var index = handlers.indexOf(handler);\n      if (index !== -1) handlers.splice(index, 1);\n    }\n    handler.unsubscribe = unsubscribe;\n    handlers.push(handler);\n    return unsubscribe;\n  }\n  return {\n    handlers: handlers,\n    subscribe: subscribe,\n    emit: function () { handlers.slice().forEach(function (handler) { handler(); }); },\n    dispose: function () {\n      active = false;\n      handlers.slice().forEach(function (handler) { handler.unsubscribe(); });\n    }\n  };\n}\n";

package/dist/standalone/reopen-events.js

@@ -0,0 +1,28 @@
+/** Wrapper-owned subscriptions; no dependency on native event names or Ext. */
+export const REOPEN_EVENTS_RUNTIME = `
+function createReopenEvents() {
+  var active = true, handlers = [];
+  function subscribe(fn) {
+    if (!active || typeof fn !== "function") return function () {};
+    function handler() { if (active && fn) fn(); }
+    function unsubscribe() {
+      if (!fn) return;
+      fn = null;
+      var index = handlers.indexOf(handler);
+      if (index !== -1) handlers.splice(index, 1);
+    }
+    handler.unsubscribe = unsubscribe;
+    handlers.push(handler);
+    return unsubscribe;
+  }
+  return {
+    handlers: handlers,
+    subscribe: subscribe,
+    emit: function () { handlers.slice().forEach(function (handler) { handler(); }); },
+    dispose: function () {
+      active = false;
+      handlers.slice().forEach(function (handler) { handler.unsubscribe(); });
+    }
+  };
+}
+`;

package/dist/standalone/root-messages.d.ts

@@ -0,0 +1,7 @@
+import type { Catalog, Locale } from "./i18n.js";
+/**
+ * Text of the authorization panel every privilege: root package shows, the
+ * same in every package. DSM's own words (Task Scheduler, Run, Remove, …) are
+ * taken verbatim from DSM 7.4; test/standalone-root-messages.test.ts pins them.
+ */
+export declare const ROOT_MESSAGES: Record<Locale, Catalog>;