@synopackageland/cli 0.3.1 → 0.3.2

package/dist/build-spk/resource-worker.d.ts

@@ -0,0 +1,14 @@
+import type { AppContract } from "../types.js";
+import type { ResourceWorkerEligibility } from "../compose/analyze.js";
+export { classifyComposeRoute, resourceWorkerEligibility, type ComposeRoute, type ComposeRouteClassification, type ResourceWorkerEligibility, type ResourceWorkerIneligibleReason, } from "../compose/analyze.js";
+export declare function composeProjectName(packageId: string): string;
+export declare function renderDockerProjectResource(packageId: string, projectPath?: string): Record<string, unknown>;
+export declare function renderWebserviceResource(contract: AppContract, adminport: number): Record<string, unknown>;
+export declare function renderResourceConfig(contract: AppContract, eligibility: ResourceWorkerEligibility): string;
+/**
+ * Renders the lifecycle control script for the Docker Project resource-worker
+ * route. ContainerManager owns the actual project start/stop operation through
+ * the worker timing hooks; the package script must wait for that operation to
+ * leave a reachable service and must not claim running unconditionally.
+ */
+export declare function renderResourceWorkerStartStopStatus(adminport?: number): string;

package/dist/build-spk/resource-worker.js

@@ -0,0 +1,140 @@
+import { cookieStripHeaders, resolvedWebLaunch, webStationAlias, webStationServiceName, } from "../contract/web-launch.js";
+export { classifyComposeRoute, resourceWorkerEligibility, } from "../compose/analyze.js";
+export function composeProjectName(packageId) {
+    const slug = packageId
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "");
+    return slug.length > 0 ? slug : "app";
+}
+export function renderDockerProjectResource(packageId, projectPath = "compose") {
+    const projectName = composeProjectName(packageId);
+    return {
+        "docker-project": {
+            projects: [
+                {
+                    name: projectName,
+                    path: projectPath,
+                    build_params: {
+                        force_pull: true,
+                        force_recreate: true,
+                        build: false,
+                    },
+                },
+            ],
+        },
+    };
+}
+export function renderWebserviceResource(contract, adminport) {
+    const alias = webStationAlias(String(contract.package));
+    const launch = resolvedWebLaunch(contract);
+    const cookieHeaders = cookieStripHeaders(contract);
+    const proxyHeaderEntries = cookieHeaders.map((header) => ({
+        name: header.name,
+        value: header.value,
+    }));
+    const service = {
+        service: webStationServiceName(alias),
+        display_name: String(contract.displayname ?? contract.package),
+        type: "reverse_proxy",
+        support_alias: true,
+        support_server: false,
+        proxy_target: `http://127.0.0.1:${adminport}`,
+        proxy_headers: proxyHeaderEntries,
+    };
+    const portal = {
+        service: webStationServiceName(alias),
+        name: alias,
+        type: "alias",
+        alias,
+    };
+    if (launch === "dsm-window") {
+        portal.app = String(contract.package);
+    }
+    return {
+        webservice: {
+            services: [service],
+            portals: [portal],
+        },
+    };
+}
+export function renderResourceConfig(contract, eligibility) {
+    const packageId = String(contract.package);
+    const dockerResource = renderDockerProjectResource(packageId, "compose");
+    let combined = { ...dockerResource };
+    if (eligibility.adminport !== undefined) {
+        const webResource = renderWebserviceResource(contract, eligibility.adminport);
+        combined = {
+            ...combined,
+            ...webResource,
+        };
+    }
+    return `${JSON.stringify(combined, null, 2)}\n`;
+}
+/**
+ * Renders the lifecycle control script for the Docker Project resource-worker
+ * route. ContainerManager owns the actual project start/stop operation through
+ * the worker timing hooks; the package script must wait for that operation to
+ * leave a reachable service and must not claim running unconditionally.
+ */
+export function renderResourceWorkerStartStopStatus(adminport) {
+    if (adminport === undefined) {
+        return `#!/bin/sh
+case "$1" in
+  start|status)
+    echo "resource-worker package has no published port to probe" >&2
+    exit 3
+    ;;
+  stop) exit 0 ;;
+  *) exit 1 ;;
+esac
+`;
+    }
+    const url = `http://127.0.0.1:${adminport}/`;
+    return `#!/bin/sh
+probe_service() {
+  if command -v curl >/dev/null 2>&1; then
+    curl --silent --output /dev/null --connect-timeout 2 --max-time 5 "${url}"
+    return $?
+  fi
+  if command -v wget >/dev/null 2>&1; then
+    wget --quiet --output-document=/dev/null --timeout=5 --tries=1 "${url}"
+    return $?
+  fi
+  return 127
+}
+
+wait_for_service() {
+  attempts=0
+  while [ "$attempts" -lt 30 ]; do
+    if probe_service; then
+      return 0
+    fi
+    attempts=$((attempts + 1))
+    sleep 1
+  done
+  return 1
+}
+
+case "$1" in
+  start)
+    if wait_for_service; then
+      exit 0
+    fi
+    exit 3
+    ;;
+  stop)
+    exit 0
+    ;;
+  status)
+    if probe_service; then
+      exit 0
+    fi
+    exit 3
+    ;;
+  *)
+    exit 1
+    ;;
+esac
+`;
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { resolve, dirname } from "node:path";
 import { findProjectRoot } from "./discovery.js";
+import { loadContract } from "./contract/load.js";
 import { formatErrors } from "./errors.js";
 import { formatInspectReport, inspectProject } from "./inspect.js";
 import { initFromTemplate, isTemplateName, listTemplates } from "./init.js";
@@ -19,6 +20,7 @@ import { publishProject, resolveCommunityAppsRoot } from "./publish/publish.js";
 import { formatPreflight, runPublicReleasePreflight } from "./publish/preflight.js";
 import { createExecGitHubCli, createExecGitOps } from "./publish/github-pr.js";
 import { communityAppsGitHubRepo } from "./publish/github-repo.js";
+import { resolveInstallParameterExtraValues } from "./deploy/param-values.js";
 function collectKvOption(value, previous, flag, example) {
     const separator = value.indexOf("=");
     if (separator <= 0) {
@@ -35,9 +37,15 @@ function collectShareOption(value, previous) {
 function collectRunAsOption(value, previous) {
     return collectKvOption(value, previous, "--run-as", "--run-as RUN_AS=alice");
 }
+function collectParamOption(value, previous) {
+    return collectKvOption(value, previous, "--param", "--param APP_MODE=prod");
+}
 function resolveProject(cwd, project) {
     const start = project ? resolve(cwd, project) : cwd;
-    const found = findProjectRoot(start);
+    return findProjectRoot(start);
+}
+function requireProject(cwd, project) {
+    const found = resolveProject(cwd, project);
     if (!found) {
         console.error("找不到 synology-app.yaml。請在專案根目錄執行，或使用 --project 指定。");
         process.exit(1);
@@ -50,12 +58,53 @@ export async function runCli(argv) {
         .name("synopkgland")
         .description("Syno Package Land Developer Kit CLI")
         .option("--project <dir>", "App 專案根目錄");
+    program
+        .command("doctor")
+        .description("唯讀診斷本機合約／Compose 與 NAS 部署狀態")
+        .option("--host <name>", "synoagentcli profile 或 NAS 名稱")
+        .option("--package <id>", "指定診斷的 Package Identity（省略時由合約判定）")
+        .option("--dev", "診斷 Development Package Identity（{package}.dev）")
+        .option("--json", "輸出 machine-readable JSON 診斷報告")
+        .action(async (options, command) => {
+        const global = command.parent?.opts() ?? {};
+        const project = resolveProject(process.cwd(), global.project);
+        let host = null;
+        if (options.host) {
+            host = createNasHost({ host: options.host });
+            if (!host) {
+                console.error(`[${"HOST_CREDENTIALS_MISSING"}] 找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。`);
+                process.exit(1);
+            }
+        }
+        try {
+            const { runDoctor, formatDoctorReport } = await import("./doctor.js");
+            const report = await runDoctor({
+                project,
+                host,
+                packageId: options.package,
+                dev: options.dev,
+            });
+            if (options.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                console.log(formatDoctorReport(report));
+            }
+            if (!report.ok) {
+                process.exit(1);
+            }
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+    });
     program
         .command("validate")
         .description("驗證 App Contract 與 Compose")
         .action((options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const result = validateProject(project, {
             profile: "personal",
         });
@@ -73,7 +122,7 @@ export async function runCli(argv) {
         .description("檢視 Compose 意圖與 Web entry 提示")
         .action((_options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const report = inspectProject(project);
         console.log(formatInspectReport(report));
     });
@@ -112,7 +161,7 @@ export async function runCli(argv) {
         .option("--files-root <dir>", "將本機目錄對應為 NAS Logical Path")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const validation = validateProject(project);
         if (!validation.ok) {
             console.error(formatErrors(validation.errors));
@@ -146,7 +195,7 @@ export async function runCli(argv) {
         .option("--dev", "檢查 Development Package Identity（{package}.dev）")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         if (options.host) {
             const host = createNasHost({ host: options.host });
             if (!host) {
@@ -189,9 +238,18 @@ export async function runCli(argv) {
         .option("--replace-curated", "危險：將既有 Curated App Package Attestation 降級為 Local Attestation")
         .option("--share <slot=name>", "此 NAS 上的 Shared Folder 邏輯名（契約 shared_folder 槽，可重複）", collectShareOption)
         .option("--run-as <slot=name>", "此 NAS 上的 DSM 使用者邏輯名（契約 dsm_user 槽）", collectRunAsOption)
+        .option("--param <NAME=value>", "契約 string/boolean Install Parameter 答案（可重複）", collectParamOption)
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
+        const parameterCheck = resolveInstallParameterExtraValues({
+            contract: loadContract(project.contractPath).contract,
+            provided: options.param,
+        });
+        if (!parameterCheck.ok) {
+            console.error(`[${parameterCheck.code}] ${parameterCheck.message}`);
+            process.exit(1);
+        }
         const host = createNasHost({ host: options.host });
         if (!host) {
             console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
@@ -210,6 +268,7 @@ export async function runCli(argv) {
                 replaceCurated: options.replaceCurated,
                 shareValues: options.share,
                 runAsValues: options.runAs,
+                paramValues: options.param,
             });
             if (!result.ok) {
                 console.error(`[${result.code ?? "DEPLOY_FAILED"}] ${result.message ?? "部署失敗。"}`);
@@ -232,7 +291,7 @@ export async function runCli(argv) {
         .option("--dev", "查詢 Development Package Identity")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const host = createNasHost({ host: options.host });
         if (!host) {
             console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
@@ -254,7 +313,7 @@ export async function runCli(argv) {
         .option("--dev", "查詢 Development Package Identity")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const host = createNasHost({ host: options.host });
         if (!host) {
             console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
@@ -312,7 +371,7 @@ export async function runCli(argv) {
         .option("--arch <family>", "native App 的目標架構：x86_64 或 aarch64（Compose App 不需要）")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
             console.error(`--arch 只接受 x86_64 或 aarch64，收到 ${String(options.arch)}。`);
             process.exit(1);
@@ -336,7 +395,7 @@ export async function runCli(argv) {
         .option("--base <branch>", "PR 目標分支", "master")
         .action(async (options, command) => {
         const global = command.parent?.opts() ?? {};
-        const project = resolveProject(process.cwd(), global.project);
+        const project = requireProject(process.cwd(), global.project);
         const preflight = await runPublicReleasePreflight(project);
         if (!preflight.ok) {
             // A gate's reasons belong on stderr so CI logs and `2>` capture them.

package/dist/compose/analyze.d.ts

@@ -1,20 +1,60 @@
-import type { ComposeDocument, ComposeService, ValidationError } from "../types.js";
+import { type Document } from "yaml";
+import type { AppContract, ComposeDocument, ComposeService, ValidationError } from "../types.js";
 import { type PrivilegeFlag } from "./privilege.js";
 export interface ParsedCompose {
     compose: ComposeDocument;
     source: string;
+    document: Document;
 }
 export declare function loadCompose(composePath: string): ParsedCompose | null;
 export declare function listServiceNames(compose: ComposeDocument): string[];
 export declare function extractPublishedTcpPorts(service: ComposeService): number[];
 export declare function collectPublishedTcpPorts(compose: ComposeDocument): Map<number, string[]>;
+export type ResourceWorkerIneligibleReason = "HAS_INSTALL_PARAMETERS" | "HAS_COMPOSE_INTERPOLATION" | "HAS_COMPOSE_SECRETS_OR_CONFIGS" | "HAS_BUILD_STANZA" | "HAS_PRIVILEGED_CAPABILITY" | "WEB_APP_MISSING_OR_AMBIGUOUS_ADMINPORT";
+export interface ResourceWorkerEligibility {
+    eligible: boolean;
+    reasons: ResourceWorkerIneligibleReason[];
+    adminport?: number;
+}
+/**
+ * Checks if a Compose contract and document are eligible for the zero-config DSM resource-worker path.
+ * Zero-config slice rejects:
+ * - any install parameter
+ * - any ${...} interpolation anywhere in compose document
+ * - compose secrets or configs
+ * - build: stanzas
+ * - privileged / host network / device / root-like capabilities
+ * - any App without a unique literal published adminport status probe
+ */
+export declare function resourceWorkerEligibility(contract: AppContract, compose: ComposeDocument): ResourceWorkerEligibility;
+export type ComposeRoute = "static-zero-config" | "dynamic" | "reject";
+export interface ComposeRouteClassification {
+    route: ComposeRoute;
+    eligibility: ResourceWorkerEligibility;
+    errors: ValidationError[];
+}
+/**
+ * Chooses the local route D0 can safely emit. The first dynamic slice is
+ * deliberately small: only string/boolean wizard answers interpolated as
+ * ordinary Compose values. Secrets/configs remain rejected because the live
+ * DSM worker does not load docker-compose.override.yml, and no secret may be
+ * placed in the project .env.
+ */
+export declare function classifyComposeRoute(contract: AppContract, parsed: ParsedCompose, composeFile?: string): ComposeRouteClassification;
 export declare function collectComposeInterpolations(compose: ComposeDocument): Set<string>;
 export declare function validateComposeSecurity(compose: ComposeDocument, composeFile: string, options: {
     profile: "personal" | "listing";
     declaredPrivilege: ReadonlySet<PrivilegeFlag>;
 }): ValidationError[];
+/**
+ * DSM's Docker Project resource worker can lose YAML quotes while acquiring a
+ * project. A quoted numeric command argument can therefore become a number;
+ * reject that platform-invalid shape before it reaches the NAS.
+ */
+export declare function validateComposeNumericCommandArgs(compose: ComposeDocument, composeFile: string): ValidationError[];
 export interface HostBindContext {
     sharedFolderParams: ReadonlySet<string>;
+    homesParams?: ReadonlySet<string>;
     installParamNames: ReadonlySet<string>;
 }
 export declare function collectVolumeSourceInterpolations(compose: ComposeDocument): Set<string>;