@synopackageland/cli 0.32.0 → 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/init-upstream.js

@@ -3,16 +3,16 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { API_PERMISSIONS_FILE } from './standalone/api-permissions.js';
-import { safeMetadataUrl } from './package-metadata.js';
+import { safeMetadataUrl, upstreamMetadata } from './package-metadata.js';
 import { parseImageReference } from './images/pin.js';
 export function validateForkRecipe(template, options) {
-    if (options.upstream && !safeMetadataUrl(options.upstream))
-        throw new Error('[INIT_UPSTREAM_INVALID] Supply an http(s) upstream repository URL without credentials.');
+    if (options.upstream && (!safeMetadataUrl(options.upstream) || !options.upstream.startsWith("https:")))
+        throw new Error('[INIT_UPSTREAM_INVALID] Supply an HTTPS upstream repository URL without credentials.');
     if (options.publisherUrl && !safeMetadataUrl(options.publisherUrl))
         throw new Error('[INIT_PUBLISHER_INVALID] Supply an http(s) publisher URL without credentials.');
     for (const value of [options.publisher, options.upstreamMaintainer]) {
-        if (value !== undefined && (!value.trim() || /[\x00-\x1f\x7f"\\]/.test(value) || value.length > 200))
-            throw new Error('[INIT_PUBLISHER_INVALID] Attribution names must be plain, non-empty single-line text.');
+        if (value !== undefined && (!value.trim() || /[\x00-\x1f\x7f"\\]/.test(value) || value.length > 80))
+            throw new Error('[INIT_PUBLISHER_INVALID] Attribution names must be plain, non-empty single-line text of at most 80 characters.');
     }
     if (template === 'native-go' && options.upstreamImage)
         throw new Error('[INIT_OPTIONS_UNSUPPORTED] Native forks stage official release binaries or use a source build hook; image options apply only to compose.');
@@ -40,7 +40,7 @@ export function writeForkScaffold(packaging, template, options) {
     doc.set('maintainer', options.upstreamMaintainer ?? 'TODO: original upstream project or owner');
     doc.setIn(['metadata', 'distributor'], options.publisher ?? 'TODO: your publisher name');
     if (options.upstream) {
-        doc.setIn(['metadata', 'upstream'], options.upstream);
+        doc.setIn(['metadata', 'upstream'], upstreamMetadata(options.upstream));
         doc.setIn(['metadata', 'maintainer_url'], options.upstream);
     }
     if (options.publisherUrl)

package/dist/package-metadata.d.ts

@@ -1,5 +1,12 @@
 /** Plain text, or a map from a BCP-47 tag (en, zh-TW, ...) to plain text. */
 export type LocalizedText = string | Record<string, string>;
+export interface UpstreamMetadata {
+    name: string;
+    url: string;
+    license?: string;
+}
+/** Normalize the URL shorthand to the catalog's existing structured contract. */
+export declare function upstreamMetadata(raw: unknown): UpstreamMetadata;
 export interface PackageMetadata {
     long_description?: LocalizedText;
     changelog?: LocalizedText;
@@ -7,7 +14,7 @@ export interface PackageMetadata {
     support_email?: string;
     homepage?: string;
     source_url?: string;
-    upstream?: string;
+    upstream?: UpstreamMetadata;
     issues_url?: string;
     license?: string;
     maintainer_url?: string;

package/dist/package-metadata.js

@@ -1,3 +1,26 @@
+/** Normalize the URL shorthand to the catalog's existing structured contract. */
+export function upstreamMetadata(raw) {
+    const value = typeof raw === "string" ? { name: upstreamName(raw), url: raw } : raw;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid upstream");
+    const v = value;
+    const text = (t) => typeof t === "string" && !!t.trim() && t.length <= 80 && !/[\x00-\x1f\x7f]/.test(t);
+    if (Object.keys(v).some(k => !["name", "url", "license"].includes(k)) ||
+        !text(v.name) || !safeMetadataUrl(v.url) || !v.url.startsWith("https:") ||
+        (v.license !== undefined && !text(v.license)))
+        throw new Error("invalid upstream");
+    return value;
+}
+function upstreamName(url) {
+    try {
+        const u = new URL(url);
+        const name = decodeURIComponent(u.pathname.split("/").filter(Boolean).at(-1) ?? u.hostname).replace(/\.git$/, "");
+        return name.trim() && name.length <= 80 && !/[\x00-\x1f\x7f]/.test(name) ? name : "TODO: original upstream project";
+    }
+    catch {
+        return "TODO: original upstream project";
+    }
+}
 export function safeMetadataUrl(value, mail = false) {
     if (typeof value !== "string" || value.length > 2048)
         return false;
@@ -40,6 +63,10 @@ export function validateMetadata(raw) {
     for (const [k, v] of Object.entries(raw)) {
         if (!allowed.includes(k))
             throw new Error("unknown metadata");
+        if (k === "upstream") {
+            upstreamMetadata(v);
+            continue;
+        }
         if (k === "screenshots") {
             if (!Array.isArray(v) ||
                 v.length > MAX_SCREENSHOTS ||
@@ -79,7 +106,7 @@ export function validateMetadata(raw) {
     }
     if (JSON.stringify(raw).length > 32000)
         throw new Error("metadata too large");
-    return raw;
+    return { ...raw, ...("upstream" in raw ? { upstream: upstreamMetadata(raw.upstream) } : {}) };
 }
 export function metadataInfoFields(metadata) {
     if (!metadata)

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/dist/upstream-attribution.js

@@ -11,7 +11,7 @@ export function upstreamRepository(root, explicit) {
     if (!raw)
         return undefined;
     const url = raw.replace(/^git@github\.com:/, 'https://github.com/').replace(/\.git$/, '');
-    return safeMetadataUrl(url) ? url : undefined;
+    return safeMetadataUrl(url) && url.startsWith("https:") ? url : undefined;
 }
 /** Best effort, bounded and public: offline/rate-limited lookups retain an explicit TODO. */
 export async function upstreamMaintainer(url, fetcher = fetch) {
@@ -28,7 +28,7 @@ export async function upstreamMaintainer(url, fetcher = fetch) {
             return undefined;
         const owner = await response.json();
         const name = typeof owner.name === 'string' && owner.name.trim() ? owner.name.trim() : owner.login;
-        return typeof name === 'string' && name.length <= 200 && !/[\x00-\x1f\x7f"\\]/.test(name) ? name : undefined;
+        return typeof name === 'string' && name.length <= 80 && !/[\x00-\x1f\x7f"\\]/.test(name) ? name : undefined;
     }
     catch {
         return undefined;
@@ -45,7 +45,8 @@ export function upstreamAttributionWarnings(root) {
     const todo = (v) => typeof v !== 'string' || !v.trim() || /^TODO\b/i.test(v.trim());
     if (!todo(raw.maintainer) && !todo(m.distributor) &&
         raw.maintainer.trim().toLowerCase() !== m.distributor.trim().toLowerCase() &&
-        !todo(m.maintainer_url) && !todo(m.distributor_url))
+        !todo(m.maintainer_url) && !todo(m.distributor_url) &&
+        !(typeof m.upstream === "object" && m.upstream && todo(m.upstream.name)))
         return [];
     return [{
             code: 'UPSTREAM_ATTRIBUTION', severity: 'warning',