@synopackageland/cli 0.3.9 → 0.4.0

package/dist/standalone/i18n.js

@@ -0,0 +1,161 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * UI languages a Standalone Package can ship, as BCP-47 tags (the catalog
+ * file names and the `Intl` locale), with the DSM language code each one
+ * answers to. Every other DSM language opens the app in English.
+ */
+export const LOCALES = ["en", "zh-TW", "zh-CN", "ja", "ko", "de", "fr", "es", "it"];
+export const DSM_LANGS = {
+    en: "enu",
+    "zh-TW": "cht",
+    "zh-CN": "chs",
+    ja: "jpn",
+    ko: "krn",
+    de: "ger",
+    fr: "fre",
+    es: "spn",
+    it: "ita",
+};
+const MESSAGE_KEY = /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)*$/;
+export function isLocale(value) {
+    return LOCALES.includes(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function placeholders(text) {
+    return [...new Set([...text.matchAll(/\{(\w+)\}/g)].map((m) => m[1]))].sort().join(",");
+}
+function readCatalog(file, locale) {
+    const invalid = (why) => ({
+        error: { code: "STANDALONE_I18N_CATALOG_INVALID", message: `${locale}.json ${why}` },
+    });
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return invalid(`不是合法的 JSON：${String(error)}`);
+    }
+    if (!isRecord(raw)) {
+        return invalid("必須是 { \"key\": \"text\" } 的 JSON 物件。");
+    }
+    for (const [key, text] of Object.entries(raw)) {
+        if (!MESSAGE_KEY.test(key) || typeof text !== "string") {
+            return invalid(`的「${key}」必須是點分隔的 key（例如 greeting.save）對應一段文字。`);
+        }
+    }
+    return { catalog: raw };
+}
+/** `<dir>/<locale>.json` for each shipped locale; en.json is required. */
+export function loadCatalogs(dir) {
+    const errors = [];
+    const catalogs = {};
+    const files = existsSync(dir) ? readdirSync(dir).filter((name) => name.endsWith(".json")).sort() : [];
+    for (const name of files) {
+        const locale = name.slice(0, -".json".length);
+        if (!isLocale(locale)) {
+            errors.push({
+                code: "STANDALONE_I18N_LOCALE_UNSUPPORTED",
+                message: `${name}：只支援 ${LOCALES.join(", ")}；其他 DSM 語言會顯示英文。`,
+            });
+            continue;
+        }
+        const read = readCatalog(join(dir, name), locale);
+        if ("error" in read) {
+            errors.push(read.error);
+        }
+        else {
+            catalogs[locale] = read.catalog;
+        }
+    }
+    const en = catalogs.en;
+    if (!en) {
+        if (!errors.some((e) => e.code === "STANDALONE_I18N_CATALOG_INVALID")) {
+            errors.push({ code: "STANDALONE_I18N_MESSAGES_MISSING", message: `${dir} 缺少 en.json（所有語言的後備文字）。` });
+        }
+        return { ok: false, errors };
+    }
+    for (const [locale, catalog] of Object.entries(catalogs)) {
+        errors.push(...compareWithEnglish(locale, catalog, en));
+    }
+    return errors.length === 0 ? { ok: true, catalogs: catalogs } : { ok: false, errors };
+}
+function compareWithEnglish(locale, catalog, en) {
+    const missing = Object.keys(en).filter((key) => !(key in catalog));
+    const extra = Object.keys(catalog).filter((key) => !(key in en));
+    if (missing.length > 0 || extra.length > 0) {
+        const parts = [
+            missing.length > 0 ? `缺少 ${missing.join(", ")}` : "",
+            extra.length > 0 ? `多出 ${extra.join(", ")}` : "",
+        ].filter(Boolean);
+        return [{ code: "STANDALONE_I18N_KEYS_MISMATCH", message: `${locale}.json 與 en.json 的 key 不同：${parts.join("；")}。` }];
+    }
+    const drifted = Object.keys(en).filter((key) => placeholders(catalog[key]) !== placeholders(en[key]));
+    return drifted.length === 0
+        ? []
+        : [{
+                code: "STANDALONE_I18N_PLACEHOLDER_MISMATCH",
+                message: `${locale}.json 的 ${drifted.join(", ")} 與 en.json 的 {placeholder} 不一致。`,
+            }];
+}
+function readGlossary(file) {
+    const invalid = (why) => ({ code: "STANDALONE_I18N_GLOSSARY_INVALID", message: `${file}：${why}` });
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return invalid(`不是合法的 JSON：${String(error)}`);
+    }
+    if (!isRecord(raw) || !Array.isArray(raw.terms)) {
+        return invalid("必須是 { \"terms\": [...] }。");
+    }
+    const terms = [];
+    for (const term of raw.terms) {
+        const ok = isRecord(term)
+            && typeof term.id === "string"
+            && isRecord(term.text)
+            && Object.entries(term.text).every(([locale, text]) => isLocale(locale) && typeof text === "string" && text !== "")
+            && (term.keys === undefined || (Array.isArray(term.keys) && term.keys.every((key) => typeof key === "string")));
+        if (!ok) {
+            return invalid(`term ${isRecord(term) ? JSON.stringify(term.id) : "?"} 需要 id、以支援語言為 key 的 text，以及選填的 keys 清單。`);
+        }
+        terms.push({ id: term.id, text: term.text, keys: term.keys ?? [] });
+    }
+    return terms;
+}
+/** Case-insensitive: a term can start a sentence or sit inside one ("Backend status"). */
+function containsTerm(message, term, locale) {
+    return message.toLocaleLowerCase(locale).includes(term.toLocaleLowerCase(locale));
+}
+/**
+ * Each glossary term lists the message keys that must use it: in every
+ * shipped locale the message has to contain that locale's official term.
+ */
+export function checkGlossary(file, catalogs) {
+    const terms = readGlossary(file);
+    if (!Array.isArray(terms)) {
+        return [terms];
+    }
+    const errors = [];
+    for (const term of terms) {
+        for (const key of term.keys) {
+            if (!(key in catalogs.en)) {
+                errors.push({ code: "STANDALONE_I18N_GLOSSARY_INVALID", message: `glossary term ${term.id} 指向不存在的 key ${key}。` });
+                continue;
+            }
+            for (const [locale, catalog] of Object.entries(catalogs)) {
+                const official = term.text[locale];
+                if (official !== undefined && !containsTerm(catalog[key], official, locale)) {
+                    errors.push({
+                        code: "STANDALONE_I18N_GLOSSARY_MISMATCH",
+                        message: `${locale}.json 的 ${key}「${catalog[key]}」沒有使用 Synology 用語「${official}」（glossary term ${term.id}）。`,
+                    });
+                }
+            }
+        }
+    }
+    return errors;
+}

package/dist/standalone/inspect-spk.d.ts

@@ -0,0 +1,21 @@
+export type SpkKind = "native-go" | "binary" | "container";
+export interface SpkInspection {
+    kind?: SpkKind;
+    package?: string;
+    version?: string;
+    arch?: string;
+    /** Whether the SPK carries a Synology package signature. */
+    signed: boolean;
+    /** Payload path of the package CGI, when present with mode 0755. */
+    cgi?: string;
+    payload: Array<{
+        path: string;
+        mode: string;
+    }>;
+    /** Anything that breaks the unsigned, package-account-only contract. */
+    findings: string[];
+}
+/** Reads an SPK without installing it and reports how it would run on DSM. */
+export declare function inspectStandaloneSpk(spkPath: string): Promise<SpkInspection>;
+/** Auto-detect the generated runtime; retain strict native-go inspection when requested. */
+export declare function inspectSpk(spkPath: string, expectedKind?: SpkKind): Promise<SpkInspection>;

package/dist/standalone/inspect-spk.js

@@ -0,0 +1,160 @@
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import * as tar from "tar";
+import { CGI_PAYLOAD_PATH } from "./dsm-window.js";
+const ROOT_SCRIPT_HINTS = [/\bsudo\b/, /\bchown\s+(-\w+\s+)*root\b/, /chmod\s+[ugo]*\+s\b/, /chmod\s+[2467][0-7]{3}\b/];
+/** Reads an SPK without installing it and reports how it would run on DSM. */
+export async function inspectStandaloneSpk(spkPath) {
+    return inspectSpk(spkPath, "native-go");
+}
+/** Auto-detect the generated runtime; retain strict native-go inspection when requested. */
+export async function inspectSpk(spkPath, expectedKind) {
+    const dir = mkdtempSync(join(tmpdir(), "syno-inspect-spk-"));
+    try {
+        await tar.x({ file: spkPath, cwd: dir });
+        const findings = [];
+        const payload = await listPayload(join(dir, "package.tgz"), findings);
+        const paths = new Set(payload.map(entry => entry.path));
+        const kind = expectedKind ?? (paths.has(CGI_PAYLOAD_PATH) ? "native-go"
+            : paths.has("native.yaml") ? "binary" : paths.has("compose.yaml") ? "container" : "native-go");
+        const identityPayload = [CGI_PAYLOAD_PATH, "integration/helper", "integration/inventory.json", "integration/workers.json", "integration/identity/app.mjs"].every(path => paths.has(path));
+        const info = readInfo(join(dir, "INFO"), findings, kind, identityPayload);
+        checkConf(dir, findings, kind);
+        checkScripts(dir, findings);
+        const cgiEntry = payload.find((entry) => entry.path === CGI_PAYLOAD_PATH);
+        if (kind === "native-go" && !cgiEntry) {
+            findings.push(`payload 沒有 ${CGI_PAYLOAD_PATH}`);
+        }
+        else if (cgiEntry && cgiEntry.mode !== "0755") {
+            findings.push(`${CGI_PAYLOAD_PATH} 的 mode 是 ${cgiEntry.mode}，應為 0755`);
+        }
+        return {
+            kind,
+            package: info.package,
+            version: info.version,
+            arch: info.arch,
+            signed: existsSync(join(dir, "syno_signature.asc")),
+            cgi: cgiEntry?.mode === "0755" ? CGI_PAYLOAD_PATH : undefined,
+            payload,
+            findings,
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+function readInfo(path, findings, kind, identityPayload) {
+    if (!existsSync(path)) {
+        findings.push("缺少 INFO");
+        return {};
+    }
+    const info = {};
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        const match = line.match(/^([a-z_]+)="(.*)"$/);
+        if (match) {
+            info[match[1]] = match[2];
+        }
+    }
+    for (const key of ["package", "version", "arch", "os_min_ver"]) {
+        if (!info[key]) {
+            findings.push(`INFO 缺少 ${key}`);
+        }
+    }
+    if (kind === "native-go" && (info.thirdparty !== "yes" || info.dsmuidir !== "ui")) {
+        findings.push('INFO 必須有 thirdparty="yes" 與 dsmuidir="ui"，DSM 才會提供 /webman/3rdparty/<package>/');
+    }
+    const allowedDependency = kind === "container"
+        ? info.install_dep_packages?.split(":").every(dep => /^(WebStation|ContainerManager)([><=].*)?$/.test(dep))
+        : kind === "native-go" && identityPayload && info.install_dep_packages === "Node.js_v22";
+    if (info.install_dep_packages && !allowedDependency) {
+        findings.push(`INFO 依賴其他套件：${info.install_dep_packages}`);
+    }
+    return info;
+}
+function checkConf(dir, findings, kind) {
+    const confDir = join(dir, "conf");
+    const entries = existsSync(confDir) ? readdirSync(confDir) : [];
+    for (const name of entries) {
+        if (name !== "privilege" && !(kind === "container" && name === "resource")) {
+            findings.push(`conf/${name} 會向 DSM 註冊額外資源；Standalone Package 不產生它`);
+        }
+    }
+    if (kind === "container") {
+        try {
+            const resource = JSON.parse(readFileSync(join(confDir, "resource"), "utf8"));
+            if (!resource["docker-project"])
+                findings.push("container 缺少 docker-project resource");
+            for (const key of Object.keys(resource)) {
+                if (!["docker-project", "webservice"].includes(key))
+                    findings.push(`未知 container resource: ${key}`);
+            }
+        }
+        catch {
+            findings.push("container 缺少有效的 conf/resource");
+        }
+    }
+    if (!entries.includes("privilege")) {
+        findings.push("缺少 conf/privilege（DSM 7 必須以 package 帳號執行）");
+        return;
+    }
+    let privilege;
+    try {
+        privilege = JSON.parse(readFileSync(join(confDir, "privilege"), "utf8"));
+    }
+    catch {
+        findings.push("conf/privilege 不是 JSON");
+        return;
+    }
+    const defaults = privilege.defaults;
+    if (defaults?.["run-as"] !== "package") {
+        findings.push('conf/privilege 的 defaults.run-as 必須是 "package"');
+    }
+    for (const key of ["tool", "ctrl-script", "executable", "join-groupname"]) {
+        if (key in privilege) {
+            findings.push(`conf/privilege 要求 ${key}（root 或額外群組權限）`);
+        }
+    }
+}
+function checkScripts(dir, findings) {
+    const scriptsDir = join(dir, "scripts");
+    if (!existsSync(join(scriptsDir, "start-stop-status"))) {
+        findings.push("缺少 scripts/start-stop-status");
+    }
+    for (const name of existsSync(scriptsDir) ? readdirSync(scriptsDir) : []) {
+        const body = readFileSync(join(scriptsDir, name), "utf8");
+        if (ROOT_SCRIPT_HINTS.some((pattern) => pattern.test(body))) {
+            findings.push(`scripts/${name} 嘗試取得 root 權限（sudo、chown root 或 setuid）`);
+        }
+    }
+}
+async function listPayload(packageTgz, findings) {
+    if (!existsSync(packageTgz)) {
+        findings.push("缺少 package.tgz");
+        return [];
+    }
+    const payload = [];
+    await tar.t({
+        file: packageTgz,
+        onReadEntry: (entry) => {
+            const path = entry.path.replace(/^\.\//, "");
+            const mode = (entry.mode ?? 0) & 0o7777;
+            if (entry.type === "SymbolicLink" || entry.type === "Link") {
+                findings.push(`payload 含連結：${path}`);
+            }
+            if (path.startsWith("/") || path.split("/").includes("..")) {
+                findings.push(`payload 路徑跳出套件目錄：${path}`);
+            }
+            if (mode & 0o6000) {
+                findings.push(`payload 含 setuid/setgid 檔案：${path}`);
+            }
+            if (mode & 0o002) {
+                findings.push(`payload 含所有人可寫的檔案：${path}`);
+            }
+            if (entry.type === "File") {
+                payload.push({ path, mode: mode.toString(8).padStart(4, "0") });
+            }
+        },
+    });
+    return payload;
+}

package/dist/standalone/manifest.d.ts

@@ -0,0 +1,71 @@
+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";
+/**
+ * `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;
+}
+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;