@synopackageland/cli 0.14.1 → 0.15.1

package/dist/init.js

@@ -1,18 +1,19 @@
 import { goChildEnv } from "./runtime/go-env.js";
 import { spawnSync } from "node:child_process";
-import { isMap, isScalar, parse, parseDocument } from "yaml";
+import { parse, parseDocument } from "yaml";
 import { setTopLevel } from "./yaml-edit.js";
-import { capabilityNames, capabilitySettings } from "./capabilities.js";
-import { MOVE_FROM_STAGING } from './runtime/delegate-contract.js';
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { capabilityNames, capabilitySettings, } from "./capabilities.js";
+import { MOVE_FROM_STAGING } from "./runtime/delegate-contract.js";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { APP_SCRIPTS_DIR } from "./standalone/app-scripts.js";
 import { SDK_MODULE, SDK_PACKAGE, sdkSource } from "./runtime/sdk-source.js";
 import { templatesRoot } from "./template-paths.js";
-import { BASE_BORROWED, BRIDGE_TEMPLATES, borrowedFiles, borrowedTarget, capabilityOverlays, VUE_OVERLAYS } from "./capability-overlays.js";
-import { copyNodeSdk, copyPythonSdk, NODE_SDK_PACKAGE } from "./standalone/bridge-app.js";
+import { BASE_BORROWED, BRIDGE_TEMPLATES, borrowedFiles, borrowedTarget, capabilityOverlays, VUE_OVERLAYS, } from "./capability-overlays.js";
+import { copyNodeSdk, copyPythonSdk, NODE_SDK_PACKAGE, } from "./standalone/bridge-app.js";
 import { API_PERMISSIONS_FILE } from "./standalone/api-permissions.js";
-import { resolveMinDsm, assertContainerMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast } from "./build-spk/dsm-version.js";
+import { resolveMinDsm, assertContainerMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast, } from "./build-spk/dsm-version.js";
+import { composeInputs } from "./standalone/compose.js";
 import { readSharedFolder } from "./standalone/shared-folder.js";
 const TEMPLATE_NAMES = [
     "compose",
@@ -26,13 +27,13 @@ const isNativeTemplate = (template) => NATIVE_TEMPLATES.includes(template);
 const isBridgeTemplate = (template) => BRIDGE_TEMPLATES.includes(template);
 /** Where each native template keeps its API permissions. */
 const PERMISSIONS_FILE = {
-    "native-go": `backend/${API_PERMISSIONS_FILE.go}`, "native-python": `backend/app/${API_PERMISSIONS_FILE.python}`,
-    "native-node": `backend/app/${API_PERMISSIONS_FILE.node}`, "native-rust": `backend/${API_PERMISSIONS_FILE.rust}`,
+    "native-go": `backend/${API_PERMISSIONS_FILE.go}`,
+    "native-python": `backend/app/${API_PERMISSIONS_FILE.python}`,
+    "native-node": `backend/app/${API_PERMISSIONS_FILE.node}`,
+    "native-rust": `backend/${API_PERMISSIONS_FILE.rust}`,
 };
 /** Templates whose App runs through the DSM docker-project resource worker. */
-const CONTAINER_TEMPLATES = [
-    "compose",
-];
+const CONTAINER_TEMPLATES = ["compose"];
 /** The container templates need DSM 7.2.1 or later; native-go and binary need 7.1. */
 export function isContainerTemplate(template) {
     return CONTAINER_TEMPLATES.includes(template);
@@ -46,26 +47,35 @@ export function listTemplates() {
 /** New native scaffolds opt in explicitly; existing manifests are never migrated. */
 export function nativeCapabilitySettings(names) {
     const settings = capabilitySettings(names);
-    if (names.includes('delegate'))
+    if (names.includes("delegate"))
         settings.delegate = {
-            scope: 'install-selected', operations: [MOVE_FROM_STAGING], destinations: ['save'], lifetime: 'until-revoked',
+            scope: "install-selected",
+            operations: [MOVE_FROM_STAGING],
+            destinations: ["save"],
+            lifetime: "until-revoked",
         };
     return settings;
 }
 /** Templates whose identity is filled in at init: every generated file may carry a placeholder. */
-const IDENTIFIED = [...NATIVE_TEMPLATES, "binary"];
+const IDENTIFIED = [...NATIVE_TEMPLATES, "binary", "compose"];
 const PACKAGE_ID = /^[A-Za-z][A-Za-z0-9]{1,63}$/;
 /** npm never publishes files named .gitignore, so templates ship them as `gitignore`. */
 const RENAMED = { gitignore: ".gitignore" };
 function words(dir) {
-    return basename(dir).split(/[^A-Za-z0-9]+/).filter(Boolean);
+    return basename(dir)
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean);
 }
 function defaultPackageId(dir) {
-    const id = words(dir).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+    const id = words(dir)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join("");
     return PACKAGE_ID.test(id) ? id : "MyPackage";
 }
 function defaultDisplayName(dir) {
-    const name = words(dir).map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+    const name = words(dir)
+        .map((w) => w[0].toUpperCase() + w.slice(1))
+        .join(" ");
     return name || "My Package";
 }
 function templateFiles(root, dir = root) {
@@ -84,7 +94,7 @@ function targetName(file) {
 }
 /** Native templates default to the Vue shell; the CLI and the library entry point agree. */
 function resolvedUi(template, options) {
-    return isNativeTemplate(template) ? options.ui ?? "vue" : options.ui;
+    return isNativeTemplate(template) ? (options.ui ?? "vue") : options.ui;
 }
 /**
  * Copy one template tree into a project. A template directory may carry a local
@@ -92,18 +102,32 @@ function resolvedUi(template, options) {
  * to a generated project (and would otherwise shadow the project's own install).
  */
 export function copyTemplateTree(source, target) {
-    cpSync(source, target, { recursive: true, filter: (path) => !isTemplateBuildArtifact(path) });
+    cpSync(source, target, {
+        recursive: true,
+        filter: (path) => !isTemplateBuildArtifact(path),
+    });
 }
 function isTemplateBuildArtifact(path) {
     const name = basename(path);
-    return name === "node_modules" || name === "dist" || name === ".go-results.json";
+    return (name === "node_modules" || name === "dist" || name === ".go-results.json");
 }
 export function initFromTemplate(template, targetDir, options = {}) {
     if (!isTemplateName(template))
         throw new Error(`[INIT_TEMPLATE_UNKNOWN] Unknown template: ${template}`);
     const requested = capabilityNames(options.with ?? []);
-    const capability = isNativeTemplate(template) ? capabilityOverlays(template, requested) : { overlays: [], borrowed: [], removed: [], permissions: {}, implied: [], methods: [] };
-    const caps = capabilityNames([...new Set([...capability.implied ?? [], ...requested])]);
+    const capability = isNativeTemplate(template)
+        ? capabilityOverlays(template, requested)
+        : {
+            overlays: [],
+            borrowed: [],
+            removed: [],
+            permissions: {},
+            implied: [],
+            methods: [],
+        };
+    const caps = capabilityNames([
+        ...new Set([...(capability.implied ?? []), ...requested]),
+    ]);
     if (caps.includes("login") && resolvedUi(template, options) === "plain")
         throw new Error("[CAPABILITY_COMBINATION_INVALID] login needs a standalone sign-in page; plain UI does not support it, use --ui vue.");
     if (caps.includes("delegate") && resolvedUi(template, options) === "plain")
@@ -112,7 +136,9 @@ export function initFromTemplate(template, targetDir, options = {}) {
         throw new Error("[INIT_OPTIONS_UNSUPPORTED] --from applies only to compose.");
     if (caps.length && !isNativeTemplate(template))
         throw new Error("[CAPABILITY_UNSUPPORTED] binary/compose does not support --with capabilities.");
-    const localSdk = isNativeTemplate(template) && process.env.SYNOPKGLAND_SDK_DIR ? resolve(process.env.SYNOPKGLAND_SDK_DIR) : undefined;
+    const localSdk = isNativeTemplate(template) && process.env.SYNOPKGLAND_SDK_DIR
+        ? resolve(process.env.SYNOPKGLAND_SDK_DIR)
+        : undefined;
     if (localSdk)
         assertLocalSdkReady(localSdk, resolvedUi(template, options) === "vue");
     const source = join(templatesRoot(), template);
@@ -126,23 +152,47 @@ export function initFromTemplate(template, targetDir, options = {}) {
     const substitutions = substitutionsFor(template, targetDir, options);
     const ui = resolvedUi(template, options);
     const rootExample = caps.includes("root-ops");
-    if (rootExample && minDsm !== undefined && !isDsmAtLeast(minDsm, DEFAULT_MIN_DSM)) {
+    if (rootExample &&
+        minDsm !== undefined &&
+        !isDsmAtLeast(minDsm, DEFAULT_MIN_DSM)) {
         throw new Error(`[MIN_DSM_INVALID] root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
     }
-    const vue = ui === "vue" && isNativeTemplate(template) ? VUE_OVERLAYS[template] : { overlays: [], borrowed: [] };
+    const vue = ui === "vue" && isNativeTemplate(template)
+        ? VUE_OVERLAYS[template]
+        : { overlays: [], borrowed: [] };
     const base = isNativeTemplate(template) ? BASE_BORROWED[template] : [];
     // Later borrowed files replace earlier ones, as later overlays do.
-    const borrowed = borrowedFiles(templatesRoot(), [...base, ...vue.borrowed, ...capability.borrowed]);
-    const overlays = [...vue.overlays, ...capability.overlays].map(name => join(templatesRoot(), name));
+    const borrowed = borrowedFiles(templatesRoot(), [
+        ...base,
+        ...vue.borrowed,
+        ...capability.borrowed,
+    ]);
+    const overlays = [...vue.overlays, ...capability.overlays].map((name) => join(templatesRoot(), name));
     // Shared legal resources also live in the CLI package; only the template
     // terms are an unconditional part of a generated project.
     const shared = join(templatesRoot(), "_shared");
     // dsm-scripts/: the DSM lifecycle scripts every project starts with (doing nothing); older templates have none.
-    const sharedScripts = existsSync(join(shared, APP_SCRIPTS_DIR)) ? readdirSync(join(shared, APP_SCRIPTS_DIR)).sort().map(name => `${APP_SCRIPTS_DIR}/${name}`) : [];
-    const sharedFiles = ["LICENSES/TEMPLATE.txt", "AGENTS.md", "CLAUDE.md", ...sharedScripts];
-    const files = [...templateFiles(source), ...sharedFiles, ...overlays.flatMap(root => templateFiles(root)),
-        ...borrowed.map(borrowedTarget), ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : [])];
-    const collisions = files.map(targetName).filter((file) => existsSync(join(targetDir, file)));
+    const sharedScripts = existsSync(join(shared, APP_SCRIPTS_DIR))
+        ? readdirSync(join(shared, APP_SCRIPTS_DIR))
+            .sort()
+            .map((name) => `${APP_SCRIPTS_DIR}/${name}`)
+        : [];
+    const sharedFiles = [
+        "LICENSES/TEMPLATE.txt",
+        "AGENTS.md",
+        "CLAUDE.md",
+        ...sharedScripts,
+    ];
+    const files = [
+        ...templateFiles(source),
+        ...sharedFiles,
+        ...overlays.flatMap((root) => templateFiles(root)),
+        ...borrowed.map(borrowedTarget),
+        ...(ui === "vue" ? ["frontend/third-party-notices.mjs"] : []),
+    ];
+    const collisions = files
+        .map(targetName)
+        .filter((file) => existsSync(join(targetDir, file)));
     if (collisions.length > 0) {
         throw new Error(`[INIT_TARGET_NOT_EMPTY] ${targetDir} already has ${collisions.join(", ")}; init does not overwrite existing files. Use an empty directory.`);
     }
@@ -154,16 +204,19 @@ export function initFromTemplate(template, targetDir, options = {}) {
     }
     for (const overlay of overlays)
         copyTemplateTree(overlay, targetDir);
-    for (const dir of (ui === "vue" ? ["frontend"] : [])) {
+    for (const dir of ui === "vue" ? ["frontend"] : []) {
         cpSync(join(shared, "third-party-notices.mjs"), join(targetDir, dir, "third-party-notices.mjs"));
     }
     for (const path of borrowed) {
-        mkdirSync(dirname(join(targetDir, borrowedTarget(path))), { recursive: true });
+        mkdirSync(dirname(join(targetDir, borrowedTarget(path))), {
+            recursive: true,
+        });
         cpSync(join(templatesRoot(), path), join(targetDir, borrowedTarget(path)));
     }
     for (const file of capability.removed)
         rmSync(join(targetDir, file));
-    if (Object.keys(capability.permissions).length && isNativeTemplate(template)) {
+    if (Object.keys(capability.permissions).length &&
+        isNativeTemplate(template)) {
         const path = join(targetDir, PERMISSIONS_FILE[template]);
         const policy = JSON.parse(readFileSync(path, "utf8"));
         Object.assign(policy.methods, capability.permissions);
@@ -183,15 +236,18 @@ export function initFromTemplate(template, targetDir, options = {}) {
     if (capability.methods?.length && template === "native-rust") {
         // A cross-compiled Rust App cannot describe itself: its manifest lists the methods.
         const manifest = join(targetDir, "dsm-package.yaml");
-        writeFileSync(manifest, readFileSync(manifest, "utf8").replace(/^( {2}methods: \[.*)\]$/m, (_, list) => `${list}${capability.methods.map(name => `, ${name}`).join("")}]`));
+        writeFileSync(manifest, readFileSync(manifest, "utf8").replace(/^( {2}methods: \[.*)\]$/m, (_, list) => `${list}${capability.methods.map((name) => `, ${name}`).join("")}]`));
     }
     if (minDsm) {
-        const manifest = join(targetDir, template !== "compose" ? "dsm-package.yaml" : "synology-app.yaml");
+        const manifest = join(targetDir, "dsm-package.yaml");
         writeFileSync(manifest, readFileSync(manifest, "utf8").replace(/^os_min_ver:.*$/m, `os_min_ver: "${minDsm}"`));
     }
     if (ui === "vue") {
         const manifest = join(targetDir, "dsm-package.yaml");
-        writeFileSync(manifest, readFileSync(manifest, "utf8").replace("  dir: ui", "  dir: frontend/dist\n  build: {cwd: frontend, command: [npm, run, build]}").replace("  launch: new-page\n", "").replace("Non-UI-SDK frontends open a full page", "UI SDK frontends open a DSM window"));
+        writeFileSync(manifest, readFileSync(manifest, "utf8")
+            .replace("  dir: ui", "  dir: frontend/dist\n  build: {cwd: frontend, command: [npm, run, build]}")
+            .replace("  launch: new-page\n", "")
+            .replace("Non-UI-SDK frontends open a full page", "UI SDK frontends open a DSM window"));
         rmSync(join(targetDir, "ui"), { recursive: true });
     }
     if (ui !== "vue")
@@ -199,14 +255,37 @@ export function initFromTemplate(template, targetDir, options = {}) {
     if (template !== "compose") {
         // Only the capabilities change: the template's comments document the optional fields.
         const path = join(targetDir, "dsm-package.yaml");
-        writeFileSync(path, setTopLevel(readFileSync(path, "utf8"), { capabilities: nativeCapabilitySettings(caps) }));
+        writeFileSync(path, setTopLevel(readFileSync(path, "utf8"), {
+            capabilities: nativeCapabilitySettings(caps),
+        }));
     }
     if (template === "compose" && options.from)
-        importCompose(options.from, targetDir, options);
+        importCompose(options.from, targetDir);
     if (template === "binary") {
         mkdirSync(join(targetDir, "prebuilt"), { recursive: true });
-        for (const [arch, goarch] of [["x86_64", "amd64"], ["aarch64", "arm64"]]) {
-            const result = spawnSync("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", "-s -w -buildid=", "-o", join(targetDir, "prebuilt", `api-${arch}`), "main.go"], { cwd: join(targetDir, "example"), env: goChildEnv({ ...process.env, CGO_ENABLED: "0", GOOS: "linux", GOARCH: goarch }), encoding: "utf8" });
+        for (const [arch, goarch] of [
+            ["x86_64", "amd64"],
+            ["aarch64", "arm64"],
+        ]) {
+            const result = spawnSync("go", [
+                "build",
+                "-trimpath",
+                "-buildvcs=false",
+                "-ldflags",
+                "-s -w -buildid=",
+                "-o",
+                join(targetDir, "prebuilt", `api-${arch}`),
+                "main.go",
+            ], {
+                cwd: join(targetDir, "example"),
+                env: goChildEnv({
+                    ...process.env,
+                    CGO_ENABLED: "0",
+                    GOOS: "linux",
+                    GOARCH: goarch,
+                }),
+                encoding: "utf8",
+            });
             if (result.error || result.status !== 0)
                 throw new Error(`[INIT_BINARY_BUILD_FAILED] Install Go and run init again, or provide your own static CGI binary. ${result.stderr ?? result.error}`);
         }
@@ -218,15 +297,19 @@ export function initFromTemplate(template, targetDir, options = {}) {
 }
 /** Each native template's method tests, as its README runs them; Node.js also compiles the backend/app the SPK ships. */
 const BACKEND_TESTS = {
-    "native-go": "go test ./...", "native-python": "python3 -m unittest discover -s tests",
-    "native-node": "npm ci && npm test && npm run build", "native-rust": "cargo test --locked",
+    "native-go": "go test ./...",
+    "native-python": "python3 -m unittest discover -s tests",
+    "native-node": "npm ci && npm test && npm run build",
+    "native-rust": "cargo test --locked",
 };
 /** What to run after init in `dir`, for a template built from source; undefined for the others. */
 export function initNextSteps(template, dir, frontend, localSdk) {
     if (!isNativeTemplate(template))
         return undefined;
     // --install-links packs a local SDK like the released package; a symlink would load the checkout's own node_modules.
-    const install = frontend ? `  (cd frontend && npm install${localSdk ? " --install-links" : ""})\n` : "";
+    const install = frontend
+        ? `  (cd frontend && npm install${localSdk ? " --install-links" : ""})\n`
+        : "";
     return `Next steps:\n  cd ${dir}\n  (cd backend && ${BACKEND_TESTS[template]})\n${install}  synopkgland build\nSee README.md.`;
 }
 /**
@@ -234,38 +317,74 @@ export function initNextSteps(template, dir, frontend, localSdk) {
  * directory-derived) identity and keeps only the example install entries the
  * imported Compose references as `${KEY}` (or `${KEY_UID}`/`${KEY_GID}`).
  */
-function importCompose(from, targetDir, options) {
+function importCompose(from, targetDir) {
     const imported = readFileSync(from, "utf8");
     const compose = parse(imported);
     if (!compose || typeof compose !== "object" || !compose.services)
         throw new Error("[INIT_COMPOSE_INVALID] --from needs a Compose YAML with services.");
-    writeFileSync(join(targetDir, "compose.yaml"), imported);
-    const path = join(targetDir, "synology-app.yaml");
+    const sourceRoot = dirname(resolve(from)), file = basename(from);
+    const envFile = existsSync(join(sourceRoot, ".env")) ? ".env" : undefined;
+    const inputs = composeInputs(sourceRoot, file, envFile);
+    for (const input of inputs) {
+        const dest = join(targetDir, input.path);
+        if (existsSync(dest) && input.path !== "compose.yaml")
+            throw new Error(`[INIT_TARGET_NOT_EMPTY] Imported input collides with scaffold: ${input.path}`);
+    }
+    if (file !== "compose.yaml")
+        rmSync(join(targetDir, "compose.yaml"));
+    for (const input of inputs) {
+        const dest = join(targetDir, input.path);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, Buffer.from(input.content, "base64"), { mode: 0o600 });
+    }
+    // Import local sidecar input files without changing the upstream YAML. The
+    // SDK planner validates the complete include/env closure before any build.
+    const path = join(targetDir, "dsm-package.yaml");
     const doc = parseDocument(readFileSync(path, "utf8"));
-    doc.set("package", options.packageId ?? defaultPackageId(targetDir));
-    doc.set("displayname", validDisplayName(options.displayName ?? defaultDisplayName(targetDir)));
-    const install = doc.get("install");
-    const referenced = new Set([...imported.matchAll(/\$\{([A-Z][A-Z0-9_]*?)(?:_UID|_GID)?\}/g)].map(match => match[1]));
-    if (isMap(install))
-        install.items = install.items.filter(item => referenced.has(String(isScalar(item.key) ? item.key.value : item.key)));
-    if (!isMap(install) || install.items.length === 0)
-        doc.delete("install");
+    doc.setIn(["compose", "files"], [file]);
+    if (envFile)
+        doc.setIn(["compose", "env_files"], [envFile]);
+    const services = Object.entries(compose.services);
+    const candidates = services
+        .flatMap(([service, spec]) => (spec.ports ?? []).map((port) => {
+        const target = typeof port === "object"
+            ? Number(port.target)
+            : Number(String(port).split("/")[0].split(":").pop());
+        return { service, port: target };
+    }))
+        .filter((p) => Number.isInteger(p.port) && p.port > 0 && p.port < 65536);
+    if (candidates.length === 1)
+        doc.setIn(["compose", "web"], {
+            ...candidates[0],
+            health: { path: "/", status: 200 },
+        });
+    else {
+        doc.deleteIn(["compose", "web"]);
+        doc.delete("identity_gateway");
+    } // Ambiguous ingress requires an explicit developer decision.
     writeFileSync(path, String(doc));
 }
 function validDisplayName(displayName) {
     if (displayName.trim() === "" || /[\r\n"\\]/.test(displayName)) {
-        throw new Error("[INIT_DISPLAY_NAME_INVALID] The display name must be single-line and without \" or \\.");
+        throw new Error('[INIT_DISPLAY_NAME_INVALID] The display name must be single-line and without " or \\.');
     }
     return displayName;
 }
 /** The `install.sharedFolder` block, validated by the same reader build-spk uses. */
 function sharedFolderYaml(options) {
-    const folder = { mode: options.mode, key: options.key ?? "shared", ...(options.name === undefined ? {} : { name: options.name }), permission: options.permission ?? "rw" };
+    const folder = {
+        mode: options.mode,
+        key: options.key ?? "shared",
+        ...(options.name === undefined ? {} : { name: options.name }),
+        permission: options.permission ?? "rw",
+    };
     const errors = [];
-    if (!readSharedFolder({ sharedFolder: folder }, e => errors.push(e.message))) {
+    if (!readSharedFolder({ sharedFolder: folder }, (e) => errors.push(e.message))) {
         throw new Error(`[INIT_SHARED_FOLDER_INVALID] ${errors.join(" ")}`);
     }
-    return `\ninstall:\n  sharedFolder:\n${Object.entries(folder).map(([k, v]) => `    ${k}: ${v}\n`).join("")}`;
+    return `\ninstall:\n  sharedFolder:\n${Object.entries(folder)
+        .map(([k, v]) => `    ${k}: ${v}\n`)
+        .join("")}`;
 }
 /**
  * The App SDK a bridge App's tests import, in backend/vendor: the Python
@@ -276,7 +395,8 @@ function sharedFolderYaml(options) {
 function vendorAppSdk(template, targetDir) {
     if (template === "native-rust")
         return;
-    const version = String(parse(readFileSync(join(targetDir, "dsm-package.yaml"), "utf8")).backend.sdk);
+    const version = String(parse(readFileSync(join(targetDir, "dsm-package.yaml"), "utf8")).backend
+        .sdk);
     const sdk = sdkSource(version).goDir;
     const vendor = join(targetDir, "backend/vendor");
     if (template === "native-python")
@@ -311,7 +431,7 @@ function useLocalSdk(targetDir, sdkDir) {
         if (existsSync(sdkPackage)) {
             const version = JSON.parse(readFileSync(sdkPackage, "utf8")).version;
             if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version))
-                throw new Error('[SDK_DIR_NOT_READY] Local SDK package version must be X.Y.Z.');
+                throw new Error("[SDK_DIR_NOT_READY] Local SDK package version must be X.Y.Z.");
             text = text.replace(/(github\.com\/synopackageland\/syno-pkg-land-sdk v)\d+\.\d+\.\d+\b/g, `$1${version}`);
         }
         writeFileSync(goMod, `${text}\nreplace ${SDK_MODULE} => ${sdkDir}\n`);
@@ -363,5 +483,9 @@ function substitutionsFor(template, targetDir, options) {
         throw new Error(`[INIT_PACKAGE_INVALID] package "${packageId}" must start with a letter and contain only alphanumerics (2-64 characters), for example PhotoTagger.`);
     }
     const displayName = validDisplayName(options.displayName ?? defaultDisplayName(targetDir));
-    return { __PACKAGE__: packageId, __DISPLAY_NAME__: displayName, __BACKGROUND_ENABLED__: caps.includes("jobs") || caps.includes("delegate") ? "true" : "false" };
+    return {
+        __PACKAGE__: packageId,
+        __DISPLAY_NAME__: displayName,
+        __BACKGROUND_ENABLED__: caps.includes("jobs") || caps.includes("delegate") ? "true" : "false",
+    };
 }

package/dist/inspect.js

@@ -18,7 +18,14 @@ export function inspectProject(project) {
     }
     const parsed = loadCompose(project.composePath);
     if (!parsed) {
-        return { services, publishedPorts, dataMounts, risks, webHints, exposedPorts: [] };
+        return {
+            services,
+            publishedPorts,
+            dataMounts,
+            risks,
+            webHints,
+            exposedPorts: [],
+        };
     }
     const compose = parsed.compose;
     services.push(...listServiceNames(compose));
@@ -29,12 +36,19 @@ export function inspectProject(project) {
     collectRisks(compose, risks);
     if (publishedPorts.length > 0) {
         const primary = publishedPorts[0];
-        webHints.push(`Detected published port ${primary.port}; consider setting adminport: ${primary.port} in synology-app.yaml.`);
-        webHints.push("A Web App usually also needs adminprotocol and adminurl.");
-        webHints.push("Launch Mode: integration.web.launch is dsm-window (DSM window) or new-page (default, new tab).");
+        webHints.push(`Detected published port ${primary.port}; declare the web service/target for no-publish ingress in dsm-package.yaml compose.web.`);
+        webHints.push("Use the SDK identity gateway for Web ingress and review its access policy.");
+        webHints.push("Launch Mode: ui.launch is dsm-window or new-page (Compose default, new tab).");
     }
     const exposedPorts = listPortExposures(compose).filter((exposure) => !exposure.loopbackOnly);
-    return { services, publishedPorts, dataMounts, risks, webHints, exposedPorts };
+    return {
+        services,
+        publishedPorts,
+        dataMounts,
+        risks,
+        webHints,
+        exposedPorts,
+    };
 }
 function collectDataMounts(compose, out) {
     if (!compose.services) {
@@ -43,7 +57,8 @@ function collectDataMounts(compose, out) {
     for (const [serviceName, service] of Object.entries(compose.services)) {
         const volumes = normalizeVolumeEntries(service.volumes);
         for (const volume of volumes) {
-            if (volume.includes("SYNOPKG_PKGVAR") || volume.includes("SYNO_APP_SECRETS_DIR")) {
+            if (volume.includes("SYNOPKG_PKGVAR") ||
+                volume.includes("SYNO_APP_SECRETS_DIR")) {
                 out.push(`${serviceName}: ${volume}`);
             }
         }

package/dist/runtime/executor-digests.json

@@ -1,5 +1,5 @@
 {
-    "0.14.1": {
+    "0.15.0": {
         "x86_64": "efe409287770f6b70e7f8465e8767eeb2413b9ab8775020cf4dffb1555d7bf1f",
         "aarch64": "d68c9889ed2391e918b9c278679ea0a01cd04425528c11090700a3b6341fc543",
         "armv7": "9149a05efb9f2d7d86a400707099b3d657382b1c0dbad6588be8c500e90445cc",
@@ -10,10 +10,10 @@
         },
         "goToolchain": "go1.26.9"
     },
-    "0.14.0": {
-        "x86_64": "efe409287770f6b70e7f8465e8767eeb2413b9ab8775020cf4dffb1555d7bf1f",
-        "aarch64": "d68c9889ed2391e918b9c278679ea0a01cd04425528c11090700a3b6341fc543",
-        "armv7": "9149a05efb9f2d7d86a400707099b3d657382b1c0dbad6588be8c500e90445cc",
+    "0.15.1": {
+        "x86_64": "4f47fb43f6e60dbad064afb0bbec96dd009fa046670e2c4b590b128a855cb404",
+        "aarch64": "c903b09ad657a838f0c62b6688e65e9094572b22b969770fca92fcc3640a5364",
+        "armv7": "8178d90de7ea720530bb9496e50ed118086b0e57382d84675aadc68f482d219f",
         "lifecycle": {
             "x86_64": "d65500c4f04713a32b45d360059281391acfa5e00ee24895fdd2de7b82735372",
             "aarch64": "94f6cd119186ff482b8aea56541dd1f9d53c147566bc1efdca6f5a1c86198331",

package/dist/skill.js

@@ -3,17 +3,59 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const SKILL_CATALOG = [
     { 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-gateway", file: "reference/identity-gateway.md", when: "Wrap OSS native or container apps with DSM account SSO" },
-    { id: "identity", file: "reference/identity.md", when: "Needs a DSM sign-in" },
+    { id: "ctl", file: "reference/ctl.md", when: "Operate registered NAS Apps or design AI commands" },
+    {
+        id: "create",
+        file: "reference/create.md",
+        when: "Start from nothing or a one-liner",
+    },
+    {
+        id: "compose",
+        file: "reference/compose.md",
+        when: "Upstream Compose with the SDK planner, fixed identity and support boundary",
+    },
+    {
+        id: "wrap",
+        file: "reference/wrap.md",
+        when: "Existing Compose, or adding a contract",
+    },
+    {
+        id: "identity-gateway",
+        file: "reference/identity-gateway.md",
+        when: "Wrap OSS native or container apps with the DSM identity gateway",
+    },
+    {
+        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: "lifecycle", file: "reference/lifecycle.md", when: "Add work to install, upgrade, uninstall, start or stop (dsm-scripts/)" },
+    {
+        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: "lifecycle",
+        file: "reference/lifecycle.md",
+        when: "Add work to install, upgrade, uninstall, start or stop (dsm-scripts/)",
+    },
     { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
-    { id: "diagnose", file: "reference/diagnose.md", when: "check/deploy/Open failed" },
+    {
+        id: "diagnose",
+        file: "reference/diagnose.md",
+        when: "check/deploy/Open failed",
+    },
 ];
 export function resolveSkillsRoot() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));

package/dist/standalone/api-description-inspect.d.ts

@@ -0,0 +1,4 @@
+export declare function inspectApiDescription(raw: string, info: {
+    id: string;
+    version: string;
+}, expectedHash: string, registry?: Record<string, string>): string[];

package/dist/standalone/api-description-inspect.js

@@ -0,0 +1,12 @@
+import { validateDescriptor } from '../ctl/descriptor.js';
+export function inspectApiDescription(raw, info, expectedHash, registry) {
+    try {
+        const description = validateDescriptor(JSON.parse(raw), info.id, info.version);
+        if (registry && Object.entries(description.payload.bindings).some(([method, binding]) => !Object.hasOwn(registry, method) || registry[method] !== binding.permission))
+            return ['CTL_COMMAND_BINDING_MISMATCH command method/permission differs from build registry.'];
+        return description.sha256 === expectedHash ? [] : ['CTL_DESCRIPTOR_HASH_MISMATCH API description differs from the build record.'];
+    }
+    catch {
+        return ['CTL_DESCRIPTOR_INVALID API description does not match the schema, commands or final INFO.'];
+    }
+}

package/dist/standalone/api-description.d.ts

@@ -0,0 +1,7 @@
+import { type Descriptor } from '../ctl/descriptor.js';
+import { type StandaloneManifest } from './manifest.js';
+import type { CommandRunner } from './build.js';
+export declare function buildApiDescription(m: StandaloneManifest, bridgeMethods: string[] | undefined, run: CommandRunner): Promise<{
+    description: Descriptor;
+    registry: Record<string, string>;
+} | undefined>;