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

package/src/__tests__/client-prepare.test.ts

@@ -0,0 +1,167 @@
+/**
+ * The one preparation, reached three ways, and the small rules beside it.
+ *
+ * Pins: `preparePluginFromTree` over a lazily-read tree yields the CLI's
+ * recorded digest for the thermos fixture (the tripwire constant lives in
+ * `client-select-archive.test.ts`); it reads only the ignore files and the
+ * selected entries, never an ignored file's bytes; an over-cap selection is
+ * refused before any selected byte is read; a reader refusal is returned
+ * with the reader's findings. `isReleaseVersion`'s five cases, the two
+ * wrong answers the console and the CLI used to give among them.
+ * `rerootSingleDirectory` on the shapes a zip takes. The built-in sources'
+ * order, their reserved names, and that the official one is first.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { BUILT_IN_MARKETPLACES, isBuiltInMarketplaceName } from "../client/builtin.js";
+import { type LazyCandidate, preparePluginFromTree } from "../client/prepare.js";
+import { OFFICIAL_MARKETPLACE_NAME } from "../client/refs.js";
+import { isReleaseVersion } from "../client/release.js";
+import { rerootSingleDirectory, stripDirectoryPrefix } from "../client/reroot.js";
+
+const FIXTURES = fileURLToPath(new URL("./fixtures/cursor-plugins/", import.meta.url));
+/** The CLI's digest for the thermos fixture, recorded in client-select-archive.test.ts. */
+const THERMOS_DIGEST = "51bc4e5450e24762bb8515765c76bfe262f65c57f9afeda015c5818038396d5a";
+
+const encoder = new TextEncoder();
+const SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+
+function manifest(name: string): string {
+  return JSON.stringify({ $schema: SCHEMA, name, version: "1.0.0", description: `the ${name} plugin` });
+}
+
+/** A directory as a lazily-read tree, recording which paths were read. */
+function lazyDirectory(root: string): { candidates: LazyCandidate[]; reads: string[] } {
+  const reads: string[] = [];
+  const candidates: LazyCandidate[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const full = `${dir}/${entry.name}`;
+      if (entry.isDirectory()) walk(full, path);
+      else if (entry.isFile()) {
+        candidates.push({
+          path,
+          size: statSync(full).size,
+          read: async () => {
+            reads.push(path);
+            return new Uint8Array(readFileSync(full));
+          },
+        });
+      }
+    }
+  };
+  walk(root, "");
+  return { candidates, reads };
+}
+
+function lazyMemory(files: Record<string, string>): { candidates: LazyCandidate[]; reads: string[] } {
+  const reads: string[] = [];
+  const candidates = Object.entries(files).map(([path, text]) => {
+    const bytes = encoder.encode(text);
+    return {
+      path,
+      size: bytes.length,
+      read: async () => {
+        reads.push(path);
+        return bytes;
+      },
+    };
+  });
+  return { candidates, reads };
+}
+
+describe("preparePluginFromTree", () => {
+  it("yields the CLI's digest for the thermos fixture from a lazily-read tree", async () => {
+    const { candidates } = lazyDirectory(`${FIXTURES}thermos`);
+    const outcome = await preparePluginFromTree(candidates, { respectGitignore: true });
+    expect(outcome.ok).toBe(true);
+    if (!outcome.ok) return;
+    expect(outcome.prepared.digest).toBe(THERMOS_DIGEST);
+    expect(outcome.prepared.plugin.name).toBe("thermos");
+    expect(outcome.prepared.stats.filesIncluded).toBe(10);
+  });
+
+  it("reads the ignore file and the selected entries only, never an ignored file's bytes", async () => {
+    const tree = lazyMemory({
+      ".gitignore": "secrets.txt\n",
+      "plugin.json": manifest("quiet"),
+      "node_modules/left-pad/index.js": "module.exports = 1;",
+      "secrets.txt": "hunter2",
+      "skills/greet/SKILL.md": "---\nname: greet\ndescription: says hello\n---\nHello.",
+    });
+    const outcome = await preparePluginFromTree(tree.candidates, { respectGitignore: true });
+    expect(outcome.ok).toBe(true);
+    expect(tree.reads.sort()).toEqual([".gitignore", "plugin.json", "skills/greet/SKILL.md"]);
+  });
+
+  it("refuses an over-cap selection before a selected byte is read", async () => {
+    const tree = lazyMemory({
+      "plugin.json": manifest("heavy"),
+      "skills/big/SKILL.md": "x".repeat(2_000),
+    });
+    const outcome = await preparePluginFromTree(tree.candidates, { respectGitignore: true, maxBytes: 1_000 });
+    expect(outcome).toMatchObject({ ok: false, kind: "too-large", maxBytes: 1_000 });
+    if (outcome.ok || outcome.kind !== "too-large") return;
+    expect(outcome.selectedBytes).toBeGreaterThan(1_000);
+    expect(tree.reads).toEqual([]);
+  });
+
+  it("returns the reader's refusal with its findings when the tree is not a plugin", async () => {
+    const tree = lazyMemory({ "README.md": "not a plugin" });
+    const outcome = await preparePluginFromTree(tree.candidates, { respectGitignore: true });
+    expect(outcome.ok).toBe(false);
+    if (outcome.ok || outcome.kind !== "refused") throw new Error("expected the reader's refusal");
+    expect(outcome.errors.length).toBeGreaterThan(0);
+  });
+});
+
+describe("isReleaseVersion", () => {
+  it("accepts a release and a pre-release the lockstep publish covers", () => {
+    expect(isReleaseVersion("3.17.0")).toBe(true);
+    // The console used to call this a development build.
+    expect(isReleaseVersion("3.17.0-rc.1")).toBe(true);
+  });
+
+  it("refuses every shape a source or dev-channel build reports", () => {
+    // The CLI used to accept the bare stamp an unbundled server reports.
+    expect(isReleaseVersion("dev")).toBe(false);
+    expect(isReleaseVersion("0.0.0-dev")).toBe(false);
+    expect(isReleaseVersion("3.17.0-dev.20260918120000")).toBe(false);
+    expect(isReleaseVersion("3.17.0+build.5")).toBe(false);
+    expect(isReleaseVersion("")).toBe(false);
+  });
+});
+
+describe("rerootSingleDirectory", () => {
+  it("names the one directory every path is under", () => {
+    const paths = ["my-plugin/plugin.json", "my-plugin/skills/a/SKILL.md", "my-plugin/.gitignore"];
+    expect(rerootSingleDirectory(paths)).toBe("my-plugin");
+    expect(stripDirectoryPrefix(paths, "my-plugin")).toEqual(["plugin.json", "skills/a/SKILL.md", ".gitignore"]);
+  });
+
+  it("leaves a tree that is already rooted, or has two roots, alone", () => {
+    expect(rerootSingleDirectory(["plugin.json", "skills/a/SKILL.md"])).toBeNull();
+    expect(rerootSingleDirectory(["a/plugin.json", "b/plugin.json"])).toBeNull();
+    expect(rerootSingleDirectory(["a/plugin.json", "README.md"])).toBeNull();
+    expect(rerootSingleDirectory([])).toBeNull();
+  });
+});
+
+describe("BUILT_IN_MARKETPLACES", () => {
+  it("lists the official catalogue first, then the three vendors, each a reserved name", () => {
+    expect(BUILT_IN_MARKETPLACES.map((entry) => entry.name)).toEqual([
+      OFFICIAL_MARKETPLACE_NAME,
+      "cursor-plugins",
+      "claude-code-plugins",
+      "codex-plugins",
+    ]);
+    expect(BUILT_IN_MARKETPLACES[0]?.source).toEqual({ type: "official" });
+    for (const entry of BUILT_IN_MARKETPLACES) expect(isBuiltInMarketplaceName(entry.name)).toBe(true);
+    expect(isBuiltInMarketplaceName("acme-plugins")).toBe(false);
+  });
+});

package/src/__tests__/marketplace.test.ts

@@ -15,7 +15,7 @@ import { describe, expect, it } from "vitest";
 
 import { inMemoryPluginFiles, PLUGIN_DOCUMENT_LIMITS, type PluginFileEntry, type PluginFiles } from "../files.js";
 import type { Marketplace, MarketplaceErrorKind, MarketplaceFinding, MarketplaceReadOutcome, MarketplaceWarningKind } from "../marketplace/outcome.js";
-import { hasMarketplaceFile, readMarketplace } from "../marketplace/read-marketplace.js";
+import { hasMarketplaceFile, readMarketplace, readMarketplaceFile } from "../marketplace/read-marketplace.js";
 import { cursorPlugin, openPlugin, type PluginFixture } from "../testing.js";
 import { directoryPluginFiles } from "../__test-utils__/directory-files.js";
 import { findingOf, type Kinds } from "../__test-utils__/read.js";
@@ -223,6 +223,18 @@ describe("the Cursor file, verbatim from cursor/plugins at c1c0a32, over a parti
     expect(new Set(outcome.warnings.map((w) => w.kind))).toEqual(new Set(["entry-directory-missing"]));
   });
 
+  it("read as a file alone, declares all seventy-nine with no directory warnings: the CLI's bare-name peek", () => {
+    const fileOnly = readMarketplaceFile(
+      inMemoryPluginFiles(new Map([[".cursor-plugin/marketplace.json", files.get(".cursor-plugin/marketplace.json")!]])),
+    );
+    const declared = accepted(fileOnly);
+    expect(declared.plugins).toHaveLength(79);
+    expect(declared.plugins.map((p) => p.name)).toContain("thermos");
+    expect(fileOnly.warnings.filter((w) => w.kind === "entry-directory-missing")).toEqual([]);
+    // Still refused for what the file itself gets wrong, exactly as the tree read is.
+    expect(readMarketplaceFile(inMemoryPluginFiles(new Map([["README.md", "x"]]))).ok).toBe(false);
+  });
+
   it("offers every entry when the whole catalogue is present (the sources all resolve inside the root)", () => {
     // Every source directory given one manifest, so the file's own shape is
     // proven independently of which plugins the fixtures vendor.

package/src/__tests__/presentation.test.ts

@@ -0,0 +1,161 @@
+/**
+ * The presentation read, the one a storefront card runs.
+ *
+ * Pins: the vendored Cursor fixtures yield their `displayName`, `logo`,
+ * `category` and author (thermos, a PNG; playwright, an SVG); a Codex
+ * manifest yields the same fields from `interface`, with the `./` spelling
+ * stripped; a Claude manifest and an open manifest yield identity only; a
+ * root manifest names the plugin ahead of a vendor manifest beside it,
+ * while the vendor manifest still lends its appearance; a logo that is
+ * absent from the listing, over the cap, not an image, a URL or an escape
+ * is dropped without a finding; an unparseable manifest contributes nothing
+ * and the read still answers. The lazy twin reads exactly the manifests
+ * listed and no other file, and treats a fetch that rejects as a manifest
+ * that is not there.
+ */
+
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { type LazyCandidate } from "../client/prepare.js";
+import { readPluginPresentationFromTree } from "../client/presentation.js";
+import { inMemoryPluginFiles, PLUGIN_DOCUMENT_LIMITS } from "../files.js";
+import { MANIFEST_LOCATIONS } from "../messages.js";
+import { readPluginPresentation } from "../presentation.js";
+import { claudePlugin, codexPlugin, cursorPlugin, openPlugin, withFile, type PluginFixture } from "../testing.js";
+import { directoryPluginFiles } from "../__test-utils__/directory-files.js";
+
+const FIXTURES = fileURLToPath(new URL("./fixtures/cursor-plugins/", import.meta.url));
+const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+
+function present(files: PluginFixture) {
+  return readPluginPresentation(inMemoryPluginFiles(files));
+}
+
+describe("readPluginPresentation over the vendored Cursor fixtures", () => {
+  it("thermos: display name, PNG logo, category, author", () => {
+    const presentation = readPluginPresentation(directoryPluginFiles(`${FIXTURES}thermos`));
+    expect(presentation).toEqual({
+      displayName: "Thermos",
+      logo: "assets/logo.png",
+      category: "developer-tools",
+      version: "1.0.0",
+      description: expect.stringContaining("Thermo-nuclear branch review"),
+      author: { name: "Cursor", email: "plugins@cursor.com" },
+    });
+  });
+
+  it("playwright: an SVG logo is an image too", () => {
+    const presentation = readPluginPresentation(directoryPluginFiles(`${FIXTURES}playwright`));
+    expect(presentation.displayName).toBe("Playwright");
+    expect(presentation.logo).toBe("assets/logo.svg");
+  });
+});
+
+describe("the dialects that carry appearance", () => {
+  it("a Cursor manifest speaks at its top level", () => {
+    const files = withFile(
+      cursorPlugin({ manifest: { displayName: "GitHub", logo: "assets/logo.png", category: "integrations", author: { name: "Cursor" } } }),
+      "assets/logo.png",
+      PNG_BYTES,
+    );
+    expect(present(files)).toMatchObject({ displayName: "GitHub", logo: "assets/logo.png", category: "integrations", author: { name: "Cursor" } });
+  });
+
+  it("a legacy Codex manifest speaks through `interface`, and `./` is stripped from its logo", () => {
+    const files = withFile(
+      codexPlugin({
+        version: "6.0.1",
+        manifest: { interface: { displayName: "Airtable", logo: "./assets/logo.png", category: "Productivity", developerName: "Airtable" } },
+      }),
+      "assets/logo.png",
+      PNG_BYTES,
+    );
+    expect(present(files)).toEqual({ displayName: "Airtable", logo: "assets/logo.png", category: "Productivity", version: "6.0.1" });
+  });
+
+  it("a Claude manifest and an open manifest yield identity only", () => {
+    expect(present(claudePlugin({ version: "1.0.0", description: "Reviews pull requests.", manifest: { author: { name: "Anthropic" } } }))).toEqual({
+      version: "1.0.0",
+      description: "Reviews pull requests.",
+      author: { name: "Anthropic" },
+    });
+    const open = present(openPlugin({ version: "2.0.0", description: "The assistant." }));
+    expect(open.displayName).toBeUndefined();
+    expect(open.logo).toBeUndefined();
+    expect(open.version).toBe("2.0.0");
+  });
+
+  it("a root manifest names the plugin first; a vendor manifest beside it still lends its appearance", () => {
+    let files = openPlugin({ version: "3.0.0", description: "From the root manifest." });
+    files = withFile(
+      files,
+      MANIFEST_LOCATIONS.cursor,
+      JSON.stringify({ name: "plugin", version: "1.0.0", description: "From the Cursor manifest.", displayName: "Plugin", logo: "assets/logo.png" }),
+    );
+    files = withFile(files, "assets/logo.png", PNG_BYTES);
+    expect(present(files)).toMatchObject({ version: "3.0.0", description: "From the root manifest.", displayName: "Plugin", logo: "assets/logo.png" });
+  });
+});
+
+describe("a logo that cannot be shown is no logo, never a finding", () => {
+  const cases: readonly [string, string, PluginFixture | undefined][] = [
+    ["not listed", "assets/missing.png", undefined],
+    ["a URL", "https://example.com/logo.png", undefined],
+    ["an escape", "../logo.png", undefined],
+    ["not an image", "assets/logo.txt", withFile(cursorPlugin(), "assets/logo.txt", "text")],
+    ["over the cap", "assets/huge.png", withFile(cursorPlugin(), "assets/huge.png", new Uint8Array(PLUGIN_DOCUMENT_LIMITS.logo + 1))],
+  ];
+  for (const [label, logo, base] of cases) {
+    it(label, () => {
+      const files = withFile(base ?? cursorPlugin(), MANIFEST_LOCATIONS.cursor, JSON.stringify({ name: "plugin", displayName: "Plugin", logo }));
+      const presentation = present(files);
+      expect(presentation.displayName).toBe("Plugin");
+      expect(presentation.logo).toBeUndefined();
+    });
+  }
+
+  it("a wrong type is absent", () => {
+    const files = withFile(cursorPlugin(), MANIFEST_LOCATIONS.cursor, JSON.stringify({ name: "plugin", displayName: 7, logo: ["assets/logo.png"], author: "Cursor" }));
+    expect(present(files)).toEqual({});
+  });
+
+  it("an unparseable manifest contributes nothing and the read answers", () => {
+    const files = withFile(cursorPlugin({ version: "1.0.0" }), MANIFEST_LOCATIONS.cursor, "{ not json");
+    expect(present(files)).toEqual({});
+  });
+});
+
+describe("readPluginPresentationFromTree", () => {
+  function lazy(files: PluginFixture, reads: string[], failing: ReadonlySet<string> = new Set()): LazyCandidate[] {
+    const encoder = new TextEncoder();
+    return [...files.entries()].map(([path, content]) => {
+      const bytes = typeof content === "string" ? encoder.encode(content) : content;
+      return {
+        path,
+        size: bytes.length,
+        read: async () => {
+          reads.push(path);
+          if (failing.has(path)) throw new Error(`cannot read ${path}`);
+          return bytes;
+        },
+      };
+    });
+  }
+
+  it("reads exactly the manifests listed and no other file", async () => {
+    const reads: string[] = [];
+    const files = withFile(cursorPlugin({ manifest: { displayName: "Thermos", logo: "assets/logo.png" }, skills: [{ name: "review" }] }), "assets/logo.png", PNG_BYTES);
+    const presentation = await readPluginPresentationFromTree(lazy(files, reads));
+    expect(presentation).toMatchObject({ displayName: "Thermos", logo: "assets/logo.png" });
+    expect(reads).toEqual([MANIFEST_LOCATIONS.cursor]);
+  });
+
+  it("a manifest whose fetch rejects is a manifest that is not there", async () => {
+    const reads: string[] = [];
+    const files = cursorPlugin({ manifest: { displayName: "Thermos" } });
+    const presentation = await readPluginPresentationFromTree(lazy(files, reads, new Set([MANIFEST_LOCATIONS.cursor])));
+    expect(presentation).toEqual({});
+  });
+});

package/src/client/builtin.ts

@@ -0,0 +1,79 @@
+/**
+ * The sources every client lists without being told: Stigmer's official
+ * catalogue and the three vendors' public ones.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+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. */
+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. */
+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));
+
+/** Whether `name` is one a user may neither add nor remove. */
+export function isBuiltInMarketplaceName(name: string): boolean {
+  return BUILT_IN_NAMES.has(name);
+}
+
+/** The one sentence every client refuses with when a user tries to add over or remove a built-in source. */
+export function builtInSourceRefusal(name: string, act: "add" | "remove"): string {
+  switch (act) {
+    case "add":
+      return `'${name}' is a built-in source and cannot be added or replaced; choose another name`;
+    case "remove":
+      return `'${name}' is a built-in source and cannot be removed`;
+    default: {
+      const exhaustive: never = act;
+      return exhaustive;
+    }
+  }
+}

package/src/client/prepare.ts

@@ -0,0 +1,160 @@
+/**
+ * The preparation every client runs once it holds a tree: select the files
+ * a push carries, read the package and refuse what the reader refuses,
+ * archive, digest.
+ *
+ * Three clients arrive here with three kinds of tree: the CLI with a
+ * directory on disk, the console with a marketplace host's file listing,
+ * and the console again with a folder or a zip the user picked. What they
+ * do after selection is identical, and it is where the plugin's identity
+ * is made (the archive's bytes are `status.digest`), so it is written once.
+ * A parity test proves that one function reached three ways yields one
+ * digest for one tree; before this module each client carried its own copy
+ * of the chain and the test proved a coincidence.
+ *
+ * `preparePluginFromTree` is the lazy form for a tree whose bytes cost
+ * something to obtain (a fetch per file, a `File.arrayBuffer()`): it reads
+ * the two root ignore files, selects, refuses an over-cap selection before
+ * another byte moves, then reads only the files the archive will carry. A
+ * plugin folder holding a `node_modules/` costs its ignore file and its
+ * manifest, wherever the tree lives. The CLI keeps its own walk (a
+ * filesystem lets it skip a directory before listing it, which a flat tree
+ * cannot) and joins at `preparePluginArchive`.
+ *
+ * Refusals are returned, not thrown: each client renders the reader's
+ * findings in its own voice (the CLI's `pluginRefusal`, the console's
+ * `PluginReadRefusal`) and adds its own provenance around the result.
+ */
+
+import type { PluginFiles } from "../files.js";
+import type { PluginFinding } from "../outcome.js";
+import { readPluginPackage } from "../read-plugin-package.js";
+import type { PluginPackage } from "../types.js";
+import { archivePlugin, digestArchive } from "./archive.js";
+import {
+  type CandidateFile,
+  type SelectPluginFilesOptions,
+  type SelectionStats,
+  IGNORE_FILE_NAMES,
+  selectPluginFiles,
+} from "./select.js";
+
+/** What a client holds after preparation: the package as read, the bytes a push sends, and their identity. */
+export interface PreparedPlugin {
+  readonly plugin: PluginPackage;
+  readonly warnings: readonly PluginFinding[];
+  /** The selected files, for the client that lists them (`push --dry-run`). */
+  readonly files: PluginFiles;
+  readonly stats: SelectionStats;
+  /** The exact bytes a push sends. */
+  readonly archive: Uint8Array;
+  /**
+   * SHA-256 of `archive`, lowercase hex: the identity the server records as
+   * `status.digest` (its digest is over the bytes it receives, and these are
+   * those bytes), so a client knows "already installed" without pushing.
+   */
+  readonly digest: string;
+}
+
+/** What an already-selected tree can come to: a prepared plugin, or the reader's refusal. */
+export type PrepareArchiveOutcome =
+  | { readonly ok: true; readonly prepared: PreparedPlugin }
+  /** The reader refused the package; `errors` are its sentences, as `stigmer validate -f` prints them. */
+  | {
+      readonly ok: false;
+      readonly kind: "refused";
+      readonly errors: readonly PluginFinding[];
+      readonly warnings: readonly PluginFinding[];
+    };
+
+/** What a lazily-read tree can come to: the above, or a refusal on size before its bytes were read. */
+export type PreparePluginOutcome =
+  | PrepareArchiveOutcome
+  /** The selected files exceed the caller's `maxBytes`; nothing beyond the ignore files was read. */
+  | { readonly ok: false; readonly kind: "too-large"; readonly selectedBytes: number; readonly maxBytes: number };
+
+/** A tree the client can list now and read later: a candidate with the promise of its bytes. */
+export interface LazyCandidate extends CandidateFile {
+  read(): Promise<Uint8Array>;
+}
+
+export interface PrepareFromTreeOptions extends SelectPluginFilesOptions {
+  /**
+   * The most bytes the SELECTED files may total, refused before they are
+   * read. A client states its own budget (the console's is the archive cap
+   * a browser will hold in memory); omitted, nothing is refused here and
+   * the server's zip gate is the only limit.
+   */
+  readonly maxBytes?: number;
+}
+
+/**
+ * Read, refuse, archive and digest an already-selected tree. `selection`
+ * is what `selectPluginFiles` returns or what the CLI's walk builds in the
+ * same shape; its `files.read` must answer synchronously for every listed
+ * entry by now.
+ */
+export async function preparePluginArchive(selection: {
+  readonly files: PluginFiles;
+  readonly stats: SelectionStats;
+}): Promise<PrepareArchiveOutcome> {
+  const outcome = readPluginPackage(selection.files);
+  if (!outcome.ok) {
+    return { ok: false, kind: "refused", errors: outcome.errors, warnings: outcome.warnings };
+  }
+  const archive = archivePlugin(selection.files);
+  return {
+    ok: true,
+    prepared: {
+      plugin: outcome.plugin,
+      warnings: outcome.warnings,
+      files: selection.files,
+      stats: selection.stats,
+      archive,
+      digest: await digestArchive(archive),
+    },
+  };
+}
+
+/**
+ * Prepare a tree whose bytes are obtained on demand. A byte is read only
+ * for a file that will be in the archive (plus the two root ignore files
+ * that decide which those are), and an over-cap selection is refused
+ * before any of them.
+ */
+export async function preparePluginFromTree(
+  candidates: readonly LazyCandidate[],
+  options: PrepareFromTreeOptions,
+): Promise<PreparePluginOutcome> {
+  const byPath = new Map(candidates.map((candidate) => [candidate.path, candidate]));
+  const contents = new Map<string, Uint8Array>();
+  const fetchInto = async (path: string): Promise<void> => {
+    const candidate = byPath.get(path);
+    if (candidate === undefined) throw new Error(`plugin file '${path}' is not listed`);
+    contents.set(path, await candidate.read());
+  };
+  const read = (path: string): Uint8Array => {
+    const bytes = contents.get(path);
+    if (bytes === undefined) throw new Error(`plugin file '${path}' was not read before selection asked for it`);
+    return bytes;
+  };
+
+  // Phase 1: only the two files that shape the selection.
+  await Promise.all(
+    [IGNORE_FILE_NAMES.gitignore, IGNORE_FILE_NAMES.stigmerignore]
+      .filter((name) => byPath.has(name))
+      .map((name) => fetchInto(name)),
+  );
+  const { maxBytes, ...selectOptions } = options;
+  const selection = selectPluginFiles(candidates, read, selectOptions);
+
+  if (maxBytes !== undefined && selection.stats.totalSize > maxBytes) {
+    return { ok: false, kind: "too-large", selectedBytes: selection.stats.totalSize, maxBytes };
+  }
+
+  // Phase 2: exactly the files the archive carries.
+  await Promise.all(
+    selection.files.entries.filter((entry) => !contents.has(entry.path)).map((entry) => fetchInto(entry.path)),
+  );
+  return preparePluginArchive(selection);
+}

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/release.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether a version string names a release the lockstep publish covers.
+ *
+ * The official catalogue (`@stigmer/plugins`) and the runtime packages are
+ * published at every release version and at every pre-release the release
+ * lane cuts (`X.Y.Z-rc.1` under the `next` tag), never for a source build
+ * (`dev`, `0.0.0-dev`) or a dev-channel stamp (`X.Y.Z-dev.<stamp>`). Two
+ * clients used to answer this with two different tests: the console
+ * accepted only `X.Y.Z` and called an `rc` server a development build; the
+ * CLI accepted anything without `-dev` and would have tried to acquire
+ * packages for the bare `dev` an unbundled server reports. One predicate,
+ * five cases pinned, no third opinion.
+ */
+
+/**
+ * A semver core, optionally followed by a pre-release whose first
+ * identifier is not `dev`. Build metadata (`+…`) is not accepted: nothing
+ * publishes with it.
+ */
+const RELEASE_PATTERN = /^\d+\.\d+\.\d+(?:-(?!dev(?:[.-]|$))[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+/** True for `3.17.0` and `3.17.0-rc.1`; false for `dev`, `0.0.0-dev` and `3.17.0-dev.20260918120000`. */
+export function isReleaseVersion(version: string): boolean {
+  return RELEASE_PATTERN.test(version);
+}