@stigmer/plugin-package 3.18.0-dev.20260918103812 → 3.18.1-dev.20260919070736

package/src/client/reroot.ts

@@ -0,0 +1,35 @@
+/**
+ * The one directory a zipped folder wraps itself in, so the archive reads
+ * as the folder.
+ *
+ * `zip -r plugin.zip my-plugin/`, a Finder "Compress", and a browser's
+ * download of a repository all produce an archive whose every path begins
+ * with the folder's own name; the manifest a reader looks for at the root
+ * is then one level down. This decides, from the paths alone, whether that
+ * is the case: it is when every path shares exactly one leading directory
+ * and nothing sits beside it. A tree with a root file, or two top-level
+ * directories, is taken as it is; a reader that then finds no manifest says
+ * so in its own words.
+ *
+ * Pure over paths; the caller strips the prefix. Kept out of `select.ts`,
+ * which reasons about a tree that already has its root.
+ */
+
+/** The shared leading directory of `paths`, or `null` when the tree is already rooted. */
+export function rerootSingleDirectory(paths: readonly string[]): string | null {
+  let prefix: string | null = null;
+  for (const path of paths) {
+    const slash = path.indexOf("/");
+    if (slash <= 0) return null;
+    const head = path.slice(0, slash);
+    if (prefix === null) prefix = head;
+    else if (prefix !== head) return null;
+  }
+  return prefix;
+}
+
+/** `paths` with `prefix/` removed from each; the caller has established every path carries it. */
+export function stripDirectoryPrefix(paths: readonly string[], prefix: string): string[] {
+  const cut = prefix.length + 1;
+  return paths.map((path) => path.slice(cut));
+}

package/src/client.ts

@@ -15,13 +15,22 @@
  *   order the CLI's original walk produced them;
  * - the archive and its digest (`archive.ts`): the deterministic zip and
  *   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
+ *   three vendors', listed by every client without configuration;
+ * - the release predicate (`release.ts`): which server versions the
+ *   catalogue is published for;
+ * - the re-rooting rule (`reroot.ts`): a zipped folder reads as the folder;
  * - the vocabulary (`vocabulary.ts`): the labels both surfaces print.
  *
  * Nothing here touches the filesystem, the network or any `node:*` module.
- * A client's edge (a directory walk, a fetch) produces the candidates and
- * the bytes; this entry decides what becomes of them.
+ * A client's edge (a directory walk, a fetch, a file pick) produces the
+ * candidates and the bytes; this entry decides what becomes of them.
  */
 
 export { DEFAULT_PATTERNS } from "./client/ignore/defaults.js";
@@ -49,6 +58,24 @@ export {
   selectPluginFiles,
 } from "./client/select.js";
 export { DETERMINISTIC_ZIP_MTIME, archivePlugin, digestArchive } from "./client/archive.js";
+export {
+  type LazyCandidate,
+  type PrepareArchiveOutcome,
+  type PrepareFromTreeOptions,
+  type PreparePluginOutcome,
+  type PreparedPlugin,
+  preparePluginArchive,
+  preparePluginFromTree,
+} from "./client/prepare.js";
+export { readPluginPresentationFromTree } from "./client/presentation.js";
+export {
+  type BuiltInMarketplace,
+  BUILT_IN_MARKETPLACES,
+  builtInSourceRefusal,
+  isBuiltInMarketplaceName,
+} from "./client/builtin.js";
+export { isReleaseVersion } from "./client/release.js";
+export { rerootSingleDirectory, stripDirectoryPrefix } from "./client/reroot.js";
 export {
   type GitHubMarketplaceSource,
   type GitHubSourceOutcome,

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/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
@@ -54,8 +55,9 @@ export type {
   MarketplaceReadOutcome,
   MarketplaceWarningKind,
 } from "./marketplace/outcome.js";
-export { hasMarketplaceFile, readMarketplace } from "./marketplace/read-marketplace.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/marketplace/read-marketplace.ts

@@ -25,6 +25,13 @@
  * `readPluginPackage`; a consumer that wants to install it hands the same
  * directory to the walker it already uses. Keeping the two reads apart is
  * what lets a catalogue of eighty entries be listed without eighty reads.
+ *
+ * `readMarketplaceFile` is the same read without the tree: what the file
+ * declares, for a client that holds the file alone and asks only "does this
+ * source offer a plugin called X" before it pays for the tree (the CLI's
+ * bare-name search across GitHub sources fetches one small file per source
+ * instead of a zipball each). Whether the tree holds an entry is still
+ * `readMarketplace`'s to say, on the tree, before anything is installed.
  */
 
 import { hasPluginManifest, isValidPluginName } from "../detect.js";
@@ -47,6 +54,24 @@ export function hasMarketplaceFile(paths: Iterable<string>): boolean {
 }
 
 export function readMarketplace(files: PluginFiles): MarketplaceReadOutcome {
+  return read(files, "tree");
+}
+
+/**
+ * The marketplace file as declared, the tree unverified: every entry with a
+ * readable source is offered, whether or not `files` holds its directory.
+ * For a client that has fetched the file alone; never for an install.
+ */
+export function readMarketplaceFile(files: PluginFiles): MarketplaceReadOutcome {
+  return read(files, "file");
+}
+
+/**
+ * `tree`: entries whose directory the tree lacks, or holds without a plugin
+ * manifest, are dropped with their warning. `file`: entries are taken as the
+ * file declares them, and the tree is not consulted.
+ */
+function read(files: PluginFiles, verify: "tree" | "file"): MarketplaceReadOutcome {
   const findings = new MarketplaceFindings();
   const index = new PluginFileIndex(files);
 
@@ -62,7 +87,7 @@ export function readMarketplace(files: PluginFiles): MarketplaceReadOutcome {
 
   const name = readName(object, path, findings);
   const raw = readEntries(object, dialect, path, findings);
-  const entries = offeredEntries(raw, index, path, findings);
+  const entries = verify === "tree" ? offeredEntries(raw, index, path, findings) : declaredEntries(raw);
   const defaults = resolveDefaults(object, raw, entries, dialect, path, findings);
 
   if (findings.errors.length > 0 || name === undefined) return refused(findings);
@@ -349,6 +374,20 @@ function offeredEntries(
   return offered;
 }
 
+/** Every entry with a readable source, as the file declares it; the tree is not asked. */
+function declaredEntries(raw: readonly RawEntry[]): readonly MarketplaceEntry[] {
+  const declared: MarketplaceEntry[] = [];
+  for (const entry of raw) {
+    if (entry.dir === undefined) continue;
+    declared.push({
+      name: entry.name,
+      dir: entry.dir,
+      ...(entry.description !== undefined && { description: entry.description }),
+    });
+  }
+  return declared;
+}
+
 /** The files under `dir` as plugin-relative paths, so `hasPluginManifest` reads them as it reads a plugin's own listing. */
 function childFilesOf(index: PluginFileIndex, dir: string): readonly string[] {
   const prefix = dir === "" ? "" : `${dir}/`;

package/src/presentation.ts

@@ -0,0 +1,165 @@
+/**
+ * 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`. Claude Code's manifest and the
+ * open format define none, and a logo rule for the `ai.stigmer` extension
+ * namespace waits for the first official plugin that needs one.
+ *
+ * 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 { 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":
+    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`). */
+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>) : {};
+}