@synopackageland/cli 0.41.13 → 0.42.1

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## Unreleased
+## 0.42.1 (2026-11-01)
+
+- Add `--version` and `-V` to report the installed CLI version.
+- Register the installed-App approval diagnostic as `CTL_APP_NEEDS_APPROVAL`
+  with the App-scoped approve command, replacing the retired error entry.
+
+## 0.42.0 (2026-11-01)
+
+- Require templates ~0.37.0 so `init` and `add` scaffold with UI 0.19.1 and
+  SDK/App 0.41.1 (executor/v0.39.0). CLI 0.41.x stays on the templates 0.35
+  minor line.
+- Pin CLI-owned runtime defaults (daemon controllers, Compose planning and
+  installer context) to SDK 0.41.1, matching the templates. Explicit App SDK
+  declarations still take precedence.
+- Skip installation when the requested package version is already installed,
+  including DSM build suffixes; report `action: "none"` in plans and avoid
+  downloads, uploads and reinstalling on confirmed runs.
+- Accept repeated ctl flags for arrays of scalar values, validate their item
+  schemas and expose repeatable flags in command help and examples. Preserve
+  sensitive-value redaction and JSON input for complex parameters.
+- Return `CTL_APP_NEEDS_APPROVAL` (exit 4) with an App-scoped
+  `ctl list --app <package> --approve-installed` hint when an installed App,
+  called by package ID or a cached alias, awaits first, new-version or
+  changed-description approval. Cached aliases identify upgraded packages but
+  never authorize execution; `CTL_APP_UNKNOWN` suggestions apply only to names
+  matching no installed package or known alias.
 
 ## 0.41.13
 

package/README.md

@@ -89,8 +89,8 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-The CLI pins SDK 0.41.0 for its daemon controllers, Compose planning and installer
-context. Explicit App SDK declarations take precedence. Templates remain ~0.35.5
+The CLI pins SDK 0.41.1 for its daemon controllers, Compose planning and installer
+context. Explicit App SDK declarations take precedence. Templates use ~0.37.0
 and retain their own scaffold SDK pins; none declare daemon ingress.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -101,8 +101,8 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.41.13 depends on `~0.35.5`: npm installation or
-update can select the latest templates patch in the 0.35 minor line. Templates
+`@synopackageland/templates`. CLI 0.42.0 depends on `~0.37.0`: npm installation or
+update can select the latest templates patch in the 0.37 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
 commit a lockfile and use `npm ci` to reproduce a chosen dependency tree.
@@ -537,7 +537,7 @@ for `ctl` calls; App command/job/transfer deadlines retain their existing defaul
 | 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`. |
+| 4 | Approval/trust or permission refusal: `CTL_APP_NEEDS_APPROVAL`, `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. |
@@ -547,13 +547,26 @@ 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`)
+results. For example, a changed pinned description (`CTL_APP_NEEDS_APPROVAL`)
 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.
+not become process exit codes 4 or 5 for a listing. Executing or requesting help
+for an installed App by package ID or a known cached alias instead returns its
+specific error; no business operation runs. A first approval, new version, or
+changed description returns `CTL_APP_NEEDS_APPROVAL` and exit 4, for example
+`SynoReclaim 1.2.0 needs approval`, with the exact App-scoped hint:
+
+```sh
+synopkgland ctl list --app SynoReclaim --approve-installed --host <profile>
+```
+
+Obtain the user's authorization before approving. Previously approved aliases
+identify upgraded installed packages without granting permission to execute.
+Use the package ID for first approval when no alias has been discovered yet.
+Only a name matching no installed package ID or known alias returns
+`CTL_APP_UNKNOWN` with “Did you mean …” suggestions. Other description failures,
+such as `CTL_DESCRIPTOR_INVALID`, remain specific errors (exit 5).
 
 `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

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { nasFlags, withNasOptions } from './nas/options.js';
 import { upstreamRepository, upstreamMaintainer } from './upstream-attribution.js';
 import { Command, CommanderError } from "commander";
+import { CLI_VERSION } from "./cli-version.js";
 import { existsSync, readFileSync, renameSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { basename, resolve, dirname, join } from "node:path";
@@ -322,6 +323,7 @@ async function runCliWithin(argv) {
     const program = new Command()
         .name("synopkgland")
         .description("Syno Package Land Developer Kit CLI")
+        .version(CLI_VERSION)
         .option("--project <dir>", "App project root")
         .option("--strict-tls", "Verify NAS CA, hostname, validity and recorded certificate")
         .option("--ca <file>", "Verify NAS HTTPS with a PEM CA file")

package/dist/ctl/cli.d.ts

@@ -12,6 +12,11 @@ export interface CtlIO {
 export declare function listView(host: string, apps: Descriptor[]): {
     commands: {
         parameters: string | Record<string, any>;
+        flags: {
+            flag: string;
+            valueType: string;
+            repeatable: boolean;
+        }[];
         examples: string[];
         summary: string;
         cli: string[];

package/dist/ctl/cli.js

@@ -6,7 +6,7 @@ import { Writable } from 'node:stream';
 import { CtlError, errorData, ctlError } from './errors.js';
 import { CtlStore } from './store.js';
 import { CtlClient, boundedMap } from './service.js';
-import { selectHosts, selectApp, selectOperation, flagName, RESERVED_FLAGS } from './input.js';
+import { selectHosts, selectOperation, flagName, flagValueType, RESERVED_FLAGS } from './input.js';
 import { canonicalOrigin, CTL_TIMEOUT_MS, createRequest } from './transport.js';
 import { loginDsm, logoutDsm } from './dsm-auth.js';
 import { publicOperation } from './redaction.js';
@@ -51,16 +51,23 @@ function take(args, flag, value = false) {
     return answer;
 }
 function q(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
+function typedFlags(op) {
+    const fields = Object.entries(op.paramsSchema?.properties ?? {}), names = fields.map(([key]) => flagName(key));
+    if (names.some(name => RESERVED_FLAGS.has(name)) || new Set(names).size !== names.length)
+        return [];
+    return fields.flatMap(([key, schema]) => /^[A-Za-z][A-Za-z0-9_]*$/.test(key) && flagValueType(schema) ? [{ flag: '--' + flagName(key), valueType: flagValueType(schema), repeatable: schema.type === 'array' }] : []);
+}
 function example(host, app, op) {
     const base = `synopkgland ctl ${app.payload.aliases[0] ?? app.payload.package.id} ${op.cli.join(' ')} --host ${host}`;
+    const flags = typedFlags(op);
     return (op.examples?.length ? op.examples : [{}]).map(params => {
-        const simple = op.paramsSchema && Object.entries(params).every(([key, value]) => ['string', 'number', 'boolean'].includes(typeof value) && /^[A-Za-z][A-Za-z0-9_]*$/.test(key) && !RESERVED_FLAGS.has(flagName(key)) && op.paramsSchema?.properties?.[key]);
+        const simple = op.paramsSchema && Object.entries(params).every(([key, value]) => { const flag = flags.find(f => f.flag === '--' + flagName(key)); return flag && (flag.repeatable ? Array.isArray(value) && value.length > 0 && value.every(v => ['string', 'number', 'boolean'].includes(typeof v)) : ['string', 'number', 'boolean'].includes(typeof value)); });
         if (simple)
-            return base + Object.entries(params).map(([key, value]) => ' --' + flagName(key) + ' ' + q(String(value))).join('') + (op.effect === 'read' ? '' : ' --yes');
+            return base + Object.entries(params).flatMap(([key, value]) => (Array.isArray(value) ? value : [value]).map(item => ' --' + flagName(key) + ' ' + q(String(item)))).join('') + (op.effect === 'read' ? '' : ' --yes');
         return `printf '%s' ${q(JSON.stringify(params))} | ${base} --input -` + (op.effect === 'read' ? '' : ' --yes');
     });
 }
-export function listView(host, apps) { return apps.map(app => ({ host, package: app.payload.package, aliases: app.payload.aliases, protocolVersion: app.version, developedBy: app.payload.provenance.developedBy, provenance: 'self-declared', hash: app.sha256, ...(app.payload.external ? { external: app.payload.external } : {}), commands: Object.entries(app.payload.commands).map(([id, original]) => { const op = publicOperation(original); return { id, ...op, parameters: op.paramsSchema ?? 'Undescribed parameters; use --input', examples: example(host, app, op) }; }) })); }
+export function listView(host, apps) { return apps.map(app => ({ host, package: app.payload.package, aliases: app.payload.aliases, protocolVersion: app.version, developedBy: app.payload.provenance.developedBy, provenance: 'self-declared', hash: app.sha256, ...(app.payload.external ? { external: app.payload.external } : {}), commands: Object.entries(app.payload.commands).map(([id, original]) => { const op = publicOperation(original); return { id, ...op, parameters: op.paramsSchema ?? 'Undescribed parameters; use --input', flags: typedFlags(op), examples: example(host, app, op) }; }) })); }
 export async function runCtl(argv, io = {}) {
     if (argv[0] === 'external')
         return runExternal(argv.slice(1), io);
@@ -237,7 +244,7 @@ async function runCtlWithin(argv, io = {}) {
                 if (args[0] === 'help' || help) {
                     const nameArg = args[0] === 'help' ? args[1] : args[0];
                     const data = await ctl.discover(discoverOptions);
-                    const app = selectApp(data.apps, nameArg ?? '');
+                    const app = ctl.selectApp(data, nameArg ?? '');
                     const path = args[0] === 'help' ? args.slice(2) : args.slice(1);
                     const view = listView(name, [app])[0];
                     return { host: name, ok: true, data: path.length ? { ...view, commands: [view.commands.find(c => c.id === selectOperation(app, path).id)] } : view };

package/dist/ctl/input.d.ts

@@ -1,12 +1,16 @@
 import { type Descriptor, type Operation } from './descriptor.js';
 export declare function selectHosts(names: string[], selected?: string, all?: boolean): string[];
-export declare function selectApp(apps: Descriptor[], name: string): Descriptor;
+export declare function selectApp<T extends {
+    id: string;
+    aliases: string[];
+}>(apps: T[], name: string): T;
 export declare function selectOperation(app: Descriptor, path: string[]): {
     id: string;
     operation: Operation;
 };
 export declare const RESERVED_FLAGS: Set<string>;
 export declare function flagName(key: string): string;
+export declare function flagValueType(schema: any): string | undefined;
 export declare function operationInput(op: Operation, args: string[], stdin?: string, helpHint?: string): Record<string, unknown>;
 export declare function requestPlan(app: Descriptor, id: string, params: Record<string, unknown>): {
     package: string;

package/dist/ctl/input.js

@@ -21,12 +21,15 @@ export function selectHosts(names, selected, all = false) {
     return [...new Set(hosts)];
 }
 export function selectApp(apps, name) {
-    const found = apps.filter(a => [a.payload.package.id, ...a.payload.aliases].some(s => s.toLowerCase() === name.toLowerCase()));
+    const exact = apps.find(app => app.id.toLowerCase() === name.toLowerCase());
+    if (exact)
+        return exact;
+    const found = apps.filter(app => app.aliases.some(alias => alias.toLowerCase() === name.toLowerCase()));
     if (found.length > 1)
-        throw new CtlError('CTL_APP_AMBIGUOUS', 'Alias matches multiple packages.', 'Use an exact DSM package ID.', 3, found.map(a => a.payload.package.id));
+        throw new CtlError('CTL_APP_AMBIGUOUS', 'Alias matches multiple packages.', 'Use an exact DSM package ID.', 3, found.map(app => app.id));
     if (found.length === 1)
         return found[0];
-    return choose(name, apps.flatMap(a => [a.payload.package.id, ...a.payload.aliases]), 'app');
+    return choose(name, apps.flatMap(app => [app.id, ...app.aliases]), 'app');
 }
 export function selectOperation(app, path) {
     const found = Object.entries(app.payload.commands).find(([, op]) => op.cli.join(' ') === path.join(' '));
@@ -36,6 +39,10 @@ export function selectOperation(app, path) {
 }
 export const RESERVED_FLAGS = new Set(['ca', 'strict-tls', 'host', 'all-hosts', 'json', 'app', 'refresh', 'yes', 'dry-run', 'approve-installed', 'help', 'input', 'wait', 'no-wait', 'timeout']);
 export function flagName(key) { return key.replace(/[A-Z]/g, c => '-' + c.toLowerCase()).replaceAll('_', '-'); }
+export function flagValueType(schema) {
+    const type = schema?.type === 'array' ? schema.items?.type : schema?.type;
+    return ['string', 'integer', 'number', 'boolean'].includes(type) ? type : undefined;
+}
 export function operationInput(op, args, stdin, helpHint) {
     const fail = (message, allowed) => { throw new CtlError('CTL_PARAMS_INVALID', message, helpHint ?? ('run: synopkgland ctl <package> ' + op.cli.join(' ') + ' --help'), 3, allowed); };
     const inputIndex = args.indexOf('--input');
@@ -78,35 +85,42 @@ export function operationInput(op, args, stdin, helpHint) {
             const field = fields.get(flag);
             if (!field)
                 return fail('Unknown parameter flag.', [...fields.keys()]);
-            const [key, schema] = field;
-            if (Object.hasOwn(params, key))
+            const [key, schema] = field, repeatable = schema.type === 'array', type = flagValueType(schema);
+            if (Object.hasOwn(params, key) && !repeatable)
                 return fail(`Duplicate parameter flag ${flag}.`);
-            if (!['string', 'integer', 'number', 'boolean'].includes(schema.type))
+            if (!type)
                 return fail(`Complex parameter ${flag}: use --input.`);
             let value = split > 0 ? args[i].slice(split + 1) : undefined;
-            if (value === undefined && schema.type === 'boolean' && (!args[i + 1] || args[i + 1].startsWith('--')))
+            if (value === undefined && type === 'boolean' && (!args[i + 1] || args[i + 1].startsWith('--')))
                 value = 'true';
+            else if (value === undefined && (!args[i + 1] || args[i + 1].startsWith('--')))
+                return fail(`Missing parameter value for ${flag}.`);
             else if (value === undefined)
                 value = args[++i];
             if (value === undefined)
                 return fail(`Missing parameter value for ${flag}.`);
-            if (schema.type === 'integer') {
+            let parsed = value;
+            if (type === 'integer') {
                 if (!/^-?\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
                     return fail(`Parameter ${flag} must be a safe integer.`);
-                params[key] = Number(value);
+                parsed = Number(value);
             }
-            else if (schema.type === 'number') {
+            else if (type === 'number') {
                 if (!value.trim() || !Number.isFinite(Number(value)))
                     return fail(`Parameter ${flag} must be a number.`);
-                params[key] = Number(value);
+                parsed = Number(value);
             }
-            else if (schema.type === 'boolean') {
+            else if (type === 'boolean') {
                 if (!['true', 'false'].includes(value))
                     return fail(`Parameter ${flag} must be true or false.`);
-                params[key] = value === 'true';
+                parsed = value === 'true';
+            }
+            if (repeatable) {
+                const values = (params[key] ??= []);
+                values.push(parsed);
             }
             else
-                params[key] = value;
+                params[key] = parsed;
         }
     }
     if (!params || Array.isArray(params) || typeof params !== 'object')

package/dist/ctl/service.d.ts

@@ -1,3 +1,4 @@
+import { CtlError } from './errors.js';
 import { type DsmSession, type JsonRequest } from './transport.js';
 import { CtlStore, type Host } from './store.js';
 import { type Descriptor } from './descriptor.js';
@@ -11,6 +12,18 @@ export interface DiscoverOptions {
         version: string;
     }[]) => Promise<boolean>;
 }
+interface InstalledApp {
+    id: string;
+    version: string;
+    aliases: string[];
+    error?: CtlError;
+}
+interface Discovery {
+    apps: Descriptor[];
+    installed: InstalledApp[];
+    diagnostics: any[];
+    cacheHits: number;
+}
 export declare class CtlClient {
     store: CtlStore;
     host: Host;
@@ -24,11 +37,9 @@ export declare class CtlClient {
         version: string;
         state?: unknown;
     }[]>;
-    discover(options?: DiscoverOptions): Promise<{
-        apps: Descriptor[];
-        diagnostics: any[];
-        cacheHits: number;
-    }>;
+    private needsApproval;
+    selectApp(listing: Discovery, name: string): Descriptor;
+    discover(options?: DiscoverOptions): Promise<Discovery>;
     execute(name: string, path: string[], args: string[], options?: DiscoverOptions & {
         yes?: boolean;
         dryRun?: boolean;
@@ -39,3 +50,4 @@ export declare class CtlClient {
     private executeWithin;
     private appCookieSession;
 }
+export {};

package/dist/ctl/service.js

@@ -1,4 +1,4 @@
-import { CtlError, errorData, choose } from './errors.js';
+import { CtlError, ctlError, errorData } from './errors.js';
 import { APP_COOKIE, CTL_TIMEOUT_MS, createRequest } from './transport.js';
 import { DESCRIPTION_METHOD, validateDescriptor, ajv } from './descriptor.js';
 import { runFlow } from './flows.js';
@@ -41,24 +41,26 @@ export class CtlClient {
         return entries.map((p) => { if (typeof p.id !== 'string' || !/^[A-Za-z][A-Za-z0-9_.+-]{0,127}$/.test(p.id) || typeof p.version !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._+~-]{0,63}$/.test(p.version))
             throw new CtlError('CTL_INVENTORY_INVALID', 'Invalid package identity.', 'Check the DSM response.', 5); return { id: p.id, version: p.version, state: p.additional?.status }; });
     }
+    needsApproval(pkg) {
+        return new CtlError('CTL_APP_NEEDS_APPROVAL', `${pkg.id} ${pkg.version} needs approval`, `run: synopkgland ctl list --app ${pkg.id} --approve-installed --host ${this.host.name}`, 4);
+    }
+    selectApp(listing, name) {
+        const pkg = selectApp(listing.installed, name);
+        if (pkg.error)
+            throw pkg.error;
+        return listing.apps.find(app => app.payload.package.id === pkg.id);
+    }
     async discover(options = {}) {
         const session = await this.store.session(this.host);
-        let packages = await this.inventory(session);
+        let packages = (await this.inventory(session)).map(pkg => {
+            const approved = this.host.approved[pkg.id];
+            // Previous-version metadata identifies aliases only; it never authorizes a call.
+            const description = this.store.cache(this.host, pkg.id, pkg.version)?.description ?? (approved ? this.store.cache(this.host, pkg.id, approved.version)?.description : undefined);
+            return { ...pkg, aliases: description?.payload.aliases ?? [] };
+        });
         // An exact package filter narrows credential delivery. Alias selection needs the cached descriptors first.
-        if (options.app) {
-            const exact = packages.find(p => p.id.toLowerCase() === options.app.toLowerCase());
-            if (exact)
-                packages = [exact];
-            else {
-                const match = packages.find(p => this.store.cache(this.host, p.id, p.version)?.description?.payload.aliases?.some((a) => a.toLowerCase() === options.app.toLowerCase()));
-                if (match)
-                    packages = [match];
-                else {
-                    const known = packages.flatMap(p => { const d = this.store.cache(this.host, p.id, p.version)?.description; return d ? [p.id, ...d.payload.aliases] : []; });
-                    choose(options.app, known, 'app');
-                }
-            }
-        }
+        if (options.app)
+            packages = [selectApp(packages, options.app)];
         const pending = packages.filter(p => this.host.approved[p.id]?.version !== p.version);
         if (pending.length && (options.approve || await options.confirm?.(pending))) {
             for (const p of pending)
@@ -68,11 +70,14 @@ export class CtlClient {
         let cacheHits = 0;
         const results = await boundedMap(packages, 4, async (pkg) => {
             const approval = this.host.approved[pkg.id];
-            if (approval?.version !== pkg.version)
-                return { error: { package: pkg.id, code: 'CTL_TRUST_REQUIRED', message: 'Description endpoint not approved.', hint: `run: synopkgland ctl list --host ${this.host.name} --approve-installed` } };
+            if (approval?.version !== pkg.version) {
+                pkg.error = this.needsApproval(pkg);
+                return { error: { package: pkg.id, ...errorData(pkg.error) } };
+            }
             const cached = options.refresh ? null : this.store.cache(this.host, pkg.id, pkg.version);
             if (cached?.failure) {
                 cacheHits++;
+                pkg.error = new CtlError(cached.failure.code, cached.failure.message, cached.failure.hint, 5);
                 return { error: { package: pkg.id, ...cached.failure, cached: true } };
             }
             try {
@@ -87,13 +92,19 @@ export class CtlClient {
                         throw new CtlError('CTL_DESCRIPTION_UNAVAILABLE', `Description refused (${String(response?.error?.code ?? 'invalid response')}).`, 'Use --refresh after updating the App.', 5);
                     description = validateDescriptor(response.data, pkg.id, pkg.version);
                 }
-                if (approval.hash && approval.hash !== description.sha256 && !options.approve)
-                    throw new CtlError('CTL_DESCRIPTION_CHANGED', 'Description hash changed; approval required.', `run: synopkgland ctl list --host ${this.host.name} --refresh --approve-installed`, 4);
+                if (approval.hash && approval.hash !== description.sha256 && !options.approve) {
+                    // Remember the observed change so a later cache hit cannot revive the old approval.
+                    this.store.putCache(this.host, pkg.id, pkg.version, description);
+                    pkg.aliases = [...new Set([...pkg.aliases, ...description.payload.aliases])];
+                    throw this.needsApproval(pkg);
+                }
+                pkg.aliases = description.payload.aliases;
                 approval.hash = description.sha256;
                 this.store.putCache(this.host, pkg.id, pkg.version, description);
                 return { description };
             }
             catch (error) {
+                pkg.error = ctlError(error);
                 const failure = errorData(error);
                 if (failure.code === 'CTL_DESCRIPTION_UNAVAILABLE')
                     this.store.putFailure(this.host, pkg.id, pkg.version, failure);
@@ -102,7 +113,7 @@ export class CtlClient {
         });
         this.host.lastUsed = new Date().toISOString();
         this.store.save(this.host);
-        return { apps: results.flatMap(r => r.description ? [r.description] : []), diagnostics: results.flatMap(r => r.error ? [r.error] : []), cacheHits };
+        return { apps: results.flatMap(r => r.description ? [r.description] : []), installed: packages, diagnostics: results.flatMap(r => r.error ? [r.error] : []), cacheHits };
     }
     async execute(name, path, args, options = {}) {
         try {
@@ -116,7 +127,7 @@ export class CtlClient {
         const started = performance.now();
         this.until = started + (options.timeoutMs ?? CTL_TIMEOUT_MS);
         const listing = await this.discover(options);
-        const app = selectApp(listing.apps, name);
+        const app = this.selectApp(listing, name);
         const { id, operation } = selectOperation(app, path);
         const params = operationInput(operation, args, options.stdin, `run: synopkgland ctl ${name} ${operation.cli.join(' ')} --host ${this.host.name} --help`);
         const output = new SensitiveOutput(params, operation.paramsSchema);

package/dist/error-registry.js

@@ -33,7 +33,7 @@ export const ERROR_REGISTRY = {
     INIT_HEALTH_INVALID: { code: "INIT_HEALTH_INVALID", description: "The Compose readiness selection is invalid.", suggestion: "Supply both --health-path and --health-status with the actual endpoint and expected 2xx response; redirects are not followed." },
     INIT_UPSTREAM_IMAGE_REQUIRED: { code: "INIT_UPSTREAM_IMAGE_REQUIRED", description: "The official upstream image repository was not selected.", suggestion: "Use init --upstream-fork --upstream-image <official-repository> for Compose." },
     INIT_UPSTREAM_IMAGE_INVALID: { code: "INIT_UPSTREAM_IMAGE_INVALID", description: "The upstream image repository is invalid.", suggestion: "Supply the official repository without a tag or digest; upgrade.sh selects the matching release and resolves its digest." },
-    CTL_TRUST_REQUIRED: { "code": "CTL_TRUST_REQUIRED", "description": "App description access requires approval.", "suggestion": "Run synopkgland ctl list with explicit host and approve the candidate batch." },
+    CTL_APP_NEEDS_APPROVAL: { "code": "CTL_APP_NEEDS_APPROVAL", "description": "The installed App needs approval or re-approval.", "suggestion": "Run synopkgland ctl list --app <package-id> --approve-installed --host <host>." },
     COMPOSE_HEALTH_REQUIRED: { code: "COMPOSE_HEALTH_REQUIRED", description: "Compose web readiness was not selected.", suggestion: "Set compose.web.health.path and expected 2xx status for the actual App; redirects are not followed." },
     CTL_UNSUPPORTED_BACKEND: { "code": "CTL_UNSUPPORTED_BACKEND", "description": "Automatic descriptions require a native SDK backend.", "suggestion": "Disable ctl for binary/Compose wrappers or implement the public contract separately." },
     CTL_DESCRIBE_REQUIRED: { "code": "CTL_DESCRIBE_REQUIRED", "description": "The Go backend has no build-only registry exporter.", "suggestion": "Update the native template and implement --describe using api.DescribeRoutes." },

package/dist/host/package-commands.d.ts

@@ -12,6 +12,20 @@ export interface InstallOptions {
     dryRun?: boolean;
 }
 export declare function installPackage(spec: string, options?: InstallOptions, connection?: NasConnection): Promise<{
+    message?: string | undefined;
+    host: string;
+    target: NasTarget;
+    source: string;
+    packages: {
+        signed?: boolean | undefined;
+        package: string;
+        version: string;
+        size: number;
+        action: string;
+    }[];
+    parameters: string[];
+} | {
+    message?: string | undefined;
     host: string;
     target: NasTarget;
     source: string;
@@ -26,6 +40,7 @@ export declare function installPackage(spec: string, options?: InstallOptions, c
     dryRun: boolean;
 } | {
     status: import("./catalog-install.js").InstalledPackageState | undefined;
+    message?: string | undefined;
     host: string;
     target: NasTarget;
     source: string;

package/dist/host/package-commands.js

@@ -122,6 +122,8 @@ export async function installPackage(spec, options = {}, connection) {
             if (installed.has(item.package) &&
                 compareVersions(item.version, installed.get(item.package)) < 0)
                 throw fail("PACKAGE_DOWNGRADE_REFUSED", `Refusing downgrade of ${item.package}`, "Choose the installed version or a newer release");
+        const changes = plan.filter((item) => !installed.has(item.package) ||
+            compareVersions(item.version, installed.get(item.package)) !== 0);
         const publicPlan = {
             host: nas.name,
             target,
@@ -130,21 +132,30 @@ export async function installPackage(spec, options = {}, connection) {
                 package: item.package,
                 version: item.version,
                 size: item.size,
-                action: installed.has(item.package) ? "upgrade" : "install",
+                action: !installed.has(item.package)
+                    ? "install"
+                    : compareVersions(item.version, installed.get(item.package)) === 0
+                        ? "none"
+                        : "upgrade",
                 ...(item.package === root.package && report
                     ? { signed: report.signed }
                     : {}),
             })),
             parameters: Object.keys(options.param ?? {}),
+            ...(!changes.length
+                ? { message: `${root.package}@${root.version} is already up to date; no package changes required.` }
+                : {}),
         };
         if (options.dryRun)
             return { dryRun: true, ...publicPlan };
+        if (!changes.length)
+            return publicPlan;
         await requireAdministrator(nas);
-        await confirm(`Install ${plan.map((e) => e.package + "@" + e.version).join(", ")}`, options.yes);
+        await confirm(`Install ${changes.map((e) => e.package + "@" + e.version).join(", ")}`, options.yes);
         // Download, verify and inspect the entire plan before the first NAS write.
         const files = new Map();
         const images = new Map();
-        for (const entry of plan) {
+        for (const entry of changes) {
             let file = localFile;
             if (!local || entry.package !== root.package) {
                 const response = await fetchPackageSource(entry.link);
@@ -163,7 +174,7 @@ export async function installPackage(spec, options = {}, connection) {
             files.set(entry.package, file);
             images.set(entry.package, containerImageReferences(checked));
         }
-        for (const entry of plan)
+        for (const entry of changes)
             await installPackageFromLocalSpk({
                 dsmOrigin: nas.session.origin,
                 cookieHeader: nas.session.cookie,

package/dist/runtime/sdk-source.d.ts

@@ -1,7 +1,7 @@
 export { goPrivateCovers } from './go-env.js';
 import { type ExecutorManifest } from './sdk-executor-manifest.js';
 /** Pinned SDK for CLI-owned controllers and Compose planning; App pins take precedence. */
-export declare const DEFAULT_SDK_VERSION = "0.41.0";
+export declare const DEFAULT_SDK_VERSION = "0.41.1";
 export declare const SDK_PACKAGE = "@synopackageland/sdk";
 export declare const SDK_MODULE = "github.com/synopackageland/syno-pkg-land-sdk";
 export declare const EXECUTOR_MODULE = "github.com/synopackageland/syno-pkg-land-sdk/executor";

package/dist/runtime/sdk-source.js

@@ -5,7 +5,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { readExecutorManifest, predatesExecutorManifest } from './sdk-executor-manifest.js';
 /** Pinned SDK for CLI-owned controllers and Compose planning; App pins take precedence. */
-export const DEFAULT_SDK_VERSION = '0.41.0';
+export const DEFAULT_SDK_VERSION = '0.41.1';
 export const SDK_PACKAGE = '@synopackageland/sdk';
 export const SDK_MODULE = 'github.com/synopackageland/syno-pkg-land-sdk';
 export const EXECUTOR_MODULE = `${SDK_MODULE}/executor`;

package/docs/ctl-external.md

@@ -68,6 +68,22 @@ selected live descriptor against its approved hash. Zero or multiple matching
 Apps refuse; revoke the unwanted approval or use distinct protocol IDs. A cache
 is only a recipient selector and never grants tool authority.
 
+For ordinary `ctl <alias|package> …` and help requests, an installed App awaiting
+first approval, a new version's approval, or approval of a changed description
+returns `CTL_APP_NEEDS_APPROVAL` (exit 4). For example, the message is
+`SynoReclaim 1.2.0 needs approval` with an App-scoped command:
+
+```sh
+synopkgland ctl list --app SynoReclaim --approve-installed --host controller
+```
+
+Obtain the user's authorization before running the hint. Cached aliases from the
+previously approved version still identify an upgraded installed App, but cannot
+authorize execution. Before an alias has been discovered, use the package ID for
+first approval. Unknown-name suggestions appear only if no installed package ID
+or known alias matches. `ctl list` includes pending approvals in its diagnostics;
+external calls retain the separate protocol/pin checks described below.
+
 Only a named, registered host and its OS-stored session are used. Ambient
 `DSM_*` credentials/URL cannot create or replace this login. HTTPS requires the
 stored SHA-256 certificate pin and refuses rotation before sending HTTP headers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.41.13",
+  "version": "0.42.1",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.35.5",
+    "@synopackageland/templates": "~0.37.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.35.5`. A templates patch needs only a
+The CLI installs templates through `~0.37.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for

package/skills/reference/ctl.md

@@ -10,8 +10,30 @@ Use this for operating installed Apps, rather than building/deploying projects.
 4. Use the discovered alias, CLI path and typed flags with an explicit `--host nas`; inspect `--help` and `--dry-run` before execution. For example, `synopkgland ctl notes list --status pending --host nas --dry-run`. Use the real command/schema from discovery, not this illustrative name.
 5. Reads need no write confirmation. For authorized write/destructive commands, add `--yes`; without it the CLI returns a plan and confirmation error. A --yes flag does not replace the user's authorization or the App's backend checks.
 
+Typed flags accept strings, integers, numbers and booleans, including arrays of
+these scalar types. Repeat an array flag for each item, for example
+`--targets /volume1 --targets /volume2`; one occurrence still produces an array.
+Use `--flag=value` when a string item starts with `--`. Commas are literal string
+content, not array separators. Items and the complete array are checked against
+the command schema. Command `--help` lists each supported flag's `valueType` and
+`repeatable` status and renders scalar-array examples as repeated flags.
+Objects, arrays of objects, nested arrays and arrays without a scalar item type
+require `--input <file|->`; use JSON input for an explicit empty array too.
+Plans keep schema-marked private paths and other sensitive values redacted.
+
 With multiple hosts, select a default with `synopkgland host default <name>` or specify --host. `--host a,b` and --all-hosts return per-host results, with exit 8 on partial failure. Do not retry a write merely because one host failed; query its state first. --refresh rereads descriptions; unchanged package versions use the host/account/package/version/hash cache. Never assume cached metadata grants resource permission.
 
+An installed App awaiting first approval, approval of a new version, or approval
+of a changed description returns `CTL_APP_NEEDS_APPROVAL` (exit 4) when selected
+by package ID or a known cached alias, including help requests. The message names
+the installed package and version, for example `SynoReclaim 1.2.0 needs approval`.
+Obtain the user's authorization, then follow the exact App-scoped hint:
+`synopkgland ctl list --app SynoReclaim --approve-installed --host <profile>`.
+Previous-version aliases identify the installed App only; they never authorize
+execution. An alias not yet discovered requires the package ID for first approval.
+`CTL_APP_UNKNOWN` and “Did you mean …” apply only when no installed package ID or
+known alias matches. `ctl list` reports pending approvals in `data.diagnostics`.
+
 Use `host show nas` to inspect approvals/pins, `host revoke nas PackageID` to remove an App approval, `host logout nas` to retain registration, and `host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
 
 Stdout defaults to JSON without a TTY. Success is {ok:true,data}; failure is {ok:false,error:{code,message,hint,allowed?}}. Multi-host output uses {ok,results:[{host,ok,data|error}]}. Follow the concrete hint and complete allowed list; do not guess another method or bypass ctl with raw HTTP. Exit codes: 2 authentication, 3 parameters/names, 4 permissions/trust, 5 App/contract, 6 network, 7 confirmation, 8 partial failure.

package/skills/reference/install.md

@@ -1,6 +1,6 @@
 # Native installation settings
 
-Use SDK/App 0.38.6, CLI 0.41.12 and templates 0.35.5. Configure installation through the manifest and generated wizard; do not add App ACL writers, root hooks or independent port state.
+Use SDK/App 0.41.1, CLI 0.42.0 and templates 0.37.0. Configure installation through the manifest and generated wizard; do not add App ACL writers, root hooks or independent port state.
 
 ```yaml
 install: