@synopackageland/cli 0.4.0 → 0.5.0

package/dist/error-registry.js

@@ -1,4 +1,8 @@
 export const ERROR_REGISTRY = {
+    "NATIVE_LAYOUT_INVALID": {
+        code: "NATIVE_LAYOUT_INVALID", description: "Native layout manifest、toolkit、hook 或產物不符合契約。",
+        suggestion: "檢查 dsm-package.yaml、SHA-256 pins、package privilege、ELF linkage 與 hook 診斷。"
+    },
     "COMPOSE_ROUTE_UNSUPPORTED": {
         "code": "COMPOSE_ROUTE_UNSUPPORTED",
         "description": "Compose 沒有可用的 DSM resource worker 執行路徑。",
@@ -54,6 +58,41 @@ export const ERROR_REGISTRY = {
         "description": "Headless App 不需要宣告 Web Launch Mode。",
         "suggestion": "請省略 integration.web.launch，或補上對應 Compose published port 的 adminport。"
     },
+    "CONTRACT_ACCESS_INVALID": {
+        "code": "CONTRACT_ACCESS_INVALID",
+        "description": "integration.web.access 模式無效。",
+        "suggestion": "請改為 dsm-users（已登入的 DSM 使用者，預設）、dsm-admins、dsm-groups（需搭配 groups），或明確選 public 以保留匿名 Web Station 入口。"
+    },
+    "CONTRACT_ACCESS_GROUPS_INVALID": {
+        "code": "CONTRACT_ACCESS_GROUPS_INVALID",
+        "description": "integration.web.groups 缺少、格式不符，或沒有搭配 access: dsm-groups。",
+        "suggestion": "請改用 access: dsm-groups 並列出 DSM 群組名稱，或移除 groups。"
+    },
+    "CONTRACT_ACCESS_REQUIRES_WEB": {
+        "code": "CONTRACT_ACCESS_REQUIRES_WEB",
+        "description": "Headless App 不需要宣告 Web access 規則。",
+        "suggestion": "請省略 integration.web.access／groups，或補上對應 Compose published port 的 adminport。"
+    },
+    "COMPOSE_GATEWAY_PORT_EXPOSED": {
+        "code": "COMPOSE_GATEWAY_PORT_EXPOSED",
+        "description": "DSM 驗證閘道是容器的唯一入口，但 adminport 對應的 Compose port 綁在所有網路介面上。",
+        "suggestion": "請把 ports 改成只綁 loopback（例如 \"127.0.0.1:18333:18333\"），或在 integration.web.access 明確選 public。"
+    },
+    "GATEWAY_ARCH_FAMILY_REQUIRED": {
+        "code": "GATEWAY_ARCH_FAMILY_REQUIRED",
+        "description": "DSM 驗證閘道是原生執行檔，SPK 必須指定目標架構。",
+        "suggestion": "請加上 --arch x86_64 或 --arch aarch64（deploy 會由 NAS 判定）；不需要 DSM 驗證的 App 才可在 integration.web.access 選 public。"
+    },
+    "GATEWAY_GO_MISSING": {
+        "code": "GATEWAY_GO_MISSING",
+        "description": "建置 DSM 驗證閘道需要 Go，但找不到 go 指令。",
+        "suggestion": "請安裝 Go 1.24 以上版本（https://go.dev/dl/），或在 integration.web.access 明確選 public。"
+    },
+    "GATEWAY_BUILD_FAILED": {
+        "code": "GATEWAY_BUILD_FAILED",
+        "description": "DSM 驗證閘道建置失敗或產出不是對應架構的靜態 ELF。",
+        "suggestion": "請查看 go build 輸出；確認 Go 版本 1.24 以上且 templates/_gateway 未被修改。"
+    },
     "CONTRACT_INVALID_STRING": {
         "code": "CONTRACT_INVALID_STRING",
         "description": "合約字串含有不允許的控制字元或未允許的插值語法。",
@@ -579,6 +618,46 @@ export const ERROR_REGISTRY = {
         "description": "每包 helper 的 integration 宣告不合法。",
         "suggestion": "使用 native-go、privilege: root、protocol: 1 和 workers map；不要自訂 helper_ 操作。"
     },
+    "STANDALONE_DAEMON_INVALID": {
+        "code": "STANDALONE_DAEMON_INVALID",
+        "description": "套件 daemon 的宣告不符合固定 argv、環境與生命週期契約。",
+        "suggestion": "核對 daemon.exec、各架構 targets、args、env、uninstall_args 與整數秒 timeouts；移除 shell、user 與自訂 conf。"
+    },
+    "STANDALONE_DAEMON_BUILD_FAILED": {
+        "code": "STANDALONE_DAEMON_BUILD_FAILED",
+        "description": "無法建置套件 daemon 的 Go supervisor。",
+        "suggestion": "安裝 Go 1.24 以上並檢查 compiler stderr；NAS 不需要 Go toolchain。"
+    },
+    "STANDALONE_DAEMON_PAYLOAD_INVALID": {
+        "code": "STANDALONE_DAEMON_PAYLOAD_INVALID",
+        "description": "daemon payload 不是專案內的有界、無連結目錄。",
+        "suggestion": "重建各架構 bundle；移除 symlink、特殊檔與 setid，並將大小限制在 512 MiB。"
+    },
+    "STANDALONE_DAEMON_ARTIFACT_REQUIRED": {
+        "code": "STANDALONE_DAEMON_ARTIFACT_REQUIRED",
+        "description": "組裝 daemon SPK 時缺少已建置的 supervisor。",
+        "suggestion": "透過 synopkgland build-spk 建置完整產物，不直接呼叫缺少 controller 的 assembler。"
+    },
+    "STANDALONE_SHARED_FOLDER_INVALID": {
+        "code": "STANDALONE_SHARED_FOLDER_INVALID",
+        "description": "dsm-package.yaml 的 install.sharedFolder 宣告不合法。",
+        "suggestion": "寫 install: { sharedFolder: { mode: select|create, key: <小寫英數與底線>, permission: ro|rw } }；create 需另加 name（DSM 共用資料夾名稱），select 不可有 name。"
+    },
+    "STANDALONE_BACKGROUND_INVALID": {
+        "code": "STANDALONE_BACKGROUND_INVALID",
+        "description": "套件背景工作的宣告不符合固定 worker 契約。",
+        "suggestion": "只寫 background: { worker: sha256-v1 }，使用 backend.go，且不要與 daemon 或 integration 並用；背景程序固定以套件帳號執行。"
+    },
+    "STANDALONE_BACKGROUND_BUILD_FAILED": {
+        "code": "STANDALONE_BACKGROUND_BUILD_FAILED",
+        "description": "無法建置套件的背景 worker。",
+        "suggestion": "安裝 Go 1.24 以上，確認 backend 含 cmd/background-worker（可用 synopkgland init --background 建立），並檢查 compiler stderr。"
+    },
+    "STANDALONE_BACKGROUND_ARTIFACT_REQUIRED": {
+        "code": "STANDALONE_BACKGROUND_ARTIFACT_REQUIRED",
+        "description": "組裝背景工作 SPK 時缺少已建置的 worker。",
+        "suggestion": "透過 synopkgland build-spk 建置完整產物，不直接呼叫缺少 worker 的 assembler。"
+    },
     "HELPER_WORKER_UNSAFE": {
         "code": "HELPER_WORKER_UNSAFE",
         "description": "worker inventory 檔案不在專案內或不是一般檔案。",
@@ -732,7 +811,7 @@ export const ERROR_REGISTRY = {
     "STANDALONE_UI_BUILD_FAILED": {
         "code": "STANDALONE_UI_BUILD_FAILED",
         "description": "UI build 指令失敗。",
-        "suggestion": "請在 ui.build.cwd 手動執行該指令並修正錯誤。"
+        "suggestion": "請在 ui.build.cwd 安裝 UI 依賴（有 package-lock.json 用 npm ci，否則 npm install），再執行 UI build 指令並修正錯誤。"
     },
     "STANDALONE_UI_ENTRY_MISSING": {
         "code": "STANDALONE_UI_ENTRY_MISSING",

package/dist/host/open-url.d.ts

@@ -2,4 +2,6 @@ export declare function appOriginFromContract(dsmOrigin: string, contract: {
     package?: unknown;
     adminprotocol?: unknown;
     adminport?: unknown;
+    adminurl?: unknown;
+    integration?: unknown;
 }): string | undefined;

package/dist/host/open-url.js

@@ -1,4 +1,4 @@
-import { webStationAlias } from "../contract/web-launch.js";
+import { gatewayEntryPath, usesAuthGateway, webStationAlias } from "../contract/web-launch.js";
 export function appOriginFromContract(dsmOrigin, contract) {
     if (contract.adminport === undefined || contract.adminport === null || contract.adminport === "") {
         return undefined;
@@ -7,6 +7,9 @@ export function appOriginFromContract(dsmOrigin, contract) {
     if (!packageId) {
         return undefined;
     }
+    if (usesAuthGateway(contract)) {
+        return new URL(gatewayEntryPath(packageId, contract.adminurl), dsmOrigin).href;
+    }
     const dsm = new URL(dsmOrigin);
     const protocol = String(contract.adminprotocol ?? "http");
     return `${protocol}://${dsm.hostname}/${webStationAlias(packageId)}/`;

package/dist/images/pin.d.ts

@@ -0,0 +1,52 @@
+import type { ProjectRoot } from "../discovery.js";
+export declare class ImageDigestError extends Error {
+    constructor(message: string);
+}
+export interface ParsedImage {
+    registry: string;
+    repository: string;
+    tag: string;
+    /** Normalized `sha256:<64 hex>` when the reference carries one. */
+    digest?: string;
+    explicitTag: boolean;
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface ResolveDeps {
+    fetch?: FetchLike;
+}
+/**
+ * `busybox:1.36` -> registry `docker.io`, repository `library/busybox`.
+ * `ghcr.io/acme/app:v1` -> registry `ghcr.io`, repository `acme/app`.
+ * Interpolated and malformed references return `null`; the caller decides
+ * whether that is a finding or a hard error.
+ */
+export declare function parseImageReference(image: string): ParsedImage | null;
+/** Resolve `tag` to the `sha256:` digest of the manifest (list) it points at. */
+export declare function resolveImageDigest(image: string, deps?: ResolveDeps): Promise<string>;
+export interface PinFinding {
+    service: string;
+    image: string;
+    code: "unpinned" | "stale" | "unsupported";
+    pinnedDigest?: string;
+    resolvedDigest?: string;
+}
+export interface PinChange {
+    service: string;
+    from: string;
+    to: string;
+}
+export interface PinResult {
+    findings: PinFinding[];
+    changes: PinChange[];
+    written: boolean;
+}
+export interface PinOptions {
+    project: ProjectRoot;
+    /** Report only; never write the compose file. */
+    check?: boolean;
+    fetch?: FetchLike;
+}
+export declare function pinProjectImages(options: PinOptions): Promise<PinResult>;
+export declare function formatPinReport(result: PinResult, options?: {
+    check?: boolean;
+}): string;

package/dist/images/pin.js

@@ -0,0 +1,249 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { isScalar, parseDocument } from "yaml";
+/**
+ * Resolve the multi-arch manifest digest a container tag currently points at,
+ * over the OCI Distribution API, and rewrite `compose.yaml` to pin it.
+ *
+ * No Docker daemon and no `docker buildx`: only anonymous registry HTTP
+ * (Docker Hub and ghcr both issue an anonymous Bearer token for public repos).
+ */
+const DIGEST_VALUE = /^sha256:[0-9a-f]{64}$/i;
+const DIGEST_AT_END = /@sha256:([0-9a-f]{64})$/i;
+/** A registry returns the index (manifest list) digest when we ask for it. */
+const MANIFEST_ACCEPT = [
+    "application/vnd.oci.image.index.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+].join(", ");
+export class ImageDigestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImageDigestError";
+    }
+}
+/**
+ * `busybox:1.36` -> registry `docker.io`, repository `library/busybox`.
+ * `ghcr.io/acme/app:v1` -> registry `ghcr.io`, repository `acme/app`.
+ * Interpolated and malformed references return `null`; the caller decides
+ * whether that is a finding or a hard error.
+ */
+export function parseImageReference(image) {
+    const value = image.trim();
+    if (value === "" || value.includes("$")) {
+        return null;
+    }
+    let name = value;
+    let digest;
+    const at = name.indexOf("@");
+    if (at !== -1) {
+        const raw = name.slice(at + 1);
+        if (!DIGEST_VALUE.test(raw)) {
+            return null;
+        }
+        digest = raw.toLowerCase();
+        name = name.slice(0, at);
+    }
+    let tag = "latest";
+    let explicitTag = false;
+    const lastSlash = name.lastIndexOf("/");
+    const lastColon = name.lastIndexOf(":");
+    if (lastColon > lastSlash) {
+        tag = name.slice(lastColon + 1);
+        name = name.slice(0, lastColon);
+        explicitTag = true;
+    }
+    if (name === "" || tag === "") {
+        return null;
+    }
+    const segments = name.split("/").filter((segment) => segment !== "");
+    if (segments.length === 0) {
+        return null;
+    }
+    const first = segments[0];
+    const hasRegistryHost = segments.length > 1 && (first.includes(".") || first.includes(":") || first === "localhost");
+    const registry = hasRegistryHost ? first : "docker.io";
+    const repository = hasRegistryHost
+        ? segments.slice(1).join("/")
+        : segments.length === 1
+            ? `library/${first}`
+            : segments.join("/");
+    if (repository === "") {
+        return null;
+    }
+    return { registry, repository, tag, digest, explicitTag };
+}
+function registryBaseUrl(registry) {
+    if (registry === "docker.io" || registry === "index.docker.io") {
+        return "https://registry-1.docker.io";
+    }
+    const host = registry.startsWith("[")
+        ? registry.slice(0, registry.indexOf("]") + 1)
+        : registry.split(":")[0];
+    if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") {
+        return `http://${registry}`;
+    }
+    return `https://${registry}`;
+}
+function parseBearerChallenge(header) {
+    if (!header) {
+        return null;
+    }
+    const bearer = /^Bearer\s+(.*)$/i.exec(header.trim());
+    if (!bearer) {
+        return null;
+    }
+    const params = {};
+    const re = /([a-zA-Z0-9_]+)="([^"]*)"/g;
+    let match;
+    while ((match = re.exec(bearer[1])) !== null) {
+        params[match[1].toLowerCase()] = match[2];
+    }
+    if (!params.realm) {
+        return null;
+    }
+    return { realm: params.realm, service: params.service, scope: params.scope };
+}
+async function fetchAnonymousToken(challenge, repository, fetchImpl) {
+    const url = new URL(challenge.realm);
+    if (challenge.service) {
+        url.searchParams.set("service", challenge.service);
+    }
+    url.searchParams.set("scope", challenge.scope ?? `repository:${repository}:pull`);
+    const response = await fetchImpl(url.toString(), {
+        headers: { accept: "application/json" },
+        redirect: "follow",
+    });
+    if (!response.ok) {
+        throw new ImageDigestError(`registry token request failed with HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    const token = typeof body.token === "string"
+        ? body.token
+        : typeof body.access_token === "string"
+            ? body.access_token
+            : undefined;
+    if (!token) {
+        throw new ImageDigestError("registry token response carried no token");
+    }
+    return token;
+}
+/** Resolve `tag` to the `sha256:` digest of the manifest (list) it points at. */
+export async function resolveImageDigest(image, deps = {}) {
+    const parsed = parseImageReference(image);
+    if (!parsed) {
+        throw new ImageDigestError(`not a resolvable image reference: ${image}`);
+    }
+    const fetchImpl = deps.fetch ?? fetch;
+    const manifestUrl = `${registryBaseUrl(parsed.registry)}/v2/${parsed.repository}/manifests/${parsed.tag}`;
+    const headers = { accept: MANIFEST_ACCEPT };
+    let response = await fetchImpl(manifestUrl, { headers, redirect: "follow" });
+    if (response.status === 401) {
+        const challenge = parseBearerChallenge(response.headers.get("www-authenticate"));
+        if (!challenge) {
+            throw new ImageDigestError(`registry requires credentials for ${image}; only anonymous pull is supported`);
+        }
+        const token = await fetchAnonymousToken(challenge, parsed.repository, fetchImpl);
+        response = await fetchImpl(manifestUrl, {
+            headers: { ...headers, authorization: `Bearer ${token}` },
+            redirect: "follow",
+        });
+    }
+    if (!response.ok) {
+        throw new ImageDigestError(`registry answered HTTP ${response.status} for ${image}`);
+    }
+    const header = response.headers.get("docker-content-digest");
+    if (header && DIGEST_VALUE.test(header)) {
+        return header.toLowerCase();
+    }
+    const body = Buffer.from(await response.arrayBuffer());
+    return `sha256:${createHash("sha256").update(body).digest("hex")}`;
+}
+/** Keep the source's quote style so only the reference text changes. */
+function quoteLike(node, value) {
+    if (node.type === "QUOTE_DOUBLE") {
+        return `"${value}"`;
+    }
+    if (node.type === "QUOTE_SINGLE") {
+        return `'${value}'`;
+    }
+    return value;
+}
+export async function pinProjectImages(options) {
+    const { project, check = false } = options;
+    const source = readFileSync(project.composePath, "utf8");
+    const doc = parseDocument(source);
+    const parsed = (doc.toJSON() ?? {});
+    const services = parsed.services && typeof parsed.services === "object" ? parsed.services : {};
+    const findings = [];
+    const changes = [];
+    // Splice only the scalar value: a full `doc.toString()` would reflow flow
+    // collections (`["sh","-c"]` -> `[ "sh", "-c" ]`) and break "keep the file
+    // format". Comments and every other byte stay untouched.
+    const edits = [];
+    for (const service of Object.keys(services)) {
+        const node = doc.getIn(["services", service, "image"], true);
+        if (!isScalar(node) || typeof node.value !== "string") {
+            continue;
+        }
+        const image = node.value;
+        const reference = parseImageReference(image);
+        if (!reference) {
+            findings.push({ service, image, code: "unsupported" });
+            continue;
+        }
+        // A digest without a tag names immutable bytes; there is nothing to refresh.
+        if (!reference.explicitTag && reference.digest) {
+            continue;
+        }
+        const resolved = await resolveImageDigest(image, { fetch: options.fetch });
+        if (reference.digest === resolved) {
+            continue;
+        }
+        const name = image.slice(0, image.indexOf("@") === -1 ? image.length : image.indexOf("@"));
+        const updated = `${name}@${resolved}`;
+        findings.push({
+            service,
+            image,
+            code: reference.digest ? "stale" : "unpinned",
+            pinnedDigest: reference.digest,
+            resolvedDigest: resolved,
+        });
+        changes.push({ service, from: image, to: updated });
+        edits.push({ start: node.range[0], end: node.range[1], text: quoteLike(node, updated) });
+    }
+    let written = false;
+    if (!check && changes.length > 0) {
+        let output = source;
+        for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+            output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+        }
+        writeFileSync(project.composePath, output, "utf8");
+        written = true;
+    }
+    return { findings, changes, written };
+}
+export function formatPinReport(result, options = {}) {
+    const lines = [];
+    for (const finding of result.findings) {
+        if (finding.code === "unpinned") {
+            lines.push(`${finding.service}: image ${finding.image} is not pinned by digest; run \`synopkgland images pin\``);
+        }
+        else if (finding.code === "stale") {
+            lines.push(`${finding.service}: image ${finding.image} is pinned to ${finding.pinnedDigest} but the tag now resolves to ${finding.resolvedDigest}; run \`synopkgland images pin\``);
+        }
+        else {
+            lines.push(`${finding.service}: image ${finding.image} cannot be resolved (interpolated or malformed); pin it manually`);
+        }
+    }
+    if (result.changes.length > 0) {
+        lines.push(options.check
+            ? `${result.changes.length} image(s) need a new pin; nothing was written (--check).`
+            : `Pinned ${result.changes.length} image(s).`);
+    }
+    else if (result.findings.length === 0) {
+        lines.push("All service images are pinned by digest.");
+    }
+    return lines.join("\n");
+}

package/dist/init.d.ts

@@ -1,14 +1,42 @@
 import type { TemplateName } from "./types.js";
+/** The container templates need DSM 7.2.1 or later; native-go and binary need 7.1. */
+export declare function isContainerTemplate(template: TemplateName): boolean;
 export declare function isTemplateName(value: string): value is TemplateName;
 export declare function listTemplates(): TemplateName[];
 export interface InitOptions {
+    /** os_min_ver of the new project: a release (7.2) or a full 7.x-build; default is the template's (DSM 7.1 for native-go/binary, DSM 7.2.1 for container templates). */
+    minDsm?: string;
     /** Standalone templates: INFO.package (default: from the directory name). */
     packageId?: string;
     /** Standalone templates: display name (default: from the directory name). */
     displayName?: string;
-    /** native-go: "root" adds administrator-approved root operations (default "none"). */
+    /**
+     * native-go: "root" adds administrator-approved root operations (default
+     * "none"). With --integration, "root" is also what adds the privileged helper.
+     */
     privilege?: "none" | "root";
     ui?: "plain" | "vue";
     integration?: "go" | "better-auth";
+    /** native-go --ui vue: package-user background jobs (systemd user unit + sha256-v1 worker). */
+    background?: boolean;
+    /** native-go: interactive File Station routes through each caller's own DSM session, run by the package account. */
+    fileStation?: boolean;
+    /** native-go: `install.sharedFolder` (select from the NAS, or create one). key defaults to "shared", permission to "rw". */
+    sharedFolder?: {
+        mode: "select" | "create";
+        name?: string;
+        key?: string;
+        permission?: "ro" | "rw";
+    };
+    /** Helper inventory protocol (needs privilege root); protocol 2 still refuses NAS data. */
+    integrationProtocol?: 1 | 2;
+    /** Protocol 2 policy (needs privilege root); unavailable adapters still refuse data. */
+    dataAccess?: "unavailable" | "relaxed";
 }
+/**
+ * Copy one template tree into a project. A template directory may carry a local
+ * `node_modules`/`dist` from developing the template itself; those never belong
+ * to a generated project (and would otherwise shadow the project's own install).
+ */
+export declare function copyTemplateTree(source: string, target: string): void;
 export declare function initFromTemplate(template: TemplateName, targetDir: string, options?: InitOptions): void;