@synopackageland/cli 0.32.1 → 0.33.0

package/dist/host/package-commands.js

@@ -0,0 +1,205 @@
+import { mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { CtlError } from "../ctl/errors.js";
+import { inspectAnySpk } from "../spk/inspect.js";
+import { connectNas, requireAdministrator, } from "./connection.js";
+import { dsmFetch } from "./dsm-http.js";
+import { fetchInstalledPackageState, installPackageFromLocalSpk, uninstallPackageFromDsm, } from "./catalog-install.js";
+import { assertCompatible, sourceUrl, selectEntry, resolveInstallPlan, verifyPins, compareVersions, } from "./install-plan.js";
+export const DEFAULT_PACKAGE_SOURCE = "https://packages.synopkgland.com";
+const fail = (code, message, hint = "Check Package Center and retry") => new CtlError(code, message, hint, 3);
+export function packageId(value) {
+    if (!/^[A-Za-z][A-Za-z0-9_.+-]{0,127}$/.test(value))
+        throw fail("PACKAGE_ID_INVALID", "Invalid package ID");
+    return value;
+}
+export async function nasTarget(nas) {
+    const packageInfo = await nas.call("SYNO.Core.Package.Info", "get", 1);
+    const info = await nas.call("SYNO.DSM.Info", "getinfo", 2);
+    const config = packageInfo?.config;
+    const unique = config?.ds_unique;
+    const arch = typeof unique === "string" && unique.startsWith("synology_")
+        ? unique.slice(9, unique.lastIndexOf("_"))
+        : undefined;
+    const build = Number(config?.ds_build);
+    const version = typeof info.version_string === "string"
+        ? /\b(\d+\.\d+(?:\.\d+)?)-\d+/.exec(info.version_string)?.[1]
+        : undefined;
+    if (typeof arch !== "string" ||
+        !/^\w+$/.test(arch) ||
+        !Number.isSafeInteger(build) ||
+        build < 1 ||
+        typeof version !== "string" ||
+        !/^\d+\.\d+(?:\.\d+)?$/.test(version))
+        throw fail("NAS_TARGET_UNKNOWN", "DSM did not report a usable platform and build", "Check NAS system information; no architecture was guessed");
+    const [major, minor] = version.split(".").map(Number);
+    return { arch, version: `${version}-${build}`, major, minor, build };
+}
+export async function readFeed(source, target) {
+    const response = await dsmFetch(sourceUrl(source, target).href);
+    if (!response.ok)
+        throw fail("PACKAGE_SOURCE_FAILED", `Package source returned HTTP ${response.status}`);
+    const body = (await response.json());
+    if (!Array.isArray(body?.packages) || body.packages.length > 4096)
+        throw fail("PACKAGE_SOURCE_INVALID", "Package source returned an invalid package list");
+    return body.packages;
+}
+async function inventory(nas) {
+    const data = await nas.call("SYNO.Core.Package", "list", 2, {
+        additional: '["status"]',
+        ignore_hidden: "false",
+    });
+    if (!Array.isArray(data?.packages) ||
+        (data.total !== undefined && data.total !== data.packages.length))
+        throw fail("NAS_INVENTORY_INVALID", "Installed package inventory is incomplete");
+    return new Map(data.packages.map((p) => [p.id, p.version]));
+}
+async function confirm(action, yes) {
+    if (yes)
+        return;
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw fail("PACKAGE_CONFIRM_REQUIRED", "Package changes require confirmation", `Use --yes to ${action} non-interactively`);
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        if (!/^y(es)?$/i.test(await rl.question(`${action}? [y/N] `)))
+            throw fail("PACKAGE_CANCELLED", "Package operation cancelled", "No changes were made");
+    }
+    finally {
+        rl.close();
+    }
+}
+function checkSpk(report, target) {
+    if (!report.dsm.ok ||
+        report.findings.length ||
+        !report.package ||
+        !report.version)
+        throw fail("PACKAGE_INSPECT_FAILED", "SPK inspection failed", "Run synopkgland inspect <file.spk> for the detailed checks");
+    assertCompatible(report.info ?? {}, target);
+}
+export async function installPackage(spec, options = {}, connection) {
+    const stage = mkdtempSync(join(tmpdir(), "synopkgland-install-"));
+    try {
+        const local = /\.spk$/i.test(spec) ||
+            spec.startsWith(".") ||
+            spec.startsWith("/") ||
+            spec.includes("\\");
+        let report;
+        const localFile = join(stage, "local.spk");
+        if (local) {
+            writeFileSync(localFile, readFileSync(resolve(spec)), { mode: 0o600 });
+            report = await inspectAnySpk(localFile);
+            if (!report.dsm.ok || report.findings.length)
+                throw fail("PACKAGE_INSPECT_FAILED", "SPK inspection failed", "Run synopkgland inspect <file.spk> for details");
+        }
+        const nas = connection ?? (await connectNas(options.host)), target = await nasTarget(nas), installed = await inventory(nas);
+        if (report)
+            checkSpk(report, target);
+        const source = options.source ?? DEFAULT_PACKAGE_SOURCE;
+        let entries = [];
+        if (!local || report?.info?.install_dep_packages)
+            entries = await readFeed(source, target);
+        let root;
+        if (report) {
+            root = {
+                package: packageId(report.package),
+                version: report.version,
+                link: "",
+                size: readFileSync(localFile).length,
+                deppkgs: report.info?.install_dep_packages,
+            };
+        }
+        else {
+            const match = /^([^@]+)(?:@([0-9][0-9._-]*))?$/.exec(spec);
+            if (!match)
+                throw fail("PACKAGE_SPEC_INVALID", "Use <package-id>[@version] or a local .spk");
+            root = selectEntry(entries, packageId(match[1]), match[2], target);
+        }
+        const plan = resolveInstallPlan(root, entries, target, installed);
+        for (const item of plan)
+            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 publicPlan = {
+            host: nas.name,
+            target,
+            source: local ? "local" : source,
+            packages: plan.map((item) => ({
+                package: item.package,
+                version: item.version,
+                size: item.size,
+                action: installed.has(item.package) ? "upgrade" : "install",
+                ...(item.package === root.package && report
+                    ? { signed: report.signed }
+                    : {}),
+            })),
+            parameters: Object.keys(options.param ?? {}),
+        };
+        if (options.dryRun)
+            return { dryRun: true, ...publicPlan };
+        await requireAdministrator(nas);
+        await confirm(`Install ${plan.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();
+        for (const entry of plan) {
+            let file = localFile;
+            if (!local || entry.package !== root.package) {
+                const response = await dsmFetch(entry.link);
+                if (!response.ok)
+                    throw fail("PACKAGE_DOWNLOAD_FAILED", `SPK download returned HTTP ${response.status}`);
+                const bytes = Buffer.from(await response.arrayBuffer());
+                verifyPins(bytes, entry);
+                file = join(stage, `${files.size}.spk`);
+                writeFileSync(file, bytes, { mode: 0o600 });
+            }
+            const checked = await inspectAnySpk(file);
+            checkSpk(checked, target);
+            if (checked.package !== entry.package ||
+                checked.version !== entry.version)
+                throw fail("PACKAGE_IDENTITY_MISMATCH", "Downloaded SPK identity differs from the selected release");
+            files.set(entry.package, file);
+        }
+        for (const entry of plan)
+            await installPackageFromLocalSpk({
+                dsmOrigin: nas.session.origin,
+                cookieHeader: nas.session.cookie,
+                packageId: entry.package,
+                version: entry.version,
+                spkPath: files.get(entry.package),
+                extraValues: entry.package === root.package ? options.param : undefined,
+            });
+        return {
+            ...publicPlan,
+            status: await fetchInstalledPackageState(nas.session.origin, nas.session.cookie, root.package),
+        };
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+    }
+}
+export async function uninstallPackage(id, options = {}) {
+    packageId(id);
+    const nas = await connectNas(options.host);
+    const state = await fetchInstalledPackageState(nas.session.origin, nas.session.cookie, id);
+    if (!state?.installed)
+        throw fail("PACKAGE_NOT_INSTALLED", `Package ${id} is not installed`);
+    if (options.dryRun)
+        return { dryRun: true, host: nas.name, package: id, action: "uninstall" };
+    await requireAdministrator(nas);
+    await confirm(`Uninstall ${id} (package uninstall hooks may remove data)`, options.yes);
+    await uninstallPackageFromDsm({
+        dsmOrigin: nas.session.origin,
+        cookieHeader: nas.session.cookie,
+        packageId: id,
+    });
+    return { host: nas.name, package: id, installed: false };
+}
+export async function packageStatus(id, host) {
+    packageId(id);
+    const nas = await connectNas(host);
+    const state = await fetchInstalledPackageState(nas.session.origin, nas.session.cookie, id);
+    if (!state)
+        throw fail("PACKAGE_STATUS_UNKNOWN", "DSM did not return a verifiable package state");
+    return { host: nas.name, package: id, ...state };
+}

package/dist/host/port-info-lookup.d.ts

@@ -1,7 +1,7 @@
 import type { PortInfoEntry } from "./port-info.js";
 export type PortInfoHttpRequest = (url: string, init?: RequestInit) => Promise<Response>;
 /**
- * Parses the native DSM response, not a synoagentcli operation envelope.
+ * Parses the native DSM response, not a shared host operation envelope.
  * `undefined` means "cannot tell" and deliberately allows deployment to
  * continue. An empty `port_info` list has the same fail-open meaning.
  */

package/dist/host/port-info-lookup.js

@@ -1,3 +1,4 @@
+import { CtlError } from '../ctl/errors.js';
 import { dsmFetch } from "./dsm-http.js";
 const PORT_INFO_API = "SYNO.Core.Service.PortInfo";
 function asRecord(value) {
@@ -20,7 +21,7 @@ function validPortRange(value) {
         end <= 65535);
 }
 /**
- * Parses the native DSM response, not a synoagentcli operation envelope.
+ * Parses the native DSM response, not a shared host operation envelope.
  * `undefined` means "cannot tell" and deliberately allows deployment to
  * continue. An empty `port_info` list has the same fail-open meaning.
  */
@@ -81,7 +82,9 @@ export async function fetchPortInfo(dsmOrigin, cookieHeader, request = dsmFetch)
         }
         return parsePortInfo(await response.json());
     }
-    catch {
+    catch (error) {
+        if (error instanceof CtlError)
+            throw error;
         return undefined;
     }
 }

package/dist/host/share-lookup.d.ts

@@ -1,5 +1,6 @@
 export declare function shareRealPathFromEntry(entry: Record<string, unknown>, logicalName: string): string | undefined;
 export declare function findShareRealPath(payload: unknown, logicalName: string): string | undefined;
 export declare function findShareNames(payload: unknown): string[];
-export declare function lookupSharePathWithSynoagentcli(logicalName: string, profileName?: string): string | undefined;
-export declare function listShareNamesWithSynoagentcli(profileName?: string): string[];
+/** Query shares through the caller's authenticated DSM transport. */
+export declare function lookupSharePath(logicalName: string, call: (api: string, method: string, version: number, params?: Record<string, string>) => Promise<any>): Promise<string | undefined>;
+export declare function listShareNames(call: (api: string, method: string, version: number, params?: Record<string, string>) => Promise<any>): Promise<string[]>;

package/dist/host/share-lookup.js

@@ -1,5 +1,3 @@
-import { spawnSync } from "node:child_process";
-import { resolveHostCredentials } from "./credentials.js";
 function asRecord(value) {
     if (value && typeof value === "object" && !Array.isArray(value)) {
         return value;
@@ -69,93 +67,9 @@ export function findShareNames(payload) {
     }
     return [...names];
 }
-function synoagentcli(args, profileName) {
-    const fullArgs = [...args];
-    if (profileName) {
-        fullArgs.push("--host", profileName);
-    }
-    const result = spawnSync("synoagentcli", fullArgs, { encoding: "utf8" });
-    return {
-        status: result.status,
-        stdout: result.stdout ?? "",
-        stderr: result.stderr ?? "",
-    };
-}
-function parseJson(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-}
-function lookupSharePathWithDsmHttp(logicalName, profileName) {
-    const credentials = resolveHostCredentials(profileName);
-    if (!credentials) {
-        return undefined;
-    }
-    const script = `
-import json, sys, urllib.parse, urllib.request
-origin, account, passwd, name = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
-def call(params):
-    url = origin.rstrip("/") + "/webapi/entry.cgi?" + urllib.parse.urlencode(params)
-    return json.loads(urllib.request.urlopen(url, timeout=8).read())
-login = call({
-    "api": "SYNO.API.Auth",
-    "version": "3",
-    "method": "login",
-    "account": account,
-    "passwd": passwd,
-    "session": "FileStation",
-    "format": "sid",
-})
-sid = (login.get("data") or {}).get("sid")
-if not sid:
-    sys.exit(2)
-try:
-    listed = call({
-        "api": "SYNO.Core.Share",
-        "version": "1",
-        "method": "list",
-        "_sid": sid,
-    })
-    print(json.dumps(listed))
-finally:
-    call({
-        "api": "SYNO.API.Auth",
-        "version": "3",
-        "method": "logout",
-        "session": "FileStation",
-        "_sid": sid,
-    })
-`;
-    const result = spawnSync("python3", ["-c", script, credentials.dsmOrigin, credentials.username, credentials.password, logicalName], { encoding: "utf8" });
-    if (result.status !== 0) {
-        return undefined;
-    }
-    return findShareRealPath(parseJson(result.stdout), logicalName);
-}
-export function lookupSharePathWithSynoagentcli(logicalName, profileName) {
-    const get = synoagentcli(["dsm", "control-panel", "shared-folder", "get", logicalName], profileName);
-    if (get.status === 0) {
-        const fromGet = findShareRealPath(parseJson(get.stdout), logicalName);
-        if (fromGet) {
-            return fromGet;
-        }
-    }
-    const list = synoagentcli(["dsm", "control-panel", "shared-folder", "list"], profileName);
-    if (list.status === 0) {
-        const fromList = findShareRealPath(parseJson(list.stdout), logicalName);
-        if (fromList) {
-            return fromList;
-        }
-    }
-    return lookupSharePathWithDsmHttp(logicalName, profileName);
-}
-export function listShareNamesWithSynoagentcli(profileName) {
-    const list = synoagentcli(["dsm", "control-panel", "shared-folder", "list"], profileName);
-    if (list.status !== 0) {
-        return [];
-    }
-    return findShareNames(parseJson(list.stdout));
+/** Query shares through the caller's authenticated DSM transport. */
+export async function lookupSharePath(logicalName, call) {
+    const body = await call('SYNO.Core.Share', 'list', 1, { additional: '["real_path"]' });
+    return findShareRealPath(body, logicalName);
 }
+export async function listShareNames(call) { return findShareNames(await call('SYNO.Core.Share', 'list', 1)); }

package/dist/host/share-permission-lookup.d.ts

@@ -11,7 +11,7 @@ import type { SharePermissionRow } from "./share-permission.js";
  * The APIs used were confirmed present on DSM 7.4 (the test NAS):
  * `SYNO.Core.Share.Permission`, `SYNO.Core.Group`, `SYNO.Core.Group.Member`.
  * `SYNO.Core.User.Group` also exists on the NAS but has no generated
- * synoagentcli operation, which is why membership is derived group-by-group.
+ * CLI operation, which is why membership is derived group-by-group.
  */
 export type DsmApiCall = (operationId: string, params: Record<string, string>) => Promise<unknown>;
 export declare function parseSharePermissionRows(payload: unknown): SharePermissionRow[] | undefined;
@@ -19,5 +19,5 @@ export declare function parseGroupNames(payload: unknown): string[] | undefined;
 export declare function parseGroupMemberNames(payload: unknown): string[] | undefined;
 export declare function fetchSharePermissions(shareName: string, call: DsmApiCall): Promise<SharePermissionListing | undefined>;
 export declare function fetchUserGroups(userName: string, call: DsmApiCall): Promise<string[] | undefined>;
-/** synoagentcli-backed `DsmApiCall`, matching how the rest of the host client talks to DSM. */
-export declare function createSynoagentcliApiCall(profileName?: string): DsmApiCall;
+/** Adapt fixed operation IDs to direct DSM WebAPI requests. */
+export declare function createDsmApiCall(call: (api: string, method: string, version: number, params: Record<string, string>) => Promise<unknown>): DsmApiCall;

package/dist/host/share-permission-lookup.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { CtlError } from '../ctl/errors.js';
 const SHARE_PERMISSION_OPERATION = "SYNO_Core_Share_Permission_list_v1";
 const GROUP_LIST_OPERATION = "SYNO_Core_Group_list_v1";
 const GROUP_MEMBER_OPERATION = "SYNO_Core_Group_Member_list_v1";
@@ -8,7 +8,7 @@ function asRecord(value) {
     }
     return undefined;
 }
-/** Unwrap the synoagentcli envelope down to the DSM `data` object. */
+/** Unwrap the CLI envelope down to the DSM `data` object. */
 function dsmData(payload) {
     const outer = asRecord(payload);
     if (!outer || outer.success === false) {
@@ -77,7 +77,9 @@ export async function fetchSharePermissions(shareName, call) {
                 limit: "-1",
             }));
         }
-        catch {
+        catch (error) {
+            if (error instanceof CtlError)
+                throw error;
             return undefined;
         }
     };
@@ -94,7 +96,9 @@ export async function fetchUserGroups(userName, call) {
     try {
         groupNames = parseGroupNames(await call(GROUP_LIST_OPERATION, { offset: "0", limit: "-1" }));
     }
-    catch {
+    catch (error) {
+        if (error instanceof CtlError)
+            throw error;
         return undefined;
     }
     if (!groupNames) {
@@ -106,7 +110,9 @@ export async function fetchUserGroups(userName, call) {
         try {
             members = parseGroupMemberNames(await call(GROUP_MEMBER_OPERATION, { group: groupName, offset: "0", limit: "-1" }));
         }
-        catch {
+        catch (error) {
+            if (error instanceof CtlError)
+                throw error;
             return undefined;
         }
         // One unreadable group could be the one that grants access, so a partial
@@ -120,30 +126,12 @@ export async function fetchUserGroups(userName, call) {
     }
     return memberships;
 }
-/** synoagentcli-backed `DsmApiCall`, matching how the rest of the host client talks to DSM. */
-export function createSynoagentcliApiCall(profileName) {
-    return async (operationId, params) => {
-        const args = ["api", "call", "--operation-id", operationId];
-        for (const [key, value] of Object.entries(params)) {
-            args.push("--param", `${key}=${value}`);
-        }
-        if (profileName) {
-            args.push("--host", profileName);
-        }
-        const result = spawnSync("synoagentcli", args, { encoding: "utf8" });
-        if (result.status !== 0) {
-            return undefined;
-        }
-        // synoagentcli may prepend an update notice before the JSON body.
-        const match = /\{[\s\S]*\}/.exec(result.stdout ?? "");
-        if (!match) {
-            return undefined;
-        }
-        try {
-            return JSON.parse(match[0]);
-        }
-        catch {
-            return undefined;
-        }
+/** Adapt fixed operation IDs to direct DSM WebAPI requests. */
+export function createDsmApiCall(call) {
+    return async (operation, params) => {
+        const match = /^(SYNO_Core_(?:Share_Permission|Group|Group_Member))_(list)_v(1)$/.exec(operation);
+        if (!match)
+            throw new Error('Unsupported DSM read operation');
+        return { success: true, data: { response: await call(match[1].replaceAll('_', '.'), match[2], Number(match[3]), params) } };
     };
 }

package/dist/host/types.d.ts

@@ -65,6 +65,10 @@ export interface NasHost {
 export interface HostCredentials {
     dsmOrigin: string;
     username: string;
-    password: string;
+    password?: string;
+    hostName?: string;
+    ca?: string;
+    fingerprint?: string;
+    loadSession?: () => Promise<import("../ctl/transport.js").DsmSession>;
     cookieHeader?: string;
 }

package/dist/skill.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const SKILL_CATALOG = [
     { id: "orchestrator", file: "SKILL.md", when: "Read first" },
+    { id: "host-install", file: "reference/host-install.md", when: "Shared NAS login, store/local SPK installation and removal" },
     { id: "ctl", file: "reference/ctl.md", when: "Operate registered NAS Apps or design AI commands" },
     {
         id: "create",

package/dist/spk/inspect.d.ts

@@ -3,6 +3,7 @@ import { type SpkFinding } from "./validate-spk.js";
 export interface SpkReport extends SpkInspection {
     /** Built by synopkgland, so its build contract (`findings`) was checked too. */
     synopkgland: boolean;
+    info?: Record<string, string>;
     /** The DSM 7 package format rules, checked on every SPK. */
     dsm: {
         ok: boolean;

package/dist/spk/inspect.js

@@ -19,7 +19,7 @@ export async function inspectAnySpk(spkPath) {
     const dsm = { ok: validation.ok, errors: validation.errors, warnings: validation.warnings };
     const facts = await readFacts(spkPath);
     if (BUILD_MARKERS.some((name) => facts.top.has(name)) || facts.payload.some((entry) => entry.path === CONTAINER_MARKER)) {
-        return { ...(await inspectSpk(spkPath)), synopkgland: true, dsm };
+        return { ...(await inspectSpk(spkPath)), synopkgland: true, info: validation.info, dsm };
     }
     return {
         ...(validation.package ? { package: validation.package } : {}),
@@ -30,6 +30,7 @@ export async function inspectAnySpk(spkPath) {
         findings: [],
         capabilities: [],
         synopkgland: false,
+        info: validation.info,
         dsm,
     };
 }

package/dist/spk/validate-spk.d.ts

@@ -3,6 +3,7 @@ export type { SpkFinding } from "./findings.js";
 export interface SpkValidation {
     /** No errors; warnings do not fail validation. */
     ok: boolean;
+    info?: Record<string, string>;
     package?: string;
     version?: string;
     arch?: string;

package/dist/spk/validate-spk.js

@@ -34,6 +34,7 @@ export async function validateSpk(spkPath) {
     const errors = findings.list.filter((finding) => finding.severity === "error");
     return {
         ok: errors.length === 0,
+        info,
         ...(info.package ? { package: info.package } : {}),
         ...(info.version ? { version: info.version } : {}),
         ...(info.arch ? { arch: info.arch } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {

package/skills/SKILL.md

@@ -48,6 +48,8 @@ Buttons follow DSM's policy ([reference/ui-vue.md](reference/ui-vue.md#buttons),
 
 Read [reference/ui-json.md](reference/ui-json.md) when generating or editing JSON UI; discover the installed catalog, validate the spec, then render and fix layout issues.
 
+Read [reference/host-install.md](reference/host-install.md) before NAS authentication, store/local-SPK installation or package removal. All DSM commands share the registered host session.
+
 ## UI copywriting
 
 For UI/locale strings we author in the SDK, UI package, templates and our own

package/skills/reference/ctl.md

@@ -2,15 +2,15 @@
 
 Use this for operating installed Apps, rather than building/deploying projects.
 
-1. `synopkgland ctl host list --json` checks registered machines and sessions.
-2. Register with `ctl host add nas --url https://nas.example:5001 --username alice`, or renew with `ctl host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
+1. `synopkgland host list --json` checks registered machines and sessions.
+2. Register with `host add nas --url https://nas.example:5001 --username alice`, or renew with `host login nas`. Credentials are hidden interactive input; `--password-stdin` is available. Do not put passwords/OTP in argv. Sessions and remembered-device tokens use OS secure storage, never a plaintext fallback.
 3. Run `synopkgland ctl list --host nas --json` for all registered Apps, commands, schemas, effects, permissions and executable examples. If description access needs approval, ask the user to approve the whole candidate batch; do not self-approve. An explicit `--approve-installed` records permission to send the DSM session to the displayed inventory's fixed description endpoints. Use `--app <package>` to narrow the batch. No description endpoint is anonymous.
 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.
 
-There is no shared current context: with multiple hosts, always 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.
+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.
 
-Use `ctl host show nas` to inspect approvals/pins, `ctl host revoke nas PackageID` to remove an App approval, `ctl host logout nas` to retain registration, and `ctl host remove nas --yes` to delete sessions, device token, approvals and cache. A failed NAS logout is reported independently from successful local removal.
+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/deploy.md

@@ -1,3 +1,5 @@
+Before deployment, register a NAS with `synopkgland host add nas --url https://nas.example:5001`, then renew it with `synopkgland host login nas`. See [host-install.md](host-install.md) for shared sessions, automation, install and uninstall.
+
 # Build and deploy
 
 1. Run `synopkgland check` and `synopkgland build --arch x86_64` (use aarch64 or armv7 for those targets; armv7 must be listed in `arches`; its jobs, daemon and executor are built but not NAS-verified). deploy detects the NAS arch, except on Marvell CPUs, where it asks for `--arch`.

package/skills/reference/host-install.md

@@ -0,0 +1,55 @@
+# Shared NAS login and package installation
+
+Register once with `synopkgland host add nas --url https://nas.example:5001 --username alice`.
+The CLI prompts for the password and OTP when DSM requires it. Session cookies,
+SynoToken and remembered-device tokens stay in the OS credential store; host
+metadata and App approvals stay under `~/.synopkgland/ctl`. Passwords are not saved.
+Use `--ca <PEM>` when adding a host with a private CA. Certificate verification stays on.
+
+Use `synopkgland host login nas` to renew an expired session. `host list`,
+`host show nas`, `host logout nas`, `host remove nas --yes` and
+`host revoke nas <package-id>` manage the registration, login and App approvals.
+`host default nas` selects a default; with one host it is selected automatically.
+Every DSM command accepts `--host nas`, including ctl, deploy, status, logs,
+install and uninstall. ctl still requires explicit App description approval.
+
+For authorized package changes:
+
+```sh
+synopkgland install SynoReclaim --host nas --dry-run --json
+synopkgland install SynoReclaim --host nas --yes --json
+synopkgland install SynoReclaim@0.1.1-1591 --host nas --yes
+synopkgland install ./MyApp.spk --host nas --param NAME=value --yes
+synopkgland status SynoReclaim --host nas --json
+synopkgland uninstall SynoReclaim --host nas --yes --json
+```
+
+Store installs default to `https://packages.synopkgland.com`; `--source <HTTPS URL>`
+selects another source. The source is queried for the NAS platform and DSM build.
+The CLI plans dependencies from the same feed, reports missing Synology packages,
+checks every feed size/MD5/SHA-256 pin and inspects SPKs before uploading.
+`<package-id>@version` selects an exact available release; downgrades are refused.
+`--dry-run` reads NAS/source metadata and prints the plan without uploading or changing DSM.
+Local SPKs pass the same inspect, architecture and DSM checks before installation.
+The inspection reports signature presence; it does not cryptographically authenticate a publisher.
+Install wizard values use repeated `--param NAME=value`; values are private and
+not printed in plans. DSM package hooks validate their meaning. Install/removal
+require administrator rights. Uninstall hooks can remove package data; review the App's policy.
+A failed multi-package install may leave earlier dependencies installed; inspect status before retrying.
+
+For automation, provide `DSM_USERNAME` and `DSM_PASSWORD` in the process environment
+(and `DSM_OTP` if required), with a registered `--host` using that same account.
+These values create an in-memory session and are never written to disk. Without a
+registration, install/deploy/status/logs also accept `DSM_URL` with both credentials.
+Use an HTTPS URL and a trusted certificate. Supply secrets through your CI secret
+store, never literal command arguments, committed files or command output.
+`host add/login --password-stdin` supports a password from standard input.
+
+Default NAS HTTPS certificates work through trust on first use: before sending a
+password, the CLI pins an untrusted leaf certificate's SHA-256 and prints
+`Trusting the NAS certificate <short fingerprint> (self-signed)`. Subsequent
+requests check the exact leaf. `HOST_CERT_CHANGED` shows old/new fingerprints;
+verify them with the user, then use `synopkgland host trust <name>` only after
+confirmation. Never disable TLS checks. `host add --fingerprint <sha256>` pins an
+expected leaf; `--ca <PEM>` uses a CA instead. Network errors distinguish
+HOST_TLS_UNTRUSTED, HOST_DNS_FAILED, HOST_CONNECTION_REFUSED and HOST_TIMEOUT.