@verentis/cli 0.2.3 → 0.2.5

package/dist/index.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { mkdir, stat, writeFile, readFile, readdir, mkdtemp, rm, glob } from 'fs/promises';
+import { mkdir, stat, writeFile, readFile, readdir, realpath, mkdtemp, rm, glob } from 'fs/promises';
 import { tmpdir, homedir } from 'os';
-import { resolve, basename, dirname, posix, join, sep, relative } from 'path';
-import { spawn } from 'child_process';
+import { resolve, basename, dirname, posix, join, isAbsolute, extname, relative, sep } from 'path';
+import { spawn, spawnSync } from 'child_process';
 import { generateKeyPairSync, createHash, randomUUID, randomBytes, createCipheriv, createPublicKey, verify, diffieHellman, hkdfSync, sign, createPrivateKey } from 'crypto';
-import { parse } from 'yaml';
-import { createWriteStream, createReadStream } from 'fs';
+import { parse, stringify } from 'yaml';
+import { createWriteStream, readFileSync, createReadStream } from 'fs';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
 import * as tar from 'tar';
+import { fileURLToPath } from 'url';
 
 var configDir = () => process.env.VERENTIS_CONFIG_DIR ?? join(homedir(), ".verentis");
 var configPath = () => join(configDir(), "config.json");
@@ -129,7 +130,7 @@ async function refreshIdentityToken(apiUrl, refreshToken) {
     `Session could not be renewed${payload?.error ? ` (${payload.error})` : ` (${res.status})`}. Run \`verentis login\` again.`
   );
 }
-var sleep = (ms) => new Promise((resolve8) => setTimeout(resolve8, ms));
+var sleep = (ms) => new Promise((resolve11) => setTimeout(resolve11, ms));
 
 // src/http.ts
 var ApiError = class extends Error {
@@ -192,8 +193,8 @@ async function createApiClient(overrides) {
   }
   async function credentialFor(scopes, workspaceId) {
     const cacheKey = `${workspaceId ?? ""}:${[...scopes].sort().join(" ")}`;
-    const cached = tokenCache.get(cacheKey);
-    if (cached && !isExpired(cached)) return cached;
+    const cached2 = tokenCache.get(cacheKey);
+    if (cached2 && !isExpired(cached2)) return cached2;
     const token = await mintAccessToken({ scopes, workspaceId });
     tokenCache.set(cacheKey, token);
     return token;
@@ -297,7 +298,6 @@ ${truncate(text)}`;
 }
 var SCOPES = {
   publisherRead: "marketplace.publisher.read",
-  publisherCreate: "marketplace.publisher.create",
   publisherUpdate: "marketplace.publisher.update",
   packageRead: "marketplace.package.read",
   packageReadAll: "marketplace.package.read-all",
@@ -366,6 +366,8 @@ var MARKETPLACE = {
   packageRead: "marketplace.package.read",
   packageUpdate: "marketplace.package.update",
   packageVisibilityManage: "marketplace.package.visibility.manage",
+  publisherCreate: "marketplace.publisher.create",
+  publisherUpdate: "marketplace.publisher.update",
   statsRead: "marketplace.stats.read"};
 var ENGINE_DEFAULT_PERMISSIONS = [
   NODE.fileRead,
@@ -454,6 +456,10 @@ var execution = {
   syncEngines: e({ method: "POST", path: "/v1/engines/sync", scopes: [EXECUTION.run], workspaceBound: true })
 };
 var marketplace = {
+  createPublisher: e({ method: "POST", path: "/v1/publishers", scopes: [MARKETPLACE.publisherCreate] }),
+  updatePublisher: e({ method: "PUT", path: "/v1/publishers/{id}", scopes: [MARKETPLACE.publisherUpdate] }),
+  setPublisherLogo: e({ method: "PUT", path: "/v1/publishers/{id}/logo", scopes: [MARKETPLACE.publisherUpdate] }),
+  removePublisherLogo: e({ method: "DELETE", path: "/v1/publishers/{id}/logo", scopes: [MARKETPLACE.publisherUpdate] }),
   getPackage: e({ method: "GET", path: "/v1/packages/{id}", scopes: [MARKETPLACE.packageRead] }),
   updatePackage: e({ method: "PUT", path: "/v1/packages/{id}", scopes: [MARKETPLACE.packageUpdate] }),
   archivePackage: e({ method: "DELETE", path: "/v1/packages/{id}", scopes: [MARKETPLACE.packageDelete] }),
@@ -844,6 +850,122 @@ function contextEnv(context, contextPath) {
     VERENTIS_TIMEOUT: String(context.execution.timeout)
   };
 }
+var KIND_MAP = {
+  application: "Application",
+  executionengine: "ExecutionEngine",
+  bundle: "Bundle"
+};
+function normalizeKind(kind) {
+  const mapped = KIND_MAP[kind.replace(/[^a-z]/gi, "").toLowerCase()];
+  if (!mapped) throw new Error(`Unsupported manifest kind '${kind}' \u2014 expected Application, ExecutionEngine or Bundle.`);
+  return mapped;
+}
+function validateLaunchManifestKind(kind, spec) {
+  if (kind === "Application" || !spec || typeof spec !== "object" || Array.isArray(spec)) return void 0;
+  if (!Object.prototype.hasOwnProperty.call(spec, "launch")) return void 0;
+  return "spec.launch is only supported for Application manifests";
+}
+async function loadManifest(path) {
+  const text = await readFile(path, "utf8");
+  const manifest = parse(text);
+  if (!manifest || typeof manifest !== "object") throw new Error(`Failed to parse manifest at ${path}.`);
+  if (!manifest.kind) throw new Error(`Manifest at ${path} is missing 'kind'.`);
+  if (!manifest.metadata?.name) throw new Error(`Manifest at ${path} is missing 'metadata.name'.`);
+  if (!manifest.metadata?.version) throw new Error(`Manifest at ${path} is missing 'metadata.version'.`);
+  const kind = normalizeKind(manifest.kind);
+  const launchKindError = validateLaunchManifestKind(kind, manifest.spec);
+  if (launchKindError) throw new Error(`Invalid manifest at ${path}: ${launchKindError}.`);
+  const marketplaceErrors = validateMarketplaceSection(manifest.marketplace);
+  if (marketplaceErrors.length > 0) {
+    throw new Error(`Invalid marketplace section in ${path}: ${marketplaceErrors.join(" ")}`);
+  }
+  return manifest;
+}
+function validateMarketplaceSection(marketplace2) {
+  if (marketplace2 === void 0) return [];
+  if (!marketplace2 || typeof marketplace2 !== "object" || Array.isArray(marketplace2)) {
+    return ["marketplace must be an object."];
+  }
+  const section = marketplace2;
+  const errors = [];
+  for (const field of ["logo", "readme", "changelog"]) {
+    const value = section[field];
+    if (value !== void 0 && (typeof value !== "string" || value.trim().length === 0)) {
+      errors.push(`marketplace.${field} must be a non-empty relative path.`);
+    }
+  }
+  if (section.hero !== void 0) {
+    if (!section.hero || typeof section.hero !== "object" || Array.isArray(section.hero)) {
+      errors.push("marketplace.hero must be an object.");
+    } else {
+      const hero = section.hero;
+      if (typeof hero.source !== "string" || hero.source.trim().length === 0) {
+        errors.push("marketplace.hero.source must be a non-empty relative path.");
+      }
+      if (typeof hero.alt !== "string" || hero.alt.trim().length === 0) {
+        errors.push("marketplace.hero.alt is required and must not be empty.");
+      }
+    }
+  }
+  if (section.images !== void 0) {
+    if (!Array.isArray(section.images)) {
+      errors.push("marketplace.images must be a list.");
+    } else {
+      if (section.images.length > 8) errors.push("marketplace.images may contain at most 8 images.");
+      section.images.forEach((value, index) => {
+        const at = `marketplace.images[${index}]`;
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          errors.push(`${at} must be an object.`);
+          return;
+        }
+        const image = value;
+        if (typeof image.source !== "string" || image.source.trim().length === 0) {
+          errors.push(`${at}.source must be a non-empty relative path.`);
+        }
+        if (typeof image.alt !== "string" || image.alt.trim().length === 0) {
+          errors.push(`${at}.alt is required and must not be empty.`);
+        }
+        if (image.caption !== void 0 && typeof image.caption !== "string") {
+          errors.push(`${at}.caption must be a string when provided.`);
+        }
+      });
+    }
+  }
+  if (section.assets !== void 0) {
+    if (!Array.isArray(section.assets)) {
+      errors.push("marketplace.assets must be a list of relative glob strings.");
+    } else {
+      section.assets.forEach((value, index) => {
+        if (typeof value !== "string" || value.trim().length === 0) {
+          errors.push(`marketplace.assets[${index}] must be a non-empty relative glob string.`);
+        }
+      });
+    }
+  }
+  return errors;
+}
+async function findManifest(dir) {
+  const explicit = join(dir, "manifest.yaml");
+  try {
+    if ((await stat(explicit)).isFile()) return explicit;
+  } catch {
+  }
+  const entries = await readdir(dir);
+  const candidates = entries.filter((name) => /\.(app|engine|bundle)\.ya?ml$/.test(name));
+  if (candidates.length === 1) return join(dir, candidates[0]);
+  if (candidates.length === 0) {
+    throw new Error(`No manifest found in ${dir}. Expected manifest.yaml or *.app.yaml / *.engine.yaml / *.bundle.yaml.`);
+  }
+  throw new Error(`Multiple manifests found in ${dir} (${candidates.join(", ")}). Pass --manifest to disambiguate.`);
+}
+var NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function validatePackageName(name, label) {
+  if (!NAME_PATTERN.test(name)) {
+    throw new Error(`Invalid ${label} '${name}' \u2014 use lowercase letters, digits and hyphens (no leading/trailing hyphen).`);
+  }
+}
+
+// src/dev/manifest.ts
 async function readManifestDocument(path) {
   const text = await readFile(path, "utf8");
   const doc = parse(text);
@@ -873,6 +995,8 @@ function validateManifest(manifest) {
     if (!meta[field]) error(`metadata.${field} is required`);
   }
   const spec = manifest.spec ?? {};
+  const launchKindError = validateLaunchManifestKind(kind, spec);
+  if (launchKindError) error(launchKindError);
   if (kind === "ExecutionEngine") {
     const runtimes = spec.runtimes ?? {};
     if (Object.keys(runtimes).length === 0) {
@@ -901,12 +1025,62 @@ function validateManifest(manifest) {
         "an Application must declare at least one contribution: spec.entry / spec.entry-points[] (iframe UI), spec.install[] (installed files), or spec.scopes[] (identity)"
       );
     }
+    validateApplicationLaunch(spec, issues);
   }
   validateInstallDirectives(spec.install, issues);
+  for (const message of validateMarketplaceSection(manifest.marketplace)) error(message);
   const packaging = manifest.packaging ?? {};
   if (!packaging.publisher) warning("packaging.publisher is not set \u2014 `verentis pack`/`publish` will refuse the package");
   return issues;
 }
+function validateApplicationLaunch(spec, issues) {
+  const launch = spec.launch;
+  if (launch === void 0) return;
+  const error = (message) => issues.push({ level: "error", message });
+  if (!launch || typeof launch !== "object" || Array.isArray(launch)) {
+    error("spec.launch must be an object");
+    return;
+  }
+  if (launch.pinnable === true && launch.enabled !== true) {
+    error("spec.launch.pinnable requires spec.launch.enabled");
+  }
+  if (launch.enabled !== true) return;
+  const launchEntryPoint = launch["entry-point"];
+  if (launchEntryPoint !== void 0 && (typeof launchEntryPoint !== "string" || !launchEntryPoint.trim())) {
+    error("spec.launch.entry-point must be a non-empty entry-point id");
+    return;
+  }
+  if (typeof launchEntryPoint === "string") {
+    const entryPoint = spec["entry-points"]?.find((candidate) => candidate.id === launchEntryPoint);
+    if (!entryPoint) {
+      error(`spec.launch.entry-point '${launchEntryPoint}' does not match spec.entry-points[].id`);
+      return;
+    }
+    if (!resolvesIframeEntry(spec.entry, entryPoint.entry ?? entryPoint.route)) {
+      error("spec.launch.enabled requires the selected entry point to resolve an iframe entry");
+    }
+    return;
+  }
+  if (!isAbsoluteHttpUrl(spec.entry)) {
+    error("spec.launch.enabled requires spec.entry or spec.launch.entry-point");
+  }
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function resolvesIframeEntry(baseEntry, routeOrEntry) {
+  if (isAbsoluteHttpUrl(routeOrEntry)) return true;
+  return isAbsoluteHttpUrl(baseEntry);
+}
+function isAbsoluteHttpUrl(value) {
+  if (!isNonEmptyString(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 function validateInstallDirectives(install, issues) {
   if (install === void 0) return;
   const error = (message) => issues.push({ level: "error", message });
@@ -936,46 +1110,6 @@ function validateInstallDirectives(install, issues) {
     }
   });
 }
-var KIND_MAP = {
-  application: "Application",
-  executionengine: "ExecutionEngine",
-  bundle: "Bundle"
-};
-function normalizeKind(kind) {
-  const mapped = KIND_MAP[kind.replace(/[^a-z]/gi, "").toLowerCase()];
-  if (!mapped) throw new Error(`Unsupported manifest kind '${kind}' \u2014 expected Application, ExecutionEngine or Bundle.`);
-  return mapped;
-}
-async function loadManifest(path) {
-  const text = await readFile(path, "utf8");
-  const manifest = parse(text);
-  if (!manifest || typeof manifest !== "object") throw new Error(`Failed to parse manifest at ${path}.`);
-  if (!manifest.kind) throw new Error(`Manifest at ${path} is missing 'kind'.`);
-  if (!manifest.metadata?.name) throw new Error(`Manifest at ${path} is missing 'metadata.name'.`);
-  if (!manifest.metadata?.version) throw new Error(`Manifest at ${path} is missing 'metadata.version'.`);
-  normalizeKind(manifest.kind);
-  return manifest;
-}
-async function findManifest(dir) {
-  const explicit = join(dir, "manifest.yaml");
-  try {
-    if ((await stat(explicit)).isFile()) return explicit;
-  } catch {
-  }
-  const entries = await readdir(dir);
-  const candidates = entries.filter((name) => /\.(app|engine|bundle)\.ya?ml$/.test(name));
-  if (candidates.length === 1) return join(dir, candidates[0]);
-  if (candidates.length === 0) {
-    throw new Error(`No manifest found in ${dir}. Expected manifest.yaml or *.app.yaml / *.engine.yaml / *.bundle.yaml.`);
-  }
-  throw new Error(`Multiple manifests found in ${dir} (${candidates.join(", ")}). Pass --manifest to disambiguate.`);
-}
-var NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
-function validatePackageName(name, label) {
-  if (!NAME_PATTERN.test(name)) {
-    throw new Error(`Invalid ${label} '${name}' \u2014 use lowercase letters, digits and hyphens (no leading/trailing hyphen).`);
-  }
-}
 
 // src/commands/dev.ts
 async function resolveDevScopes(flags) {
@@ -1325,7 +1459,7 @@ async function followExecution(api, workspaceId, executionId, json) {
       if (exec.status !== "Completed") process.exitCode = 1;
       return;
     }
-    await new Promise((resolve8) => setTimeout(resolve8, 1e3));
+    await new Promise((resolve11) => setTimeout(resolve11, 1e3));
   }
   console.error("Timed out waiting for a terminal status \u2014 check `verentis exec get`.");
   process.exitCode = 1;
@@ -1478,10 +1612,31 @@ metadata:
   version: 0.1.0
   author: ""
 
+# Marketplace presentation (optional):
+# marketplace:
+#   logo: ./marketplace/logo.png
+#   hero:
+#     source: ./marketplace/hero.webp
+#     alt: A concise description of the hero background
+#   images:
+#     - source: ./marketplace/screenshot.png
+#       alt: A concise description of the screenshot
+#       caption: Optional visible caption
+#   readme: ./README.md
+#   changelog: ./CHANGELOG.md
+#   assets:
+#     - "marketplace/**/*.{png,jpg,jpeg,webp,svg}"
+
 spec:
   entry: https://example.com   # hosted app origin
   scope: global
 
+  # Opt into a standalone workspace surface. Contextual file handlers should omit this block.
+  # launch:
+  #   enabled: true
+  #   entry-point: home        # optional; otherwise spec.entry is used
+  #   pinnable: true
+
   entry-points: []
   capabilities: []
   permissions: []
@@ -1508,6 +1663,20 @@ metadata:
   version: 0.1.0
   author: ""
 
+# Marketplace presentation (optional):
+# marketplace:
+#   logo: ./marketplace/logo.png
+#   hero:
+#     source: ./marketplace/hero.webp
+#     alt: A concise description of the hero background
+#   images:
+#     - source: ./marketplace/screenshot.png
+#       alt: A concise description of the screenshot
+#   readme: ./README.md
+#   changelog: ./CHANGELOG.md
+#   assets:
+#     - "marketplace/**/*.{png,jpg,jpeg,webp,svg}"
+
 spec:
   runtimes: {}
   file-types: []
@@ -1529,6 +1698,20 @@ metadata:
   version: 0.1.0
   author: ""
 
+# Marketplace presentation (optional):
+# marketplace:
+#   logo: ./marketplace/logo.png
+#   hero:
+#     source: ./marketplace/hero.webp
+#     alt: A concise description of the hero background
+#   images:
+#     - source: ./marketplace/screenshot.png
+#       alt: A concise description of the screenshot
+#   readme: ./README.md
+#   changelog: ./CHANGELOG.md
+#   assets:
+#     - "marketplace/**/*.{png,jpg,jpeg,webp,svg}"
+
 packaging:
   publisher: ""                # your publisher name
   files:
@@ -1908,20 +2091,260 @@ function rawX25519Private(key) {
 function publicKeyFromRaw(raw) {
   return createPublicKey({ key: { kty: "OKP", crv: "X25519", x: raw.toString("base64url") }, format: "jwk" });
 }
+var MIB = 1024 * 1024;
+var MAX_LOGO_BYTES = MIB;
+var MAX_IMAGE_BYTES = 5 * MIB;
+var MAX_TOTAL_IMAGE_BYTES = 25 * MIB;
+var MAX_MARKDOWN_BYTES = MIB;
+async function buildCatalog(projectDir, marketplace2) {
+  const root = await realpath(projectDir);
+  const entries = /* @__PURE__ */ new Map();
+  const imageDigests = /* @__PURE__ */ new Map();
+  const index = { schemaVersion: 1 };
+  const addImage = async (source, label, maxBytes) => {
+    const file = await resolveDirectFile(root, source, label);
+    if (file.bytes.length > maxBytes) {
+      throw new Error(`${label} exceeds the ${formatMiB(maxBytes)} MiB limit (${file.bytes.length} bytes).`);
+    }
+    const image = validateImage(file.bytes, file.path, label);
+    const reference = addContentAddressedEntry(file, image, "assets", entries);
+    imageDigests.set(reference.sha256, reference.size);
+    return reference;
+  };
+  const addMarkdown = async (source, label) => {
+    const file = await resolveDirectFile(root, source, label);
+    if (file.bytes.length > MAX_MARKDOWN_BYTES) {
+      throw new Error(`${label} exceeds the 1 MiB limit (${file.bytes.length} bytes).`);
+    }
+    validateMarkdown(file.bytes, file.path, label);
+    return addContentAddressedEntry(file, { extension: ".md", mediaType: "text/markdown" }, "docs", entries);
+  };
+  if (marketplace2.logo) index.logo = await addImage(marketplace2.logo, "marketplace.logo", MAX_LOGO_BYTES);
+  if (marketplace2.hero) {
+    const reference = await addImage(marketplace2.hero.source, "marketplace.hero.source", MAX_IMAGE_BYTES);
+    index.hero = { ...reference, alt: marketplace2.hero.alt.trim() };
+  }
+  if (marketplace2.images?.length) {
+    index.images = [];
+    for (const [position, image] of marketplace2.images.entries()) {
+      const reference = await addImage(image.source, `marketplace.images[${position}].source`, MAX_IMAGE_BYTES);
+      index.images.push({
+        ...reference,
+        alt: image.alt.trim(),
+        ...image.caption !== void 0 ? { caption: image.caption } : {}
+      });
+    }
+  }
+  if (marketplace2.readme) index.readme = await addMarkdown(marketplace2.readme, "marketplace.readme");
+  if (marketplace2.changelog) index.changelog = await addMarkdown(marketplace2.changelog, "marketplace.changelog");
+  if (marketplace2.assets?.length) {
+    index.assets = [];
+    const assetFiles = await resolveAssetGlobs(root, marketplace2.assets);
+    for (const file of assetFiles) {
+      if (file.bytes.length > MAX_IMAGE_BYTES) {
+        throw new Error(`marketplace.assets matched '${file.source}', which exceeds the 5 MiB per-image limit (${file.bytes.length} bytes).`);
+      }
+      const image = validateImage(file.bytes, file.path, `marketplace.assets entry '${file.source}'`);
+      const reference = addContentAddressedEntry(file, image, "assets", entries);
+      imageDigests.set(reference.sha256, reference.size);
+      index.assets.push(reference);
+    }
+  }
+  const totalImageBytes = [...imageDigests.values()].reduce((sum, size) => sum + size, 0);
+  if (totalImageBytes > MAX_TOTAL_IMAGE_BYTES) {
+    throw new Error(`Marketplace image assets exceed the 25 MiB total limit (${totalImageBytes} bytes).`);
+  }
+  const indexJson = `${JSON.stringify(index, null, 2)}
+`;
+  return {
+    index,
+    indexJson,
+    entries: [...entries.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([path, bytes]) => ({ path, bytes }))
+  };
+}
+async function resolveDirectFile(root, source, label) {
+  const normalized = normalizeRelativeReference(source, label);
+  return readContainedFile(root, normalized, label);
+}
+async function resolveAssetGlobs(root, patterns) {
+  const matched = /* @__PURE__ */ new Set();
+  for (const sourcePattern of patterns) {
+    const pattern = normalizeRelativeReference(sourcePattern, "marketplace.assets glob");
+    for await (const entry of glob(pattern, { cwd: root })) {
+      const normalized = toEntryPath(entry);
+      const info = await stat(join(root, normalized)).catch(() => null);
+      if (info?.isFile()) matched.add(normalized);
+    }
+  }
+  const files2 = [];
+  for (const source of [...matched].sort()) {
+    files2.push(await readContainedFile(root, source, `marketplace.assets entry '${source}'`));
+  }
+  return files2;
+}
+async function readContainedFile(root, source, label) {
+  const candidate = resolve(root, source);
+  const actual = await realpath(candidate).catch(() => {
+    throw new Error(`${label} references missing file '${source}'.`);
+  });
+  const fromRoot = relative(root, actual);
+  if (fromRoot === "" || fromRoot.startsWith(`..${sep}`) || fromRoot === ".." || isAbsolute(fromRoot)) {
+    throw new Error(`${label} references '${source}', which escapes the manifest directory.`);
+  }
+  const info = await stat(actual);
+  if (!info.isFile()) throw new Error(`${label} references '${source}', which is not a file.`);
+  return { source: toEntryPath(source), path: actual, bytes: await readFile(actual) };
+}
+function normalizeRelativeReference(source, label) {
+  const value = source.trim();
+  if (value.length === 0 || value.includes("\0") || value.includes("\\") || isAbsolute(value) || /^[a-z]:/i.test(value) || value.split("/").includes("..")) {
+    throw new Error(`${label} must be relative to the manifest directory and must not escape it (got '${source}').`);
+  }
+  const normalized = value.replace(/^(?:\.\/)+/, "");
+  if (normalized.length === 0 || normalized === ".") throw new Error(`${label} must reference a file inside the manifest directory.`);
+  return normalized;
+}
+function addContentAddressedEntry(file, type, directory, entries) {
+  const sha256 = createHash("sha256").update(file.bytes).digest("hex");
+  const path = `catalog/${directory}/${sha256}${type.extension}`;
+  entries.set(path, file.bytes);
+  return {
+    source: file.source,
+    path,
+    mediaType: type.mediaType,
+    size: file.bytes.length,
+    sha256
+  };
+}
+function validateImage(bytes, path, label) {
+  const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+  if (bytes.length >= 24 && bytes.subarray(0, 8).equals(pngSignature)) {
+    if (bytes.readUInt32BE(8) !== 13 || bytes.toString("ascii", 12, 16) !== "IHDR") throw new Error(`${label} is not a valid PNG file.`);
+    return { extension: ".png", mediaType: "image/png" };
+  }
+  if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216) {
+    if (bytes[bytes.length - 2] !== 255 || bytes[bytes.length - 1] !== 217) throw new Error(`${label} is not a valid JPEG file.`);
+    return { extension: ".jpg", mediaType: "image/jpeg" };
+  }
+  if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") {
+    const declaredLength = bytes.readUInt32LE(4) + 8;
+    if (declaredLength !== bytes.length) throw new Error(`${label} has an invalid WebP length.`);
+    return { extension: ".webp", mediaType: "image/webp" };
+  }
+  const extension = extname(path).toLowerCase();
+  if (extension === ".svg" || looksLikeSvg(bytes)) {
+    validateSvg(bytes, label);
+    return { extension: ".svg", mediaType: "image/svg+xml" };
+  }
+  throw new Error(`${label} must be a valid PNG, JPEG, WebP or SVG image.`);
+}
+function looksLikeSvg(bytes) {
+  const prefix = bytes.subarray(0, Math.min(bytes.length, 512)).toString("utf8").replace(/^\uFEFF/, "").trimStart();
+  return prefix.startsWith("<svg") || prefix.startsWith("<?xml") || prefix.startsWith("<!--");
+}
+function validateSvg(bytes, label) {
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error(`${label} is not valid UTF-8 SVG content.`);
+  }
+  const trimmed = text.replace(/^\uFEFF/, "").trim();
+  const root = /^(?:<\?xml[\s\S]*?\?>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg\b/i;
+  if (!root.test(trimmed) || !/<\/svg>\s*$/i.test(trimmed) && !/<svg\b[\s\S]*\/>\s*$/i.test(trimmed)) {
+    throw new Error(`${label} is not a well-formed SVG document.`);
+  }
+  if (/&#(?:x[0-9a-f]+|[0-9]+);/i.test(trimmed)) {
+    throw new Error(`${label} contains numeric XML character references, which are not allowed in SVG content.`);
+  }
+  if (/<!DOCTYPE|<!ENTITY/i.test(trimmed) || /<(?:script|foreignObject|iframe|object|embed|audio|video)\b/i.test(trimmed) || /\son[a-z]+\s*=/i.test(trimmed) || /(?:javascript|vbscript)\s*:/i.test(trimmed) || /data\s*:\s*text\/html/i.test(trimmed)) {
+    throw new Error(`${label} contains active SVG content, which is not allowed.`);
+  }
+}
+function validateMarkdown(bytes, _path, label) {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    if (text.includes("\0")) throw new Error("NUL");
+  } catch {
+    throw new Error(`${label} must contain valid UTF-8 Markdown text.`);
+  }
+}
+function formatMiB(bytes) {
+  return bytes / MIB;
+}
+function toEntryPath(path) {
+  return path.split(sep).join("/");
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMerge(base, overlay) {
+  if (!isPlainObject(base) || !isPlainObject(overlay)) {
+    return overlay;
+  }
+  const result = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    result[key] = key in result ? deepMerge(result[key], value) : value;
+  }
+  return result;
+}
+function applyOverlay(base, overlay) {
+  return deepMerge(base, overlay);
+}
+function resolveOverlayPath(projectDir, selector) {
+  if (selector.overlay) {
+    return isAbsolute(selector.overlay) ? selector.overlay : resolve(selector.overlay);
+  }
+  if (selector.env) {
+    return join(projectDir, "environments", `${selector.env}.yaml`);
+  }
+  return void 0;
+}
+async function loadOverlay(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(`Overlay file not found: ${path}`);
+    }
+    throw error;
+  }
+  const parsed = parse(text);
+  if (parsed === null || parsed === void 0) return {};
+  if (!isPlainObject(parsed)) {
+    throw new Error(`Overlay ${path} must be a YAML mapping (got ${Array.isArray(parsed) ? "a list" : typeof parsed}).`);
+  }
+  return parsed;
+}
+
+// src/vpkg/pack.ts
 async function pack(options) {
   const manifestPath = resolve(options.manifestPath);
   const projectDir = dirname(manifestPath);
-  const manifest = await loadManifest(manifestPath);
+  const base = await loadManifest(manifestPath);
+  const overlayPath = resolveOverlayPath(projectDir, { env: options.env, overlay: options.overlay });
+  let manifest = overlayPath ? applyOverlay(base, await loadOverlay(overlayPath)) : base;
+  let overrideApplied = overlayPath !== void 0;
+  if (options.version !== void 0) {
+    manifest = { ...manifest, metadata: { ...manifest.metadata, version: options.version } };
+    overrideApplied = true;
+  }
   const kind = normalizeKind(manifest.kind);
+  const launchKindError = validateLaunchManifestKind(kind, manifest.spec);
+  if (launchKindError) throw new Error(`Invalid manifest: ${launchKindError}.`);
+  const marketplaceErrors = validateMarketplaceSection(manifest.marketplace);
+  if (marketplaceErrors.length > 0) throw new Error(`Invalid marketplace section: ${marketplaceErrors.join(" ")}`);
   const name = (options.name ?? manifest.packaging?.name ?? manifest.metadata.name).toLowerCase();
   const publisher = options.publisher.toLowerCase();
   validatePackageName(name, "package name");
   validatePackageName(publisher, "publisher name");
   const version = manifest.metadata.version;
   const payloadFiles = await resolvePayloadFiles(projectDir, manifestPath, manifest);
+  const catalog = manifest.marketplace ? await buildCatalog(projectDir, manifest.marketplace) : void 0;
   const staging = await mkdtemp(join(tmpdir(), "vpkg-"));
   try {
-    const manifestText = await readFile(manifestPath, "utf8");
+    const manifestText = overrideApplied ? stringify(manifest) : await readFile(manifestPath, "utf8");
     await writeFile(join(staging, "manifest.yaml"), manifestText);
     const encrypt = (options.encryptFor?.length ?? 0) > 0;
     const contentKey = encrypt ? generateContentKey() : null;
@@ -1930,13 +2353,24 @@ async function pack(options) {
     };
     for (const file of payloadFiles) {
       const sourcePath = join(projectDir, file);
-      const entryName = `files/${toEntryPath(file)}`;
+      const entryName = `files/${toEntryPath2(file)}`;
       const targetPath = join(staging, "files", file);
       await mkdir(dirname(targetPath), { recursive: true });
       const bytes = contentKey ? encryptBytes(contentKey, await readFile(sourcePath)) : await readFile(sourcePath);
       await writeFile(targetPath, bytes);
       digests[entryName] = sha256Hex(bytes);
     }
+    if (catalog) {
+      for (const entry of catalog.entries) {
+        const targetPath = join(staging, entry.path);
+        await mkdir(dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, entry.bytes);
+        digests[entry.path] = sha256Hex(entry.bytes);
+      }
+      await mkdir(join(staging, "catalog"), { recursive: true });
+      await writeFile(join(staging, "catalog", "index.json"), catalog.indexJson);
+      digests["catalog/index.json"] = sha256Hex(Buffer.from(catalog.indexJson, "utf8"));
+    }
     await mkdir(join(staging, ".verentis", "signatures"), { recursive: true });
     if (contentKey) {
       const encryption = {
@@ -1972,16 +2406,19 @@ async function pack(options) {
       ".verentis/digests.json",
       ...contentKey ? [".verentis/encryption.json"] : [],
       ...signed ? [".verentis/signatures/developer.dsse.json"] : [],
-      ...payloadFiles.map((file) => `files/${toEntryPath(file)}`)
+      ...payloadFiles.map((file) => `files/${toEntryPath2(file)}`),
+      ...catalog ? ["catalog/index.json", ...catalog.entries.map((entry) => entry.path)] : []
     ];
-    await tar.create({ gzip: true, file: outFile, cwd: staging, portable: true }, entries);
+    await tar.create({ gzip: true, file: outFile, cwd: staging, portable: true, mtime: /* @__PURE__ */ new Date(0) }, entries);
     return {
       outFile,
       name,
       publisher,
       version,
       kind,
-      files: payloadFiles.map(toEntryPath),
+      files: payloadFiles.map(toEntryPath2),
+      catalog: catalog?.index,
+      catalogFiles: catalog ? ["index.json", ...catalog.entries.map((entry) => entry.path.replace(/^catalog\//, ""))] : [],
       treeDigest: sha256Hex(Buffer.from(digestsJson, "utf8")),
       signed,
       encrypted: encrypt
@@ -2008,7 +2445,7 @@ async function resolvePayloadFiles(projectDir, manifestPath, manifest) {
 }
 function defaultIncludes(manifest) {
   const sources = /* @__PURE__ */ new Set();
-  collectSchemaSources(manifest, sources);
+  collectSchemaSources(manifest.spec, sources);
   collectInstallSources(manifest, sources);
   if (sources.size === 0) return [];
   return [...sources];
@@ -2039,7 +2476,7 @@ function collectSchemaSources(node, sources) {
     }
   }
 }
-function toEntryPath(file) {
+function toEntryPath2(file) {
   return file.split(sep).join("/");
 }
 function sha256Hex(data) {
@@ -2060,21 +2497,18 @@ async function readVpkg(vpkgPath) {
     });
     const metadata = parse(packageYaml);
     const declared = JSON.parse(digestsJson);
-    const files2 = [];
-    for await (const entry of glob("files/**/*", { cwd: staging })) {
-      const abs = join(staging, entry);
-      const info = await readFile(abs).catch(() => null);
-      if (info === null) continue;
-      files2.push(entry.split(sep).join("/"));
-    }
-    files2.sort();
+    const files2 = await listFiles(staging, "files/**/*");
+    const catalogFiles = await listFiles(staging, "catalog/**/*");
+    const contentFiles = [...files2, ...catalogFiles];
     const digestErrors = [];
     const entries = declared.entries ?? {};
     const manifestDigest = createHash("sha256").update(manifestYaml, "utf8").digest("hex");
-    if (entries["manifest.yaml"] && entries["manifest.yaml"].toLowerCase() !== manifestDigest) {
+    if (!entries["manifest.yaml"]) {
+      digestErrors.push("Entry 'manifest.yaml' is not covered by digests.json.");
+    } else if (entries["manifest.yaml"].toLowerCase() !== manifestDigest) {
       digestErrors.push("Digest mismatch for manifest.yaml.");
     }
-    for (const file of files2) {
+    for (const file of contentFiles) {
       const declaredDigest = entries[file];
       if (!declaredDigest) {
         digestErrors.push(`Entry '${file}' is not covered by digests.json.`);
@@ -2084,10 +2518,21 @@ async function readVpkg(vpkgPath) {
       if (actual !== declaredDigest.toLowerCase()) digestErrors.push(`Digest mismatch for '${file}'.`);
     }
     for (const declaredPath of Object.keys(entries)) {
-      if (declaredPath !== "manifest.yaml" && !files2.includes(declaredPath)) {
+      if (declaredPath !== "manifest.yaml" && !contentFiles.includes(declaredPath)) {
         digestErrors.push(`Digest declared for missing entry '${declaredPath}'.`);
       }
     }
+    let catalog;
+    if (catalogFiles.includes("catalog/index.json")) {
+      try {
+        catalog = JSON.parse(await readFile(join(staging, "catalog", "index.json"), "utf8"));
+        if (catalog.schemaVersion !== 1) digestErrors.push(`Unsupported catalog schema version '${String(catalog.schemaVersion)}'.`);
+      } catch {
+        digestErrors.push("Invalid catalog/index.json.");
+      }
+    } else if (catalogFiles.length > 0) {
+      digestErrors.push("Catalog entries are present but catalog/index.json is missing.");
+    }
     const developerSignature = await readJsonIfExists(join(staging, ".verentis", "signatures", "developer.dsse.json"));
     const marketplaceSignature = await readJsonIfExists(join(staging, ".verentis", "signatures", "marketplace.dsse.json"));
     const encryption = await readJsonIfExists(join(staging, ".verentis", "encryption.json"));
@@ -2100,12 +2545,23 @@ async function readVpkg(vpkgPath) {
       marketplaceSignature: marketplaceSignature ?? void 0,
       encryption: encryption ?? void 0,
       files: files2.map((f) => f.replace(/^files\//, "")),
+      catalog,
+      catalogFiles: catalogFiles.map((f) => f.replace(/^catalog\//, "")),
       digestErrors
     };
   } finally {
     await rm(staging, { recursive: true, force: true });
   }
 }
+async function listFiles(root, pattern) {
+  const files2 = [];
+  for await (const entry of glob(pattern, { cwd: root })) {
+    const abs = join(root, entry);
+    const info = await readFile(abs).catch(() => null);
+    if (info !== null) files2.push(entry.split(sep).join("/"));
+  }
+  return files2.sort();
+}
 async function readJsonIfExists(path) {
   try {
     return JSON.parse(await readFile(path, "utf8"));
@@ -2116,7 +2572,7 @@ async function readJsonIfExists(path) {
 
 // src/commands/pack.ts
 function registerPack(program2) {
-  program2.command("pack [dir]").description("Build a signed .vpkg from a project directory").option("--manifest <path>", "manifest path (default: auto-detected in the project directory)").option("--publisher <name>", "publisher name (default: packaging.publisher in the manifest)").option("--name <name>", "override the package name").option("--out <dir>", "output directory (default: the project directory)").option("--key <name>", "signing key name (default: the configured default key)").option("--no-sign", "produce an unsigned package").option("--encrypt", "seal the payload (AES-256-GCM); requires at least one recipient").option("--recipient <id=base64key...>", "additional X25519 recipient (repeatable)", collectRecipients, []).action(async (dir, options) => {
+  program2.command("pack [dir]").description("Build a signed .vpkg from a project directory").option("--manifest <path>", "manifest path (default: auto-detected in the project directory)").option("--publisher <name>", "publisher name (default: packaging.publisher in the manifest)").option("--name <name>", "override the package name").option("--env <name>", "merge a per-environment overlay (environments/<name>.yaml) before packing").option("--overlay <path>", "merge an explicit overlay file before packing (wins over --env)").option("--set-version <version>", "override metadata.version (e.g. a CI-derived build number)").option("--out <dir>", "output directory (default: the project directory)").option("--key <name>", "signing key name (default: the configured default key)").option("--no-sign", "produce an unsigned package").option("--encrypt", "seal the payload (AES-256-GCM); requires at least one recipient").option("--recipient <id=base64key...>", "additional X25519 recipient (repeatable)", collectRecipients, []).action(async (dir, options) => {
     const projectDir = resolve(dir ?? ".");
     const manifestPath = options.manifest ? resolve(options.manifest) : await findManifest(projectDir);
     const manifest = await loadManifest(manifestPath);
@@ -2151,6 +2607,9 @@ function registerPack(program2) {
       manifestPath,
       publisher,
       name: options.name,
+      env: options.env,
+      overlay: options.overlay,
+      version: options.setVersion,
       outDir: options.out,
       signingKey,
       encryptFor
@@ -2158,6 +2617,7 @@ function registerPack(program2) {
     console.log(`Packed ${result.publisher}/${result.name}@${result.version} (${result.kind})`);
     console.log(`  ${result.outFile}`);
     console.log(`  ${result.files.length} payload file(s), tree digest ${result.treeDigest.slice(0, 16)}\u2026, ${result.signed ? "signed" : "UNSIGNED"}${result.encrypted ? ", ENCRYPTED" : ""}`);
+    if (result.catalog) console.log(`  ${result.catalogFiles.length} plaintext catalog file(s)`);
   });
   program2.command("seal-keygen").description("Generate an X25519 sealing keypair (for platform escrow or custom recipients)").action(() => {
     const pair = generateSealingKeyPair();
@@ -2168,7 +2628,11 @@ function registerPack(program2) {
   program2.command("verify <vpkg>").description("Verify the digests (and, when possible, the developer signature) of a .vpkg").option("--key <name>", "verify the developer signature against a local key").action(async (vpkgPath, options) => {
     const contents = await readVpkg(resolve(vpkgPath));
     console.log(`${contents.metadata.publisher}/${contents.metadata.name}@${contents.metadata.version} (${contents.metadata.kind})`);
-    console.log(`  files: ${contents.files.length}, tree digest ${contents.treeDigest.slice(0, 16)}\u2026`);
+    console.log(`  payload files: ${contents.files.length}, catalog files: ${contents.catalogFiles.length}, tree digest ${contents.treeDigest.slice(0, 16)}\u2026`);
+    if (contents.catalog) {
+      const docs = Number(!!contents.catalog.readme) + Number(!!contents.catalog.changelog);
+      console.log(`  catalog schema v${contents.catalog.schemaVersion}: ${contents.catalog.images?.length ?? 0} gallery image(s), ${docs} document(s)${contents.catalog.logo ? ", logo" : ""}${contents.catalog.hero ? ", hero" : ""}`);
+    }
     if (contents.encryption) {
       console.log(`  \u{1F512} encrypted (${contents.encryption.algorithm}); recipients: ${contents.encryption.recipients.map((r) => r.id).join(", ")}`);
     }
@@ -2309,19 +2773,62 @@ function registerPackage(program2) {
     output(pageItems(page), { packageName: "Package", version: "Version", status: "Status", installPath: "Path", id: "Id" }, options, page);
   });
 }
+var MAX_LOGO_BYTES2 = 1024 * 1024;
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+async function readPublisherLogo(path) {
+  const absolutePath = resolve(path);
+  const info = await stat(absolutePath).catch(() => {
+    throw new Error(`Publisher logo '${absolutePath}' does not exist.`);
+  });
+  if (!info.isFile()) throw new Error(`Publisher logo '${absolutePath}' is not a file.`);
+  if (info.size > MAX_LOGO_BYTES2) {
+    throw new Error(`Publisher logo exceeds the 1 MiB limit (${info.size} bytes).`);
+  }
+  const bytes = await readFile(absolutePath);
+  return { path: absolutePath, bytes, contentType: detectPublisherLogoContentType(bytes) };
+}
+function detectPublisherLogoContentType(bytes) {
+  if (bytes.length >= 24 && bytes.subarray(0, 8).equals(PNG_SIGNATURE) && bytes.readUInt32BE(8) === 13 && bytes.toString("ascii", 12, 16) === "IHDR") {
+    return "image/png";
+  }
+  if (bytes.length >= 4 && bytes[0] === 255 && bytes[1] === 216 && bytes[bytes.length - 2] === 255 && bytes[bytes.length - 1] === 217) {
+    return "image/jpeg";
+  }
+  if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP" && bytes.readUInt32LE(4) + 8 === bytes.length) {
+    return "image/webp";
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/^\uFEFF/, "").trim();
+  } catch {
+    throw unsupportedLogoError();
+  }
+  const root = /^(?:<\?xml[\s\S]*?\?>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg\b/i;
+  const closed = /<\/svg>\s*$/i.test(text) || /<svg\b[\s\S]*\/>\s*$/i.test(text);
+  if (!root.test(text) || !closed) throw unsupportedLogoError();
+  if (/&#(?:x[0-9a-f]+|[0-9]+);/i.test(text)) {
+    throw new Error("Publisher logo SVG contains numeric XML character references, which are not allowed.");
+  }
+  if (/<!DOCTYPE|<!ENTITY/i.test(text) || /<(?:script|foreignObject|iframe|object|embed|audio|video)\b/i.test(text) || /\son[a-z]+\s*=/i.test(text) || /(?:javascript|vbscript)\s*:/i.test(text) || /data\s*:\s*text\/html/i.test(text)) {
+    throw new Error("Publisher logo SVG contains active content, which is not allowed.");
+  }
+  return "image/svg+xml";
+}
+function unsupportedLogoError() {
+  return new Error("Publisher logo must be a valid PNG, JPEG, WebP or SVG image.");
+}
 
 // src/commands/publisher.ts
 function registerPublisher(program2) {
   const publisherCmd = program2.command("publisher").description("Manage your publisher profile");
-  publisherCmd.command("create").description("Onboard your account as a marketplace publisher").requiredOption("--name <name>", "URL-safe publisher name (e.g. acme)").requiredOption("--display-name <displayName>", "human-readable publisher name").option("--description <description>").option("--website <url>").option("--email <email>").action(async (options) => {
+  publisherCmd.command("create").description("Onboard your account as a marketplace publisher").requiredOption("--name <name>", "URL-safe publisher name (e.g. acme)").requiredOption("--display-name <displayName>", "human-readable publisher name").option("--description <description>").option("--website <url>").option("--email <email>").option("--logo <file>", "PNG, JPEG, WebP or SVG logo (maximum 1 MiB)").action(async (options) => {
     const api = await createApiClient();
     const existing = await getMyPublisher(api);
     if (existing) {
       console.log(`This account already has publisher '${existing.name}'.`);
       return;
     }
-    const id = await api.request("POST", "/v1/publishers", {
-      scopes: [SCOPES.publisherCreate],
+    const id = await call(api, marketplace.createPublisher, {
       body: {
         name: options.name,
         displayName: options.displayName,
@@ -2331,8 +2838,51 @@ function registerPublisher(program2) {
       }
     });
     console.log(`Publisher '${options.name}' created (${id}).`);
+    if (options.logo) {
+      await uploadPublisherLogo(api, id, options.logo);
+      console.log(`Publisher logo uploaded from ${options.logo}.`);
+    }
     console.log("Next: generate and register a signing key with `verentis keygen`.");
   });
+  publisherCmd.command("update").description("Update your publisher profile").option("--display-name <displayName>").option("--description <description>").option("--website <url>").option("--email <email>").action(async (options) => {
+    if (Object.values(options).every((value) => value === void 0)) {
+      throw new Error("No publisher fields supplied. Pass --display-name, --description, --website or --email.");
+    }
+    const api = await createApiClient();
+    const current = await requireMyPublisher(api);
+    await call(api, marketplace.updatePublisher, {
+      params: { id: current.id },
+      body: {
+        id: current.id,
+        displayName: options.displayName ?? current.displayName,
+        description: options.description ?? current.description ?? null,
+        websiteUrl: options.website ?? current.websiteUrl ?? null,
+        contactEmail: options.email ?? current.contactEmail ?? null
+      }
+    });
+    console.log(`Publisher '${current.name}' updated.`);
+  });
+  const logoCmd = publisherCmd.command("logo").description("Manage your publisher logo");
+  logoCmd.command("set <file>").description("Upload a PNG, JPEG, WebP or SVG publisher logo (maximum 1 MiB)").action(async (file) => {
+    const api = await createApiClient();
+    const publisher = await requireMyPublisher(api);
+    await uploadPublisherLogo(api, publisher.id, file);
+    console.log(`Publisher logo uploaded from ${file}.`);
+  });
+  logoCmd.command("remove").description("Remove your publisher logo").action(async () => {
+    const api = await createApiClient();
+    const publisher = await requireMyPublisher(api);
+    await call(api, marketplace.removePublisherLogo, { params: { id: publisher.id } });
+    console.log("Publisher logo removed.");
+  });
+}
+async function uploadPublisherLogo(api, publisherId, path) {
+  const logo = await readPublisherLogo(path);
+  await callRaw(api, marketplace.setPublisherLogo, {
+    params: { id: publisherId },
+    rawBody: new Blob([new Uint8Array(logo.bytes)], { type: logo.contentType }),
+    contentType: logo.contentType
+  });
 }
 function registerRegistry(program2) {
   program2.command("publish <vpkg>").description("Upload a packed .vpkg to the marketplace registry (creates the package on first publish)").option("--visibility <visibility>", "catalog visibility for a newly created package: Public | Private", "Private").action(async (vpkgPath, options) => {
@@ -2482,6 +3032,271 @@ function registerSettings(program2) {
     console.log(`Setting ${key} deleted.`);
   });
 }
+var PACKAGE_NAME = "@verentis/cli";
+var cached;
+function getCliVersion() {
+  if (cached) return cached;
+  cached = readVersion() ?? "0.0.0";
+  return cached;
+}
+function readVersion() {
+  const candidates = ["../package.json", "../../package.json"];
+  for (const relative3 of candidates) {
+    try {
+      const raw = readFileSync(fileURLToPath(new URL(relative3, import.meta.url)), "utf8");
+      const pkg = JSON.parse(raw);
+      if (pkg.version && (relative3 === "../package.json" || pkg.name === PACKAGE_NAME)) return pkg.version;
+    } catch {
+    }
+  }
+  return void 0;
+}
+
+// src/update/registry.ts
+var DEFAULT_REGISTRY = "https://registry.npmjs.org";
+function registryUrl() {
+  const configured = process.env.VERENTIS_UPDATE_REGISTRY ?? process.env.npm_config_registry ?? DEFAULT_REGISTRY;
+  return configured.replace(/\/+$/, "");
+}
+async function fetchLatestVersion(options = {}) {
+  const url = `${registryUrl()}/${PACKAGE_NAME.replace("/", "%2F")}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+  try {
+    const res = await fetch(url, {
+      // The abbreviated packument is far smaller than the full manifest but still carries dist-tags.
+      headers: { Accept: "application/vnd.npm.install-v1+json" },
+      signal: controller.signal
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body["dist-tags"]?.latest ?? null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/update/semver.ts
+function isNewerVersion(candidate, base) {
+  return compareVersions(candidate, base) > 0;
+}
+function compareVersions(a, b) {
+  const pa = parse5(a);
+  const pb = parse5(b);
+  for (let i = 0; i < 3; i++) {
+    if (pa.main[i] !== pb.main[i]) return pa.main[i] < pb.main[i] ? -1 : 1;
+  }
+  if (pa.pre.length === 0 && pb.pre.length === 0) return 0;
+  if (pa.pre.length === 0) return 1;
+  if (pb.pre.length === 0) return -1;
+  const len = Math.max(pa.pre.length, pb.pre.length);
+  for (let i = 0; i < len; i++) {
+    if (i >= pa.pre.length) return -1;
+    if (i >= pb.pre.length) return 1;
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    const xNum = /^\d+$/.test(x);
+    const yNum = /^\d+$/.test(y);
+    if (xNum && yNum) {
+      const nx = Number(x);
+      const ny = Number(y);
+      if (nx !== ny) return nx < ny ? -1 : 1;
+    } else if (xNum !== yNum) {
+      return xNum ? -1 : 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+function parse5(version) {
+  const cleaned = version.trim().replace(/^v/i, "").split("+", 1)[0];
+  const dash = cleaned.indexOf("-");
+  const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
+  const pre = dash === -1 ? "" : cleaned.slice(dash + 1);
+  const parts = core.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  return { main: [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0], pre: pre ? pre.split(".") : [] };
+}
+var DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1e3;
+var statePath = () => join(configDir(), "update-check.json");
+async function readUpdateState() {
+  try {
+    return JSON.parse(await readFile(statePath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writeUpdateState(state) {
+  await mkdir(configDir(), { recursive: true, mode: 448 });
+  await writeFile(statePath(), JSON.stringify(state, null, 2) + "\n", { mode: 384 });
+}
+function isStale(state, maxAgeMs = DEFAULT_MAX_AGE_MS) {
+  if (!state?.lastCheckAt) return true;
+  const checkedAt = Date.parse(state.lastCheckAt);
+  return !Number.isFinite(checkedAt) || Date.now() - checkedAt > maxAgeMs;
+}
+
+// src/update/notifier.ts
+var SUPPRESSED_COMMANDS = /* @__PURE__ */ new Set(["update", "__update-check", "help"]);
+async function notifyOnExit(argv) {
+  if (isUpdateCheckSuppressed(argv)) return;
+  try {
+    const current = getCliVersion();
+    const state = await readUpdateState();
+    if (state?.latestVersion && isNewerVersion(state.latestVersion, current)) {
+      printUpdateNotice(current, state.latestVersion);
+    }
+    if (isStale(state)) spawnBackgroundRefresh();
+  } catch {
+  }
+}
+async function runUpdateCheckRefresh() {
+  const latest = await fetchLatestVersion({ timeoutMs: 4e3 }).catch(() => null);
+  await writeUpdateState({ lastCheckAt: (/* @__PURE__ */ new Date()).toISOString(), latestVersion: latest ?? void 0 }).catch(() => {
+  });
+}
+function isUpdateCheckSuppressed(argv) {
+  if (isEnvDisabled()) return true;
+  if (process.env.CI) return true;
+  if (!process.stderr.isTTY) return true;
+  const args = argv.slice(2);
+  if (args.length === 0) return true;
+  if (args.some((a) => a === "--json" || a === "-h" || a === "--help" || a === "-V" || a === "--version")) return true;
+  const command = args.find((a) => !a.startsWith("-"));
+  return command !== void 0 && SUPPRESSED_COMMANDS.has(command);
+}
+function isEnvDisabled() {
+  const off = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+  const noCheck = process.env.VERENTIS_NO_UPDATE_CHECK;
+  if (noCheck !== void 0 && noCheck !== "" && !off.has(noCheck.toLowerCase())) return true;
+  const explicit = process.env.VERENTIS_UPDATE_CHECK;
+  return explicit !== void 0 && off.has(explicit.toLowerCase());
+}
+function printUpdateNotice(current, latest) {
+  const message = [
+    `Update available ${current} \u2192 ${latest}`,
+    "Run `verentis update` to install the latest version."
+  ];
+  const width = Math.max(...message.map((line) => line.length));
+  const border = "\u2500".repeat(width + 2);
+  const lines = ["", `\u256D${border}\u256E`, ...message.map((line) => `\u2502 ${line.padEnd(width)} \u2502`), `\u2570${border}\u256F`, ""];
+  process.stderr.write(lines.join("\n") + "\n");
+}
+function spawnBackgroundRefresh() {
+  try {
+    const entry = process.argv[1];
+    if (!entry) return;
+    const child = spawn(process.execPath, [entry, "__update-check"], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/commands/update.ts
+function registerUpdate(program2) {
+  program2.command("update").description("Update the Verentis CLI to the latest published version").option("--check", "report whether a newer version is available without installing").option("--to <version>", "install a specific version instead of the latest").action(async (options) => {
+    const current = getCliVersion();
+    const target = await resolveTarget(options.to);
+    if (options.check) {
+      reportCheck(current, target, Boolean(options.to));
+      return;
+    }
+    if (!options.to && !isNewerVersion(target, current)) {
+      console.log(`Already on the latest version (${current}).`);
+      return;
+    }
+    const install = resolveInstallCommand(`${PACKAGE_NAME}@${target}`);
+    if (!install) {
+      throw new Error(
+        `Automatic update is only supported for a global install of ${PACKAGE_NAME}.
+Update manually, for example:
+  npm install -g ${PACKAGE_NAME}@${target}`
+      );
+    }
+    console.log(`Updating ${PACKAGE_NAME}: ${current} \u2192 ${target}`);
+    console.log(`$ ${install.command} ${install.args.join(" ")}`);
+    const result = spawnSync(install.command, install.args, { stdio: "inherit" });
+    if (result.error) {
+      const code = result.error.code;
+      const hint = code === "ENOENT" ? ` ('${install.command}' was not found on PATH).` : `: ${result.error.message}`;
+      throw new Error(`Could not run the update${hint}
+Update manually:
+  ${install.command} ${install.args.join(" ")}`);
+    }
+    if (typeof result.status === "number" && result.status !== 0) {
+      throw new Error(
+        `Update failed (${install.command} exited with code ${result.status}).
+You can retry manually:
+  ${install.command} ${install.args.join(" ")}`
+      );
+    }
+    console.log(`Updated to ${target}. Run \`verentis --version\` to confirm.`);
+  });
+  program2.command("__update-check", { hidden: true }).description("(internal) refresh the cached latest-version marker").action(async () => {
+    await runUpdateCheckRefresh();
+  });
+}
+async function resolveTarget(requested) {
+  if (requested) return requested.replace(/^v/i, "");
+  const latest = await fetchLatestVersion({ timeoutMs: 8e3 });
+  if (!latest) {
+    throw new Error(
+      "Could not reach the package registry to determine the latest version. Check your connection, or point VERENTIS_UPDATE_REGISTRY at a reachable registry."
+    );
+  }
+  await writeUpdateState({ lastCheckAt: (/* @__PURE__ */ new Date()).toISOString(), latestVersion: latest }).catch(() => {
+  });
+  return latest;
+}
+function reportCheck(current, target, pinned) {
+  if (pinned) {
+    console.log(`Current version:   ${current}`);
+    console.log(`Requested version: ${target}`);
+    return;
+  }
+  if (isNewerVersion(target, current)) {
+    console.log(`A new version is available: ${current} \u2192 ${target}`);
+    console.log("Run `verentis update` to install it.");
+  } else {
+    console.log(`You are on the latest version (${current}).`);
+  }
+}
+function resolveInstallCommand(spec) {
+  const location = packageLocation();
+  if (!location || !location.replace(/\\/g, "/").includes("/node_modules/")) return null;
+  switch (detectPackageManager(location)) {
+    case "pnpm":
+      return { command: "pnpm", args: ["add", "-g", spec] };
+    case "yarn":
+      return { command: "yarn", args: ["global", "add", spec] };
+    case "bun":
+      return { command: "bun", args: ["add", "-g", spec] };
+    default:
+      return { command: "npm", args: ["install", "-g", spec] };
+  }
+}
+function packageLocation() {
+  try {
+    return fileURLToPath(import.meta.url);
+  } catch {
+    return process.argv[1];
+  }
+}
+function detectPackageManager(location) {
+  const path = location.replace(/\\/g, "/");
+  if (/\/(\.pnpm|pnpm)\//.test(path)) return "pnpm";
+  if (/\/(\.yarn|yarn)\//.test(path)) return "yarn";
+  if (/\/\.bun\//.test(path)) return "bun";
+  return "npm";
+}
 
 // src/commands/use.ts
 function registerUse(program2) {
@@ -2573,13 +3388,22 @@ function registerUser(program2) {
   });
 }
 function registerValidate(program2) {
-  program2.command("validate [pathOrDir]").description("Validate an engine/app/bundle manifest (structure + registration-time checks)").action(async (pathOrDir) => {
+  program2.command("validate [pathOrDir]").description("Validate an engine/app/bundle manifest (structure + registration-time checks)").option("--env <name>", "merge a per-environment overlay (environments/<name>.yaml) before validating").option("--overlay <path>", "merge an explicit overlay file before validating (wins over --env)").action(async (pathOrDir, options) => {
     const target = resolve(pathOrDir ?? ".");
     const info = await stat(target).catch(() => null);
     const manifestPath = info?.isDirectory() ? await findManifest(target) : target;
     if (!info) throw new Error(`${target} does not exist.`);
-    const manifest = await readManifestDocument(manifestPath);
+    const base = await readManifestDocument(manifestPath);
+    const overlayPath = resolveOverlayPath(dirname(manifestPath), { env: options.env, overlay: options.overlay });
+    const manifest = overlayPath ? applyOverlay(base, await loadOverlay(overlayPath)) : base;
     const issues = validateManifest(manifest);
+    if (manifest.marketplace && !issues.some((issue) => issue.level === "error" && issue.message.startsWith("marketplace"))) {
+      try {
+        await buildCatalog(dirname(manifestPath), manifest.marketplace);
+      } catch (error) {
+        issues.push({ level: "error", message: error instanceof Error ? error.message : String(error) });
+      }
+    }
     const errors = issues.filter((issue) => issue.level === "error");
     const warnings = issues.filter((issue) => issue.level === "warning");
     console.log(`${manifestPath} \u2014 kind ${manifest.kind ?? "(unknown)"}, ${manifest.metadata?.name ?? "?"}@${manifest.metadata?.version ?? "?"}`);
@@ -2678,7 +3502,7 @@ function registerWorkspace(program2) {
 }
 
 // src/index.ts
-var program = new Command().name("verentis").description("Verentis CLI \u2014 admin, marketplace publishing, and the engine/app developer loop").version("0.2.0");
+var program = new Command().enablePositionalOptions().name("verentis").description("Verentis CLI \u2014 admin, marketplace publishing, and the engine/app developer loop").version(getCliVersion());
 registerLogin(program);
 registerUse(program);
 registerAccount(program);
@@ -2697,13 +3521,20 @@ registerPack(program);
 registerRegistry(program);
 registerPackage(program);
 registerApi(program);
-program.parseAsync().catch((error) => {
-  if (error instanceof ApiError || error instanceof Error) {
-    console.error(`Error: ${error.message}`);
-  } else {
-    console.error(error);
+registerUpdate(program);
+async function main() {
+  try {
+    await program.parseAsync();
+  } catch (error) {
+    if (error instanceof ApiError || error instanceof Error) {
+      console.error(`Error: ${error.message}`);
+    } else {
+      console.error(error);
+    }
+    process.exitCode = 1;
   }
-  process.exitCode = 1;
-});
+  await notifyOnExit(process.argv);
+}
+void main();
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map