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

package/src/client.ts

@@ -15,13 +15,20 @@
  *   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 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 +56,23 @@ 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 {
+  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/index.ts

@@ -54,7 +54,7 @@ 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 {
   IgnoredComponent,

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}/`;