@synopackageland/cli 0.32.0 → 0.32.1

package/CHANGELOG.md

@@ -1,8 +1,9 @@
 # Changelog
 
-## 0.32.0 (2026-10-27)
+## 0.32.1 (2026-10-27)
 
 - Attribute upstream Apps to their original project/team or owner and the packaging publisher as distributor, with generic skill guidance and a release checklist
 - Prefill upstream-fork attribution from the upstream repository and publisher options or environment configuration; use a bounded public GitHub owner lookup and explicit TODOs offline
 - Warn when upstream attribution is incomplete or the maintainer equals the distributor; warnings appear in check JSON and keep exit status successful
 - Keep templates 0.31.x and its SDK defaults; CLI minor releases can ship independently of templates
+- Write upstream provenance as the catalog-compatible `{name, url, license?}` object; normalize HTTPS URL shorthand when building SPKs

package/README.md

@@ -74,7 +74,7 @@ CLI-only releases can differ from the SDK patch. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.32.0 depends on `~0.31.0`: npm installation or
+`@synopackageland/templates`. CLI 0.32.1 depends on `~0.31.0`: npm installation or
 update can select the latest templates patch in the 0.31 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;

package/dist/cli.js

@@ -473,7 +473,7 @@ export async function runCli(argv) {
         const targetDir = resolve(dir);
         const upstream = options.upstreamFork ? upstreamRepository(targetDir, options.upstream) : undefined;
         if (options.upstream && !upstream)
-            throw failure("INIT_UPSTREAM_INVALID", "Supply an http(s) repository URL without credentials");
+            throw failure("INIT_UPSTREAM_INVALID", "Supply an HTTPS repository URL without credentials");
         if (!options.upstreamFork && (options.upstream || options.upstreamMaintainer || options.publisher || options.publisherUrl))
             throw failure("INIT_OPTIONS_UNSUPPORTED", "Attribution options require --upstream-fork");
         initFromTemplate(options.template, targetDir, {

package/dist/error-registry.js

@@ -1,7 +1,7 @@
 import { COMPOSE_ERRORS } from "./standalone/compose-errors.js";
 export const ERROR_REGISTRY = {
     ...COMPOSE_ERRORS,
-    INIT_UPSTREAM_INVALID: { code: "INIT_UPSTREAM_INVALID", description: "The upstream repository URL is invalid.", suggestion: "Supply --upstream with an http(s) repository URL without credentials." },
+    INIT_UPSTREAM_INVALID: { code: "INIT_UPSTREAM_INVALID", description: "The upstream repository URL is invalid.", suggestion: "Supply --upstream with an HTTPS repository URL without credentials." },
     INIT_PUBLISHER_INVALID: { code: "INIT_PUBLISHER_INVALID", description: "The attribution name or publisher URL is invalid.", suggestion: "Use plain single-line project/publisher names and an http(s) publisher URL without credentials." },
     UPSTREAM_ATTRIBUTION: { code: "UPSTREAM_ATTRIBUTION", description: "Upstream App attribution is incomplete or names the distributor as maintainer.", suggestion: "Name the original project/team or owner as maintainer; set metadata.maintainer_url to the upstream repository and metadata.distributor/distributor_url to your publisher; resolve TODOs before release." },
     INSTALL_SETTINGS_INVALID: { "code": "INSTALL_SETTINGS_INVALID", "description": "The installation setting declaration is invalid.", "suggestion": "Declare 1–32 lowercase identifier keys in install.settings, each with type https-origin, a plain label and an explicit boolean required; omit defaults and values." },

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/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',

package/package.json

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

package/schema/package-metadata.schema.json

@@ -98,9 +98,38 @@
       }
     },
     "upstream": {
-      "type": "string",
-      "maxLength": 2048,
-      "pattern": "^https?://"
+      "oneOf": [
+        {
+          "type": "string",
+          "maxLength": 2048,
+          "pattern": "^https://"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "name",
+            "url"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            },
+            "url": {
+              "type": "string",
+              "maxLength": 2048,
+              "pattern": "^https://"
+            },
+            "license": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80
+            }
+          }
+        }
+      ]
     }
   }
 }

package/schema/synology-app.schema.json

@@ -189,9 +189,38 @@
       "additionalProperties": false,
       "properties": {
         "upstream": {
-          "type": "string",
-          "maxLength": 2048,
-          "pattern": "^https?://"
+          "oneOf": [
+            {
+              "type": "string",
+              "maxLength": 2048,
+              "pattern": "^https://"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "name",
+                "url"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 80
+                },
+                "url": {
+                  "type": "string",
+                  "maxLength": 2048,
+                  "pattern": "^https://"
+                },
+                "license": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 80
+                }
+              }
+            }
+          ]
         },
         "changelog": {
           "oneOf": [

package/skills/SKILL.md

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

package/skills/reference/compose.md

@@ -247,7 +247,7 @@ declared availability readiness, LAN isolation/egress, protected grant lifecycle
 ACLs, two-user visibility and clean install/upgrade/reboot/stop/uninstall before
 calling the package supported on a NAS. No NAS is accessed by the build gate.
 
-The unified Compose contract uses SDK defaults from locally installed templates `~0.31.0` with CLI 0.32.0. Templates patches can ship independently; npm install/update resolves them, and SDK defaults come from the installed templates. SDK minor upgrades do not require a CLI release when they declare supported executor manifest format 1; the resolved SDK owns the release mapping and verified payload digests. The CLI does not fetch templates at runtime. The legacy packaging route and bridge publish mode are removed.
+The unified Compose contract uses SDK defaults from locally installed templates `~0.31.0` with CLI 0.32.1. Templates patches can ship independently; npm install/update resolves them, and SDK defaults come from the installed templates. SDK minor upgrades do not require a CLI release when they declare supported executor manifest format 1; the resolved SDK owns the release mapping and verified payload digests. The CLI does not fetch templates at runtime. The legacy packaging route and bridge publish mode are removed.
 
 Primary override files, and each included override set, must share a directory. Cross-directory override bases are rejected before loader I/O. Included implicit .env files are confined, inventoried and preserved; symlinks are rejected.
 

package/skills/reference/upstream-fork.md

@@ -27,7 +27,8 @@ Pass `--upstream <repo-url>` (or retain the `upstream` Git remote), your verifie
 GitHub owner profile with a bounded lookup, using its display name then login.
 Offline or unsupported hosts leave an explicit maintainer TODO. Missing publisher
 configuration leaves a distributor TODO. Resolve these manually before release.
-`metadata.upstream` records the repository; `check` warns, without failing, for
+`metadata.upstream: {name, url}` records the original project name and HTTPS repository;
+URL shorthand is normalized to that object in SPK metadata; `check` warns, without failing, for
 missing attribution or a maintainer that equals the distributor. The fork layout
 also enables this warning without `metadata.upstream`.