@synopackageland/cli 0.9.7 → 0.10.0

package/dist/cli.js

@@ -9,7 +9,7 @@ import { codedMessage, formatErrors } from "./errors.js";
 import { getErrorCode } from "./error-registry.js";
 import { formatInspectReport, inspectProject } from "./inspect.js";
 import { formatPinReport, pinProjectImages } from "./images/pin.js";
-import { initFromTemplate, isTemplateName, listTemplates } from "./init.js";
+import { initFromTemplate, initNextSteps, isTemplateName, listTemplates } from "./init.js";
 import { templatesRoot } from "./template-paths.js";
 import { addCapabilities } from "./add.js";
 import { CAPABILITY_NAMES } from "./capabilities.js";
@@ -33,13 +33,13 @@ import { buildStandalone, runnerFor } from "./standalone/build.js";
 import { checkJobs, commitOutputs, forEachArch } from "./standalone/arch-jobs.js";
 import { checkReproducible } from "./reproducible.js";
 import { inspectAnySpk } from "./spk/inspect.js";
-function failure(code, message, hint = "修正設定後重試；使用 --help 查看指令用法。") {
+function failure(code, message, hint = "Fix the configuration and retry; use --help to see command usage.") {
     return Object.assign(new Error(codedMessage(code, message)), { code, hint });
 }
 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 指定。");
+        throw failure("PROJECT_NOT_FOUND", "synology-app.yaml or dsm-package.yaml was not found.", "Run from the project root, or pass --project.");
     return found;
 }
 function standaloneRoot(cwd, project) {
@@ -48,7 +48,7 @@ function standaloneRoot(cwd, project) {
 function collectKv(value, previous, flag) {
     const separator = value.indexOf("=");
     if (separator <= 0)
-        throw failure("CLI_OPTION_INVALID", `${flag} 格式應為 SLOT=值。`);
+        throw failure("CLI_OPTION_INVALID", `${flag} expects the format SLOT=value.`);
     return {
         ...previous,
         [value.slice(0, separator)]: value.slice(separator + 1),
@@ -58,14 +58,14 @@ function collectKv(value, previous, flag) {
 function formatIconReport(report, manifestFile) {
     return {
         lines: report.source === "custom"
-            ? [`圖示：自訂 ${report.path}`]
+            ? [`Icon: custom ${report.path}`]
             : report.source === "layout"
-                ? ["圖示：由 layout metadata 的 PACKAGE_ICON*.PNG 提供（若有）", `info：在 ${manifestFile} 設定 icon: 可改由 CLI 產生 Package Center 圖示。`]
-                : ["圖示：SDK 預設圖示", `info：在 ${manifestFile} 設定 icon: <正方形 PNG（至少 256×256）或 icon_<size>.png 目錄> 換成自己的圖示。`],
-        ...(report.solid ? { warning: "warning：圖示只有單一顏色，Package Center 與 DSM 主選單會像一個色塊；建議換成有圖形的圖示。" } : {}),
+                ? ["Icon: provided by the layout metadata's PACKAGE_ICON*.PNG (if present)", `info: set icon: in ${manifestFile} to have the CLI generate the Package Center icon.`]
+                : ["Icon: SDK default icon", `info: set icon: in ${manifestFile} to <a square PNG (at least 256x256) or an icon_<size>.png directory> to use your own icon.`],
+        ...(report.solid ? { warning: "warning: the icon is a single colour, so Package Center and the DSM main menu show a flat block; use an icon with a graphic." } : {}),
     };
 }
-const LABEL = { error: "錯誤", warning: "警告" };
+const LABEL = { error: "error", warning: "warning" };
 /** One line per finding: severity, stable code, where, and what to fix. */
 function formatFindings(findings) {
     return findings.map((f) => `${LABEL[f.severity]} ${f.code}${f.path ? ` ${f.path}` : ""}: ${f.message}`);
@@ -74,17 +74,17 @@ function formatFindings(findings) {
 function formatSpkChecks(report) {
     const { errors, warnings } = report.dsm;
     return [
-        "DSM 格式：",
+        "DSM format:",
         ...formatFindings([...errors, ...warnings]).map((line) => `  ${line}`),
-        `  ${report.dsm.ok ? "符合" : "不符合"} DSM 7 套件格式：${errors.length} 個錯誤、${warnings.length} 個警告。`,
+        `  ${report.dsm.ok ? "matches" : "does not match"} the DSM 7 package format: ${errors.length} errors, ${warnings.length} warnings.`,
         ...(report.synopkgland
             ? [
-                "synopkgland 合約：",
+                "synopkgland contract:",
                 report.findings.length
-                    ? "  問題："
+                    ? "  Problems:"
                     : report.executor
-                        ? "  檢查：沒有異常。管理員核准後會建立 root executor 排程（boot 與 control task），以 root 執行此 SPK 固定的 executor 與 policy。"
-                        : "  檢查：沒有 root 權限需求或異常。",
+                        ? "  Check: no problems. After an administrator approves, it creates root executor tasks (boot and control task) that run this SPK's fixed executor and policy as root."
+                        : "  Check: no root privilege requirement or problem.",
                 ...report.findings.map((f) => `    - ${f}`),
             ]
             : []),
@@ -92,25 +92,25 @@ function formatSpkChecks(report) {
 }
 function formatSpkReport(spk, report) {
     return [
-        `SPK：${spk}`,
-        `package：${report.package ?? "?"}  version：${report.version ?? "?"}`,
-        report.synopkgland ? `arch：${report.arch ?? "?"}  runtime：${report.kind ?? "?"}` : `arch：${report.arch ?? "?"}  建置：不是 synopkgland（只檢查 DSM 格式）`,
-        `簽署：${report.signed ? "有 Synology 簽章" : "未簽署（Package Center 需允許任何發行者）"}`,
-        ...(report.synopkgland ? [`CGI：${report.cgi ?? "無"}`] : []),
-        ...(report.icon ? [`圖示：${report.icon.source === "default" ? "SDK 預設圖示" : report.icon.source === "custom" ? `自訂（PACKAGE_ICON_256 sha256 ${report.icon.sha256.slice(0, 12)}…）` : "無 PACKAGE_ICON"}`] : []),
-        ...(report.entry === "admin-only" ? ["入口：entry: admin-only，只有 DSM 管理員能開啟與呼叫任何 route（含 SDK routes）"] : []),
-        ...(report.entry === "app-privilege" ? ["入口：entry: app-privilege，由 DSM 控制台「應用程式權限」決定誰能使用"] : []),
-        ...(report.portal ? [`Application Portal：預設別名 /${report.portal.alias}/（${report.portal.appId}），由管理員套用後啟用`] : []),
-        ...report.capabilities.map((cap) => `能力 ${cap.name}：${cap.requiresAdminApproval ? "需要 DSM 管理員核准" : "安裝後 ready"}`),
-        "payload：",
-        ...(report.uninstallCleanup ?? []).map(item => `Uninstall cleanup (if needed)：${item.target} — ${item.condition} ${item.action}`),
+        `SPK: ${spk}`,
+        `package: ${report.package ?? "?"}  version: ${report.version ?? "?"}`,
+        report.synopkgland ? `arch: ${report.arch ?? "?"}  runtime: ${report.kind ?? "?"}` : `arch: ${report.arch ?? "?"}  build: not synopkgland (DSM format only)`,
+        `Signature: ${report.signed ? "Synology-signed" : "unsigned (Package Center must allow any publisher)"}`,
+        ...(report.synopkgland ? [`CGI: ${report.cgi ?? "none"}`] : []),
+        ...(report.icon ? [`Icon: ${report.icon.source === "default" ? "SDK default icon" : report.icon.source === "custom" ? `custom (PACKAGE_ICON_256 sha256 ${report.icon.sha256.slice(0, 12)}…)` : "no PACKAGE_ICON"}`] : []),
+        ...(report.entry === "admin-only" ? ["Entry: entry: admin-only; only a DSM administrator can open it and call any route (including SDK routes)"] : []),
+        ...(report.entry === "app-privilege" ? ["Entry: entry: app-privilege; DSM Control Panel > Application Privileges decides who can use it"] : []),
+        ...(report.portal ? [`Application Portal: default alias /${report.portal.alias}/ (${report.portal.appId}), active after an administrator applies it`] : []),
+        ...report.capabilities.map((cap) => `Capability ${cap.name}: ${cap.requiresAdminApproval ? "needs DSM administrator approval" : "ready after install"}`),
+        "payload:",
+        ...(report.uninstallCleanup ?? []).map(item => `Uninstall cleanup (if needed): ${item.target} — ${item.condition} ${item.action}`),
         ...report.payload.map((e) => `  ${e.mode} ${e.path}`),
         ...formatSpkChecks(report),
     ].join("\n");
 }
 async function standaloneBuild(root, arches, options) {
     if (options.output && arches?.length !== 1)
-        throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o 只能搭配 --arch 建置單一架構；多架構請用 --out-dir。");
+        throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o requires a single --arch; use --out-dir for multiple architectures.");
     const outDir = options.output
         ? dirname(resolve(options.output))
         : options.outDir
@@ -146,10 +146,10 @@ function reproducibleTarget(standalone, project, arches) {
 }
 function reproducibleLines(report) {
     if (report.skipped)
-        return [`可重現檢查：依賴指紋 ${report.fingerprint.slice(0, 12)} 與上次通過時相同，略過。`];
+        return [`Reproducible check: the dependency fingerprint ${report.fingerprint.slice(0, 12)} matches the last passing run, skipping.`];
     return report.results.map((result) => result.identical
-        ? `可重現檢查：${basename(result.output)} 相同（sha256 ${result.sha256[0].slice(0, 12)}）`
-        : `可重現檢查：${basename(result.output)} 不同（sha256 ${result.sha256[0].slice(0, 12)} ≠ ${result.sha256[1].slice(0, 12)}）\n` +
+        ? `Reproducible check: ${basename(result.output)} is identical (sha256 ${result.sha256[0].slice(0, 12)})`
+        : `Reproducible check: ${basename(result.output)} differs (sha256 ${result.sha256[0].slice(0, 12)} ≠ ${result.sha256[1].slice(0, 12)})\n` +
             [...result.payload.map((file) => `  payload ${file}`), ...result.metadata.map((file) => `  metadata ${file}`)].join("\n"));
 }
 const ARCH_REQUIRED = [
@@ -160,12 +160,12 @@ async function containerBuild(project, arches, options) {
     const jobs = checkJobs(options.jobs);
     const unsupported = arches?.find((arch) => !isContainerArchFamily(arch));
     if (unsupported)
-        throw failure("CONTAINER_ARCH_UNSUPPORTED", `Container Manager App 只支援 ${CONTAINER_ARCH_FAMILIES.join("、")}；DSM 不為 ${unsupported} 提供 Container Manager。`);
+        throw failure("CONTAINER_ARCH_UNSUPPORTED", `Container Manager Apps support only ${CONTAINER_ARCH_FAMILIES.join(", ")}; DSM does not provide Container Manager for ${unsupported}.`);
     const output = options.output ? resolve(options.output) : undefined;
     const build = async (archFamily, outputPath = output) => {
         const result = await buildSpk({ project, archFamily, outputPath, minDsm: options.minDsm, gatewayRun: archFamily && runnerFor(undefined, jobs, archFamily) });
         if (!result.ok && !(archFamily === undefined && result.errors.every((code) => ARCH_REQUIRED.includes(code))))
-            throw failure(result.errors[0] ?? "BUILD_FAILED", `建置失敗：${result.errors.join(", ")}`);
+            throw failure(result.errors[0] ?? "BUILD_FAILED", `Build failed: ${result.errors.join(", ")}`);
         return result;
     };
     if (arches?.length === 1)
@@ -174,7 +174,7 @@ async function containerBuild(project, arches, options) {
     if (first.ok)
         return [first.outputPath];
     if (output)
-        throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o 只能搭配 --arch 建置單一架構。");
+        throw failure("CLI_OUTPUT_ARCH_REQUIRED", "-o requires a single --arch.");
     const packageId = String(loadContract(project.contractPath).contract.package);
     return commitOutputs(options.outDir ? resolve(options.outDir) : project.root, (stage) => forEachArch(arches ?? CONTAINER_ARCH_FAMILIES, jobs, async (arch) => (await build(arch, join(stage, `${packageId}-${arch}.spk`))).outputPath));
 }
@@ -186,21 +186,21 @@ export async function runCli(argv) {
     const program = new Command()
         .name("synopkgland")
         .description("Syno Package Land Developer Kit CLI")
-        .option("--project <dir>", "App 專案根目錄")
+        .option("--project <dir>", "App project root")
         .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>。");
+            throw failure("HOST_REQUIRED", "--host is required.", "Set a synoagentcli profile, then use --host <name>.");
         const nas = createNasHost({ host });
         if (!nas)
-            throw failure("NAS_CREDENTIALS_MISSING", "找不到 NAS 憑證。", "設定 synoagentcli profile 或 DSM_URL／DSM_PASSWORD。");
+            throw failure("NAS_CREDENTIALS_MISSING", "NAS credentials were not found.", "Set a synoagentcli profile or DSM_URL/DSM_PASSWORD.");
         return nas;
     };
     program
         .command("check")
-        .description("驗證 manifest、能力組合與 Compose")
-        .option("--json", "輸出單一 JSON 物件")
+        .description("Validate the manifest, capability combination and Compose")
+        .option("--json", "Print a single JSON object")
         .action((_options, command) => {
         const validation = validateProject(requireProject(rootOf(command)), {
             profile: "personal",
@@ -211,7 +211,7 @@ export async function runCli(argv) {
         if (standalone) {
             const loaded = isNativeLayout(standalone) ? loadNativeLayout(standalone) : 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，修正宣告後重試。");
+                throw failure(loaded.errors[0].code, loaded.errors.map((e) => `[${e.code}] ${e.message}`).join("\n"), "Update dsm-package.yaml to schema: 2, fix the declaration and retry.");
             const declared = "icon" in loaded.manifest && loaded.manifest.icon ? resolve(standalone, loaded.manifest.icon) : undefined;
             const icon = isNativeLayout(standalone) && !declared ? { source: "layout", solid: false } : iconReport(standalone, declared);
             const iconText = formatIconReport(icon, "dsm-package.yaml");
@@ -221,7 +221,7 @@ export async function runCli(argv) {
                 package: loaded.manifest.package,
                 capabilities: "capabilities" in loaded.manifest ? loaded.manifest.capabilities : {},
                 icon,
-            }, ["驗證通過。", ...iconText.lines].join("\n"));
+            }, ["Validation passed.", ...iconText.lines].join("\n"));
             return;
         }
         const project = requireProject(rootOf(command));
@@ -235,26 +235,26 @@ export async function runCli(argv) {
         const iconText = formatIconReport(icon, "synology-app.yaml");
         if (iconText.warning)
             console.error(iconText.warning);
-        emit("check", { report, warnings: result.warnings ?? [], icon }, [`驗證通過。`, formatInspectReport(report), ...iconText.lines].join("\n"));
+        emit("check", { report, warnings: result.warnings ?? [], icon }, [`Validation passed.`, formatInspectReport(report), ...iconText.lines].join("\n"));
     });
     program
         .command("inspect <spk>")
-        .description("不安裝，依 DSM 7 套件格式檢查任何 SPK；synopkgland 建置的 SPK 另查建置合約與 root 權限需求")
-        .option("--json", "輸出單一 JSON 物件")
+        .description("Inspect any SPK against the DSM 7 package format without installing; for a synopkgland-built SPK also check the build contract and root privilege requirements")
+        .option("--json", "Print a single JSON object")
         .action(async (input) => {
         const spk = resolve(input);
         if (existsSync(spk) && statSync(spk).isDirectory())
-            throw failure("SPK_INSPECTION_FAILED", `${spk} 是目錄；inspect 檢查 .spk 檔。`, "檢查專案設定請用 synopkgland check。");
+            throw failure("SPK_INSPECTION_FAILED", `${spk} is a directory; inspect checks .spk files.`, "Use synopkgland check to inspect project settings.");
         const report = await inspectAnySpk(spk);
         if (!report.dsm.ok || report.findings.length)
-            throw Object.assign(failure("SPK_INSPECTION_FAILED", formatSpkChecks(report).join("\n"), "依錯誤碼修正 SPK 並重新打包，錯誤碼說明見 reference/errors；勿安裝檢查未通過的 SPK。"), { report: { spk, ...report } });
+            throw Object.assign(failure("SPK_INSPECTION_FAILED", formatSpkChecks(report).join("\n"), "Fix the SPK by error code and repackage; see reference/errors for the codes; do not install an SPK that fails inspection."), { report: { spk, ...report } });
         emit("inspect", { spk, ...report }, formatSpkReport(spk, report));
     });
-    const images = program.command("images").description("Container image 工具");
+    const images = program.command("images").description("Container image tools");
     images
         .command("pin")
-        .description("把 compose.yaml 的 image tag 解析為 digest 並寫回（匿名 registry 查詢）")
-        .option("--check", "只檢查，不寫入；未 pin 或過期時失敗")
+        .description("Resolve compose.yaml image tags to digests and write them back (anonymous registry lookup)")
+        .option("--check", "Check only, do not write; fail when unpinned or stale")
         .action(async (options, command) => {
         const project = requireProject(process.cwd(), command.parent?.parent?.opts().project);
         const result = await pinProjectImages({
@@ -263,31 +263,31 @@ export async function runCli(argv) {
         });
         stdout(formatPinReport(result, { check: options.check === true }));
         if (options.check && result.findings.length)
-            throw failure("IMAGE_PIN_REQUIRED", "Container images 未 pin 或已過期。");
+            throw failure("IMAGE_PIN_REQUIRED", "Container images are unpinned or stale.");
     });
     program
         .command("init")
-        .description("從模板建立 App 專案（不覆蓋既有檔案）")
-        .option("-t, --template <name>", `模板：${listTemplates().join(" | ")}`)
-        .option("--package <id>", "INFO.package（預設由目錄名產生）")
-        .option("--name <display>", "顯示名稱")
-        .option("--ui <vue|plain>", `原生模板 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>", `能力（逗號分隔）：${CAPABILITY_NAMES.join(",")}`)
-        .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／native-rust／binary 預設 ${DEFAULT_MIN_DSM}，compose 預設 ${CONTAINER_MIN_DSM}）`)
-        .argument("[dir]", "目標目錄", ".")
-        .addHelpText("after", "\n原生專案：native-go、native-rust 與 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")
+        .description("Create an App project from a template (never overwrites existing files)")
+        .option("-t, --template <name>", `Template: ${listTemplates().join(" | ")}`)
+        .option("--package <id>", "INFO.package (defaults to the directory name)")
+        .option("--name <display>", "Display name")
+        .option("--ui <vue|plain>", `Native UI ${JSON.parse(readFileSync(join(templatesRoot(), "native-go-vue/frontend/package.json"), "utf8")).dependencies["@synopackageland/ui"]} by default (vue); plain uses ui/app.js`)
+        .option("--with <caps>", `Capabilities (comma-separated): ${CAPABILITY_NAMES.join(",")}`)
+        .option("--from <compose.yaml>", "compose: import an existing Compose; omit to create an example")
+        .option("--shared-folder <select|create>", "Select or create a shared folder in the install wizard")
+        .option("--shared-folder-name <name>", "Name of the shared folder to create")
+        .option("--shared-folder-key <key>", "Settings key, defaults to shared")
+        .option("--shared-folder-permission <ro|rw>", "Package account permission, defaults to rw")
+        .option("--min-dsm <version>", `Minimum DSM version (native templates and binary default to ${DEFAULT_MIN_DSM}, compose to ${CONTAINER_MIN_DSM})`)
+        .argument("[dir]", "Target directory", ".")
+        .addHelpText("after", "\nNative projects: native-go, native-python, native-node, native-rust and binary use dsm-package.yaml schema 2.\nCompose projects: compose uses synology-app.yaml; --from imports compose.yaml.\nQuick start: 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。");
+            throw failure("CLI_OPTION_INVALID", "--project does not apply to init.");
         if (!options.template)
-            throw failure("INIT_TEMPLATE_REQUIRED", `請指定 -t, --template <name>。可選模板：${listTemplates().join(" | ")}`);
+            throw failure("INIT_TEMPLATE_REQUIRED", `Specify -t, --template <name>. Available templates: ${listTemplates().join(" | ")}`);
         if (!isTemplateName(options.template))
-            throw failure("INIT_TEMPLATE_UNKNOWN", `未知模板：${options.template}`);
+            throw failure("INIT_TEMPLATE_UNKNOWN", `Unknown template: ${options.template}`);
         const targetDir = resolve(dir);
         initFromTemplate(options.template, targetDir, {
             packageId: options.package,
@@ -307,30 +307,30 @@ export async function runCli(argv) {
                     permission: options.sharedFolderPermission,
                 },
         });
-        stdout(`已建立 ${options.template} 專案於 ${targetDir}`);
-        // --install-links packs a local SDK like the released package; a symlink would load the checkout's own node_modules.
-        if (options.template === "native-go" || options.template === "native-rust")
-            stdout(`下一步：\n  cd ${dir}\n  (cd backend && ${options.template === "native-go" ? "go test ./..." : "cargo test"})\n${existsSync(join(targetDir, "frontend", "package.json")) ? `  (cd frontend && npm install${process.env.SYNOPKGLAND_SDK_DIR ? " --install-links" : ""})\n` : ""}  synopkgland build\n說明見 README.md。`);
+        stdout(`Created the ${options.template} project at ${targetDir}`);
+        const next = initNextSteps(options.template, dir, existsSync(join(targetDir, "frontend", "package.json")), Boolean(process.env.SYNOPKGLAND_SDK_DIR));
+        if (next)
+            stdout(next);
     });
     program
         .command("add <caps...>")
-        .description(`加入能力（${CAPABILITY_NAMES.join("、")}）或 portal 與 SDK-owned overlay；不覆寫既有應用檔案`)
+        .description(`Add capabilities (${CAPABILITY_NAMES.join(", ")}) or a portal and SDK-owned overlay; never overwrite existing app files`)
         .action((caps, _options, command) => {
         const result = addCapabilities(rootOf(command), caps);
         for (const note of result.notes ?? [])
-            console.error(`[注意] ${note}`);
-        stdout(`已新增：${result.added.join(", ") || "無"}；已存在：${result.unchanged.join(", ") || "無"}`);
+            console.error(`[note] ${note}`);
+        stdout(`Added: ${result.added.join(", ") || "none"}; already present: ${result.unchanged.join(", ") || "none"}`);
     });
     program
         .command("dev")
-        .description("啟動本機 Compose")
+        .description("Start the local Compose")
         .action(async (_options, command) => {
         const project = requireProject(rootOf(command));
         const validation = validateProject(project);
         if (!validation.ok)
             throw failure(validation.errors[0].code, formatErrors(validation.errors));
         const handle = await runDev({ project });
-        stdout("Compose 已就緒。按 Ctrl+C 結束。");
+        stdout("Compose is ready. Press Ctrl+C to stop.");
         const shutdown = async () => {
             await handle.close();
             process.exit(0);
@@ -341,26 +341,26 @@ export async function runCli(argv) {
     });
     program
         .command("test")
-        .description("驗證契約並等待 Compose 就緒")
+        .description("Validate the contract and wait for Compose to be ready")
         .action(async (_options, command) => {
         const result = await testProject({
             project: requireProject(rootOf(command)),
         });
         if (!result.ok)
-            throw failure(result.errors[0] ?? "TEST_FAILED", `測試失敗：${result.errors.join(", ")}`);
-        stdout("測試通過。");
+            throw failure(result.errors[0] ?? "TEST_FAILED", `Test failed: ${result.errors.join(", ")}`);
+        stdout("Tests passed.");
     });
     program
         .command("deploy")
-        .description("建置 SPK 並安裝到 DSM")
-        .option("--json", "輸出單一 JSON 物件")
+        .description("Build the SPK and install it into DSM")
+        .option("--json", "Print a single JSON object")
         .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）或安裝精靈值（native-go／binary）", (value, previous) => collectKv(value, previous, "--param"))
-        .option("--dry-run", "只輸出本機部署計畫，不連接 NAS")
+        .option("--share <slot=name>", "Compose shared folder", (value, previous) => collectKv(value, previous, "--share"))
+        .option("--run-as <slot=name>", "Compose DSM user", (value, previous) => collectKv(value, previous, "--run-as"))
+        .option("--param <NAME=value>", "Install parameter (Compose) or install wizard value (native-go/binary)", (value, previous) => collectKv(value, previous, "--param"))
+        .option("--dry-run", "Print the local deploy plan only, without connecting to the NAS")
         .action(async (options, command) => {
         if (options.arch !== undefined &&
             !isNativeArchFamily(String(options.arch)))
@@ -371,7 +371,7 @@ export async function runCli(argv) {
         });
         if (plan.kind !== "container" &&
             (options.share || options.runAs))
-            throw failure("CLI_OPTION_INVALID", "native-go／binary 不接受 --share／--run-as；安裝精靈值請用 --param。");
+            throw failure("CLI_OPTION_INVALID", "native-go/binary do not accept --share/--run-as; pass install wizard values with --param.");
         if (options.dryRun) {
             emit("deploy", plan, JSON.stringify(plan, null, 2));
             return;
@@ -380,7 +380,7 @@ export async function runCli(argv) {
             const host = hostOf(options.host);
             const output = await deployStandalone(plan, host, { params: options.param });
             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") : ""}`);
+            emit("deploy", { ...plan, output, status }, `Deployed ${plan.packageId}: ${output}\n${formatProjectInfo(status)}${plan.notes.length ? "\n" + plan.notes.join("\n") : ""}`);
             return;
         }
         const project = requireProject(rootOf(command));
@@ -400,15 +400,15 @@ export async function runCli(argv) {
             paramValues: options.param,
         });
         if (!result.ok)
-            throw failure(result.code ?? "DEPLOY_FAILED", result.message ?? "部署失敗。");
+            throw failure(result.code ?? "DEPLOY_FAILED", result.message ?? "Deployment failed.");
         for (const note of result.notes ?? [])
-            console.error(`[注意] ${note}`);
-        emit("deploy", result, `已部署 ${result.packageId}${result.openUrl ? "\nOpen URL：" + result.openUrl : ""}`);
+            console.error(`[note] ${note}`);
+        emit("deploy", result, `Deployed ${result.packageId}${result.openUrl ? "\nOpen URL: " + result.openUrl : ""}`);
     });
     program
         .command("status")
-        .description("DSM 套件狀態、Open URL 與能力就緒狀態")
-        .option("--json", "輸出單一 JSON 物件")
+        .description("DSM package status, Open URL and capability readiness")
+        .option("--json", "Print a single JSON object")
         .option("--host <name>", "NAS profile")
         .option("--dev", "Development Package Identity")
         .action(async (options, command) => {
@@ -426,7 +426,7 @@ export async function runCli(argv) {
     });
     program
         .command("logs")
-        .description("狀態診斷：DSM 套件狀態與遮罩後的診斷資訊；不串流應用程式日誌")
+        .description("Status diagnosis: DSM package status and masked diagnostics; does not stream application logs")
         .requiredOption("--host <name>", "NAS profile")
         .option("--dev", "Development Package Identity")
         .action(async (options, command) => {
@@ -445,32 +445,32 @@ export async function runCli(argv) {
                 dev: options.dev,
             });
         if (!result.ok)
-            throw failure("NOT_INSTALLED", "套件尚未安裝。先執行 synopkgland deploy --host。");
+            throw failure("NOT_INSTALLED", "The package is not installed. Run synopkgland deploy --host first.");
         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");
+    const skill = program.command("skill").description("Bundled 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")
-        .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(",")}（armv7 用於 native-go 與 binary，不用於 Container Manager App）；native layout 另支援 armv8`, (value, previous) => [...(previous ?? []), value])
-        .option("--min-dsm <version>", "最低 DSM 版本，省略時使用 manifest 值")
-        .option("--jobs <n>", "同時建置的架構數，預設 1（依序）", Number)
-        .option("--verify-reproducible [when]", "從乾淨狀態再建置一次並比對；when：changed（預設，依賴指紋未變時略過）或 always")
+        .description("Build an SPK from synology-app.yaml or dsm-package.yaml")
+        .option("--json", "Print a single JSON object")
+        .option("-o, --output <path>", "Output SPK; use with a single --arch")
+        .option("--out-dir <dir>", "Output directory; native projects default to dist/")
+        .option("--arch <families>", `Architectures, comma-separated or repeated: ${NATIVE_ARCH_FAMILIES.join(",")} (armv7 is for native-go and binary, not for Container Manager Apps); native layout also supports armv8`, (value, previous) => [...(previous ?? []), value])
+        .option("--min-dsm <version>", "Minimum DSM version; uses the manifest value when omitted")
+        .option("--jobs <n>", "Number of architectures to build in parallel, default 1 (sequential)", Number)
+        .option("--verify-reproducible [when]", "Build again from a clean state and compare; when: changed (default, skips when the dependency fingerprint is unchanged) or always")
         .action(async (options, command) => {
         const root = rootOf(command);
         const standalone = standaloneRoot(root);
         const verify = options.verifyReproducible === true ? "changed" : options.verifyReproducible;
         if (verify !== undefined && verify !== "changed" && verify !== "always")
-            throw failure("CLI_OPTION_INVALID", `--verify-reproducible 只接受 changed 或 always，收到 ${verify}。`);
+            throw failure("CLI_OPTION_INVALID", `--verify-reproducible accepts only changed or always, got ${verify}.`);
         let arches;
         try {
             arches =
@@ -501,9 +501,9 @@ export async function runCli(argv) {
                 ? build({ output: undefined, outDir })
                 : build({ output: join(outDir, basename(outputs[0])), outDir: undefined }),
         });
-        const lines = [...outputs.map((output) => `已產生 ${output}`), ...(reproducible ? reproducibleLines(reproducible) : [])];
+        const lines = [...outputs.map((output) => `Built ${output}`), ...(reproducible ? reproducibleLines(reproducible) : [])];
         if (reproducible && !reproducible.identical)
-            throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "找出 payload 中每次建置都不同的檔案（時間戳、隨機路徑、未鎖定的依賴），修正後重試。"), { report: { outputs, reproducible } });
+            throw Object.assign(failure("BUILD_NOT_REPRODUCIBLE", lines.join("\n"), "Find the payload files that differ between builds (timestamps, random paths, unpinned dependencies) and retry after fixing them."), { report: { outputs, reproducible } });
         emit("build", { outputs, ...(reproducible ? { reproducible } : {}) }, lines.join("\n"));
     });
     if (json)
@@ -532,7 +532,7 @@ export async function runCli(argv) {
                 ok: false,
                 code,
                 message,
-                hint: detail.hint ?? getErrorCode(code)?.suggestion ?? "修正設定後重試；使用 --help 查看指令用法。",
+                hint: detail.hint ?? getErrorCode(code)?.suggestion ?? "Fix the configuration and retry; use --help to see command usage.",
                 ...(detail.report ? { data: detail.report } : {}),
             }));
         }