@synopackageland/cli 0.5.0 → 0.6.0

package/dist/cli.js

@@ -1,573 +1,435 @@
-import { isNativeLayout, loadNativeLayout, buildNativeLayout } from "./standalone/native-layout.js";
-import { planDeployment, deployStandalone } from "./deploy/plan.js";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { readFileSync, renameSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, join } 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 { formatPinReport, pinProjectImages } from "./images/pin.js";
 import { initFromTemplate, isTemplateName, listTemplates } from "./init.js";
+import { templatesRoot } from "./template-paths.js";
+import { addCapabilities } from "./add.js";
 import { validateProject } from "./validate.js";
 import { runDev } from "./dev.js";
 import { testProject } from "./test-command.js";
 import { buildSpk } from "./build-spk/generator.js";
-import { isNativeArchFamily, NATIVE_ARCH_FAMILIES, parseArchList } from "./build-spk/dsm-arch.js";
+import { isNativeArchFamily, NATIVE_ARCH_FAMILIES, parseArchList, } from "./build-spk/dsm-arch.js";
 import { DEFAULT_MIN_DSM, CONTAINER_MIN_DSM } from "./build-spk/dsm-version.js";
 import { deployProject } from "./deploy/deploy.js";
+import { planDeployment, deployStandalone } from "./deploy/plan.js";
 import { createNasHost } from "./host/dsm-client.js";
-import { projectInfo, formatProjectInfo } from "./info.js";
-import { followProjectLogs } from "./log.js";
+import { projectInfo, standaloneInfo, formatProjectInfo } from "./info.js";
+import { followProjectLogs, followStandaloneLogs } from "./log.js";
 import { formatSkillList, readSkill, resolveSkillsRoot } from "./skill.js";
 import { resolveInstallParameterExtraValues } from "./deploy/param-values.js";
-import { findStandaloneRoot, loadStandaloneManifest } from "./standalone/manifest.js";
+import { findStandaloneRoot, loadStandaloneManifest, } from "./standalone/manifest.js";
 import { buildStandalone } from "./standalone/build.js";
 import { inspectSpk } from "./standalone/inspect-spk.js";
-import { templatesRoot } from "./template-paths.js";
-import { join } from "node:path";
-function collectKvOption(value, previous, flag, example) {
-    const separator = value.indexOf("=");
-    if (separator <= 0) {
-        throw new Error(`${flag} 格式應為 SLOT=邏輯名，例如 ${example}`);
-    }
-    return {
-        ...(previous ?? {}),
-        [value.slice(0, separator)]: value.slice(separator + 1),
-    };
+function failure(code, message, hint = "修正設定後重試；使用 --help 查看指令用法。") {
+    return Object.assign(new Error(`[${code}] ${message}`), { code, hint });
 }
-function collectShareOption(value, previous) {
-    return collectKvOption(value, previous, "--share", "--share MEDIA_SHARE=photos");
-}
-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;
-    return findProjectRoot(start);
+function requireProject(cwd, project) {
+    const found = findProjectRoot(project ? resolve(cwd, project) : cwd);
+    if (!found)
+        throw failure("PROJECT_NOT_FOUND", "找不到 synology-app.yaml 或 dsm-package.yaml。", "在專案根目錄執行，或使用 --project 指定。");
+    return found;
 }
 function standaloneRoot(cwd, project) {
     return findStandaloneRoot(project ? resolve(cwd, project) : cwd);
 }
+function collectKv(value, previous, flag) {
+    const separator = value.indexOf("=");
+    if (separator <= 0)
+        throw failure("CLI_OPTION_INVALID", `${flag} 格式應為 SLOT=值。`);
+    return {
+        ...previous,
+        [value.slice(0, separator)]: value.slice(separator + 1),
+    };
+}
 function formatSpkInspection(spk, report) {
-    const lines = [
+    return [
         `SPK：${spk}`,
         `package：${report.package ?? "?"}  version：${report.version ?? "?"}`,
         `arch：${report.arch ?? "?"}  runtime：${report.kind ?? "?"}`,
         `簽署：${report.signed ? "有 Synology 簽章" : "未簽署（Package Center 需允許任何發行者）"}`,
         `CGI：${report.cgi ?? "無"}`,
-        ...(report.integration ? [`integration protocol：${report.integration.protocol}；NAS data mode：${report.integration.dataAccess}；policy：${report.integration.dataAccess === "relaxed" ? "UID + username" : "unavailable"}；inspect 只核對產物，不證明 runtime adapters／DSM 認證`] : []),
+        ...report.capabilities.map((cap) => `能力 ${cap.name}：${cap.requiresAdminApproval ? "需要 DSM 管理員核准" : "安裝後 ready"}`),
         "payload：",
-        ...report.payload.map((entry) => `  ${entry.mode} ${entry.path}`),
-    ];
-    const integration = report.payload.some(entry => entry.path === "integration/helper");
-    lines.push(report.findings.length === 0
-        ? integration ? "檢查：安裝以套件帳號執行；執行期整合另需管理員核准，此檢查不證明 integration ready。" : "檢查：沒有 root 權限需求或異常。"
-        : "問題：");
-    lines.push(...report.findings.map((finding) => `  - ${finding}`));
-    return lines.join("\n");
-}
-function requireProject(cwd, project) {
-    const found = resolveProject(cwd, project);
-    if (!found) {
-        console.error("找不到 synology-app.yaml。請在專案根目錄執行，或使用 --project 指定。");
-        process.exit(1);
-    }
-    return found;
+        ...(report.uninstallCleanup ?? []).map(item => `Uninstall cleanup (if needed)：${item.target} — ${item.condition} ${item.action}`),
+        ...report.payload.map((e) => `  ${e.mode} ${e.path}`),
+        report.findings.length ? "問題：" : "檢查：沒有 root 權限需求或異常。",
+        ...report.findings.map((f) => `  - ${f}`),
+    ].join("\n");
 }
-async function buildStandaloneCommand(root, arches, options) {
-    if (options.output && arches?.length !== 1) {
-        console.error("-o 只能搭配 --arch 建置單一架構；多架構請用 --out-dir。");
-        process.exit(1);
-    }
+async function standaloneBuild(root, arches, options) {
+    if (options.output && arches?.length !== 1)
+        throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o 只能搭配 --arch 建置單一架構；多架構請用 --out-dir。");
     const outDir = options.output
-        ? dirname(resolve(process.cwd(), options.output))
-        : options.outDir ? resolve(process.cwd(), options.outDir) : undefined;
-    try {
-        const { outputs } = await buildStandalone({ root, arches, outDir, minDsm: options.minDsm });
-        for (let output of outputs) {
-            if (options.output) {
-                const target = resolve(process.cwd(), options.output);
-                renameSync(output, target);
-                output = target;
-            }
-            console.log(`已產生 ${output}`);
-        }
-    }
-    catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
-        process.exit(1);
-    }
+        ? dirname(resolve(options.output))
+        : options.outDir
+            ? resolve(options.outDir)
+            : undefined;
+    const result = await buildStandalone({
+        root,
+        arches,
+        outDir,
+        minDsm: options.minDsm,
+    });
+    return result.outputs.map((output) => {
+        if (!options.output)
+            return output;
+        const target = resolve(options.output);
+        renameSync(output, target);
+        return target;
+    });
 }
-const MIN_DSM_HELP = `最低 DSM 版本（INFO os_min_ver）：7.0、7.1、7.2、7.2.1 或完整的 7.x-build（例如 7.2.1-69057）；省略時用專案宣告的值（native-go／binary 預設 DSM ${DEFAULT_MIN_DSM}，容器模板 ${CONTAINER_MIN_DSM}）`;
-const ARCH_REQUIRED = ["NATIVE_ARCH_FAMILY_REQUIRED", "GATEWAY_ARCH_FAMILY_REQUIRED"];
-/**
- * Container / binary App: an architecture-neutral App builds one SPK. One that
- * needs an architecture (binary, DSM gateway) builds one SPK per --arch family,
- * all of them when --arch is omitted.
- */
-async function buildContainerCommand(project, arches, options) {
-    const outputPath = options.output ? resolve(process.cwd(), options.output) : undefined;
-    const build = (archFamily, output = outputPath) => buildSpk({ project, outputPath: output, archFamily, minDsm: options.minDsm });
-    const fail = (errors) => {
-        console.error(`建置失敗：${errors.join(", ")}`);
-        return process.exit(1);
-    };
+const ARCH_REQUIRED = [
+    "NATIVE_ARCH_FAMILY_REQUIRED",
+    "GATEWAY_ARCH_FAMILY_REQUIRED",
+];
+async function containerBuild(project, arches, options) {
+    const output = options.output ? resolve(options.output) : undefined;
+    const build = (archFamily, outputPath = output) => buildSpk({ project, archFamily, outputPath, minDsm: options.minDsm });
     let results = [];
-    if (arches?.length === 1) {
+    if (arches?.length === 1)
         results = [await build(arches[0])];
-    }
     else {
         const first = await build();
-        if (first.ok || !first.errors.every((code) => ARCH_REQUIRED.includes(code))) {
+        if (first.ok || !first.errors.every((code) => ARCH_REQUIRED.includes(code)))
             results = [first];
-        }
         else {
-            if (outputPath) {
-                console.error("-o 只能搭配 --arch 建置單一架構；多架構請不要加 -o。");
-                process.exit(1);
-            }
+            if (output)
+                throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o 只能搭配 --arch 建置單一架構。");
             const packageId = String(loadContract(project.contractPath).contract.package);
-            for (const arch of arches ?? NATIVE_ARCH_FAMILIES) {
-                results.push(await build(arch, join(project.root, `${packageId}-${arch}.spk`)));
-            }
+            for (const arch of arches ?? NATIVE_ARCH_FAMILIES)
+                results.push(await build(arch, join(options.outDir ? resolve(options.outDir) : project.root, `${packageId}-${arch}.spk`)));
         }
     }
-    for (const result of results) {
+    for (const result of results)
         if (!result.ok)
-            fail(result.errors);
-        console.log(`已產生 ${result.outputPath}`);
-    }
+            throw failure(result.errors[0] ?? "BUILD_FAILED", `建置失敗：${result.errors.join(", ")}`);
+    return results.map((result) => result.outputPath);
 }
 export async function runCli(argv) {
-    const program = new Command();
-    program
+    const json = argv.includes("--json");
+    const stdout = console.log.bind(console);
+    const progress = console.log;
+    const emit = (command, data, text) => json ? stdout(JSON.stringify({ ok: true, command, data })) : stdout(text);
+    const program = new Command()
         .name("synopkgland")
         .description("Syno Package Land Developer Kit CLI")
-        .option("--project <dir>", "App 專案根目錄");
+        .option("--project <dir>", "App 專案根目錄")
+        .exitOverride();
+    const rootOf = (command) => resolve(process.cwd(), command.parent?.opts().project ?? ".");
+    const hostOf = (host) => {
+        if (!host)
+            throw failure("HOST_REQUIRED", "請指定 --host。", "設定 synoagentcli profile，然後使用 --host <name>。");
+        const nas = createNasHost({ host });
+        if (!nas)
+            throw failure("NAS_CREDENTIALS_MISSING", "找不到 NAS 憑證。", "設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
+        return nas;
+    };
     program
-        .command("validate")
-        .description("驗證 App Contract 與 Compose，或 Standalone Package 的 dsm-package.yaml")
+        .command("check")
+        .description("驗證 manifest、能力組合與 Compose")
+        .option("--json", "輸出單一 JSON 物件")
         .action((_options, command) => {
-        const global = command.parent?.opts() ?? {};
-        const standalone = standaloneRoot(process.cwd(), global.project);
+        const validation = validateProject(requireProject(rootOf(command)), {
+            profile: "personal",
+        });
+        if (!validation.ok)
+            throw failure(validation.errors[0].code, formatErrors(validation.errors), validation.errors[0].suggestion);
+        const standalone = standaloneRoot(rootOf(command));
         if (standalone) {
-            const loaded = isNativeLayout(standalone) ? loadNativeLayout(standalone) : loadStandaloneManifest(standalone);
-            if (!loaded.ok) {
-                console.error(loaded.errors.map((e) => `[${e.code}] ${e.message}`).join("\n"));
-                process.exit(1);
-            }
-            console.log("驗證通過。");
+            const loaded = loadStandaloneManifest(standalone);
+            if (!loaded.ok)
+                throw failure(loaded.errors[0].code, loaded.errors.map((e) => `[${e.code}] ${e.message}`).join("\n"), "將 dsm-package.yaml 更新為 schema: 2，修正宣告後重試。");
+            emit("check", {
+                package: loaded.manifest.package,
+                capabilities: loaded.manifest.capabilities,
+            }, "驗證通過。");
             return;
         }
-        const project = requireProject(process.cwd(), global.project);
-        const result = validateProject(project, {
-            profile: "personal",
-        });
-        if (result.warnings && result.warnings.length > 0) {
+        const project = requireProject(rootOf(command));
+        const result = validateProject(project, { profile: "personal" });
+        if (result.warnings?.length)
             console.error(formatErrors(result.warnings));
-        }
-        if (!result.ok) {
-            console.error(formatErrors(result.errors));
-            process.exit(1);
-        }
-        console.log("驗證通過。");
+        if (!result.ok)
+            throw failure(result.errors[0].code, formatErrors(result.errors), result.errors[0].suggestion);
+        const report = inspectProject(project);
+        emit("check", { report, warnings: result.warnings ?? [] }, `驗證通過。\n${formatInspectReport(report)}`);
     });
     program
-        .command("inspect")
-        .description("檢視 Compose 意圖與 Web entry 提示；--spk 檢查已產生的 SPK")
-        .option("--spk <file>", "不安裝，檢查 SPK 的 identity、檔案 mode 與 root 權限需求")
-        .action(async (options, command) => {
-        const global = command.parent?.opts() ?? {};
-        if (options.spk) {
-            const spk = resolve(process.cwd(), options.spk);
-            try {
-                const report = await inspectSpk(spk);
-                console.log(formatSpkInspection(spk, report));
-                if (report.findings.length > 0) {
-                    process.exit(1);
-                }
-            }
-            catch (error) {
-                console.error(error instanceof Error ? error.message : String(error));
-                process.exit(1);
-            }
-            return;
-        }
-        const project = requireProject(process.cwd(), global.project);
-        const report = inspectProject(project);
-        console.log(formatInspectReport(report));
+        .command("inspect <spk>")
+        .description("不安裝，檢查 SPK 身分、檔案與 root 權限需求")
+        .option("--json", "輸出單一 JSON 物件")
+        .action(async (input) => {
+        const spk = resolve(input);
+        const report = await inspectSpk(spk);
+        if (report.findings.length)
+            throw Object.assign(failure("SPK_INSPECTION_FAILED", report.findings.join("\n"), "修正產物並重新 build；勿安裝檢查未通過的 SPK。"), { report });
+        emit("inspect", { spk, ...report }, formatSpkInspection(spk, report));
     });
-    const images = program
-        .command("images")
-        .description("Container image 工具");
+    const images = program.command("images").description("Container image 工具");
     images
         .command("pin")
-        .description("讀取 compose.yaml 的 image，向 registry 取得 manifest digest，改寫為 tag@sha256:...")
-        .option("--check", "只報告未 pin 或已過期的 image，不寫入；有問題時 exit 1")
+        .option("--check", "只檢查，不寫入")
         .action(async (options, command) => {
-        const global = command.parent?.parent?.opts() ?? {};
-        const project = requireProject(process.cwd(), global.project);
-        const check = options.check === true;
-        try {
-            const result = await pinProjectImages({ project, check });
-            console.log(formatPinReport(result, { check }));
-            if (check && result.findings.length > 0) {
-                process.exit(1);
-            }
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+        const project = requireProject(process.cwd(), command.parent?.parent?.opts().project);
+        const result = await pinProjectImages({
+            project,
+            check: options.check === true,
+        });
+        stdout(formatPinReport(result, { check: options.check === true }));
+        if (options.check && result.findings.length)
+            throw failure("IMAGE_PIN_REQUIRED", "Container images 未 pin 或已過期。");
     });
     program
         .command("init")
         .description("從模板建立 App 專案（不覆蓋既有檔案）")
         .option("-t, --template <name>", `模板：${listTemplates().join(" | ")}`)
-        .option("--binary", "建立 Binary App：以套件自己的帳號執行預先建置的 binary（等同 -t binary）")
-        .option("--package <id>", "native-go：INFO.package（預設由目錄名產生，例如 photo-tagger → PhotoTagger）")
-        .option("--name <display>", "native-go：顯示名稱（預設由目錄名產生）")
-        .option("--privilege <none|root>", "native-go：root 另加由 DSM 管理員在套件視窗核准的 root 操作；與 --integration 並用時才加入特權 helper（預設 none）")
-        .option("--ui <plain|vue>", `native-go：UI 實作；預設 vue（沿用 UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} 的 DSM 左右分欄版面）；plain 為舊的純 JS UI`)
-        .option("--background", "native-go（預設 --ui vue）：以套件帳號執行的背景工作（systemd user unit + 固定 sha256-v1 worker；僅管理員；可併用 --integration go、--file-station，不可併用 --privilege root）")
-        .option("--file-station", "native-go：以使用者自己的 DSM session 提供互動 File Station 路由，由套件帳號執行、不需 root（不保存 session，不支援離線 job）")
-        .option("--shared-folder <select|create>", "native-go：安裝精靈選擇既有共用資料夾（select），或由 DSM data-share 建立專屬共用資料夾（create，需 --shared-folder-name）；解除安裝不會刪除共用資料夾")
-        .option("--shared-folder-name <name>", "--shared-folder create：要建立的共用資料夾名稱")
-        .option("--shared-folder-key <key>", "--shared-folder：精靈變數與 var/config.json 的鍵（預設 shared）")
-        .option("--shared-folder-permission <ro|rw>", "--shared-folder：套件帳號需要的權限（預設 rw）")
-        .option("--integration <go|better-auth>", "native-go（預設 --ui vue）：以套件帳號執行的私有範例，不含 helper（加 --privilege root 才有每包 helper）；better-auth 才加入 Node")
-        .option("--integration-protocol <1|2>", "helper inventory protocol（需要 --privilege root；預設 1）；2 可選 NAS data policy，缺已認證 adapters 仍拒絕")
-        .option("--data-access <unavailable|relaxed>", "protocol 2 build-time 身分模式（需要 --privilege root；預設 unavailable）；relaxed 不繞過 DSM／App／lifecycle gates")
-        .option("--min-dsm <version>", `新專案的最低 DSM 版本（os_min_ver）：7.0、7.1、7.2、7.2.1 或完整的 7.x-build（native-go／binary 預設 ${DEFAULT_MIN_DSM}，容器模板 ${CONTAINER_MIN_DSM}）`)
+        .option("--package <id>", "INFO.package（預設由目錄名產生）")
+        .option("--name <display>", "顯示名稱")
+        .option("--ui <vue|plain>", `native-go：UI，預設 vue（UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]}）；plain 使用 ui/app.js`)
+        .option("--with <caps>", "能力（逗號分隔）：files,jobs,login,root-ops")
+        .option("--from <compose.yaml>", "compose：匯入現有 Compose；省略時建立範例")
+        .option("--shared-folder <select|create>", "安裝精靈選擇或建立共用資料夾")
+        .option("--shared-folder-name <name>", "建立的共用資料夾名稱")
+        .option("--shared-folder-key <key>", "設定鍵，預設 shared")
+        .option("--shared-folder-permission <ro|rw>", "套件帳號權限，預設 rw")
+        .option("--min-dsm <version>", `最低 DSM 版本（native-go／binary 預設 ${DEFAULT_MIN_DSM}，compose 預設 ${CONTAINER_MIN_DSM}）`)
         .argument("[dir]", "目標目錄", ".")
-        .addHelpText("after", `
-模板分兩類：
-  獨立 Container / Binary App（synology-app.yaml）：
-    容器（compose.yaml）：hello-web、hello-web-page、hello-files、compose-import
-    binary（native.yaml）：執行一個預先建置的 binary 服務；可用 adminport 在自己的 port 提供網頁
-  Standalone Package（未簽署原生 SPK，含 Go CGI 與 DSM 視窗，dsm-package.yaml）：
-    native-go：Go CGI backend + DSM 視窗 UI，預設需登入、admin 動作另外宣告。
-      --privilege root：另加固定的 root 操作（root/<名稱>.sh），由 DSM 管理員在套件視窗
-      以密碼核准後才能執行；預設 none，完全不用 root。
-
-快速開始（native-go，需要 Go 1.24+）：
-  synopkgland init -t native-go my-app
-  cd my-app && $EDITOR backend/internal/app/routes.go frontend/src/App.vue
-  synopkgland build-spk          # → dist/<Package>-<version>-<arch>.spk
-  synopkgland inspect --spk dist/<file>.spk
-
-UI 預設為 --ui vue（DSM 左右分欄）；--ui plain 使用舊的 ui/app.js。`)
-        .action(async (dir, options, command) => {
-        const global = command.parent?.opts() ?? {};
-        if (global.project) {
-            console.error("--project 不適用於 init。");
-            process.exit(1);
-        }
-        const targetDir = resolve(process.cwd(), dir);
-        const template = options.binary ? "binary" : options.template;
-        if (!template) {
-            console.error(`請指定 -t, --template <name> 或 --binary。可選模板：${listTemplates().join(" | ")}`);
-            process.exit(1);
-        }
-        if (!isTemplateName(template)) {
-            console.error(`未知模板：${template}`);
-            process.exit(1);
-        }
-        if ((options.package || options.name || options.privilege) && template !== "native-go") {
-            console.error("--package／--name／--privilege 只適用於 -t native-go。");
-            process.exit(1);
-        }
-        try {
-            initFromTemplate(template, targetDir, {
-                packageId: options.package,
-                displayName: options.name,
-                minDsm: options.minDsm,
-                privilege: options.privilege,
-                ui: options.ui,
-                integration: options.integration,
-                background: options.background === true,
-                fileStation: options.fileStation === true,
-                sharedFolder: options.sharedFolder === undefined ? undefined : { mode: options.sharedFolder, name: options.sharedFolderName, key: options.sharedFolderKey, permission: options.sharedFolderPermission },
-                integrationProtocol: options.integrationProtocol === undefined ? undefined : (["1", "2"].includes(options.integrationProtocol) ? Number(options.integrationProtocol) : NaN),
-                dataAccess: options.dataAccess,
-            });
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
-        console.log(`已建立 ${template} 專案於 ${targetDir}`);
-        if (template === "native-go") {
-            console.log(`下一步：
-  cd ${dir}
-  (cd backend && go test ./...)   # 認證與權限政策測試
-  synopkgland build-spk           # 編譯 Go + 打包每個架構的未簽署 SPK
-說明見 README.md。`);
-        }
+        .addHelpText("after", "\n原生專案：native-go 與 binary 使用 dsm-package.yaml schema 2。\nCompose 專案：compose 使用 synology-app.yaml；--from 匯入 compose.yaml。\n快速開始：synopkgland init -t native-go --with files,jobs,login my-app\n  cd my-app && synopkgland build\n")
+        .action((dir, options, command) => {
+        if (command.parent?.opts().project)
+            throw failure("CLI_OPTION_INVALID", "--project 不適用於 init。");
+        if (!options.template)
+            throw failure("INIT_TEMPLATE_REQUIRED", `請指定 -t, --template <name>。可選模板：${listTemplates().join(" | ")}`);
+        if (!isTemplateName(options.template))
+            throw failure("INIT_TEMPLATE_UNKNOWN", `未知模板：${options.template}`);
+        const targetDir = resolve(dir);
+        initFromTemplate(options.template, targetDir, {
+            packageId: options.package,
+            displayName: options.name,
+            minDsm: options.minDsm,
+            ui: options.ui,
+            with: options.with === undefined
+                ? undefined
+                : String(options.with).split(","),
+            from: options.from === undefined ? undefined : resolve(options.from),
+            sharedFolder: options.sharedFolder === undefined
+                ? undefined
+                : {
+                    mode: options.sharedFolder,
+                    name: options.sharedFolderName,
+                    key: options.sharedFolderKey,
+                    permission: options.sharedFolderPermission,
+                },
+        });
+        stdout(`已建立 ${options.template} 專案於 ${targetDir}`);
+        if (options.template === "native-go")
+            stdout(`下一步：\n  cd ${dir}\n  (cd backend && go test ./...)\n  synopkgland build\n說明見 README.md。`);
+    });
+    program
+        .command("add <caps...>")
+        .description("加入能力與 SDK-owned overlay；不覆寫既有應用檔案")
+        .action((caps, _options, command) => {
+        const result = addCapabilities(rootOf(command), caps);
+        stdout(`已新增：${result.added.join(", ") || "無"}；已存在：${result.unchanged.join(", ") || "無"}`);
     });
     program
         .command("dev")
-        .description("啟動 App 自己的本機 Compose")
+        .description("啟動本機 Compose")
         .action(async (_options, command) => {
-        const global = command.parent?.opts() ?? {};
-        const project = requireProject(process.cwd(), global.project);
+        const project = requireProject(rootOf(command));
         const validation = validateProject(project);
-        if (!validation.ok) {
-            console.error(formatErrors(validation.errors));
-            process.exit(1);
-        }
-        try {
-            const handle = await runDev({
-                project,
-            });
-            console.log("Compose 已就緒。按 Ctrl+C 結束。");
-            const shutdown = async () => {
-                await handle.close();
-                process.exit(0);
-            };
-            process.on("SIGINT", shutdown);
-            process.on("SIGTERM", shutdown);
-            await new Promise(() => { });
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+        if (!validation.ok)
+            throw failure(validation.errors[0].code, formatErrors(validation.errors));
+        const handle = await runDev({ project });
+        stdout("Compose 已就緒。按 Ctrl+C 結束。");
+        const shutdown = async () => {
+            await handle.close();
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+        await new Promise(() => { });
     });
     program
         .command("test")
         .description("驗證契約並等待 Compose 就緒")
         .action(async (_options, command) => {
-        const global = command.parent?.opts() ?? {};
-        const project = requireProject(process.cwd(), global.project);
-        try {
-            const result = await testProject({ project });
-            if (!result.ok) {
-                console.error(`測試失敗：${result.errors.join(", ")}`);
-                process.exit(1);
-            }
-            console.log("測試通過。");
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+        const result = await testProject({
+            project: requireProject(rootOf(command)),
+        });
+        if (!result.ok)
+            throw failure(result.errors[0] ?? "TEST_FAILED", `測試失敗：${result.errors.join(", ")}`);
+        stdout("測試通過。");
     });
     program
         .command("deploy")
-        .description("建置獨立 SPK 並直接安裝到 DSM")
-        .option("--host <name>", "synoagentcli profile 或 NAS 名稱")
-        .option("--arch <family>", `native App 的目標架構：${NATIVE_ARCH_FAMILIES.join(" 或 ")}（省略時由 NAS 判定）`)
-        .option("--dev", "部署到 Development Package Identity（{package}.dev）")
-        .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)
+        .description("建置 SPK 並安裝到 DSM")
+        .option("--json", "輸出單一 JSON 物件")
+        .option("--host <name>", "NAS profile")
+        .option("--arch <family>", NATIVE_ARCH_FAMILIES.join(" | "))
+        .option("--dev", "Development Package Identity")
+        .option("--share <slot=name>", "Compose 共用資料夾", (value, previous) => collectKv(value, previous, "--share"))
+        .option("--run-as <slot=name>", "Compose DSM 使用者", (value, previous) => collectKv(value, previous, "--run-as"))
+        .option("--param <NAME=value>", "Compose 安裝參數", (value, previous) => collectKv(value, previous, "--param"))
         .option("--dry-run", "只輸出本機部署計畫，不連接 NAS")
         .action(async (options, command) => {
-        const global = command.parent?.opts() ?? {};
-        if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
-            throw new Error(`--arch accepts ${NATIVE_ARCH_FAMILIES.join(" or ")}`);
-        }
-        const plan = planDeployment(resolve(process.cwd(), global.project ?? '.'), {
-            arch: options.arch, dev: options.dev,
+        if (options.arch !== undefined &&
+            !isNativeArchFamily(String(options.arch)))
+            throw failure("CLI_ARCH_INVALID", `--arch accepts ${NATIVE_ARCH_FAMILIES.join(" or ")}`);
+        const plan = planDeployment(rootOf(command), {
+            arch: options.arch,
+            dev: options.dev,
         });
+        if (plan.kind !== "container" &&
+            (options.share || options.runAs || options.param))
+            throw failure("CLI_OPTION_INVALID", "native-go／binary 不接受 Compose 安裝參數。");
         if (options.dryRun) {
-            console.log(JSON.stringify(plan, null, 2));
+            emit("deploy", plan, JSON.stringify(plan, null, 2));
             return;
         }
-        if (!options.host)
-            throw new Error('deploy requires --host, or use --dry-run');
-        if (plan.kind === 'native-go') {
-            if (options.share || options.runAs || options.param)
-                throw new Error('native-go does not accept container install parameters');
-            const host = createNasHost({ host: options.host });
-            if (!host)
-                throw new Error('NAS credentials not found');
+        if (plan.kind !== "container") {
+            const host = hostOf(options.host);
             const output = await deployStandalone(plan, host);
-            console.log(`已部署 ${plan.packageId}: ${output}`);
-            for (const note of plan.notes)
-                console.log(note);
+            const status = await standaloneInfo({ root: plan.root, host });
+            emit("deploy", { ...plan, output, status }, `已部署 ${plan.packageId}: ${output}\n${formatProjectInfo(status)}${plan.notes.length ? "\n" + plan.notes.join("\n") : ""}`);
             return;
         }
-        const project = requireProject(process.cwd(), global.project);
+        const project = requireProject(rootOf(command));
         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。");
-            process.exit(1);
-        }
-        try {
-            if (options.arch !== undefined && !isNativeArchFamily(String(options.arch))) {
-                console.error(`--arch 只接受 ${NATIVE_ARCH_FAMILIES.join("、")}，收到 ${String(options.arch)}。`);
-                process.exit(1);
-            }
-            const result = await deployProject({
-                archFamily: options.arch ? String(options.arch) : undefined,
-                project,
-                host,
-                dev: options.dev,
-                shareValues: options.share,
-                runAsValues: options.runAs,
-                paramValues: options.param,
-            });
-            if (!result.ok) {
-                console.error(`[${result.code ?? "DEPLOY_FAILED"}] ${result.message ?? "部署失敗。"}`);
-                process.exit(1);
-            }
-            for (const note of result.notes ?? []) {
-                console.warn(`[注意] ${note}`);
-            }
-            console.log(`已部署 ${result.packageId}`);
-            if (result.openUrl) {
-                console.log(`Open URL：${result.openUrl}`);
-            }
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+        if (!parameterCheck.ok)
+            throw failure(parameterCheck.code, parameterCheck.message);
+        const result = await deployProject({
+            project,
+            host: hostOf(options.host),
+            archFamily: options.arch,
+            dev: options.dev,
+            shareValues: options.share,
+            runAsValues: options.runAs,
+            paramValues: options.param,
+        });
+        if (!result.ok)
+            throw failure(result.code ?? "DEPLOY_FAILED", result.message ?? "部署失敗。");
+        for (const note of result.notes ?? [])
+            console.error(`[注意] ${note}`);
+        emit("deploy", result, `已部署 ${result.packageId}${result.openUrl ? "\nOpen URL：" + result.openUrl : ""}`);
     });
     program
-        .command("info")
-        .description("顯示 DSM 套件狀態與 Open URL")
-        .requiredOption("--host <name>", "synoagentcli profile 或 NAS 名稱")
-        .option("--dev", "查詢 Development Package Identity")
+        .command("status")
+        .description("DSM 套件狀態、Open URL 與能力就緒狀態")
+        .option("--json", "輸出單一 JSON 物件")
+        .option("--host <name>", "NAS profile")
+        .option("--dev", "Development Package Identity")
         .action(async (options, command) => {
-        const global = command.parent?.opts() ?? {};
-        const project = requireProject(process.cwd(), global.project);
-        const host = createNasHost({ host: options.host });
-        if (!host) {
-            console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
-            process.exit(1);
-        }
-        try {
-            const info = await projectInfo({ project, host, dev: options.dev });
-            console.log(formatProjectInfo(info));
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+        const host = hostOf(options.host);
+        const root = rootOf(command);
+        const standalone = standaloneRoot(root);
+        const info = standalone
+            ? await standaloneInfo({ root: standalone, host, dev: options.dev })
+            : await projectInfo({
+                project: requireProject(root),
+                host,
+                dev: options.dev,
+            });
+        emit("status", info, formatProjectInfo(info));
     });
     program
-        .command("log")
-        .description("顯示 App 容器 log 與遮罩後的診斷資訊")
-        .requiredOption("--host <name>", "synoagentcli profile 或 NAS 名稱")
-        .option("--dev", "查詢 Development Package Identity")
+        .command("logs")
+        .description("App log 與遮罩後的診斷資訊")
+        .requiredOption("--host <name>", "NAS profile")
+        .option("--dev", "Development Package Identity")
         .action(async (options, command) => {
-        const global = command.parent?.opts() ?? {};
-        const project = requireProject(process.cwd(), global.project);
-        const host = createNasHost({ host: options.host });
-        if (!host) {
-            console.error("找不到 NAS 憑證。請設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
-            process.exit(1);
-        }
-        try {
-            const result = await followProjectLogs({ project, host, dev: options.dev });
-            if (!result.ok) {
-                console.error("套件尚未安裝。先執行 synopkgland deploy --host。");
-                process.exit(1);
-            }
-            for (const line of result.lines) {
-                console.log(line);
-            }
-            if (result.diagnostics) {
-                console.log(JSON.stringify(result.diagnostics, null, 2));
-            }
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
-    });
-    const skill = program
-        .command("skill")
-        .description("列出或讀取隨 CLI 內建的 Agent Skill Pack");
-    skill
-        .command("path")
-        .description("輸出 Skill Pack 根目錄（供 agent 載入 SKILL.md）")
-        .action(() => {
-        console.log(resolveSkillsRoot());
-    });
-    skill
-        .command("list")
-        .description("列出漸進式 skill 與檔案路徑")
-        .action(() => {
-        console.log(formatSkillList());
-    });
-    skill
-        .command("show <id>")
-        .description("輸出指定 skill 內容（orchestrator、create、wrap、identity、files、deploy、diagnose）")
-        .action((id) => {
-        try {
-            console.log(readSkill(id));
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+        const host = hostOf(options.host);
+        const root = rootOf(command);
+        const standalone = standaloneRoot(root);
+        const result = standalone
+            ? await followStandaloneLogs({
+                root: standalone,
+                host,
+                dev: options.dev,
+            })
+            : await followProjectLogs({
+                project: requireProject(root),
+                host,
+                dev: options.dev,
+            });
+        if (!result.ok)
+            throw failure("NOT_INSTALLED", "套件尚未安裝。先執行 synopkgland deploy --host。");
+        for (const line of result.lines)
+            stdout(line);
+        if (result.diagnostics)
+            stdout(JSON.stringify(result.diagnostics, null, 2));
     });
+    const skill = program.command("skill").description("內建 Agent Skill Pack");
+    skill.command("path").action(() => stdout(resolveSkillsRoot()));
+    skill.command("list").action(() => stdout(formatSkillList()));
+    skill.command("show <id>").action((id) => stdout(readSkill(id)));
     program
-        .command("build-spk")
-        .description("產生本機未簽署 SPK：容器 App（synology-app.yaml）或 Standalone Package（dsm-package.yaml，會先編譯 UI 與 Go）")
-        .option("-o, --output <path>", "輸出 .spk 路徑（Standalone Package 只在建置單一架構時可用）")
-        .option("--out-dir <dir>", "Standalone Package：輸出目錄（預設 dist/）")
-        .option("--arch <families>", `目標架構，可用逗號列出多個，例如 x86_64,aarch64（可填：${NATIVE_ARCH_FAMILIES.join("、")}；省略時兩者都建，每個架構各產一個 SPK）`)
-        .option("--min-dsm <version>", MIN_DSM_HELP)
-        .option("--build <number>", "Native layout: override DSM build number")
+        .command("build")
+        .description("產生 SPK：synology-app.yaml 或 dsm-package.yaml")
+        .option("--json", "輸出單一 JSON 物件")
+        .option("-o, --output <path>", "輸出 SPK，搭配單一 --arch")
+        .option("--out-dir <dir>", "輸出目錄，原生專案預設 dist/")
+        .option("--arch <families>", `架構，可用逗號分隔：${NATIVE_ARCH_FAMILIES.join(",")}`)
+        .option("--min-dsm <version>", "最低 DSM 版本，省略時使用 manifest 值")
         .action(async (options, command) => {
-        const global = command.parent?.opts() ?? {};
-        const layoutRoot = standaloneRoot(process.cwd(), global.project);
-        if (layoutRoot && isNativeLayout(layoutRoot)) {
-            try {
-                if (options.minDsm)
-                    throw new Error("Native layout: set os_min_ver in dsm-package.yaml");
-                const arches = options.arch === undefined ? undefined : String(options.arch).split(",");
-                if (options.output && arches?.length !== 1)
-                    throw new Error("-o requires exactly one --arch");
-                const result = await buildNativeLayout({ root: layoutRoot, arches, build: options.build === undefined ? undefined : Number(options.build), outDir: options.outDir ? resolve(options.outDir) : undefined });
-                for (const output of result.outputs) {
-                    if (options.output)
-                        renameSync(output, resolve(options.output));
-                    console.log(`已產生 ${options.output ?? output}`);
-                }
-            }
-            catch (e) {
-                console.error(String(e));
-                process.exit(1);
-            }
-            return;
-        }
-        if (options.build !== undefined) {
-            console.error("--build requires native layout");
-            process.exit(1);
-        }
         let arches;
         try {
-            arches = options.arch === undefined ? undefined : parseArchList(String(options.arch));
+            arches =
+                options.arch === undefined
+                    ? undefined
+                    : parseArchList(String(options.arch));
         }
         catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
-        const standalone = standaloneRoot(process.cwd(), global.project);
-        if (standalone) {
-            await buildStandaloneCommand(standalone, arches, options);
-            return;
-        }
-        const project = requireProject(process.cwd(), global.project);
-        await buildContainerCommand(project, arches, options);
+            throw failure("CLI_ARCH_INVALID", error instanceof Error ? error.message : String(error));
+        }
+        const root = rootOf(command);
+        const standalone = standaloneRoot(root);
+        const outputs = standalone
+            ? await standaloneBuild(standalone, arches, options)
+            : await containerBuild(requireProject(root), arches, options);
+        emit("build", { outputs }, outputs.map((output) => `已產生 ${output}`).join("\n"));
     });
-    await program.parseAsync(argv);
+    if (json)
+        console.log = (...args) => console.error(...args);
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        if (error instanceof CommanderError && error.exitCode === 0)
+            return;
+        if (json) {
+            const detail = error;
+            const codes = {
+                "commander.unknownOption": "CLI_OPTION_UNKNOWN",
+                "commander.missingArgument": "CLI_ARGUMENT_MISSING",
+                "commander.missingMandatoryOptionValue": "CLI_OPTION_MISSING",
+                "commander.optionMissingArgument": "CLI_OPTION_ARGUMENT_MISSING",
+                "commander.unknownCommand": "CLI_COMMAND_UNKNOWN",
+            };
+            const message = detail.message ?? String(error);
+            const code = codes[detail.code ?? ""] ??
+                detail.code ??
+                /^\[?([A-Z][A-Z0-9_]+)\]?:?\s/.exec(message)?.[1] ??
+                "COMMAND_FAILED";
+            stdout(JSON.stringify({
+                ok: false,
+                code,
+                message,
+                hint: detail.hint ?? "修正設定後重試；使用 --help 查看指令用法。",
+                ...(detail.report ? { data: detail.report } : {}),
+            }));
+        }
+        throw error;
+    }
+    finally {
+        console.log = progress;
+    }
 }