@stigmer/plugin-package 3.18.0 → 3.19.0

package/src/client/builtin.ts

@@ -1,60 +1,41 @@
 /**
- * The sources every client lists without being told: Stigmer's official
- * catalogue and the three vendors' public ones.
+ * The one source every client lists without being told: Stigmer's official
+ * catalogue.
  *
- * The product's promise is "bring your Cursor, Claude Code or Codex
- * plugin", so the catalogues those vendors publish are on offer from the
- * first screen, in the console's Marketplace and in `stigmer marketplace
- * list`, without a user having to know a repository slug. They are code,
- * not stored state: a client's remembered sources hold only what the user
- * added, so the two clients cannot drift from each other and a vendor
- * moving its repository is one release, not a migration. The names are
- * reserved the way the official one is; a user can neither add nor remove
- * them.
+ * The catalogue is curated (`plugins/README.md`, "What the catalogue holds"):
+ * every entry is one Stigmer may ship and one whose servers Stigmer can
+ * connect to, vendored from a publisher's redistributable set or authored
+ * by Stigmer for a vendor's public endpoint. The vendors' own repositories
+ * were built in for one release and were taken out again when the audit
+ * behind the catalogue measured that more than half of their entries fail
+ * that bar: a chip that offers what the catalogue left out re-surfaces
+ * what curation removed. A user who wants another catalogue adds it as a
+ * source of his own (a repository with a marketplace file, read from
+ * GitHub), in the console's Manage sources or with `stigmer marketplace
+ * add`; the vendors' repositories are ordinary candidates for that, at the
+ * user's word, never on offer by default.
  *
- * Each vendor keeps its marketplace file at the repository root in its own
- * location, all four of which `readMarketplace` reads (`.cursor-plugin/`,
- * `.claude-plugin/`, `.agents/plugins/`). Measured on 2026-09-18 through
- * the GitHub Trees API: 1,168, 1,594 and 7,746 entries respectively, none
- * truncated, all under the console's 20,000-entry listing cap; Codex's
- * catalogue names its entries as `{source: "local", path}` objects, which
- * the reader accepts, and three of its 65 as remote sources, which it
- * drops with its own sentence.
+ * The list is code, not stored state: a client's remembered sources hold
+ * only what the user added, so the two clients cannot drift from each
+ * other. The official name is reserved the way it always was; a user can
+ * neither add over it nor remove it.
  */
 
 import type { GitHubMarketplaceSource } from "./refs.js";
 import { OFFICIAL_MARKETPLACE_NAME } from "./refs.js";
 
-/** A source a client ships with: named, described for a section heading, and either the official catalogue or a public GitHub tree. */
+/** A source a client ships with: named, and either the official catalogue or a public GitHub tree. */
 export interface BuiltInMarketplace {
   readonly name: string;
-  /** One sentence for the Marketplace's section heading and `marketplace list`. */
-  readonly description: string;
   readonly source: { readonly type: "official" } | GitHubMarketplaceSource;
 }
 
-/** In listing order: the official catalogue first, then the vendors in the order the product names them. */
+/** In listing order. Today one entry; the type keeps the shape a future built-in would take. */
 export const BUILT_IN_MARKETPLACES: readonly BuiltInMarketplace[] = [
   {
     name: OFFICIAL_MARKETPLACE_NAME,
-    description: "Stigmer's official catalogue, published with each release.",
     source: { type: "official" },
   },
-  {
-    name: "cursor-plugins",
-    description: "Cursor's public plugin catalogue.",
-    source: { type: "github", repo: "cursor/plugins" },
-  },
-  {
-    name: "claude-code-plugins",
-    description: "Claude Code's public plugin catalogue.",
-    source: { type: "github", repo: "anthropics/claude-code" },
-  },
-  {
-    name: "codex-plugins",
-    description: "Codex's public plugin catalogue.",
-    source: { type: "github", repo: "openai/plugins" },
-  },
 ];
 
 const BUILT_IN_NAMES: ReadonlySet<string> = new Set(BUILT_IN_MARKETPLACES.map((entry) => entry.name));

package/src/client/presentation.ts

@@ -0,0 +1,47 @@
+/**
+ * A plugin's presentation from a tree whose bytes cost something to obtain:
+ * the lazy twin of `readPluginPresentation`, as `preparePluginFromTree` is
+ * the lazy twin of the full read.
+ *
+ * A storefront lists a catalogue from one file and then shows a card per
+ * entry; the face on each card is in that entry's manifest, one small file
+ * in a directory the client has listed but not read. This reads exactly the
+ * manifest paths the listing shows (one, rarely two) and nothing else, then
+ * hands a `PluginFiles` whose `read` answers for those paths alone to the
+ * pure reader. A manifest that cannot be fetched contributes nothing, the
+ * pure reader's own rule for a manifest that cannot be parsed: a card is
+ * never refused, it is drawn with what arrived.
+ */
+
+import { comparePaths, type PluginFiles } from "../files.js";
+import { MANIFEST_LOCATIONS } from "../messages.js";
+import { type PluginPresentation, readPluginPresentation } from "../presentation.js";
+import type { LazyCandidate } from "./prepare.js";
+
+const MANIFEST_PATHS: ReadonlySet<string> = new Set(Object.values(MANIFEST_LOCATIONS));
+
+/** The presentation of the plugin whose files `candidates` list, reading only its manifests. */
+export async function readPluginPresentationFromTree(candidates: readonly LazyCandidate[]): Promise<PluginPresentation> {
+  const contents = new Map<string, Uint8Array>();
+  await Promise.all(
+    candidates
+      .filter((candidate) => MANIFEST_PATHS.has(candidate.path))
+      .map(async (candidate) => {
+        try {
+          contents.set(candidate.path, await candidate.read());
+        } catch {
+          // Unfetchable is unreadable: the pure reader skips a manifest it cannot open.
+        }
+      }),
+  );
+  const files: PluginFiles = {
+    // `PluginFiles` promises a sorted listing; a host's tree order is its own.
+    entries: candidates.map(({ path, size }) => ({ path, size })).sort((a, b) => comparePaths(a.path, b.path)),
+    read: (path) => {
+      const bytes = contents.get(path);
+      if (bytes === undefined) throw new Error(`plugin file '${path}' was not fetched for presentation`);
+      return bytes;
+    },
+  };
+  return readPluginPresentation(files);
+}

package/src/client.ts

@@ -17,6 +17,8 @@
  *   the SHA-256 the server records;
  * - the preparation (`prepare.ts`): select, read, refuse, archive, digest,
  *   once, for a tree on disk, on a host, or in a browser's memory;
+ * - the presentation (`presentation.ts`): a card's face from a listed
+ *   tree, reading the entry's manifest and nothing else;
  * - the grammars (`refs.ts`): an install ref and a GitHub marketplace
  *   source, with their refusal sentences;
  * - the built-in sources (`builtin.ts`): the official catalogue and the
@@ -65,6 +67,7 @@ export {
   preparePluginArchive,
   preparePluginFromTree,
 } from "./client/prepare.js";
+export { readPluginPresentationFromTree } from "./client/presentation.js";
 export {
   type BuiltInMarketplace,
   BUILT_IN_MARKETPLACES,

package/src/detect.ts

@@ -41,6 +41,14 @@ export const OPEN_MCP_CONFIG = "mcp.json";
 /** The vendor precedence when no root manifest exists. */
 const VENDOR_PRECEDENCE: readonly Exclude<PluginDialect, "agent-plugins">[] = ["claude", "cursor", "codex"];
 
+/**
+ * Every manifest location in the order that names a plugin: the root
+ * manifest, then the vendors. The one precedence the reader applies,
+ * exported so a partial read (`presentation.ts`) cannot rank the manifests
+ * differently from the full one.
+ */
+export const MANIFEST_PRECEDENCE: readonly PluginDialect[] = ["agent-plugins", ...VENDOR_PRECEDENCE];
+
 const NAME_MAX_LENGTH = 64;
 const NAME_PATTERN = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
 

package/src/dialects/manifest.ts

@@ -215,11 +215,36 @@ const EXPERIMENTAL_KINDS: Readonly<Record<string, IgnoredComponentKind>> = {
 };
 
 /**
- * `extensions` in a root manifest: every namespace with content is an
- * ignored component (a client ignores namespaces it does not implement
- * without validating them); an empty object, including Stigmer's own
- * reserved `ai.stigmer`, is silent. A non-object `extensions` is the open
- * format's one non-fatal type violation: reported and ignored.
+ * Stigmer's own namespace under a root manifest's `extensions`. The open
+ * format has no appearance fields, so this is where an open-format plugin
+ * says what a storefront card shows: the same three the Cursor manifest
+ * carries at its top level, read by `presentation.ts` and treated by the
+ * install exactly as Cursor's are (`logo` an ignored component, because
+ * nothing in an Organization carries the image; `displayName` and
+ * `category` silent). The overlay FOLDER `ai.stigmer/` (`normalise/overlay.ts`)
+ * is the same name in a different place: resources there, appearance here.
+ */
+export const STIGMER_EXTENSION_NAMESPACE = "ai.stigmer";
+export const STIGMER_EXTENSION_FIELDS: ReadonlySet<string> = new Set(["displayName", "logo", "category"]);
+
+/** The `ai.stigmer` extension object of a root manifest, or `undefined` when absent or not an object. */
+export function stigmerExtensionOf(object: JsonObject): JsonObject | undefined {
+  const extensions = object["extensions"];
+  if (!isJsonObject(extensions)) return undefined;
+  const content = extensions[STIGMER_EXTENSION_NAMESPACE];
+  return isJsonObject(content) ? content : undefined;
+}
+
+/**
+ * `extensions` in a root manifest: every foreign namespace with content is
+ * an ignored component (a client ignores namespaces it does not implement
+ * without validating them); an empty object is silent. Stigmer's own
+ * namespace is read field by field: `logo` is recorded as the `logo`
+ * component Cursor's would be, the other appearance fields are silent, and
+ * any field beyond `STIGMER_EXTENSION_FIELDS` makes the namespace an
+ * ignored `extension` component so a misspelled key stays visible. A
+ * non-object `extensions` is the open format's one non-fatal type
+ * violation: reported and ignored.
  */
 export function extensionComponents(object: JsonObject, path: string, findings: Findings): IgnoredComponent[] {
   const value = object["extensions"];
@@ -231,7 +256,13 @@ export function extensionComponents(object: JsonObject, path: string, findings:
   const ignored: IgnoredComponent[] = [];
   for (const [namespace, content] of fields(value)) {
     if (isJsonObject(content) && fields(content).length === 0) continue;
-    ignored.push({ kind: "extension", path: `${path}#extensions.${namespace}` });
+    const at = `${path}#extensions.${namespace}`;
+    if (namespace === STIGMER_EXTENSION_NAMESPACE && isJsonObject(content)) {
+      if (content["logo"] !== undefined) ignored.push({ kind: "logo", path: `${at}.logo` });
+      if (fields(content).some(([name]) => !STIGMER_EXTENSION_FIELDS.has(name))) ignored.push({ kind: "extension", path: at });
+      continue;
+    }
+    ignored.push({ kind: "extension", path: at });
   }
   return ignored;
 }

package/src/dialects/open.ts

@@ -8,8 +8,9 @@
  * so this manifest declares no paths and no inline servers; `mcp.json` is
  * read under the open format's rules by `detect.ts` when it exists.
  * Client-specific data belongs under `extensions`, which Stigmer records as
- * ignored per namespace (its own `ai.stigmer` namespace is reserved and
- * empty today).
+ * ignored per foreign namespace; its own `ai.stigmer` namespace carries the
+ * appearance fields a storefront card shows (`manifest.ts`,
+ * `STIGMER_EXTENSION_FIELDS`), the open format's only place for them.
  */
 
 import { describeValue, type JsonObject } from "../documents.js";

package/src/files.ts

@@ -58,6 +58,13 @@ export const PLUGIN_DOCUMENT_LIMITS = {
   subAgent: 1024 * 1024,
   /** A document under `ai.stigmer/`: a resource YAML. */
   overlay: 1024 * 1024,
+  /**
+   * A plugin's logo, the image a storefront card shows. Checked from the
+   * listing's declared size before a client hands the file's URL to an
+   * `<img>`; measured across the three vendors' catalogues on 2026-09-18,
+   * the largest published logo is 361 KB and the median 7.5 KB.
+   */
+  logo: 1024 * 1024,
   /**
    * A marketplace file in any dialect. The largest public catalogue
    * (`cursor/plugins`, 79 entries with descriptions) is under 32 KB; the cap

package/src/index.ts

@@ -2,7 +2,8 @@
  * `@stigmer/plugin-package`: the public surface.
  *
  * `readPluginPackage` reads one plugin; `readMarketplace` reads a catalogue
- * of them. Everything else here is what a consumer needs to supply its
+ * of them; `readPluginPresentation` reads what a card shows for one entry
+ * without opening the rest of it. Everything else here is what a consumer needs to supply its
  * input (`PluginFiles`, the caps), route a directory (`MANIFEST_LOCATIONS`,
  * `hasPluginManifest`, `MARKETPLACE_LOCATIONS`, `hasMarketplaceFile`), or
  * render an outcome (the finding kinds and `isErrorKind`). The dialect
@@ -56,6 +57,7 @@ export type {
 } from "./marketplace/outcome.js";
 export { hasMarketplaceFile, readMarketplace, readMarketplaceFile } from "./marketplace/read-marketplace.js";
 export { readPluginPackage } from "./read-plugin-package.js";
+export { type PluginPresentation, readPluginPresentation } from "./presentation.js";
 export type {
   IgnoredComponent,
   IgnoredComponentKind,

package/src/presentation.ts

@@ -0,0 +1,170 @@
+/**
+ * What a storefront shows for a plugin before anyone installs it: a display
+ * name, a logo, an author, a version, a description, a category.
+ *
+ * This is a read apart from `readPluginPackage` on purpose. The full read
+ * decides what Stigmer INSTALLS and refuses what it cannot; a card must
+ * render for every entry a catalogue lists, refused or not, and must cost
+ * one manifest, not the plugin's whole tree. So this reader opens only the
+ * manifests present, takes what they say about appearance, and never
+ * reports a finding: an unreadable manifest contributes nothing, a wrong
+ * type is treated as absent, and the caller draws a fallback face.
+ *
+ * Which manifest speaks is the full reader's rule (`MANIFEST_PRECEDENCE`:
+ * the root manifest, then Claude, Cursor, Codex), so a plugin shipping two
+ * dialects is named the same way on a card and in an install. Identity
+ * fields (`name`, `version`, `description`, `author`) come from the first
+ * manifest that carries each; the presentation fields come from the
+ * dialects that define them: Cursor's top-level `displayName`, `logo` and
+ * `category`; the legacy Codex manifest's `interface.displayName`,
+ * `interface.logo` and `interface.category`; the open format's
+ * `extensions["ai.stigmer"]` with the same three names, the one place that
+ * format leaves a client for them (Stigmer's authored catalogue plugins are
+ * its first users). Claude Code's manifest defines none.
+ *
+ * A logo is a path inside the plugin, and the card that shows it fetches it
+ * by URL from wherever the tree lives. So the path is kept only when it is
+ * contained, names an image by extension, is LISTED in the tree, and its
+ * declared size is under `PLUGIN_DOCUMENT_LIMITS.logo`; the library's rule
+ * that a cap is checked from declared sizes before a byte moves holds here
+ * too. Both spellings the vendors use (`assets/logo.png`, `./assets/logo.png`)
+ * are accepted, as the marketplace reader accepts both for a source.
+ *
+ * `logo` stays an ignored component in the full read: nothing in an
+ * Organization carries the image after an install, and the preview's "Not
+ * installed" line is true until the stored plugin does.
+ */
+
+import { MANIFEST_PRECEDENCE } from "./detect.js";
+import { stigmerExtensionOf } from "./dialects/manifest.js";
+import { decodeUtf8, isContainedPath, PLUGIN_DOCUMENT_LIMITS, PluginFileIndex, type PluginFiles } from "./files.js";
+import { isJsonObject, type JsonObject } from "./documents.js";
+import { MANIFEST_LOCATIONS } from "./messages.js";
+import type { PluginAuthor, PluginDialect } from "./types.js";
+
+/** What a card shows for a plugin; every field optional, because every dialect may omit it. */
+export interface PluginPresentation {
+  /** The name for people (`Thermos`); the install name stays `name`. */
+  readonly displayName?: string;
+  /** A plugin-relative path to an image the tree lists, verified as described in the module header. */
+  readonly logo?: string;
+  readonly author?: PluginAuthor;
+  readonly version?: string;
+  readonly description?: string;
+  /** The catalogue's own grouping word (`developer-tools`, `Productivity`), as written. */
+  readonly category?: string;
+}
+
+/** The image extensions a browser renders in an `<img>`; a logo named otherwise is not shown. */
+const LOGO_EXTENSIONS: ReadonlySet<string> = new Set(["png", "svg", "jpg", "jpeg", "webp", "gif"]);
+
+/** The appearance fields of every manifest present, merged in precedence order. */
+export function readPluginPresentation(files: PluginFiles): PluginPresentation {
+  const index = new PluginFileIndex(files);
+  const presentation: { -readonly [K in keyof PluginPresentation]: PluginPresentation[K] } = {};
+
+  for (const dialect of MANIFEST_PRECEDENCE) {
+    const object = readManifest(index, MANIFEST_LOCATIONS[dialect]);
+    if (object === undefined) continue;
+    const contribution = contributionOf(dialect, object, index);
+    for (const key of Object.keys(contribution) as (keyof PluginPresentation)[]) {
+      if (presentation[key] === undefined) Object.assign(presentation, { [key]: contribution[key] });
+    }
+  }
+
+  return presentation;
+}
+
+/** The manifest at `path` as an object, or `undefined` for anything a card should not stumble on. */
+function readManifest(index: PluginFileIndex, path: string): JsonObject | undefined {
+  const entry = index.entry(path);
+  if (entry === undefined || entry.size > PLUGIN_DOCUMENT_LIMITS.manifest) return undefined;
+  let bytes: Uint8Array;
+  try {
+    bytes = index.files.read(path);
+  } catch {
+    return undefined;
+  }
+  if (bytes.length > PLUGIN_DOCUMENT_LIMITS.manifest) return undefined;
+  let value: unknown;
+  try {
+    value = JSON.parse(decodeUtf8(bytes));
+  } catch {
+    return undefined;
+  }
+  return isJsonObject(value) ? value : undefined;
+}
+
+function contributionOf(dialect: PluginDialect, object: JsonObject, index: PluginFileIndex): PluginPresentation {
+  const identity = identityOf(object);
+  switch (dialect) {
+    case "cursor":
+      return { ...identity, ...appearanceOf(object, index) };
+    case "codex": {
+      const surface = object["interface"];
+      return isJsonObject(surface) ? { ...identity, ...appearanceOf(surface, index) } : identity;
+    }
+    case "agent-plugins": {
+      const extension = stigmerExtensionOf(object);
+      return extension === undefined ? identity : { ...identity, ...appearanceOf(extension, index) };
+    }
+    case "claude":
+      return identity;
+    default: {
+      const exhaustive: never = dialect;
+      return exhaustive;
+    }
+  }
+}
+
+/** The identity fields every dialect shares, typed loosely: a wrong type is absent, never a finding. */
+function identityOf(object: JsonObject): PluginPresentation {
+  const author = authorOf(object["author"]);
+  return {
+    ...optional("version", object["version"]),
+    ...optional("description", object["description"]),
+    ...(author !== undefined && { author }),
+  };
+}
+
+/** `displayName`, `logo` and `category` from an object that carries them at its top level (a Cursor manifest, a Codex `interface`, an open manifest's `extensions["ai.stigmer"]`). */
+function appearanceOf(object: JsonObject, index: PluginFileIndex): PluginPresentation {
+  const logo = logoPath(object["logo"], index);
+  return {
+    ...optional("displayName", object["displayName"]),
+    ...optional("category", object["category"]),
+    ...(logo !== undefined && { logo }),
+  };
+}
+
+function authorOf(value: unknown): PluginAuthor | undefined {
+  if (!isJsonObject(value)) return undefined;
+  const author: { -readonly [K in keyof PluginAuthor]: PluginAuthor[K] } = {
+    ...optional("name", value["name"]),
+    ...optional("email", value["email"]),
+    ...optional("url", value["url"]),
+  };
+  return Object.keys(author).length === 0 ? undefined : author;
+}
+
+/**
+ * A declared logo as a plugin-relative path the tree lists, or nothing.
+ * `./` is stripped (Codex's spelling); an absolute path, a `..` segment, a
+ * URL, a non-image extension, an unlisted file or an over-cap file all
+ * mean "no logo", never a refusal.
+ */
+function logoPath(value: unknown, index: PluginFileIndex): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const path = value.startsWith("./") ? value.slice(2) : value;
+  if (!isContainedPath(path)) return undefined;
+  const dot = path.lastIndexOf(".");
+  if (dot === -1 || !LOGO_EXTENSIONS.has(path.slice(dot + 1).toLowerCase())) return undefined;
+  const entry = index.entry(path);
+  if (entry === undefined || entry.size > PLUGIN_DOCUMENT_LIMITS.logo) return undefined;
+  return path;
+}
+
+/** `{ [key]: value }` when `value` is a non-empty string; `{}` otherwise. */
+function optional<K extends string>(key: K, value: unknown): Partial<Record<K, string>> {
+  return typeof value === "string" && value !== "" ? ({ [key]: value } as Record<K, string>) : {};
+}