@synopackageland/cli 0.4.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 synopkgland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,10 +15,51 @@ synopkgland --project ./my-app deploy --dry-run --arch x86_64
 synopkgland --project ./my-app deploy --host my-nas --arch x86_64
 ```
 
-Native-go requires Go 1.24+; binary consumes checked prebuilt archives; container SPKs use DSM resource workers. Root operations require per-operation DSM approval. Remove root tasks before uninstall; changed task text needs fresh approval.
+Native-go requires Go 1.24+; binary consumes checked prebuilt archives; container SPKs use DSM resource workers. Root operations require DSM 7.1-42661 or later and per-operation DSM approval. DSM 7.1 keeps the native password dialog but creates root tasks using the admin session without a server-side password token; DSM 7.2+ retains its one-use token. See the native-go template README for the API matrix and completion limits. Remove root tasks before uninstall; changed task text needs fresh approval.
+
+`--ui vue --integration go|better-auth` generates a package-account integration
+(`privilege: none`, no helper). The privileged helper needs an explicit
+`--privilege root`; protocol, data-access and worker settings belong to it.
+
+For native-go helper integration, `--ui vue --integration go --privilege root
+--integration-protocol 2 --data-access relaxed` selects the S1R build policy (`integration.dataAccess`).
+Default data access remains unavailable. Mode is pinned in helper/CGI inventory
+and requires rebuild and new root approval when changed. Missing certified DSM
+adapters still refuse NAS access; this setting does not open write gates.
+Recreated accounts with the same UID and username may retain grants; a change to
+either invalidates all grants for that identity and requires new authorization.
 
 For containers, `--share MEDIA_SHARE=photos`, `--run-as RUN_AS=alice` and `--param APP_MODE=prod` supply declared values. Keep upstream target paths. Fixed service credentials govern mount access, while each upstream app owns user login and authorization.
 
 `dev` and `test` run local Compose. `info` and `log` read DSM package state/status; status output is not application log streaming. `skill path/list/show` exposes the bundled authoring guidance. `--dev` is available for container/binary development package identities. There is no release or public-submit command; deploy never publishes.
 
 See the repository's docs/independent-packages.md for supported parameters, lifecycle and limitations.
+## Licensing
+
+The CLI and original templates are MIT licensed, Copyright (c) 2026 synopkgland.
+Third-party components retain their own terms.
+Generated projects keep these template terms in `LICENSES/TEMPLATE.txt`.
+`init` does not create an app-level `LICENSE` or select a license for your work:
+choose your own terms and copyright holder in the project root `LICENSE`.
+Retain the template and dependency notices when distributing derived code.
+
+SPKs place legal material under the installed payload's `LICENSES/` directory:
+`TEMPLATE.txt`, optional developer `APP.txt`, Go's `GO-LICENSE`/`GO-PATENTS`,
+`GO-THIRD_PARTY_NOTICES.txt`, optional `HELPER-THIRD_PARTY_NOTICES.txt`, and
+`ui/` or `better-auth/` notice trees. The helper also retains its existing
+`integration/THIRD_PARTY_NOTICES.txt` location for compatibility.
+
+Vue and Better Auth builds generate full notices plus `inventory.json` from
+the installed, locked production dependency tree (a conservative superset of
+bundled code). Missing text or a version mismatch fails the build. Run `npm ci`
+in the generated frontend/Node directories before building. For
+`@better-auth/utils` 0.4.2 and 0.5.0, which omit license text in their npm
+archives, the tool retains the upstream project's subsequently added MIT
+license, with its pinned source commit and exact npm integrity recorded in
+`notice-overrides/index.json`. Unknown missing licenses require a new review;
+the tool never manufactures a license from a package's SPDX field.
+
+Keep `backend/THIRD_PARTY_NOTICES.txt` current if you change Go modules.
+The supplied notice inventory covers the pinned template dependencies and Go
+runtime; arbitrary developer binaries, Go module additions, container images,
+custom UI bundles and upstream applications need their own notice inventory.

package/dist/build-spk/delete-app-data.d.ts

@@ -1,11 +1,31 @@
 /**
  * The Delete App Data block shared by the Compose and native postuninst scripts.
  *
- * The uninstall wizard sets `delete_app_data` (and DSM mirrors it as
- * `wizard_delete_app_data`); unchecked is the default, so an absent variable
- * must leave the data in place. `delete_root` refuses to follow a symlink out
- * of `@appdata`/`@apphome`, empties the directory rather than removing the
- * mount point DSM owns, and reports remnants instead of failing the script —
- * a non-zero postuninst blocks uninstall.
+ * DSM keeps `@appdata`, `@apphome` and `@appconf` after an uninstall, so a
+ * package that offers deletion has to do it itself. The uninstall wizard's
+ * `pkgwizard_remove_additional` box (the key Synology's own packages use) is
+ * unchecked by default, so an absent variable leaves the data in place. The
+ * pre-0.5 key `delete_app_data` and DSM's `wizard_` mirror of either key are
+ * still honoured for scripted callers.
+ *
+ * Deletion never runs on an upgrade: DSM replays postuninst for the old
+ * version, and the new version must find its data.
+ *
+ * Every root is resolved first and must land on `/volumeN/@<area>/<package>`
+ * (or below it) for this package; anything else — an empty variable, another
+ * package, a shared folder, `@appconf` — is reported and left alone. A root is
+ * emptied rather than removed (the mount point is DSM's), symlinks inside it
+ * are removed rather than followed, and remnants are reported instead of
+ * failing the script: a non-zero postuninst blocks uninstall.
  */
-export declare function renderDeleteAppDataBlock(roots: readonly string[]): string;
+export type AppDataArea = "appdata" | "apphome" | "appstore";
+export interface DeleteRoot {
+    /** Name of the shell variable that holds the root directory. */
+    variable: string;
+    area: AppDataArea;
+}
+export interface DeleteAppDataOptions {
+    /** Prefix in front of `/volumeN`; tests point it at a scratch tree, packages leave it empty. */
+    mountRoot?: string;
+}
+export declare function renderDeleteAppDataBlock(packageName: string, roots: readonly DeleteRoot[], options?: DeleteAppDataOptions): string;

package/dist/build-spk/delete-app-data.js

@@ -1,42 +1,43 @@
-/**
- * The Delete App Data block shared by the Compose and native postuninst scripts.
- *
- * The uninstall wizard sets `delete_app_data` (and DSM mirrors it as
- * `wizard_delete_app_data`); unchecked is the default, so an absent variable
- * must leave the data in place. `delete_root` refuses to follow a symlink out
- * of `@appdata`/`@apphome`, empties the directory rather than removing the
- * mount point DSM owns, and reports remnants instead of failing the script —
- * a non-zero postuninst blocks uninstall.
- */
-export function renderDeleteAppDataBlock(roots) {
-    const calls = roots.map((name) => `  delete_root "$${name}"`).join("\n");
-    return `should_delete=0
-case "\${delete_app_data:-}" in
-  true|True|TRUE|yes|1) should_delete=1 ;;
-esac
-case "\${wizard_delete_app_data:-}" in
-  true|True|TRUE|yes|1) should_delete=1 ;;
-esac
-if [ "$should_delete" -eq 1 ]; then
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function renderDeleteAppDataBlock(packageName, roots, options = {}) {
+    const calls = roots.map((root) => `  delete_root "$${root.variable}" ${root.area}`).join("\n");
+    return `remove_additional=0
+if [ "\${SYNOPKG_PKG_STATUS:-}" != UPGRADE ]; then
+  for flag in "\${pkgwizard_remove_additional:-}" "\${wizard_pkgwizard_remove_additional:-}" "\${delete_app_data:-}" "\${wizard_delete_app_data:-}"; do
+    case "$flag" in
+      true|True|TRUE|yes|1) remove_additional=1 ;;
+    esac
+  done
+fi
+if [ "$remove_additional" -eq 1 ]; then
+  app_pkg=${shellQuote(packageName)}
+  volume_base=${shellQuote(`${options.mountRoot ?? ""}/volume`)}
+  is_package_area() {
+    rest=\${1#"$volume_base"}
+    [ "$rest" != "$1" ] || return 1
+    number=\${rest%%/*}
+    case "$number" in
+      ""|*[!0-9]*) return 1 ;;
+    esac
+    case "\${rest#*/}" in
+      "@$2/$app_pkg"|"@$2/$app_pkg"/*) return 0 ;;
+    esac
+    return 1
+  }
   delete_root() {
     target="$1"
-    if [ ! -e "$target" ] && [ ! -L "$target" ]; then
+    area="$2"
+    if [ -z "$target" ]; then
       return 0
     fi
-    if [ -L "$target" ]; then
-      real=$(readlink -f "$target" 2>/dev/null || true)
-      case "$real" in
-        */@appdata/*|*/@apphome/*)
-          ;;
-        *)
-          echo "Delete App Data skipped symlink: $target" >&2
-          return 0
-          ;;
-      esac
-    else
-      real="$target"
+    if [ ! -e "$target" ] && [ ! -L "$target" ]; then
+      return 0
     fi
-    if [ ! -e "$real" ]; then
+    real=$(readlink -f "$target" 2>/dev/null || true)
+    if ! is_package_area "$real" "$area"; then
+      echo "Delete App Data skipped unsafe path: $target" >&2
       return 0
     fi
     chmod -R u+w "$real" 2>/dev/null || true

package/dist/build-spk/dsm-arch.d.ts

@@ -1,4 +1,9 @@
-export type NativeArchFamily = "x86_64" | "aarch64";
+export declare const NATIVE_ARCH_FAMILIES: readonly ["x86_64", "aarch64"];
+export type NativeArchFamily = (typeof NATIVE_ARCH_FAMILIES)[number];
 export declare const NATIVE_ARCH_PLATFORMS: Record<NativeArchFamily, readonly string[]>;
 export declare function isNativeArchFamily(value: string): value is NativeArchFamily;
+/** `--arch x86_64,aarch64`: one or more families, in the given order, each once. */
+export declare function parseArchList(value: string): NativeArchFamily[];
 export declare function infoArchValue(family: NativeArchFamily): string;
+/** The family an INFO `arch` token belongs to: a family name or one of its platforms. */
+export declare function familyOfArchToken(token: string): NativeArchFamily | undefined;

package/dist/build-spk/dsm-arch.js

@@ -1,3 +1,4 @@
+export const NATIVE_ARCH_FAMILIES = ["x86_64", "aarch64"];
 export const NATIVE_ARCH_PLATFORMS = {
     x86_64: [
         "apollolake",
@@ -11,10 +12,13 @@ export const NATIVE_ARCH_PLATFORMS = {
         "cedarview",
         "denverton",
         "epyc7002",
+        "epyc7003",
+        "epyc7003ntb",
         "geminilake",
         "geminilakenk",
         "grantley",
         "icelaked",
+        "kvmcloud",
         "kvmx64",
         "purley",
         "r1000",
@@ -25,8 +29,28 @@ export const NATIVE_ARCH_PLATFORMS = {
     aarch64: ["armada37xx", "rtd1296", "rtd1619b"],
 };
 export function isNativeArchFamily(value) {
-    return value === "x86_64" || value === "aarch64";
+    return NATIVE_ARCH_FAMILIES.includes(value);
+}
+/** `--arch x86_64,aarch64`: one or more families, in the given order, each once. */
+export function parseArchList(value) {
+    const families = [];
+    for (const item of value.split(",").map((part) => part.trim())) {
+        if (!isNativeArchFamily(item)) {
+            throw new Error(`--arch 只接受 ${NATIVE_ARCH_FAMILIES.join("、")}（可用逗號列出多個），收到「${value}」。`);
+        }
+        if (!families.includes(item)) {
+            families.push(item);
+        }
+    }
+    return families;
 }
 export function infoArchValue(family) {
     return NATIVE_ARCH_PLATFORMS[family].join(" ");
 }
+/** The family an INFO `arch` token belongs to: a family name or one of its platforms. */
+export function familyOfArchToken(token) {
+    if (isNativeArchFamily(token)) {
+        return token;
+    }
+    return NATIVE_ARCH_FAMILIES.find((family) => NATIVE_ARCH_PLATFORMS[family].includes(token));
+}

package/dist/build-spk/dsm-version.d.ts

@@ -0,0 +1,14 @@
+/** INFO os_min_ver for native-go and binary templates, and the default release for --min-dsm. */
+export declare const DEFAULT_MIN_DSM: string;
+/**
+ * Container Apps run through the DSM docker-project resource worker, which
+ * Container Manager only provides from DSM 7.2.1 on. Declaring anything lower
+ * would install and then fail to start.
+ */
+export declare const CONTAINER_MIN_DSM: string;
+/** `true` when `value` is not older than `floor`, comparing version parts then build. */
+export declare function isDsmAtLeast(value: string, floor: string): boolean;
+/** Container Apps cannot declare an os_min_ver below {@link CONTAINER_MIN_DSM}. */
+export declare function assertContainerMinDsm(value: string): void;
+/** `--min-dsm`: a release (`7.1`) or a full `<version>-<build>` string (`7.2-69057`). */
+export declare function resolveMinDsm(value: string): string;

package/dist/build-spk/dsm-version.js

@@ -0,0 +1,47 @@
+/** First public build of each DSM 7 release; `--min-dsm 7.2` means `7.2-64570`. */
+const FIRST_BUILD = {
+    "7.0": "7.0-41890",
+    "7.1": "7.1-42661",
+    "7.2": "7.2-64570",
+    "7.2.1": "7.2.1-69057",
+};
+/** INFO os_min_ver for native-go and binary templates, and the default release for --min-dsm. */
+export const DEFAULT_MIN_DSM = FIRST_BUILD["7.1"];
+/**
+ * Container Apps run through the DSM docker-project resource worker, which
+ * Container Manager only provides from DSM 7.2.1 on. Declaring anything lower
+ * would install and then fail to start.
+ */
+export const CONTAINER_MIN_DSM = FIRST_BUILD["7.2.1"];
+/** `true` when `value` is not older than `floor`, comparing version parts then build. */
+export function isDsmAtLeast(value, floor) {
+    const [valueVersion, valueBuild] = value.split("-");
+    const [floorVersion, floorBuild] = floor.split("-");
+    const valueParts = valueVersion.split(".").map(Number);
+    const floorParts = floorVersion.split(".").map(Number);
+    for (let i = 0; i < Math.max(valueParts.length, floorParts.length); i++) {
+        const difference = (valueParts[i] ?? 0) - (floorParts[i] ?? 0);
+        if (difference !== 0) {
+            return difference > 0;
+        }
+    }
+    return Number(valueBuild) >= Number(floorBuild);
+}
+/** Container Apps cannot declare an os_min_ver below {@link CONTAINER_MIN_DSM}. */
+export function assertContainerMinDsm(value) {
+    if (!isDsmAtLeast(value, CONTAINER_MIN_DSM)) {
+        throw new Error(`[MIN_DSM_CONTAINER_FLOOR] 容器 App 需要 DSM ${CONTAINER_MIN_DSM} 以上（docker-project／Container Manager 從 DSM 7.2.1 才有），收到「${value}」。`);
+    }
+}
+const FULL_VERSION = /^7\.\d+(\.\d+)?-\d+$/;
+/** `--min-dsm`: a release (`7.1`) or a full `<version>-<build>` string (`7.2-69057`). */
+export function resolveMinDsm(value) {
+    if (FULL_VERSION.test(value)) {
+        return value;
+    }
+    const build = FIRST_BUILD[value];
+    if (!build) {
+        throw new Error(`[MIN_DSM_INVALID] --min-dsm 只接受 ${Object.keys(FIRST_BUILD).join("、")}，或完整的 <版本>-<build>（例如 7.2-64570），收到「${value}」。`);
+    }
+    return build;
+}

package/dist/build-spk/gateway.d.ts

@@ -0,0 +1,31 @@
+import { type CommandRunner } from "../standalone/build.js";
+import type { AppContract } from "../types.js";
+import type { NativeArchFamily } from "./dsm-arch.js";
+export { gatewayEntryPath } from "../contract/web-launch.js";
+/** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
+export declare const GATEWAY_CGI_PAYLOAD = "ui/cgi/gateway.cgi";
+/** Readable copy of the baked-in configuration, for inspection; the CGI does not read it. */
+export declare const GATEWAY_CONFIG_PAYLOAD = "gateway.json";
+export type GatewayErrorCode = "GATEWAY_GO_MISSING" | "GATEWAY_BUILD_FAILED";
+export interface GatewayConfig {
+    upstream: string;
+    access: "users" | "admins" | "groups";
+    groups?: string[];
+}
+/** The access rule and container address the gateway enforces; undefined for an App without one. */
+export declare function gatewayConfig(contract: AppContract, adminport: number): GatewayConfig | undefined;
+/** Compiles the fixed gateway module for `arch`; the result is a static ELF or a coded failure. */
+export declare function buildGatewayBinary(input: {
+    packageId: string;
+    arch: NativeArchFamily;
+    config: GatewayConfig;
+    work: string;
+    run?: CommandRunner;
+}): {
+    binary: string;
+} | {
+    error: GatewayErrorCode;
+    detail: string;
+};
+/** Puts the CGI (mode 0755) and its readable configuration into the package payload. */
+export declare function writeGatewayPayload(packageDir: string, binary: string, config: GatewayConfig): void;

package/dist/build-spk/gateway.js

@@ -0,0 +1,55 @@
+import { chmodSync, copyFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkCgiBinary } from "../standalone/binary.js";
+import { runCommand } from "../standalone/build.js";
+import { resolvedWebAccess } from "../contract/web-launch.js";
+import { templatesRoot } from "../template-paths.js";
+export { gatewayEntryPath } from "../contract/web-launch.js";
+/** Where the gateway CGI sits in the package payload; DSM serves `ui/` under /webman/3rdparty/<package>/. */
+export const GATEWAY_CGI_PAYLOAD = "ui/cgi/gateway.cgi";
+/** Readable copy of the baked-in configuration, for inspection; the CGI does not read it. */
+export const GATEWAY_CONFIG_PAYLOAD = "gateway.json";
+const GOARCH = { x86_64: "amd64", aarch64: "arm64" };
+const ACCESS = { "dsm-users": "users", "dsm-admins": "admins", "dsm-groups": "groups" };
+/** The access rule and container address the gateway enforces; undefined for an App without one. */
+export function gatewayConfig(contract, adminport) {
+    const access = resolvedWebAccess(contract);
+    if (!access || access.mode === "public") {
+        return undefined;
+    }
+    return {
+        upstream: `127.0.0.1:${adminport}`,
+        access: ACCESS[access.mode],
+        ...(access.mode === "dsm-groups" ? { groups: access.groups } : {}),
+    };
+}
+/** Compiles the fixed gateway module for `arch`; the result is a static ELF or a coded failure. */
+export function buildGatewayBinary(input) {
+    const out = join(input.work, `gateway-${input.arch}.cgi`);
+    const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${input.packageId}`, `-X 'main.configJSON=${JSON.stringify(input.config)}'`].join(" ");
+    const result = (input.run ?? runCommand)("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, "."], {
+        cwd: join(templatesRoot(), "_gateway"),
+        env: { ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: GOARCH[input.arch] },
+    });
+    if (result.missing) {
+        return { error: "GATEWAY_GO_MISSING", detail: "找不到 go 指令。DSM 驗證閘道需要 Go 1.24 以上版本（https://go.dev/dl/）才能建置。" };
+    }
+    if (result.status !== 0) {
+        return { error: "GATEWAY_BUILD_FAILED", detail: `go build（${input.arch}）失敗。\n${result.stderr}` };
+    }
+    const problem = checkCgiBinary(input.work, out, input.arch);
+    if (problem) {
+        return { error: "GATEWAY_BUILD_FAILED", detail: problem.message };
+    }
+    return { binary: out };
+}
+/** Puts the CGI (mode 0755) and its readable configuration into the package payload. */
+export function writeGatewayPayload(packageDir, binary, config) {
+    const cgi = join(packageDir, GATEWAY_CGI_PAYLOAD);
+    mkdirSync(join(cgi, ".."), { recursive: true });
+    copyFileSync(binary, cgi);
+    chmodSync(cgi, 0o755);
+    const configPath = join(packageDir, GATEWAY_CONFIG_PAYLOAD);
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    chmodSync(configPath, 0o644);
+}

package/dist/build-spk/generator.d.ts

@@ -1,13 +1,18 @@
 import type { ProjectRoot } from "../discovery.js";
+import type { CommandRunner } from "../standalone/build.js";
 import { type NativeArchFamily } from "./dsm-arch.js";
 export interface BuildSpkOptions {
     project: ProjectRoot;
     outputPath?: string;
     archFamily?: NativeArchFamily;
+    /** INFO os_min_ver (a release such as 7.1, or a full 7.x-build); defaults to the contract's. */
+    minDsm?: string;
     packageIdentity?: string;
     displayname?: string;
     /** Overrides contract version before INFO is rendered (e.g. `1.0.0-0002`). */
     spkVersion?: string;
+    /** Command runner for the DSM gateway's `go build` (tests inject a fake). */
+    gatewayRun?: CommandRunner;
 }
 export interface BuildSpkResult {
     ok: boolean;