@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/cli/lib/plugin-details.ts

@@ -6,16 +6,21 @@
  * most authoritative for each field:
  *   1. The locally installed copy under `<workspacePluginsDir>/<name>/`, when
  *      present — its `package.json` and `README.md` are read straight off disk.
- *   2. The curated `plugins/marketplace.json` entry, for external
- *      ecosystem plugins (description / homepage / license / pinned source).
+ *   2. The catalog metadata for external ecosystem plugins (description /
+ *      homepage / license / pinned source). At the default ref, the gated
+ *      plugin catalog (platform-first, bundled offline) — the same source
+ *      `assistant plugins search` and install-by-name resolve. At an explicit
+ *      historical `ref`, the GitHub `plugins/marketplace.json` at that revision,
+ *      so a reviewed/rolled-back marketplace entry is inspected at the ref
+ *      requested (inherently a git operation, matching pin history / inspect).
  *   3. The plugin's own external repository at the pinned `owner/repo[/path]`,
  *      fetched via the GitHub Contents API for the README and any
  *      `package.json` fields the manifest doesn't carry.
  *
- * The `source` field is the marketplace entry's pinned origin when one claims
- * the name, otherwise `null` — an installed copy with no catalog entry has no
+ * The `source` field is the catalog entry's pinned origin when one claims the
+ * name, otherwise `null` — an installed copy with no catalog entry has no
  * advertised origin. Name-collision precedence matches {@link ./search-plugins}
- * and {@link ./install-from-github}: a marketplace entry owns its name, so the
+ * and {@link ./install-from-github}: a catalog entry owns its name, so the
  * detail page advertises the external source the catalog and installer use. A
  * same-named `plugins/<name>/` directory is that plugin's adapter stub, not a
  * standalone plugin, so it does not override the claim.
@@ -35,13 +40,19 @@ import {
   parsePluginIcon,
   type PluginArtifact,
 } from "./plugin-artifact.js";
+import {
+  findCatalogEntry,
+  resolveSourceFromMatch,
+} from "./plugin-catalog-resolve.js";
 import { DEFAULT_PLUGIN_REF } from "./plugin-constants.js";
 import { readValidatedPluginIcon } from "./plugin-icon-file.js";
+import { fetchMarketplaceEntries } from "./plugin-marketplace.js";
 import {
-  fetchMarketplaceEntries,
-  type MarketplaceEntry,
-} from "./plugin-marketplace.js";
-import type { PluginMatchSource } from "./search-plugins.js";
+  marketplaceMatch,
+  PluginCatalogUnavailableError,
+  type PluginMatchSource,
+  type PluginSearchMatch,
+} from "./search-plugins.js";
 
 /** Recognised README filenames, matched case-insensitively against a listing. */
 const README_RE = /^readme(\.md|\.markdown)?$/i;
@@ -96,7 +107,7 @@ export interface PluginDetails {
   readonly version: string | null;
   /**
    * Pinned origin, mirroring the catalog's {@link PluginMatchSource}; `null`
-   * when an installed copy has no marketplace entry to advertise an origin.
+   * when an installed copy has no catalog entry to advertise an origin.
    */
   readonly source: PluginMatchSource | null;
   /** README markdown, or `null` when the plugin ships none. */
@@ -143,9 +154,12 @@ export class PluginDetailsNotFoundError extends Error {
  * Resolve the detail view for {@link opts.name}.
  *
  * Throws {@link PluginDetailsNotFoundError} when the name is neither installed
- * locally nor present in the marketplace catalog. Network failures while
- * enriching from GitHub degrade to the fields
- * already known from disk / the manifest rather than failing the whole view —
+ * locally nor present in the catalog (gated at the default ref, the GitHub
+ * marketplace at an explicit historical ref). A gated-catalog outage
+ * ({@link PluginCatalogUnavailableError}) degrades to the on-disk fields only
+ * when a local copy exists; with nothing installed to render it propagates so
+ * the caller can map the transient failure to a retryable 503 rather than a
+ * misleading 404. Network failures while enriching from GitHub always degrade —
  * a detail page that renders metadata without a README beats a hard error.
  */
 export async function getPluginDetails(
@@ -162,22 +176,18 @@ export async function getPluginDetails(
   // invalid icon — including a not-installed plugin — resolves to no icon).
   const localIcon = readValidatedPluginIcon(join(pluginsDir, name));
 
-  const marketplaceEntry = await findMarketplaceEntry(name, ref, fetchFn);
+  const catalogMatch = await resolveCatalogEntry(
+    name,
+    ref,
+    fetchFn,
+    local.installed,
+  );
 
-  if (!local.installed && !marketplaceEntry) {
+  if (!local.installed && !catalogMatch) {
     throw new PluginDetailsNotFoundError(name, ref);
   }
 
-  const source: PluginMatchSource | null = marketplaceEntry
-    ? {
-        kind: "github",
-        repo: marketplaceEntry.source.repo,
-        ref: marketplaceEntry.source.ref,
-        ...(marketplaceEntry.source.path
-          ? { path: marketplaceEntry.source.path }
-          : {}),
-      }
-    : null;
+  const source: PluginMatchSource | null = catalogMatch?.source ?? null;
 
   const remote = source
     ? await readRemotePlugin(source, fetchFn)
@@ -190,17 +200,17 @@ export async function getPluginDetails(
     installed: local.installed,
     description:
       local.manifest.description ??
-      marketplaceEntry?.description ??
+      catalogMatch?.description ??
       remote.manifest.description ??
       null,
     homepage:
       local.manifest.homepage ??
-      marketplaceEntry?.homepage ??
+      catalogMatch?.homepage ??
       remote.manifest.homepage ??
       null,
     license:
       local.manifest.license ??
-      marketplaceEntry?.license ??
+      catalogMatch?.license ??
       remote.manifest.license ??
       null,
     version: local.manifest.version ?? remote.manifest.version ?? null,
@@ -362,21 +372,77 @@ async function fetchRawFile(
   }
 }
 
-async function findMarketplaceEntry(
+/**
+ * Resolve the external catalog entry claiming {@link name}.
+ *
+ * The default ref reads the gated catalog (the same source search / install
+ * use). An explicit historical {@link ref} reads the GitHub marketplace
+ * manifest at that revision — the gated catalog is ref-agnostic, so honoring a
+ * reviewed/rolled-back revision is inherently a git lookup, matching the pin
+ * history / inspect carve-out.
+ *
+ * A gated-catalog outage (fail-hard {@link PluginCatalogUnavailableError})
+ * propagates when nothing is installed — there is nothing to render and the
+ * failure is transient, so the caller maps it to a retryable 503 instead of a
+ * misleading not-found. When a local copy exists ({@link installed}) that same
+ * outage degrades to `null` so the view still renders from disk. A marketplace
+ * fetch/parse failure or a malformed entry always degrades to `null`: that
+ * metadata is supplementary, never required to render a detail view.
+ */
+async function resolveCatalogEntry(
   name: string,
   ref: string,
   fetchFn: FetchLike,
-): Promise<MarketplaceEntry | null> {
+  installed: boolean,
+): Promise<PluginSearchMatch | null> {
   try {
-    const entries = await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
-    return entries.find((e) => e.name === name) ?? null;
+    const match =
+      ref === DEFAULT_PLUGIN_REF
+        ? await findCatalogEntry(name, { fetch: fetchFn })
+        : await findMarketplaceMatch(name, ref, fetchFn);
+    return validateCatalogMatchSource(match);
+  } catch (err) {
+    if (err instanceof PluginCatalogUnavailableError && !installed) {
+      throw err;
+    }
+    return null;
+  }
+}
+
+/**
+ * Guard a resolved catalog match through the installer's source validation.
+ *
+ * Returns the match only when {@link resolveSourceFromMatch} accepts its source
+ * (valid `owner/repo` slug, clean path, full commit SHA). A malformed row — the
+ * exact coordinate install-by-name refuses — resolves to `null`, so the detail
+ * view neither advertises its source nor enriches from it (metadata included):
+ * the whole row is untrusted, mirroring install rejecting it.
+ */
+function validateCatalogMatchSource(
+  match: PluginSearchMatch | null,
+): PluginSearchMatch | null {
+  if (!match) {
+    return null;
+  }
+  try {
+    resolveSourceFromMatch(match);
+    return match;
   } catch {
-    // A missing or malformed manifest degrades to "no external entry" — the
-    // marketplace is supplementary, never required to render a detail view.
     return null;
   }
 }
 
+/** Read the GitHub marketplace at {@link ref} and project the named entry. */
+async function findMarketplaceMatch(
+  name: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<PluginSearchMatch | null> {
+  const entries = await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
+  const entry = entries.find((e) => e.name === name);
+  return entry ? marketplaceMatch(entry) : null;
+}
+
 function githubFetch(
   url: string,
   accept: string,

package/src/cli/lib/plugin-fingerprint.ts

@@ -18,7 +18,10 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 
-import { walkPluginTree } from "../../plugins/plugin-tree-walk.js";
+import {
+  GENERATED_APP_BUILD_DIR,
+  walkPluginTree,
+} from "../../plugins/plugin-tree-walk.js";
 
 /** Digest algorithm recorded alongside the file map, for forward compatibility. */
 export type FingerprintAlgorithm = "sha256";
@@ -64,9 +67,13 @@ export function computeFingerprint(
   exclude: readonly string[] = [],
 ): Fingerprint {
   const files: Record<string, string> = {};
-  walkPluginTree(root, { excludeRootEntries: exclude }, (rel, abs) => {
-    files[rel] = hashFile(abs);
-  });
+  walkPluginTree(
+    root,
+    { excludeRootEntries: [...exclude, GENERATED_APP_BUILD_DIR] },
+    (rel, abs) => {
+      files[rel] = hashFile(abs);
+    },
+  );
   return { algorithm: "sha256", files };
 }
 
@@ -178,9 +185,13 @@ export function computeContentHash(
   exclude: readonly string[] = [],
 ): string {
   const entries: Array<{ rel: string; abs: string }> = [];
-  walkPluginTree(root, { excludeRootEntries: exclude }, (rel, abs) => {
-    entries.push({ rel, abs });
-  });
+  walkPluginTree(
+    root,
+    { excludeRootEntries: [...exclude, GENERATED_APP_BUILD_DIR] },
+    (rel, abs) => {
+      entries.push({ rel, abs });
+    },
+  );
   entries.sort((a, b) => a.rel.localeCompare(b.rel));
 
   const hash = createHash("sha256");

package/src/cli/lib/plugin-icon-file.ts

@@ -17,11 +17,11 @@ import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 /** Fixed icon filename in the plugin root — no author path, no traversal. */
-const ICON_FILENAME = "icon.png";
+export const ICON_FILENAME = "icon.png";
 /** Byte cap: reject anything larger (also bounds what we read into memory). */
-const MAX_ICON_BYTES = 32 * 1024;
+export const MAX_ICON_BYTES = 32 * 1024;
 /** Dimension cap (px) enforced against the IHDR width/height. */
-const MAX_ICON_DIMENSION = 128;
+export const MAX_ICON_DIMENSION = 128;
 /** PNG signature: the first 8 bytes of every PNG file. */
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 /** The first chunk of a valid PNG is always IHDR with a 13-byte payload. */
@@ -41,29 +41,13 @@ export interface ValidatedPluginIcon {
 }
 
 /**
- * Read and validate `<pluginDir>/icon.png`. Returns `{ hasIcon: true }` with a
- * content-hash `iconVersion` and `path` only when the file is a PNG whose IHDR
- * dimensions are within {@link MAX_ICON_DIMENSION} and whose size is within
- * {@link MAX_ICON_BYTES}. Every other case returns `{ hasIcon: false }`.
+ * Validate in-memory PNG bytes against the icon contract. Returns
+ * `{ hasIcon: true, iconVersion }` — a content-hash version — only when the
+ * bytes are a PNG whose IHDR dimensions are within {@link MAX_ICON_DIMENSION}
+ * and whose size is within {@link MAX_ICON_BYTES}. Every other case returns
+ * `{ hasIcon: false }`. No `path`: the bytes source is caller-defined.
  */
-export function readValidatedPluginIcon(
-  pluginDir: string,
-): ValidatedPluginIcon {
-  const iconPath = join(pluginDir, ICON_FILENAME);
-
-  let bytes: Buffer;
-  try {
-    const stat = statSync(iconPath);
-    // Size-gate before reading so an oversized file never enters memory.
-    // A missing file throws here and is caught as "no icon".
-    if (!stat.isFile() || stat.size > MAX_ICON_BYTES) {
-      return { hasIcon: false };
-    }
-    bytes = readFileSync(iconPath);
-  } catch {
-    return { hasIcon: false };
-  }
-
+export function validatePluginIconBytes(bytes: Buffer): ValidatedPluginIcon {
   if (bytes.length < MIN_HEADER_BYTES || bytes.length > MAX_ICON_BYTES) {
     return { hasIcon: false };
   }
@@ -97,5 +81,33 @@ export function readValidatedPluginIcon(
     .update(bytes)
     .digest("hex")
     .slice(0, 16);
-  return { hasIcon: true, iconVersion, path: iconPath };
+  return { hasIcon: true, iconVersion };
+}
+
+/**
+ * Read and validate `<pluginDir>/icon.png`. Returns `{ hasIcon: true }` with a
+ * content-hash `iconVersion` and `path` only when the file is a PNG whose IHDR
+ * dimensions are within {@link MAX_ICON_DIMENSION} and whose size is within
+ * {@link MAX_ICON_BYTES}. Every other case returns `{ hasIcon: false }`.
+ */
+export function readValidatedPluginIcon(
+  pluginDir: string,
+): ValidatedPluginIcon {
+  const iconPath = join(pluginDir, ICON_FILENAME);
+
+  let bytes: Buffer;
+  try {
+    const stat = statSync(iconPath);
+    // Size-gate before reading so an oversized file never enters memory.
+    // A missing file throws here and is caught as "no icon".
+    if (!stat.isFile() || stat.size > MAX_ICON_BYTES) {
+      return { hasIcon: false };
+    }
+    bytes = readFileSync(iconPath);
+  } catch {
+    return { hasIcon: false };
+  }
+
+  const result = validatePluginIconBytes(bytes);
+  return result.hasIcon ? { ...result, path: iconPath } : result;
 }

package/src/cli/lib/plugin-marketplace.ts

@@ -59,7 +59,7 @@ const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
  */
 const COMMIT_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
 
-const githubSourceSchema = z.object({
+export const githubSourceSchema = z.object({
   /** Discriminator. Only GitHub sources are resolved today. */
   source: z.literal("github"),
   /** `owner/repo` of the external plugin repository. */
@@ -98,9 +98,22 @@ const marketplaceEntrySchema = z.object({
   category: z.string().optional(),
   homepage: z.string().optional(),
   license: z.string().optional(),
+  /**
+   * A single curated author/curator emoji shown as the plugin's icon (e.g. on
+   * the marketing catalog). Not a URL or file path — bounded to a short
+   * emoji-length string; a multi-code-point emoji (skin tone, ZWJ sequence)
+   * still fits comfortably under the cap.
+   */
+  icon: z
+    .string()
+    .refine(
+      (s) => [...s].length <= 8 && !/[/\\]|^https?:/i.test(s),
+      "expected a short emoji, not a URL or path",
+    )
+    .optional(),
 });
 
-const marketplaceManifestSchema = z.object({
+export const marketplaceManifestSchema = z.object({
   name: z.string(),
   owner: z
     .object({

package/src/cli/lib/publish-plugin.ts

@@ -330,9 +330,9 @@ export async function postPublishRequest(
  * Resolve platform credentials for the publish request.
  *
  * Returns `null` when not connected to the Vellum platform (no API key
- * or base URL configured). The CLI command uses this to avoid importing
- * `VellumPlatformClient` directly, which would violate the
- * `cli/no-daemon-internals` lint rule for `local`-transport commands.
+ * or base URL configured). The CLI command uses this to avoid hoisting
+ * `VellumPlatformClient` into its static import graph; resolving it lazily
+ * keeps that daemon code out of the CLI process until the command needs it.
  */
 export async function resolvePlatformDeps(): Promise<PublishDeps | null> {
   const { VellumPlatformClient } = await import("../../platform/client.js");

package/src/cli/lib/search-plugins.ts

@@ -1,39 +1,19 @@
 /**
- * Search the installable plugin catalog in the canonical GitHub source.
+ * Filtering and projection helpers for the installable plugin catalog.
  *
- * The catalog is the set of whitelisted external ecosystem plugins listed in
- * the curated `plugins/marketplace.json` manifest, fetched from the repo at
- * the configured git ref (see {@link ./plugin-marketplace}).
+ * The catalog itself is resolved by {@link ./plugin-catalog-cache}
+ * (`getPluginCatalog`), which is platform-first with a bundled offline
+ * fallback. This module owns the query semantics on top of a resolved
+ * catalog: compile a pattern, filter entries by name, and project a raw
+ * marketplace entry onto the catalog match shape.
  *
  * Entries are filtered by case-insensitive ECMAScript regex against the
  * plugin name. A plain query like `"memory"` matches anywhere in the name;
  * anchors like `"^simple"` work without escaping.
- *
- * Designed for direct programmatic use. The CLI command
- * `assistant plugins search <query>` is a thin wrapper that supplies
- * production deps (`globalThis.fetch`) and formats the result for the
- * terminal; downstream callers may supply their own `fetch` (e.g. a
- * retry-decorated client, or a test fixture).
  */
 
 import type { FetchLike } from "./fetch-like.js";
-import { DEFAULT_PLUGIN_REF } from "./plugin-constants.js";
-import {
-  fetchMarketplaceEntries,
-  type MarketplaceEntry,
-  MarketplaceFetchError,
-} from "./plugin-marketplace.js";
-
-/** Options that control the search. */
-export interface SearchPluginsOptions {
-  /**
-   * ECMAScript regex pattern. Matched case-insensitively against directory
-   * names. Empty string matches everything.
-   */
-  readonly query: string;
-  /** Git ref to list from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
-  readonly ref?: string;
-}
+import type { MarketplaceEntry } from "./plugin-marketplace.js";
 
 /** Dependencies injected by the caller. */
 export interface SearchPluginsDeps {
@@ -63,22 +43,24 @@ export interface PluginSearchMatch {
   readonly path: string;
   /** Short description, when known (external entries only today). */
   readonly description?: string;
+  /**
+   * Plugin icon: a curated emoji from the marketplace entry, or an icon URL
+   * served by the platform catalog when the plugin ships a bundled image.
+   */
+  readonly icon?: string;
   /**
    * Free-form grouping hint from the curated marketplace entry (e.g.
    * `productivity`), or `null` when the entry declares none.
    */
   readonly category: string | null;
+  /** Homepage URL, from the curated marketplace entry when present. */
+  readonly homepage?: string;
+  /** License identifier, from the curated marketplace entry when present. */
+  readonly license?: string;
   /** Discriminated origin, so callers can render/install accordingly. */
   readonly source: PluginMatchSource;
 }
 
-/** Search result envelope. */
-export interface SearchPluginsResult {
-  readonly query: string;
-  readonly ref: string;
-  readonly matches: readonly PluginSearchMatch[];
-}
-
 /** Caller passed a query that doesn't compile as an ECMAScript regex. */
 export class InvalidSearchPatternError extends Error {
   constructor(pattern: string, cause: unknown) {
@@ -89,10 +71,9 @@ export class InvalidSearchPatternError extends Error {
 }
 
 /**
- * The catalog source (GitHub) was reachable but refused or could not serve
- * the request right now — rate limiting (HTTP 403 with the rate-limit budget
- * exhausted, or 429) or an upstream 5xx. Distinct from a hard 404 on the
- * plugins prefix (a real "source gone" misconfiguration): a transient
+ * The catalog source was reachable but refused or could not serve the request
+ * right now — rate limiting or an upstream 5xx. Distinct from a hard 404 on
+ * the plugins prefix (a real "source gone" misconfiguration): a transient
  * upstream failure should surface as a retryable "temporarily unavailable"
  * rather than a generic internal error, and is a candidate for serving a
  * stale cached catalog.
@@ -107,32 +88,11 @@ export class PluginCatalogUnavailableError extends Error {
   }
 }
 
-/**
- * Build the catalog at {@link opts.ref} and return the entries whose name
- * matches {@link opts.query} (case-insensitive ECMAScript regex; an empty
- * query matches everything).
- */
-export async function searchPlugins(
-  opts: SearchPluginsOptions,
-  deps: SearchPluginsDeps,
-): Promise<SearchPluginsResult> {
-  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
-
-  // Compile the matcher up front so an invalid regex fails before we hit
-  // the network — keeps "user typo" cheap to recover from.
-  const matcher = buildMatcher(opts.query);
-
-  const { matches: catalog } = await loadPluginCatalog({ ref }, deps);
-  const matches = catalog.filter((m) => matcher(m.name));
-
-  return { query: opts.query, ref, matches };
-}
-
 /**
  * Validate that {@link query} compiles as a case-insensitive ECMAScript regex,
- * throwing {@link InvalidSearchPatternError} if not. Lets a caching caller
- * (the daemon) reject a malformed query before loading the catalog, so a typo
- * is a cheap deterministic 400 rather than a wasted GitHub request.
+ * throwing {@link InvalidSearchPatternError} if not. Lets a caller reject a
+ * malformed query before loading the catalog, so a typo is a cheap
+ * deterministic error rather than a wasted catalog fetch.
  */
 export function assertValidSearchPattern(query: string): void {
   buildMatcher(query);
@@ -141,8 +101,8 @@ export function assertValidSearchPattern(query: string): void {
 /**
  * Filter a pre-loaded {@link PluginCatalog} by {@link query}, compiling it as
  * a case-insensitive ECMAScript regex (an empty query matches everything).
- * Lets a caching caller (the daemon) reuse one catalog load across many
- * searches. Throws {@link InvalidSearchPatternError} on a malformed pattern.
+ * Lets a caller reuse one catalog load across many searches. Throws
+ * {@link InvalidSearchPatternError} on a malformed pattern.
  */
 export function filterPluginCatalog(
   catalog: PluginCatalog,
@@ -159,71 +119,48 @@ export interface PluginCatalog {
   readonly matches: readonly PluginSearchMatch[];
 }
 
-/**
- * Build the full catalog at {@link opts.ref}: every whitelisted external
- * entry in the marketplace manifest, deduped by name.
- *
- * The result is **query-independent** — `searchPlugins` applies the regex
- * filter in memory afterwards. That separation is what lets a long-lived
- * caller (the daemon) cache one catalog load and serve any number of
- * searches from it without re-hitting GitHub (see {@link ./plugin-catalog-cache}).
- */
-export async function loadPluginCatalog(
-  opts: { readonly ref?: string },
-  deps: SearchPluginsDeps,
-): Promise<PluginCatalog> {
-  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
-
-  const marketplace = await fetchMarketplaceCatalog(deps.fetch, ref);
-
-  const matches: PluginSearchMatch[] = [];
-  const seen = new Set<string>();
-  for (const entry of marketplace) {
-    if (seen.has(entry.name)) continue;
-    matches.push(marketplaceMatch(entry));
-    seen.add(entry.name);
-  }
-
-  matches.sort((a, b) => a.name.localeCompare(b.name));
-
-  return { ref, matches };
-}
-
 /**
  * Project a marketplace entry onto the catalog match shape, building a
  * `github:owner/repo[/path]@ref` locator for display.
+ *
+ * Shared by the platform fetcher and bundled reader so all catalog sources
+ * project entries identically.
  */
-function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
+export function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
   const { repo, path, ref } = entry.source;
   const locator = `github:${repo}${path ? `/${path}` : ""}@${ref}`;
   return {
     name: entry.name,
     path: locator,
     description: entry.description,
+    icon: entry.icon,
     category: entry.category ?? null,
+    homepage: entry.homepage,
+    license: entry.license,
     source: { kind: "github", repo, path, ref },
   };
 }
 
 /**
- * Fetch the marketplace entries, mapping a transient upstream failure to
- * {@link PluginCatalogUnavailableError} so the cache can serve a stale catalog
- * and the route can surface a retryable 503. A missing manifest is a normal
- * empty catalog; a hard failure (malformed or invalid manifest) propagates
- * as-is, since the catalog is the source of truth for installable plugins.
+ * Project raw marketplace entries onto catalog matches: dedupe by name
+ * (first occurrence wins), map via {@link marketplaceMatch}, and return
+ * sorted alphabetically by name.
+ *
+ * Shared by every catalog source (platform fetcher, bundled reader) so they
+ * dedupe, project, and order entries identically.
  */
-async function fetchMarketplaceCatalog(
-  fetchFn: FetchLike,
-  ref: string,
-): Promise<readonly MarketplaceEntry[]> {
-  try {
-    return await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
-  } catch (err) {
-    if (err instanceof MarketplaceFetchError && err.transient) {
-      throw new PluginCatalogUnavailableError(err.message, err.status ?? 503);
-    }
-    throw err;
+export function projectMarketplaceEntries(
+  entries: Iterable<MarketplaceEntry>,
+): PluginSearchMatch[] {
+  const matches: PluginSearchMatch[] = [];
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    if (seen.has(entry.name)) continue;
+    seen.add(entry.name);
+    matches.push(marketplaceMatch(entry));
   }
+  matches.sort((a, b) => a.name.localeCompare(b.name));
+  return matches;
 }
 
 function buildMatcher(query: string): (name: string) => boolean {

package/src/cli/program.ts

@@ -5,6 +5,7 @@ import { Command } from "commander";
 import { initFeatureFlagOverrides } from "../config/assistant-feature-flags.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { APP_VERSION } from "../version.js";
+import { registerAppsCommand } from "./commands/apps.js";
 import { registerAttachmentCommand } from "./commands/attachment.js";
 import { registerAuditCommand } from "./commands/audit.js";
 import { registerAuthCommand } from "./commands/auth.js";
@@ -54,6 +55,7 @@ import { registerUsageCommand } from "./commands/usage.js";
 import { registerWatchersCommand } from "./commands/watchers.js";
 import { registerWebhooksCommand } from "./commands/webhooks.js";
 import { red } from "./lib/cli-colors.js";
+import { registerGlobalJsonOption } from "./lib/global-json-option.js";
 import { log } from "./logger.js";
 
 /**
@@ -101,6 +103,7 @@ Examples:
 
   registerDefaultAction(program);
 
+  registerAppsCommand(program);
   registerAttachmentCommand(program);
   registerAuditCommand(program);
   registerAuthCommand(program);
@@ -149,6 +152,10 @@ Examples:
   registerWatchersCommand(program);
   registerWebhooksCommand(program);
 
+  // Every command accepts `--json` — see registerGlobalJsonOption. Must run
+  // after all commands are registered so the whole tree is covered.
+  registerGlobalJsonOption(program);
+
   // Fail fast when no assistant workspace exists on disk. The workspace is
   // created by `vellum hatch` and must be present for any command to work.
   // Commander handles --help and --version before preAction fires, so those