@synopackageland/cli 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.15.2 (2026-10-18)
+
+- Preserve command-set process exit codes instead of resetting them to 0 after CLI dispatch. `ctl` failures now reach scripts and CI with their documented exit codes; successful commands still exit 0 and uncaught exceptions exit 1.
+- Add subprocess regression coverage for `ctl` exit codes 0–8, confirmation before writes, and failures from `check`, `build`, `inspect`, `status` and `test`. Document the existing `ctl` exit-code contract and informational discovery/session results.
+- CLI-only patch: templates and SDK fixtures/examples remain pinned to 0.15.1; executor/lifecycle digests are unchanged.
+
+繁中摘要：修正 CLI 在子指令完成後把退出碼覆寫成 0 的問題，讓 `ctl` 失敗正確傳遞至腳本與 CI；成功仍為 0，未捕捉例外仍為 1。新增實際子行程測試，涵蓋 `ctl` 的 0–8 退出碼、寫入確認及其他主要指令的失敗；README 記錄既有退出碼與 discovery／session 資訊結果。此次僅更新 CLI，templates／SDK 維持 0.15.1，executor／lifecycle digest 不變。
+
 ## 0.15.1 (2026-10-18)
 
 - Require explicit `DSM_E2E_SSH` for e2e tunnels and use `dsm` as the default saved-profile target; set `DSM_E2E_TARGET` to reuse an earlier target name. Anonymize internal NAS fixtures and documentation.

package/README.md

@@ -68,6 +68,19 @@ templates checkout and `SYNOPKGLAND_SDK_DIR` to an SDK checkout; SPKs built with
 packs the local SDK into its frontend (`npm install --install-links`) without building it: run
 `npm ci && npm run build` in `$SYNOPKGLAND_SDK_DIR/ts` first, and again after SDK changes.
 
+To check the CLI's DSM terminology rules against templates without a new templates release:
+
+```sh
+SYNOPKGLAND_TEMPLATES_DIR=/path/to/templates npm run test:glossary
+```
+
+This compares `OFF_GLOSSARY` and the Italian sentence rule, including regex sources and
+flags. It supports declaration-only rules with read-only use in `glossaryProblems`;
+post-declaration mutations, aliases and other unsupported rule uses fail the check instead of
+comparing a partial snapshot. The command also fails on drift or missing source. It needs a checkout because templates
+0.15.1 does not publish `scripts/test/i18n.test.mjs`. The npm gate runs this check when
+`SYNOPKGLAND_TEMPLATES_DIR` is set; otherwise it explicitly reports that the drift check was skipped.
+
 ## Capabilities
 
 Add them with `init --with …` or later with `synopkgland add <capability…>`.
@@ -260,6 +273,37 @@ commands and their schemas. Run the listed alias/command with typed flags,
 `--help` and `--dry-run`; writes require `--yes`. There is no mutable current
 context. Use `--host a,b` or `--all-hosts` for bounded parallel operations.
 
+`ctl` preserves these process exit codes, including with `--json`:
+
+| Exit code | Meaning and examples |
+| --- | --- |
+| 0 | Command completed successfully (including help and `--dry-run`). |
+| 1 | Unexpected internal error (`CTL_INTERNAL`), or an uncaught CLI exception. |
+| 2 | Authentication/session failure: `CTL_NOT_AUTHENTICATED`, `CTL_AUTH_FAILED`, `CTL_CREDENTIAL_MISMATCH`, or unavailable OS credential storage. |
+| 3 | Invalid parameters, schema validation or unknown names: `CTL_PARAMS_INVALID`, `CTL_ARGUMENT_INVALID`, `CTL_APP_UNKNOWN`, `CTL_COMMAND_UNKNOWN`. |
+| 4 | Permission refusal that fails the command: `CTL_PERMISSION_DENIED`, `CTL_INVENTORY_DENIED`. |
+| 5 | App/contract failure that fails the command: `CTL_APP_ERROR`, `CTL_RESPONSE_INVALID`, `CTL_JOB_FAILED`. |
+| 6 | Network/HTTP failure or uncertain completion: `CTL_NETWORK`, `CTL_HTTP_ERROR`, `CTL_JOB_TIMEOUT`, `CTL_LOGOUT_FAILED`. |
+| 7 | Confirmation required (`CTL_CONFIRM_REQUIRED`): a write/destructive command or host removal without confirmation; no business operation runs. |
+| 8 | A multi-host command has at least one failed host (including when all hosts fail); inspect each host's error. |
+
+For example, `synopkgland ctl studio drafts create --host nas --json` without
+`--yes` returns `ok:false` with `CTL_CONFIRM_REQUIRED` and exits 7 once discovery
+and parameter validation succeed. Missing sessions fail earlier with exit 2.
+Discovery catches per-App description errors and excludes those Apps from its
+results. For example, a changed pinned description (`CTL_DESCRIPTION_CHANGED`)
+or an invalid descriptor (`CTL_DESCRIPTOR_INVALID`) appears in
+`ctl list --host nas --refresh --json` under `data.diagnostics`; the listing still
+returns `ok:true` and exits 0, even if no Apps remain. These diagnostic codes do
+not become process exit codes 4 or 5. Attempting to execute an excluded App with
+`--refresh` instead returns `ok:false`, `CTL_APP_UNKNOWN` and exit 3 because the
+App is absent from discovery results; no business operation runs.
+
+`ctl host list/show` can also succeed while reporting `authenticated:false` and
+exit 0. Check discovery `apps`/`diagnostics` and session fields as well as the exit
+code when deciding whether an App is ready.
+After a network or job timeout, query the App's state before retrying a write.
+
 Read `synopkgland skill show ctl` for the AI workflow, batch discovery approval,
 cache refresh, host removal/revocation and explicit `ctl.commands` authoring.
 API descriptions are private SPK files named `synopkgland-api.json`, served

package/dist/bin.js

@@ -3,9 +3,8 @@ import { loadDotEnv } from "./load-env.js";
 import { runCli } from "./cli.js";
 loadDotEnv();
 // Package deployment is explicit; this CLI does not publish releases.
-runCli(process.argv).then(() => 0).then((status) => {
-    process.exitCode = status;
-}).catch((error) => {
+// Successful completion leaves Node's default 0 or the command's exitCode intact.
+runCli(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });

package/dist/cli.d.ts

@@ -1 +1,2 @@
+/** Resolves after dispatch; commands may set process.exitCode. Rejections are failures. */
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -275,6 +275,7 @@ async function containerBuild(project, arches, options) {
     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));
 }
+/** Resolves after dispatch; commands may set process.exitCode. Rejections are failures. */
 export async function runCli(argv) {
     if (argv[2] === "ctl") {
         const { runCtl } = await import("./ctl/cli.js");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc",
     "test": "npm run build && node --import tsx --test test/*.test.ts test/ctl/*.test.ts",
+    "test:glossary": "node --test scripts/test/glossary-drift.test.mjs",
     "test:scripts": "node --test scripts/test/gate.test.mjs scripts/test/release.test.mjs scripts/test/pack-docker.test.mjs scripts/test/npm-pack.test.mjs scripts/test/executor-bump.test.mjs scripts/test/smoke-exports.test.mjs scripts/test/executor-digests.test.mjs scripts/test/parallel.test.mjs scripts/test/scaffold-matrix.test.mjs scripts/test/frontend-deps.test.mjs scripts/test/docker-gate.test.mjs scripts/test/gate-plan.test.mjs scripts/test/gates.test.mjs",
     "gates": "bash scripts/ci/gates.sh",
     "gates:fast": "bash scripts/ci/gates.sh --fast",