@vellumai/assistant 0.8.11 → 0.8.12-staging.2

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

@@ -0,0 +1,252 @@
+/**
+ * Inspect a single plugin: what is installed locally versus what the curated
+ * marketplace currently pins, and whether the two have drifted.
+ *
+ * The marketplace pins every plugin to a full, immutable commit SHA (see
+ * {@link ./plugin-marketplace}); an install records the exact commit it
+ * materialized in an `install-meta.json` provenance sidecar (see
+ * {@link ./install-from-github}). Drift detection is therefore an exact
+ * commit-SHA comparison — the pin only moves when a curator bumps it, so a
+ * mismatch means a newer pin is available. The local `package.json` version is
+ * surfaced as informational metadata, not the drift signal: a semver string may
+ * not change between pins, whereas the SHA always determines the bytes.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring the
+ * sibling plugin libraries. The CLI command `assistant plugins inspect <name>`
+ * is a thin wrapper that supplies production deps and formats the result.
+ */
+
+import {
+  DEFAULT_PLUGIN_REF,
+  type FetchLike,
+  INSTALL_META_FILENAME,
+  type InstallMeta,
+  readInstallMeta,
+  sanitizePluginName,
+} from "./install-from-github.js";
+import {
+  type InstalledPluginInfo,
+  readInstalledPlugin,
+} from "./list-installed-plugins.js";
+import {
+  compareFingerprint,
+  type FingerprintComparison,
+} from "./plugin-fingerprint.js";
+import {
+  fetchMarketplaceEntries,
+  type MarketplaceEntry,
+} from "./plugin-marketplace.js";
+
+/** Full commit SHA (40 hex SHA-1 or 64 hex SHA-256). */
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+
+/**
+ * Drift classification between the installed copy and the marketplace pin.
+ *
+ * - `up-to-date` — installed commit equals the current marketplace pin.
+ * - `update-available` — installed commit differs from the pin; a newer
+ *   reviewed revision is available via `plugins install --force`.
+ * - `not-installed` — no local copy; the marketplace metadata is shown as a
+ *   preview of what would be installed.
+ * - `not-in-marketplace` — installed but no catalog entry claims the name, so
+ *   there is no advertised remote to compare against.
+ * - `unknown-provenance` — installed and in the catalog, but no resolvable
+ *   commit was recorded (an older or manually-copied install); reinstall to
+ *   record provenance.
+ * - `remote-unavailable` — installed, but the marketplace could not be reached
+ *   to determine the current pin (rate-limit / network); local info is shown.
+ */
+export type PluginUpdateStatus =
+  | "up-to-date"
+  | "update-available"
+  | "not-installed"
+  | "not-in-marketplace"
+  | "unknown-provenance"
+  | "remote-unavailable";
+
+/** Locally installed copy of a plugin. */
+export interface PluginLocalInfo {
+  /** Absolute path to the installed plugin directory. */
+  readonly target: string;
+  /** Resolved commit the copy was installed at; `null` when no provenance was recorded. */
+  readonly commit: string | null;
+  /** `package.json` `version`, when present. */
+  readonly version: string | null;
+  /** `package.json` `description`, when present. */
+  readonly description: string | null;
+  /** ISO-8601 install timestamp from the provenance sidecar; `null` when absent. */
+  readonly installedAt: string | null;
+  /** Source coordinates recorded at install time; `null` when no sidecar exists. */
+  readonly source: InstallMeta["source"] | null;
+  /**
+   * Local-edit state relative to the install-time fingerprint: `null` when no
+   * fingerprint was recorded (an older or manually-copied install), so
+   * modification cannot be determined.
+   */
+  readonly localChanges: FingerprintComparison | null;
+  /** Non-fatal issues with the installed copy (e.g. malformed `package.json`). */
+  readonly issues: readonly string[];
+}
+
+/** The marketplace's current pin and advertised metadata for a plugin. */
+export interface PluginRemoteInfo {
+  /** `owner/repo` of the external plugin repository. */
+  readonly repo: string;
+  /** Repo-relative directory holding the plugin root; `""` = repo root. */
+  readonly path: string;
+  /** Pinned commit SHA the marketplace currently resolves installs to. */
+  readonly commit: string;
+  readonly description: string | null;
+  readonly homepage: string | null;
+  readonly license: string | null;
+  readonly category: string | null;
+  /** Ref of the canonical repo the marketplace manifest was read from. */
+  readonly marketplaceRef: string;
+}
+
+/** Resolved inspection of a single plugin. */
+export interface PluginInspection {
+  /** Install name. Matches `assistant plugins install <name>`. */
+  readonly name: string;
+  /** Whether a copy is materialized under the workspace plugins directory. */
+  readonly installed: boolean;
+  /** Drift classification between the installed copy and the marketplace pin. */
+  readonly status: PluginUpdateStatus;
+  /** Locally installed copy; `null` when the plugin is not installed. */
+  readonly local: PluginLocalInfo | null;
+  /** Marketplace pin + metadata; `null` when no entry claims the name or it was unreachable. */
+  readonly remote: PluginRemoteInfo | null;
+  /** Marketplace fetch error message, when the catalog could not be read. */
+  readonly remoteError: string | null;
+}
+
+/** Neither an installed copy nor a marketplace entry claims the name. */
+export class PluginInspectNotFoundError extends Error {
+  constructor(readonly pluginName: string) {
+    super(
+      `Plugin "${pluginName}" is not installed and has no marketplace entry.`,
+    );
+    this.name = "PluginInspectNotFoundError";
+  }
+}
+
+/** Options that control which plugin to inspect. */
+export interface InspectPluginOptions {
+  /** Install name (kebab-case directory name). */
+  readonly name: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface InspectPluginDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+  /** Override the workspace plugins directory. Falls back to the live workspace. */
+  readonly workspacePluginsDir?: string;
+}
+
+function readLocal(
+  entry: InstalledPluginInfo,
+  manifest: InstallMeta | null,
+): PluginLocalInfo {
+  // The provenance commit is authoritative; fall back to the recorded ref only
+  // when it is itself a full SHA (marketplace installs always pin one), so a
+  // sidecar written before the commit could be read still yields a comparable
+  // revision instead of dropping to "unknown".
+  const commit =
+    manifest?.commit ??
+    (manifest && FULL_SHA_RE.test(manifest.source.ref)
+      ? manifest.source.ref
+      : null);
+  // Compare the on-disk tree against the install-time baseline, applying the
+  // same exclusion so the sidecar is never counted as a local addition.
+  const localChanges = manifest?.fingerprint
+    ? compareFingerprint(entry.target, manifest.fingerprint, [
+        INSTALL_META_FILENAME,
+      ])
+    : null;
+  return {
+    target: entry.target,
+    commit,
+    version: entry.packageJson?.version ?? null,
+    description: entry.packageJson?.description ?? null,
+    installedAt: manifest?.installedAt || null,
+    source: manifest?.source ?? null,
+    localChanges,
+    issues: entry.issues,
+  };
+}
+
+function readRemote(
+  entry: MarketplaceEntry,
+  marketplaceRef: string,
+): PluginRemoteInfo {
+  return {
+    repo: entry.source.repo,
+    path: entry.source.path ?? "",
+    commit: entry.source.ref,
+    description: entry.description ?? null,
+    homepage: entry.homepage ?? null,
+    license: entry.license ?? null,
+    category: entry.category ?? null,
+    marketplaceRef,
+  };
+}
+
+/**
+ * Resolve the local-vs-remote inspection for a single plugin.
+ *
+ * Throws {@link PluginInspectNotFoundError} only when the plugin is neither
+ * installed nor present in the marketplace — there is nothing to show. A
+ * marketplace fetch failure for an *installed* plugin is not fatal: the local
+ * copy is reported with `status: "remote-unavailable"`.
+ */
+export async function inspectPlugin(
+  opts: InspectPluginOptions,
+  deps: InspectPluginDeps,
+): Promise<PluginInspection> {
+  const name = sanitizePluginName(opts.name);
+  const marketplaceRef = DEFAULT_PLUGIN_REF;
+
+  const entry = readInstalledPlugin(name, {
+    workspacePluginsDir: deps.workspacePluginsDir,
+  });
+  const installed = entry !== null;
+  const local = entry ? readLocal(entry, readInstallMeta(entry.target)) : null;
+
+  let remote: PluginRemoteInfo | null = null;
+  let remoteError: string | null = null;
+  try {
+    const entries = await fetchMarketplaceEntries(
+      { fetch: deps.fetch },
+      { ref: marketplaceRef },
+    );
+    const match = entries.find((e) => e.name === name);
+    if (match) remote = readRemote(match, marketplaceRef);
+  } catch (err) {
+    remoteError = err instanceof Error ? err.message : String(err);
+  }
+
+  if (!installed && !remote) {
+    // A reachable-but-empty catalog with no local copy is a genuine not-found;
+    // a fetch failure with no local copy leaves nothing to report either.
+    throw new PluginInspectNotFoundError(name);
+  }
+
+  const status = classify(installed, local, remote, remoteError);
+  return { name, installed, status, local, remote, remoteError };
+}
+
+function classify(
+  installed: boolean,
+  local: PluginLocalInfo | null,
+  remote: PluginRemoteInfo | null,
+  remoteError: string | null,
+): PluginUpdateStatus {
+  if (!installed) return "not-installed";
+  if (remoteError && !remote) return "remote-unavailable";
+  if (!remote) return "not-in-marketplace";
+  if (!local?.commit) return "unknown-provenance";
+  return local.commit.toLowerCase() === remote.commit.toLowerCase()
+    ? "up-to-date"
+    : "update-available";
+}

package/src/cli/lib/install-from-github.ts

@@ -40,6 +40,12 @@ import { promisify } from "node:util";
 
 import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
+import {
+  computeContentHash,
+  computeFingerprint,
+  type Fingerprint,
+  parseFingerprint,
+} from "./plugin-fingerprint.js";
 import {
   fetchMarketplaceEntries,
   MarketplaceFetchError,
@@ -389,11 +395,25 @@ export async function installPlugin(
     throw new PluginNotFoundError(name, ref, sourceLabel(source));
   }
 
-  // Record install provenance (source coordinates + resolved commit) as a
-  // hidden sidecar before the swap so it lands atomically with the files. The
-  // daemon loader enumerates plugin directories and reads each plugin's
-  // `package.json`, skipping dotfiles — so this never gets mistaken for code.
-  writeInstallManifest(stagingDir, name, source, ref, commit);
+  // Hash the materialized tree before the sidecar is written (so the sidecar
+  // never hashes itself) — the baseline `plugins inspect` uses to detect later
+  // local edits. The per-file fingerprint answers "which files changed"; the
+  // whole-tree content hash is a compact integrity signal mirroring skills.
+  const fingerprint = computeFingerprint(stagingDir, [INSTALL_META_FILENAME]);
+  const contentHash = computeContentHash(stagingDir, [INSTALL_META_FILENAME]);
+
+  // Record install provenance (source coordinates + resolved commit + content
+  // digests) as a sidecar before the swap so it lands atomically with the
+  // files. The external plugin loader only reads `package.json` and the
+  // `hooks/`/`tools/` dirs, so this JSON file is never mistaken for code.
+  writeInstallMeta(stagingDir, {
+    name,
+    source,
+    ref,
+    commit,
+    fingerprint,
+    contentHash,
+  });
 
   // Atomic-ish swap: rmSync + renameSync. On POSIX the rename itself is
   // atomic, so the only window where the target is absent is between the
@@ -412,8 +432,78 @@ export async function installPlugin(
 /** Cap on any single git invocation; a shallow fetch is well under this. */
 const GIT_TIMEOUT_MS = 120_000;
 
-/** Install-provenance sidecar written at the plugin root. */
-const INSTALL_MANIFEST_FILENAME = ".vellum-plugin.json";
+/**
+ * Install-provenance sidecar written at the plugin root. Named to match the
+ * skills' sidecar (`install-meta.json`, see `src/skills/install-meta.ts`) so
+ * both subsystems share one vocabulary. The external plugin loader only reads
+ * `package.json` and the `hooks/`/`tools/` surface dirs, so a plain JSON file
+ * at the root is ignored by it.
+ */
+export const INSTALL_META_FILENAME = "install-meta.json";
+
+/**
+ * Which catalog manages an installed plugin. Mirrors the skill origin values
+ * (`SkillInstallMeta.origin` in `src/skills/install-meta.ts`) so the two
+ * systems keep a consistent vocabulary. `"vellum"` denotes the first-party
+ * `marketplace.json`; the union widens as new sources are supported.
+ */
+export type InstallOrigin = "vellum";
+
+/** Resolved source coordinates recorded in the provenance sidecar. */
+export interface InstallMetaSource {
+  /** Source kind. Only `github` is written today. */
+  readonly kind: string;
+  readonly owner: string;
+  readonly repo: string;
+  /** Repo-relative directory holding the plugin root; absent = repo root. */
+  readonly path?: string;
+  /** Ref the install resolved through (the pinned commit SHA for marketplace installs). */
+  readonly ref: string;
+}
+
+/**
+ * Parsed contents of the `install-meta.json` provenance sidecar — what was
+ * installed, from where, and at exactly which commit. Read by
+ * {@link readInstallMeta} for provenance reporting (e.g. `plugins inspect`).
+ *
+ * The leading fields share names (and meaning) with the skills'
+ * `SkillInstallMeta`; everything below {@link InstallMeta.name} is the
+ * plugin-specific superset that the git-backed install needs.
+ */
+export interface InstallMeta {
+  /** Catalog the install is managed from. */
+  readonly origin: InstallOrigin;
+  /** ISO-8601 timestamp of when the install was materialized. */
+  readonly installedAt: string;
+  /** Principal that initiated the install, when known. */
+  readonly installedBy?: string;
+  /** Set by a backfill migration when provenance was reconstructed after the fact. */
+  readonly backfilledBy?: string;
+  /** Plugin `package.json` version at install time, when present. */
+  readonly version?: string;
+  /** Registry slug, recorded when it diverges from {@link InstallMeta.name}. */
+  readonly slug?: string;
+  /** `owner/repo` the install was sourced from. */
+  readonly sourceRepo?: string;
+  /**
+   * Whole-tree `v2:` content hash — a compact integrity signal using the same
+   * scheme as the skills' `contentHash`. Complements the per-file
+   * {@link InstallMeta.fingerprint}.
+   */
+  readonly contentHash?: string;
+
+  /** Install name. Matches the plugins directory and `plugins install <name>`. */
+  readonly name: string;
+  readonly source: InstallMetaSource;
+  /** Resolved commit SHA the source was cloned at; `null` when it could not be read at install time. */
+  readonly commit: string | null;
+  /**
+   * Per-file content digest of the materialized tree, captured at install
+   * time. `null` for older installs written before fingerprinting; callers
+   * then report local-modification state as unknown rather than clean.
+   */
+  readonly fingerprint: Fingerprint | null;
+}
 
 /**
  * Materialize an external plugin by shallow-cloning its repo at the pinned ref.
@@ -852,20 +942,59 @@ function pluginGitEnv(): NodeJS.ProcessEnv {
   return env;
 }
 
+/** Inputs for {@link writeInstallMeta}, resolved during a fresh install. */
+interface WriteInstallMetaParams {
+  readonly name: string;
+  readonly source: PluginFetchSource;
+  readonly ref: string;
+  readonly commit: string | null;
+  readonly fingerprint: Fingerprint;
+  readonly contentHash: string;
+}
+
+/**
+ * Read the `version` field from a staged plugin's `package.json`. Lenient — a
+ * missing or malformed manifest simply yields `undefined` so provenance is
+ * recorded without it rather than failing the install.
+ */
+function readStagedPackageVersion(stagingDir: string): string | undefined {
+  const pkgPath = join(stagingDir, "package.json");
+  if (!existsSync(pkgPath)) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(pkgPath, "utf8"));
+    if (typeof parsed === "object" && parsed !== null) {
+      const version = (parsed as Record<string, unknown>).version;
+      if (typeof version === "string" && version.length > 0) return version;
+    }
+  } catch {
+    // fall through to undefined
+  }
+  return undefined;
+}
+
 /**
- * Write the install-provenance sidecar into the staged plugin root, recording
- * the resolved source coordinates and commit so we can later report or verify
- * exactly what is installed. Hidden (dot-prefixed) so the daemon loader, which
- * skips dotfiles, never mistakes it for plugin code.
+ * Write the `install-meta.json` provenance sidecar into the staged plugin root,
+ * recording the resolved source coordinates, commit, and content digests so we
+ * can later report or verify exactly what is installed. The schema is an
+ * equal-name superset of the skills' `SkillInstallMeta`.
  */
-function writeInstallManifest(
+function writeInstallMeta(
   stagingDir: string,
-  name: string,
-  source: PluginFetchSource,
-  ref: string,
-  commit: string | null,
+  {
+    name,
+    source,
+    ref,
+    commit,
+    fingerprint,
+    contentHash,
+  }: WriteInstallMetaParams,
 ): void {
-  const manifest = {
+  const meta: InstallMeta = {
+    origin: "vellum",
+    installedAt: new Date().toISOString(),
+    version: readStagedPackageVersion(stagingDir),
+    sourceRepo: `${source.owner}/${source.repo}`,
+    contentHash,
     name,
     source: {
       kind: "github",
@@ -874,15 +1003,79 @@ function writeInstallManifest(
       path: source.rootPath || undefined,
       ref,
     },
-    commit: commit ?? undefined,
-    installedAt: new Date().toISOString(),
+    commit,
+    fingerprint,
   };
   writeFileSync(
-    join(stagingDir, INSTALL_MANIFEST_FILENAME),
-    `${JSON.stringify(manifest, null, 2)}\n`,
+    join(stagingDir, INSTALL_META_FILENAME),
+    `${JSON.stringify(meta, null, 2)}\n`,
   );
 }
 
+/**
+ * Read the install-provenance sidecar from an installed plugin's root.
+ *
+ * Lenient by design — a missing, unreadable, or malformed sidecar yields
+ * `null` rather than throwing, mirroring {@link ./list-installed-plugins}.
+ * Older or manually-copied installs that predate the sidecar simply report no
+ * provenance. The resolved commit is the authoritative record of which bytes
+ * are installed, so callers (e.g. `plugins inspect`) can compare it against the
+ * marketplace's current pin to detect drift.
+ */
+export function readInstallMeta(pluginDir: string): InstallMeta | null {
+  const metaPath = join(pluginDir, INSTALL_META_FILENAME);
+  if (!existsSync(metaPath)) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(metaPath, "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const src = obj.source;
+  if (typeof src !== "object" || src === null || Array.isArray(src)) {
+    return null;
+  }
+  const source = src as Record<string, unknown>;
+  if (
+    typeof obj.name !== "string" ||
+    typeof source.owner !== "string" ||
+    typeof source.repo !== "string" ||
+    typeof source.ref !== "string"
+  ) {
+    return null;
+  }
+
+  const optionalString = (value: unknown): string | undefined =>
+    typeof value === "string" ? value : undefined;
+
+  return {
+    origin: "vellum",
+    installedAt: typeof obj.installedAt === "string" ? obj.installedAt : "",
+    installedBy: optionalString(obj.installedBy),
+    backfilledBy: optionalString(obj.backfilledBy),
+    version: optionalString(obj.version),
+    slug: optionalString(obj.slug),
+    sourceRepo: optionalString(obj.sourceRepo),
+    contentHash: optionalString(obj.contentHash),
+    name: obj.name,
+    source: {
+      kind: typeof source.kind === "string" ? source.kind : "github",
+      owner: source.owner,
+      repo: source.repo,
+      path: typeof source.path === "string" ? source.path : undefined,
+      ref: source.ref,
+    },
+    commit: typeof obj.commit === "string" ? obj.commit : null,
+    fingerprint: parseFingerprint(obj.fingerprint),
+  };
+}
+
 /**
  * Recursively copy a curated adapter stub directory via the GitHub Contents API.
  *

package/src/cli/lib/list-installed-plugins.ts

@@ -12,12 +12,7 @@
  * and we want both surfaces to agree on what's present.
  */
 
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  statSync,
-} from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 import { getWorkspacePluginsDir } from "../../util/platform.js";
@@ -81,6 +76,22 @@ export function listInstalledPlugins(
   return entries.map((name) => readPluginEntry(pluginsDir, name));
 }
 
+/**
+ * Read a single installed plugin entry by name, or `null` when no directory
+ * for it exists under the workspace plugins directory. Parses leniently like
+ * {@link listInstalledPlugins} — a malformed `package.json` surfaces as an
+ * `issues` entry rather than throwing.
+ */
+export function readInstalledPlugin(
+  name: string,
+  opts: ListInstalledPluginsOptions = {},
+): InstalledPluginInfo | null {
+  const pluginsDir = opts.workspacePluginsDir ?? getWorkspacePluginsDir();
+  const target = join(pluginsDir, name);
+  if (!existsSync(target) || !statSync(target).isDirectory()) return null;
+  return readPluginEntry(pluginsDir, name);
+}
+
 function readPluginEntry(
   pluginsDir: string,
   name: string,

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

@@ -0,0 +1,103 @@
+/**
+ * Parse a plugin's prebuilt client-artifact descriptor from its
+ * `package.json` `vellum.artifact` block.
+ *
+ * Some plugins ship a native companion the assistant cannot build itself —
+ * e.g. a macOS app whose Swift toolchain is absent from the Linux container
+ * the daemon runs in. Those plugins publish a prebuilt, author-signed binary
+ * out-of-band (a GitHub Release) and point at it from their manifest:
+ *
+ *     "vellum": {
+ *       "artifact": {
+ *         "url": "https://github.com/owner/repo/releases/download/v1.0.0/App.dmg",
+ *         "sha256": "<64-hex>",
+ *         "label": "Download for macOS"
+ *       }
+ *     }
+ *
+ * The `url` is mutable (a Release asset can be re-uploaded); the `sha256` is
+ * the integrity anchor a client verifies the download against — the same
+ * "pin the immutable hash, not the mutable pointer" philosophy the source
+ * whitelist already enforces with full commit SHAs.
+ *
+ * An artifact is only surfaced when **both** fields are well-formed. A
+ * missing block, a non-`https:` URL, or an absent / placeholder `sha256`
+ * (e.g. the empty string a release workflow fills in on its first run) all
+ * resolve to `null` — "no downloadable artifact yet" — so a client never
+ * offers an unverifiable download.
+ */
+
+import { z } from "zod";
+
+/** A verified, downloadable client artifact declared by a plugin. */
+export interface PluginArtifact {
+  /** HTTPS URL the artifact is downloaded from. */
+  readonly url: string;
+  /** Lowercase 64-char hex SHA-256 the download is verified against. */
+  readonly sha256: string;
+  /**
+   * Optional human label for the download affordance — useful when a plugin
+   * ships more than one artifact (e.g. "Download for macOS", "Apple Silicon").
+   * Absent (or blank) when the plugin doesn't name it; clients fall back to a
+   * generic label.
+   */
+  readonly label?: string;
+}
+
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Schema for a complete artifact descriptor. The URL must be absolute and
+ * `https:` (an artifact fetched over plaintext defeats the integrity story);
+ * the digest must be canonical lowercase hex so client-side comparison is a
+ * plain string equality with no normalization step.
+ */
+const PluginArtifactSchema = z.object({
+  url: z
+    .string()
+    .url()
+    .refine((u) => u.startsWith("https://"), {
+      message: "artifact url must be an https:// URL",
+    }),
+  sha256: z
+    .string()
+    .regex(SHA256_HEX_RE, "artifact sha256 must be 64 lowercase hex chars"),
+  // Optional, non-critical metadata: a malformed label must never nullify an
+  // otherwise-valid `url` + `sha256`, so a wrong-typed value falls back to
+  // `undefined` rather than failing the whole descriptor.
+  label: z.string().optional().catch(undefined),
+});
+
+/**
+ * Read `vellum.artifact` from an already-parsed `package.json` value and
+ * return it only when it is a complete, well-formed descriptor. Any shape
+ * problem — missing block, wrong types, non-https URL, placeholder/empty
+ * `sha256` — yields `null` rather than throwing, so callers can union this
+ * across sources without per-source error handling.
+ */
+export function parsePluginArtifact(
+  packageJson: unknown,
+): PluginArtifact | null {
+  if (
+    typeof packageJson !== "object" ||
+    packageJson === null ||
+    Array.isArray(packageJson)
+  ) {
+    return null;
+  }
+  const vellum = (packageJson as Record<string, unknown>).vellum;
+  if (typeof vellum !== "object" || vellum === null || Array.isArray(vellum)) {
+    return null;
+  }
+  const artifact = (vellum as Record<string, unknown>).artifact;
+  const parsed = PluginArtifactSchema.safeParse(artifact);
+  if (!parsed.success) return null;
+  // A blank or whitespace-only label is treated as absent so it never
+  // invalidates an otherwise well-formed `url` + `sha256` descriptor.
+  const label = parsed.data.label?.trim();
+  return {
+    url: parsed.data.url,
+    sha256: parsed.data.sha256,
+    ...(label ? { label } : {}),
+  };
+}