@synopackageland/cli 0.14.1 → 0.15.1

package/dist/compose/env.d.ts

@@ -1,7 +1,9 @@
 export interface ComposeEnvironment {
     SYNOPKG_PKGVAR: string;
-    SYNO_APP_SECRETS_DIR: string;
+    SYNOPKGLAND_UID: string;
+    SYNOPKGLAND_GID: string;
 }
+/** Local Docker development only. DSM storage is prepared by the SDK as the package account. */
 export declare function prepareComposeEnvironment(projectRoot: string): ComposeEnvironment;
-export declare function materializeComposePaths(projectRoot: string, composePath: string): ComposeEnvironment;
-export declare function composeEnvDirsExist(projectRoot: string): boolean;
+export declare function materializeComposePaths(projectRoot: string, _composePath?: string): ComposeEnvironment;
+export declare function composeEnvDirsExist(root: string): boolean;

package/dist/compose/env.js

@@ -1,36 +1,28 @@
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { loadStandaloneManifest } from "../standalone/manifest.js";
+import { prepareLocalCompose } from "../standalone/compose.js";
+/** Local Docker development only. DSM storage is prepared by the SDK as the package account. */
 export function prepareComposeEnvironment(projectRoot) {
     const varDir = join(projectRoot, ".synopkgland", "var");
-    const secretsDir = join(projectRoot, ".synopkgland", "secrets");
-    mkdirSync(varDir, { recursive: true });
-    mkdirSync(secretsDir, { recursive: true });
+    mkdirSync(varDir, { recursive: true, mode: 0o700 });
     return {
         SYNOPKG_PKGVAR: varDir,
-        SYNO_APP_SECRETS_DIR: secretsDir,
+        SYNOPKGLAND_UID: String(process.getuid?.() ?? ""),
+        SYNOPKGLAND_GID: String(process.getgid?.() ?? ""),
     };
 }
-export function materializeComposePaths(projectRoot, composePath) {
+export function materializeComposePaths(projectRoot, _composePath) {
+    const loaded = loadStandaloneManifest(projectRoot);
+    if (!loaded.ok)
+        throw new Error(`[${loaded.errors[0].code}] ${loaded.errors[0].message}`);
+    if (!loaded.manifest.compose)
+        throw new Error("[COMPOSE_REQUEST_INVALID] Local Docker commands require the unified Compose declaration.");
     const env = prepareComposeEnvironment(projectRoot);
-    if (!existsSync(composePath)) {
-        return env;
-    }
-    const source = readFileSync(composePath, "utf8");
-    for (const match of source.matchAll(/\$\{SYNOPKG_PKGVAR\}([^:\s"'`]+)/g)) {
-        const subpath = match[1].replace(/^\/+/, "");
-        if (subpath) {
-            mkdirSync(join(env.SYNOPKG_PKGVAR, subpath), { recursive: true });
-        }
-    }
-    for (const match of source.matchAll(/\$\{SYNO_APP_SECRETS_DIR\}([^:\s"'`]+)/g)) {
-        const subpath = match[1].replace(/^\/+/, "");
-        if (subpath) {
-            mkdirSync(join(env.SYNO_APP_SECRETS_DIR, subpath), { recursive: true });
-        }
-    }
+    prepareLocalCompose(loaded.manifest, env.SYNOPKG_PKGVAR);
     return env;
 }
-export function composeEnvDirsExist(projectRoot) {
-    return (existsSync(join(projectRoot, ".synopkgland", "var")) &&
-        existsSync(join(projectRoot, ".synopkgland", "secrets")));
+export function composeEnvDirsExist(root) {
+    return (existsSync(join(root, ".synopkgland/var")) &&
+        existsSync(join(root, ".synopkgland/local-compose/docker-compose.yml")));
 }

package/dist/compose/runner.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { materializeComposePaths } from "./env.js";
@@ -10,7 +11,7 @@ export function evaluateComposeReady(containers) {
     }
     const hasHealthcheck = containers.some((c) => c.Health && c.Health !== "");
     if (hasHealthcheck) {
-        const ready = containers.every((c) => !c.Health || c.Health === "healthy");
+        const ready = containers.every((c) => c.State === "running" && (!c.Health || c.Health === "healthy"));
         return { ready, hasHealthcheck: true };
     }
     const ready = containers.every((c) => c.State === "running");
@@ -19,7 +20,8 @@ export function evaluateComposeReady(containers) {
 export async function pollUntilComposeReady(inspect, options = {}) {
     const timeoutMs = options.timeoutMs ?? 60_000;
     const intervalMs = options.intervalMs ?? 1_000;
-    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         const containers = await inspect();
@@ -39,12 +41,23 @@ export class RecordingComposeRunner {
         this.invocations.push({ command: "compose", args: ["up", "-d"] });
     }
     async waitReady(_projectRoot) {
-        this.invocations.push({ command: "compose", args: ["ps", "--format", "json"] });
+        this.invocations.push({
+            command: "compose",
+            args: ["ps", "--format", "json"],
+        });
     }
 }
 async function runDockerCompose(projectRoot, args, env) {
-    const { stdout } = await execFileAsync("docker", ["compose", ...args], {
-        cwd: projectRoot,
+    const { stdout } = await execFileAsync("docker", [
+        "compose",
+        "--project-name",
+        "synopkgland-local-" +
+            createHash("sha256").update(projectRoot).digest("hex").slice(0, 12),
+        "-f",
+        "docker-compose.yml",
+        ...args,
+    ], {
+        cwd: join(projectRoot, ".synopkgland/local-compose"),
         encoding: "utf8",
         maxBuffer: 10 * 1024 * 1024,
         env: env ? { ...process.env, ...env } : process.env,
@@ -52,7 +65,11 @@ async function runDockerCompose(projectRoot, args, env) {
     return stdout;
 }
 async function inspectComposeContainers(projectRoot) {
-    const stdout = await runDockerCompose(projectRoot, ["ps", "--format", "json"]);
+    const stdout = await runDockerCompose(projectRoot, [
+        "ps",
+        "--format",
+        "json",
+    ]);
     const lines = stdout
         .split("\n")
         .map((line) => line.trim())

package/dist/contract/unsupported-types.js

@@ -3,7 +3,7 @@ import { collectInstallParameters } from "./load.js";
  * Install parameter types that the schema still accepts but that have no working
  * install path on the live package-only route.
  *
- * Measured on vt-nas 2026-08-27: both end in DSM broken/150 with no Container
+ * Measured on the test NAS 2026-08-27: both end in DSM broken/150 with no Container
  * Manager project, while a no-parameter control package installed fine on the
  * same NAS. `secret` renders its password field and fails; `homes` renders no
  * input at all. `check` reports these as warnings so build keeps working

package/dist/contract/validate.js

@@ -33,7 +33,7 @@ export function validateContract(parsed, contractFile) {
     }
     // DSM 7.4 Package Center refuses an SPK whose package identity exceeds 32
     // characters -- "Invalid file format", before the install starts and with
-    // nothing written to synopkg.log. Measured on 10.17.83.200: 32 installs, 33
+    // nothing written to synopkg.log. Measured on a DSM 7.4 test NAS: 32 installs, 33
     // does not.
     if (typeof contract.package === "string" && contract.package.length > DSM_PACKAGE_IDENTITY_MAX) {
         const pos = getValuePosition(doc, ["package"]) ?? { line: 1, column: 1 };
@@ -164,7 +164,7 @@ function validateInstallParameters(parsed, contractFile) {
             }
         }
         // A45/A46: both types are in the schema enum but neither has a working
-        // install path on the live package-only route -- measured on vt-nas as DSM
+        // install path on the live package-only route -- measured on the test NAS as DSM
         // broken/150 with no Container Manager project, against a no-parameter
         // control that installed fine. Refusing here is what makes the failure
         // honest: `homes` used to validate, build a valid SPK, and only break at

package/dist/contract/web-launch.d.ts

@@ -1,5 +1,4 @@
-import { type AppLaunchMode } from './app-launch.js';
-import { type PackageIcons } from "../build-spk/dsm-icons.js";
+import { type AppLaunchMode } from "./app-launch.js";
 import type { AppContract } from "../types.js";
 /** DSM Web Station portal alias max length (error 1311 above this). */
 export declare const WEB_STATION_ALIAS_MAX = 20;
@@ -37,13 +36,3 @@ export declare function webStationAlias(packageId: string): string;
 /** DSM serves a package's `ui` directory under this root; the gateway CGI lives in it. */
 export declare function gatewayEntryPath(packageId: string, adminurl: unknown): string;
 export declare function trustedAppEntryPath(contract: AppContract): string;
-export declare const DSM_RESERVED_COOKIES: readonly ["id", "did"];
-export declare function extractContractCookieNames(contract: AppContract): string[];
-export declare function cookieStripHeaders(contract: AppContract): Array<{
-    name: string;
-    value: string;
-}>;
-export declare function webStationServiceName(alias: string): string;
-export declare function webStationServiceRoot(alias: string): string;
-export declare function renderWebStationResource(contract: AppContract): string;
-export declare function renderDsmWindowConfig(contract: AppContract, icons: PackageIcons): string;

package/dist/contract/web-launch.js

@@ -1,8 +1,5 @@
-import { APP_LAUNCH_MODES, DEFAULT_WEB_LAUNCH, isAppLaunchMode, resolveAppLaunch, dsmLauncherType } from './app-launch.js';
+import { APP_LAUNCH_MODES, DEFAULT_WEB_LAUNCH, isAppLaunchMode, resolveAppLaunch, } from "./app-launch.js";
 import { createHash } from "node:crypto";
-import { uiTitleFields } from "../build-spk/ui-texts.js";
-import { windowIconTemplate } from "../build-spk/dsm-icons.js";
-import { contractAppTitle } from "./i18n.js";
 /** DSM Web Station portal alias max length (error 1311 above this). */
 export const WEB_STATION_ALIAS_MAX = 20;
 export const WEB_LAUNCH_MODES = APP_LAUNCH_MODES;
@@ -27,7 +24,12 @@ export function resolvedWebLaunch(contract) {
     }
     return resolveAppLaunch(readWebIntegration(contract)?.launch, true);
 }
-export const WEB_ACCESS_MODES = ["dsm-users", "dsm-admins", "dsm-groups", "public"];
+export const WEB_ACCESS_MODES = [
+    "dsm-users",
+    "dsm-admins",
+    "dsm-groups",
+    "public",
+];
 export const DEFAULT_WEB_ACCESS_MODE = "dsm-users";
 /** Local or qualified directory group names (exact case and domain); also what the gateway accepts at startup. */
 export const DSM_GROUP_NAME = /^(?:[A-Za-z0-9._-]{1,64}|[A-Za-z0-9._-]{1,64}\\[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?|[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?@[A-Za-z0-9._-]{1,64})$(?![\s\S])/;
@@ -48,7 +50,9 @@ export function resolvedWebAccess(contract) {
     if (!isWebAccessMode(mode)) {
         return undefined;
     }
-    const groups = Array.isArray(web?.groups) ? web.groups.filter((g) => typeof g === "string") : [];
+    const groups = Array.isArray(web?.groups)
+        ? web.groups.filter((g) => typeof g === "string")
+        : [];
     return { mode, groups };
 }
 /** True when the App's container is reached only through the DSM-authenticated gateway CGI. */
@@ -83,71 +87,3 @@ export function trustedAppEntryPath(contract) {
     }
     return `/${alias}${extra}`;
 }
-export const DSM_RESERVED_COOKIES = ["id", "did"];
-export function extractContractCookieNames(contract) {
-    const web = readWebIntegration(contract);
-    if (!web || !Array.isArray(web.cookies)) {
-        return [];
-    }
-    const reserved = new Set(DSM_RESERVED_COOKIES);
-    const result = [];
-    for (const item of web.cookies) {
-        if (typeof item === "string") {
-            const name = item.trim();
-            if (name && !reserved.has(name) && !result.includes(name)) {
-                result.push(name);
-            }
-        }
-    }
-    return result;
-}
-export function cookieStripHeaders(contract) {
-    const names = extractContractCookieNames(contract);
-    const value = names.length > 0
-        ? names.map((name) => `${name}=$cookie_${name}`).join("; ")
-        : "_synopkgland=";
-    return [{ name: "Cookie", value }];
-}
-export function webStationServiceName(alias) {
-    return `PROXY-${alias}`;
-}
-export function webStationServiceRoot(alias) {
-    return `web/synopkgland-${alias}`;
-}
-export function renderWebStationResource(contract) {
-    const alias = webStationAlias(String(contract.package));
-    const launch = resolvedWebLaunch(contract);
-    // DSM synowebapi crashes on type=reverse_proxy. Package acquire of reverse_proxy
-    const service = {
-        service: webStationServiceName(alias),
-        display_name: String(contract.displayname ?? contract.package),
-        type: "static",
-        support_alias: true,
-        support_server: false,
-        root: webStationServiceRoot(alias),
-    };
-    const portal = {
-        service: webStationServiceName(alias),
-        name: alias,
-        type: "alias",
-        alias,
-    };
-    if (launch === "dsm-window") {
-        portal.app = String(contract.package);
-    }
-    return `${JSON.stringify({ webservice: { services: [service], portals: [portal] } }, null, 2)}\n`;
-}
-export function renderDsmWindowConfig(contract, icons) {
-    const packageId = String(contract.package);
-    return `${JSON.stringify({
-        ".url": {
-            [packageId]: {
-                type: dsmLauncherType(resolvedWebLaunch(contract), false),
-                allUsers: true,
-                ...uiTitleFields(contractAppTitle(contract)),
-                icon: windowIconTemplate(icons),
-                url: trustedAppEntryPath(contract),
-            },
-        },
-    }, null, 2)}\n`;
-}

package/dist/ctl/cli.d.ts

@@ -0,0 +1,36 @@
+import { CtlStore, type Host } from './store.js';
+import { type JsonRequest } from './transport.js';
+import type { Descriptor } from './descriptor.js';
+export interface CtlIO {
+    store?: CtlStore;
+    out?: (line: string) => void;
+    isTTY?: boolean;
+    prompt?: (message: string, secret?: boolean) => Promise<string>;
+    requestFor?: (host: Host) => JsonRequest;
+}
+export declare function listView(host: string, apps: Descriptor[]): {
+    host: string;
+    package: {
+        id: string;
+        version: string;
+        displayName: string;
+    };
+    aliases: string[];
+    protocolVersion: 1;
+    developedBy: string;
+    provenance: string;
+    hash: string;
+    commands: {
+        parameters: string | Record<string, any>;
+        examples: string[];
+        summary: string;
+        cli: string[];
+        effect: "read" | "write" | "destructive";
+        permission: "public" | "authenticated" | "administrators";
+        paramsSchema?: Record<string, any>;
+        resultSchema?: Record<string, any>;
+        flow: import("./descriptor.js").Flow;
+        id: string;
+    }[];
+}[];
+export declare function runCtl(argv: string[], io?: CtlIO): Promise<void>;

package/dist/ctl/cli.js

@@ -0,0 +1,218 @@
+import { readBounded } from './json.js';
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+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 { canonicalOrigin, createRequest } from './transport.js';
+import { loginDsm, logoutDsm } from './dsm-auth.js';
+import { publicOperation } from './redaction.js';
+const USAGE = 'synopkgland ctl host add|list|show|login|logout|remove|revoke; ctl list [--host a,b|--all-hosts] [--app pkg] [--refresh]; ctl <alias|package> <command...> [typed flags|--input file|-] [--dry-run] [--yes]';
+async function prompt(message, secret = false) {
+    if (!process.stdin.isTTY)
+        throw new CtlError('CTL_INTERACTION_REQUIRED', 'Interactive input required.', 'Use --username and --password-stdin for host authentication.', 2);
+    process.stderr.write(message);
+    const muted = new Writable({ write(chunk, _encoding, done) { if (!secret)
+            process.stderr.write(chunk); done(); } });
+    const rl = createInterface({ input: process.stdin, output: muted, terminal: true });
+    try {
+        return await rl.question('');
+    }
+    finally {
+        rl.close();
+        if (secret)
+            process.stderr.write('\n');
+    }
+}
+function take(args, flag, value = false) {
+    const index = args.findIndex(a => a === flag || a.startsWith(flag + '='));
+    if (index < 0)
+        return undefined;
+    const token = args[index];
+    let answer = true;
+    let count = 1;
+    if (value) {
+        if (token.includes('='))
+            answer = token.slice(flag.length + 1);
+        else {
+            answer = args[index + 1];
+            count = 2;
+        }
+        if (typeof answer !== 'string' || !answer || answer.startsWith('--'))
+            throw new CtlError('CTL_ARGUMENT_INVALID', `Missing value for ${flag}.`, 'run: synopkgland ctl --help');
+    }
+    args.splice(index, count);
+    if (args.some(a => a === flag || a.startsWith(flag + '=')))
+        throw new CtlError('CTL_ARGUMENT_INVALID', `Duplicate option ${flag}.`, 'Use each option once.');
+    return answer;
+}
+function q(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
+function example(host, app, op) {
+    const base = `synopkgland ctl ${app.payload.aliases[0] ?? app.payload.package.id} ${op.cli.join(' ')} --host ${host}`;
+    return (op.examples?.length ? op.examples : [{}]).map(params => {
+        const simple = op.paramsSchema && Object.entries(params).every(([key, value]) => ['string', 'number', 'boolean'].includes(typeof value) && !RESERVED_FLAGS.has(flagName(key)) && op.paramsSchema?.properties?.[key]);
+        if (simple)
+            return base + Object.entries(params).map(([key, value]) => ' --' + flagName(key) + ' ' + q(String(value))).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, 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 async function runCtl(argv, io = {}) {
+    const args = [...argv], store = io.store ?? new CtlStore(), out = io.out ?? console.log, tty = io.isTTY ?? !!process.stdout.isTTY, ask = io.prompt ?? prompt;
+    let json = argv.includes('--json') || !tty;
+    const emit = (value) => out(json ? JSON.stringify(value) : JSON.stringify(value, null, 2));
+    try {
+        json = !!take(args, '--json') || !tty;
+        const hostOption = take(args, '--host', true), allHosts = !!take(args, '--all-hosts'), yes = !!take(args, '--yes'), dryRun = !!take(args, '--dry-run'), refresh = !!take(args, '--refresh'), appFilter = take(args, '--app', true), approve = !!take(args, '--approve-installed'), help = !!take(args, '--help');
+        if (!args.length || help && args.length === 0) {
+            emit({ ok: true, data: { usage: USAGE } });
+            return;
+        }
+        const client = (host) => new CtlClient(store, host, io.requestFor?.(host));
+        const discoverOptions = { refresh, app: appFilter, approve, confirm: tty ? async (packages) => /^y(es)?$/i.test(await ask('Allow DSM session to fixed description endpoints for ' + packages.map(p => p.id + '@' + p.version).join(', ') + '? [y/N] ')) : undefined };
+        if (args[0] === 'host') {
+            const action = args[1], name = args[2];
+            if (help || !action) {
+                emit({ ok: true, data: { usage: USAGE, actions: ['add', 'list', 'show', 'login', 'logout', 'remove', 'revoke'] } });
+                return;
+            }
+            if (action === 'list') {
+                const hosts = await boundedMap(store.list(), 4, async (host) => { const session = await store.credentials.get(store.key(host)); return { name: host.name, url: host.origin, username: host.username, authenticated: await client(host).valid(), lastUsed: host.lastUsed ?? null, rememberedDevice: !!session?.deviceId }; });
+                emit({ ok: true, data: hosts });
+                return;
+            }
+            if (!name)
+                throw new CtlError('CTL_ARGUMENT_INVALID', 'Host name is required.', 'run: synopkgland ctl host list');
+            if (action === 'add' || action === 'login') {
+                const remaining = args.slice(3);
+                const url = take(remaining, '--url', true), usernameOption = take(remaining, '--username', true), passwordStdin = !!take(remaining, '--password-stdin'), tunnel = !!take(remaining, '--ssh-tunnel'), noRemember = !!take(remaining, '--no-remember-device'), ca = take(remaining, '--ca', true);
+                if (remaining.length)
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Unknown host options.', 'run: synopkgland ctl host --help', 3, remaining);
+                if (action === 'add' && store.list().some(h => h.name === name))
+                    throw new CtlError('CTL_HOST_EXISTS', `Host ${name} already registered.`, `run: synopkgland ctl host login ${name}`);
+                if (action === 'login' && (url || usernameOption || tunnel || ca))
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Login uses the registered URL/account; add a separately named host to change them.', `run: synopkgland ctl host show ${name}`);
+                const old = action === 'login' ? store.get(name) : undefined;
+                if (action === 'add' && !url)
+                    throw new CtlError('CTL_URL_REQUIRED', '--url is required.', `run: synopkgland ctl host add ${name} --url https://${name}:5001`);
+                const host = old ?? { name, origin: canonicalOrigin(url, tunnel), username: usernameOption ?? await ask('DSM account: '), approved: {}, ...(tunnel ? { tunnel: true } : {}), ...(ca ? { ca } : {}) };
+                const previous = old ? await store.credentials.get(store.key(host)) : null;
+                const secret = passwordStdin ? readBounded(0, 4096).replace(/[\r\n]+$/, '') : await ask('DSM password: ', true);
+                const session = await loginDsm(host.origin, host.username, secret, { remember: !noRemember, deviceId: previous?.deviceId, otp: () => ask('DSM OTP: ', true), request: io.requestFor?.(host), ca: host.ca ? readFileSync(host.ca, 'utf8') : undefined });
+                try {
+                    if (old)
+                        await store.credentials.set(store.key(host), session);
+                    else
+                        await store.add(host, session);
+                }
+                catch (e) {
+                    await logoutDsm(session, io.requestFor?.(host) ?? createRequest(host.origin)).catch(() => { });
+                    throw e;
+                }
+                host.lastUsed = new Date().toISOString();
+                store.save(host);
+                emit({ ok: true, data: { name: host.name, url: host.origin, username: host.username, authenticated: true, rememberedDevice: !!session.deviceId } });
+                return;
+            }
+            const host = store.get(name);
+            if (action === 'show') {
+                emit({ ok: true, data: { ...host, authenticated: await client(host).valid() } });
+                return;
+            }
+            if (action === 'revoke') {
+                if (!args[3])
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Package ID is required.', `run: synopkgland ctl host show ${name}`);
+                emit({ ok: true, data: store.revoke(name, args[3]) });
+                return;
+            }
+            if (action === 'logout' || action === 'remove') {
+                if (action === 'remove' && !yes && (!tty || !/^y(es)?$/i.test(await ask(`Remove all local data for ${name}? [y/N] `))))
+                    throw new CtlError('CTL_CONFIRM_REQUIRED', 'Host removal requires --yes.', `run: synopkgland ctl host remove ${name} --yes`, 7);
+                const session = await store.credentials.get(store.key(host));
+                let loggedOut = false;
+                let logoutError;
+                if (session?.cookie) {
+                    try {
+                        await logoutDsm(session, io.requestFor?.(host) ?? createRequest(host.origin, 10000, host.ca ? readFileSync(host.ca, 'utf8') : undefined));
+                        loggedOut = true;
+                    }
+                    catch (error) {
+                        logoutError = errorData(error);
+                    }
+                }
+                if (action === 'remove') {
+                    emit({ ok: true, data: { ...await store.remove(name), loggedOut, ...(logoutError ? { logoutError } : {}) } });
+                    return;
+                }
+                if (logoutError)
+                    throw new CtlError('CTL_LOGOUT_FAILED', 'DSM logout was not confirmed; local session retained for retry.', `run: synopkgland ctl host logout ${name}`, 6);
+                if (session)
+                    await store.credentials.set(store.key(host), { ...session, cookie: '', token: '' });
+                emit({ ok: true, data: { name, loggedOut, registrationRetained: true } });
+                return;
+            }
+            throw new CtlError('CTL_COMMAND_UNKNOWN', `Unknown host action ${action}.`, 'run: synopkgland ctl host --help', 3, ['add', 'list', 'show', 'login', 'logout', 'remove', 'revoke']);
+        }
+        const names = selectHosts(store.list().map(h => h.name), hostOption, allHosts);
+        const inputAt = args.indexOf('--input');
+        let commonInput;
+        if (inputAt >= 0 && args[inputAt + 1] === '-') {
+            try {
+                commonInput = readBounded(0);
+            }
+            catch {
+                throw new CtlError('CTL_PARAMS_INVALID', 'Cannot read bounded UTF-8 stdin input.', 'Use a JSON input file of at most 1 MiB.');
+            }
+        }
+        const results = await boundedMap(names, 4, async (name) => {
+            try {
+                const host = store.get(name), ctl = client(host);
+                if (args[0] === 'list') {
+                    if (args.length !== 1)
+                        throw new CtlError('CTL_ARGUMENT_INVALID', 'Unexpected list arguments.', `run: synopkgland ctl list --host ${name}`);
+                    const result = await ctl.discover(discoverOptions);
+                    return { host: name, ok: true, data: { apps: listView(name, result.apps), diagnostics: result.diagnostics, cacheHits: result.cacheHits } };
+                }
+                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 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 };
+                }
+                const tail = args.slice(1);
+                const noWait = !!take(tail, '--no-wait'), wait = !!take(tail, '--wait'), timeout = take(tail, '--timeout', true);
+                if (noWait && wait)
+                    throw new CtlError('CTL_ARGUMENT_INVALID', 'Use --wait or --no-wait.', 'run: synopkgland ctl list --json');
+                if (timeout && (!/^\d+$/.test(timeout) || Number(timeout) < 1 || Number(timeout) > 3600))
+                    throw new CtlError('CTL_ARGUMENT_INVALID', '--timeout must be 1–3600 seconds.', 'Use --timeout 60.');
+                const firstFlag = tail.findIndex(token => token.startsWith('--'));
+                const path = firstFlag < 0 ? tail : tail.slice(0, firstFlag), params = firstFlag < 0 ? [] : tail.slice(firstFlag);
+                const data = await ctl.execute(args[0], path, params, { ...discoverOptions, yes, dryRun, stdin: commonInput, wait: !noWait, timeoutMs: timeout ? Number(timeout) * 1000 : undefined });
+                return { host: name, ok: true, data };
+            }
+            catch (error) {
+                return { host: name, ok: false, error: errorData(error), exitCode: ctlError(error).exitCode };
+            }
+        });
+        const failed = results.filter(r => !r.ok);
+        if (names.length === 1) {
+            const result = results[0];
+            emit(result.ok ? { ok: true, data: result.data } : { ok: false, error: result.error });
+            if (!result.ok)
+                process.exitCode = result.exitCode;
+        }
+        else {
+            emit({ ok: failed.length === 0, results: results.map(({ host, ok, ...rest }) => ({ host, ok, ...('data' in rest ? { data: rest.data } : { error: rest.error }) })) });
+            if (failed.length)
+                process.exitCode = 8;
+        }
+    }
+    catch (error) {
+        emit({ ok: false, error: errorData(error) });
+        process.exitCode = ctlError(error).exitCode;
+    }
+}

package/dist/ctl/descriptor.d.ts

@@ -0,0 +1,81 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+export declare const DESCRIPTION_METHOD = "synopkgland.describe";
+export declare const DESCRIPTION_FILE = "synopkgland-api.json";
+export type Operation = {
+    summary: string;
+    cli: string[];
+    effect: 'read' | 'write' | 'destructive';
+    permission: 'public' | 'authenticated' | 'administrators';
+    paramsSchema?: Record<string, any>;
+    resultSchema?: Record<string, any>;
+    examples?: Record<string, unknown>[];
+    flow: Flow;
+};
+export type Flow = {
+    type: 'invoke';
+    method: string;
+} | {
+    type: 'job';
+    start: string;
+    poll: string;
+    result?: string;
+    jobId: string;
+    idParam: string;
+    state: string;
+    done: string[];
+    failed: string[];
+    intervalMs: number;
+    timeoutMs: number;
+} | {
+    type: 'paginate';
+    method: string;
+    items: string;
+    offsetParam: string;
+    limitParam: string;
+    pageSize: number;
+    maxPages: number;
+} | {
+    type: 'ndjson';
+    method: string;
+} | {
+    type: 'upload';
+    method: string;
+    fileParam: string;
+    parentParam: string;
+    nameParam: string;
+};
+export interface Binding {
+    effect: 'read' | 'write' | 'destructive';
+    permission: 'public' | 'authenticated' | 'administrators';
+}
+export interface ApiPayload {
+    package: {
+        id: string;
+        version: string;
+        displayName: string;
+    };
+    aliases: string[];
+    provenance: {
+        developedBy: string;
+        generator: string;
+    };
+    entry: string;
+    transport: {
+        path: string;
+        auth: string;
+    };
+    commands: Record<string, Operation>;
+    bindings: Record<string, Binding>;
+}
+export interface Descriptor {
+    format: 'synopkgland.api';
+    version: 1;
+    payload: ApiPayload;
+    sha256: string;
+}
+export declare const ajv: Ajv2020.Ajv2020;
+export declare function makeDescriptor(payload: ApiPayload | any): Descriptor;
+export declare function validateDescriptor(value: any, id: string, version: string): Descriptor;
+export declare function safeSchema(schema: unknown, depth?: number): void;
+export declare function flowMethods(flow: Flow): string[];
+export declare function validateFlow(op: Operation, bindings: Record<string, Binding>): void;