@stigmer/plugin-package 3.16.0 → 3.17.0

package/src/marketplace/read-marketplace.ts

@@ -0,0 +1,402 @@
+/**
+ * The marketplace entry: a `PluginFiles` over a marketplace tree in, a
+ * `MarketplaceReadOutcome` out.
+ *
+ * The read is a fixed sequence, like the plugin read: locate the marketplace
+ * file (first present in the dialect precedence, and only that one is read;
+ * a tree that carries two dialects' files describes one catalogue twice);
+ * parse it under the marketplace cap; read the dialect's shape into the one
+ * normalised shape; validate names and sources; drop the entries the tree
+ * cannot install, each with its own warning; resolve the defaults. Findings
+ * are collected and the read continues, so the outcome names every problem
+ * at once, and the marketplace is returned only when nothing refused.
+ *
+ * Sources. Every dialect names a plugin's directory relative to the
+ * marketplace root (Claude and Codex with a `./` prefix, Cursor without,
+ * Claude optionally under `metadata.pluginRoot`); the reader accepts both
+ * spellings and refuses a path that escapes the root. A source that is not
+ * such a directory (Claude's `github`, `url`, `npm` and `git-subdir` objects,
+ * Codex's non-`local` sources, Cursor's remote URLs) is a form this reader
+ * does not fetch: the entry is dropped with `entry-source-unsupported`, and
+ * nothing is invented in its place.
+ *
+ * This reader does not open the plugins it lists. A consumer that wants an
+ * entry's own description or version reads that directory with
+ * `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.
+ */
+
+import { hasPluginManifest, isValidPluginName } from "../detect.js";
+import { describeValue, isJsonObject, isStringArray, type JsonObject } from "../documents.js";
+import { decodeUtf8, isContainedPath, PLUGIN_DOCUMENT_LIMITS, PluginFileIndex, type PluginFiles } from "../files.js";
+import { MARKETPLACE_LOCATIONS, MarketplaceFindings } from "./messages.js";
+import type { Marketplace, MarketplaceDialect, MarketplaceEntry, MarketplaceOwner, MarketplaceReadOutcome } from "./outcome.js";
+
+/** The precedence the reader applies when a tree carries more than one marketplace file. */
+const DIALECT_PRECEDENCE: readonly MarketplaceDialect[] = ["stigmer", "claude", "cursor", "codex"];
+
+/** Codex's per-entry install policy that marks a default. */
+const CODEX_INSTALLED_BY_DEFAULT = "INSTALLED_BY_DEFAULT";
+
+/** True when the tree holds any of the four marketplace files; the CLI's routing test. */
+export function hasMarketplaceFile(paths: Iterable<string>): boolean {
+  const locations = new Set<string>(Object.values(MARKETPLACE_LOCATIONS));
+  for (const path of paths) if (locations.has(path)) return true;
+  return false;
+}
+
+export function readMarketplace(files: PluginFiles): MarketplaceReadOutcome {
+  const findings = new MarketplaceFindings();
+  const index = new PluginFileIndex(files);
+
+  const located = locate(index);
+  if (located === undefined) {
+    findings.error("marketplace-not-found");
+    return refused(findings);
+  }
+  const { dialect, path } = located;
+
+  const object = readObject(index, path, findings);
+  if (object === undefined) return refused(findings);
+
+  const name = readName(object, path, findings);
+  const raw = readEntries(object, dialect, path, findings);
+  const entries = offeredEntries(raw, index, path, findings);
+  const defaults = resolveDefaults(object, raw, entries, dialect, path, findings);
+
+  if (findings.errors.length > 0 || name === undefined) return refused(findings);
+
+  const description = readDescription(object, dialect);
+  const owner = readOwner(object);
+  const marketplace: Marketplace = {
+    name,
+    ...(description !== undefined && { description }),
+    ...(owner !== undefined && { owner }),
+    dialect,
+    path,
+    plugins: entries,
+    defaults,
+  };
+  return { ok: true, marketplace, warnings: findings.warnings };
+}
+
+function refused(findings: MarketplaceFindings): MarketplaceReadOutcome {
+  return { ok: false, errors: findings.errors, warnings: findings.warnings };
+}
+
+function locate(index: PluginFileIndex): { dialect: MarketplaceDialect; path: string } | undefined {
+  for (const dialect of DIALECT_PRECEDENCE) {
+    const path = MARKETPLACE_LOCATIONS[dialect];
+    if (index.has(path)) return { dialect, path };
+  }
+  return undefined;
+}
+
+function readObject(index: PluginFileIndex, path: string, findings: MarketplaceFindings): JsonObject | undefined {
+  const limit = PLUGIN_DOCUMENT_LIMITS.marketplace;
+  const entry = index.entry(path);
+  if (entry === undefined) {
+    throw new Error(`marketplace file '${path}' is not listed`);
+  }
+  if (entry.size > limit) {
+    findings.error("marketplace-too-large", { path, subject: String(entry.size), detail: String(limit) });
+    return undefined;
+  }
+  const bytes = index.files.read(path);
+  if (bytes.length > limit) {
+    findings.error("marketplace-too-large", { path, subject: String(bytes.length), detail: String(limit) });
+    return undefined;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(decodeUtf8(bytes));
+  } catch (error) {
+    findings.error("marketplace-unreadable", { path, detail: error instanceof Error ? error.message : String(error) });
+    return undefined;
+  }
+  if (!isJsonObject(value)) {
+    findings.error("marketplace-unreadable", { path, detail: "the document is not a JSON object" });
+    return undefined;
+  }
+  return value;
+}
+
+/** The marketplace's own name, validated under the plugin name rule (the same characters an install ref can carry). */
+function readName(object: JsonObject, path: string, findings: MarketplaceFindings): string | undefined {
+  const value = object["name"];
+  if (value === undefined) {
+    findings.error("marketplace-name-missing", { path });
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    findings.error("marketplace-field-type", { path, subject: "name", detail: "a string" });
+    return undefined;
+  }
+  if (!isValidPluginName(value)) {
+    findings.error("marketplace-name-invalid", { path, subject: value });
+    return undefined;
+  }
+  return value;
+}
+
+function readDescription(object: JsonObject, dialect: MarketplaceDialect): string | undefined {
+  switch (dialect) {
+    case "stigmer":
+      return optionalStringOf(object, "description");
+    case "claude":
+    case "cursor": {
+      const metadata = object["metadata"];
+      return isJsonObject(metadata) ? optionalStringOf(metadata, "description") : undefined;
+    }
+    case "codex":
+      // Codex's `interface.displayName` is a label for a picker, not a description.
+      return undefined;
+    default: {
+      const exhaustive: never = dialect;
+      return exhaustive;
+    }
+  }
+}
+
+function readOwner(object: JsonObject): MarketplaceOwner | undefined {
+  const value = object["owner"];
+  if (!isJsonObject(value)) return undefined;
+  const name = optionalStringOf(value, "name");
+  const email = optionalStringOf(value, "email");
+  const url = optionalStringOf(value, "url");
+  if (name === undefined && email === undefined && url === undefined) return undefined;
+  return {
+    ...(name !== undefined && { name }),
+    ...(email !== undefined && { email }),
+    ...(url !== undefined && { url }),
+  };
+}
+
+/** A string field or `undefined`; a field of another type is treated as absent (metadata never refuses a catalogue). */
+function optionalStringOf(object: JsonObject, field: string): string | undefined {
+  const value = object[field];
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * One entry as the file states it, before the tree is consulted. `dir` is
+ * the resolved marketplace-relative directory, or `undefined` when the
+ * source is a form this reader does not fetch (the warning is recorded here
+ * so the entry's order in the file is kept for the sentence).
+ */
+interface RawEntry {
+  readonly name: string;
+  readonly dir: string | undefined;
+  readonly description?: string;
+  readonly installedByDefault: boolean;
+}
+
+function readEntries(object: JsonObject, dialect: MarketplaceDialect, path: string, findings: MarketplaceFindings): readonly RawEntry[] {
+  const list = object["plugins"];
+  if (list === undefined) {
+    findings.error("marketplace-plugins-missing", { path });
+    return [];
+  }
+  if (!Array.isArray(list)) {
+    findings.error("marketplace-field-type", { path, subject: "plugins", detail: "an array" });
+    return [];
+  }
+  const pluginRoot = dialect === "claude" ? claudePluginRoot(object) : "";
+
+  const entries: RawEntry[] = [];
+  const seen = new Set<string>();
+  list.forEach((item: unknown, position: number) => {
+    if (!isJsonObject(item)) {
+      findings.error("entry-shape", { path, subject: String(position) });
+      return;
+    }
+    const name = item["name"];
+    if (name === undefined) {
+      findings.error("entry-name-missing", { path, subject: String(position) });
+      return;
+    }
+    if (typeof name !== "string" || !isValidPluginName(name)) {
+      findings.error("entry-name-invalid", { path, subject: describeValue(name) });
+      return;
+    }
+    if (seen.has(name)) {
+      findings.error("entry-name-duplicate", { path, subject: name });
+      return;
+    }
+    seen.add(name);
+
+    const description = optionalStringOf(item, "description");
+    entries.push({
+      name,
+      dir: resolveSource(item["source"], name, pluginRoot, path, findings),
+      ...(description !== undefined && { description }),
+      installedByDefault: dialect === "codex" && codexInstalledByDefault(item),
+    });
+  });
+  return entries;
+}
+
+/** Claude's `metadata.pluginRoot`, prepended to every relative source; the empty string when absent or unusable. */
+function claudePluginRoot(object: JsonObject): string {
+  const metadata = object["metadata"];
+  if (!isJsonObject(metadata)) return "";
+  const root = optionalStringOf(metadata, "pluginRoot");
+  if (root === undefined) return "";
+  const resolved = relativeDirectory(root);
+  return resolved.ok ? resolved.dir : "";
+}
+
+function codexInstalledByDefault(item: JsonObject): boolean {
+  const policy = item["policy"];
+  return isJsonObject(policy) && policy["installation"] === CODEX_INSTALLED_BY_DEFAULT;
+}
+
+/**
+ * A source becomes a marketplace-relative directory or nothing. A string is
+ * a relative directory (with or without `./`) unless it is a URL; Codex's
+ * `{source: "local", path}` object is the same directory; every other
+ * object form is a remote this reader does not fetch.
+ */
+function resolveSource(
+  source: unknown,
+  entryName: string,
+  pluginRoot: string,
+  path: string,
+  findings: MarketplaceFindings,
+): string | undefined {
+  if (source === undefined) {
+    findings.error("entry-source-missing", { path, subject: entryName });
+    return undefined;
+  }
+  let candidate: string | undefined;
+  if (typeof source === "string") {
+    if (isUrl(source)) {
+      findings.warn("entry-source-unsupported", { path, subject: entryName, detail: source });
+      return undefined;
+    }
+    candidate = source;
+  } else if (isJsonObject(source) && source["source"] === "local" && typeof source["path"] === "string") {
+    candidate = source["path"];
+  } else {
+    findings.warn("entry-source-unsupported", { path, subject: entryName, detail: describeSource(source) });
+    return undefined;
+  }
+
+  const resolved = relativeDirectory(candidate);
+  if (!resolved.ok) {
+    findings.error("entry-source-escapes-root", { path, subject: entryName, detail: candidate });
+    return undefined;
+  }
+  return joinDirectories(pluginRoot, resolved.dir);
+}
+
+/** The `source` discriminator of a remote object, or the whole value, for the sentence. */
+function describeSource(source: unknown): string {
+  if (isJsonObject(source) && typeof source["source"] === "string") return source["source"];
+  return describeValue(source);
+}
+
+function isUrl(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+type RelativeDirectory = { readonly ok: true; readonly dir: string } | { readonly ok: false };
+
+/**
+ * `./thermos`, `thermos`, `third_party/github/`, `.` and `./` all name a
+ * directory inside the root (the root itself is the empty string); an
+ * absolute path, a backslash, or a `..` segment does not.
+ */
+function relativeDirectory(value: string): RelativeDirectory {
+  let trimmed = value;
+  if (trimmed === "." || trimmed === "./") return { ok: true, dir: "" };
+  if (trimmed.startsWith("./")) trimmed = trimmed.slice(2);
+  trimmed = trimmed.replace(/\/+$/, "");
+  if (trimmed === "") return { ok: true, dir: "" };
+  return isContainedPath(trimmed) ? { ok: true, dir: trimmed } : { ok: false };
+}
+
+function joinDirectories(root: string, dir: string): string {
+  if (root === "") return dir;
+  return dir === "" ? root : `${root}/${dir}`;
+}
+
+/** The entries the tree can install: a directory that exists and holds a plugin manifest at its root. */
+function offeredEntries(
+  raw: readonly RawEntry[],
+  index: PluginFileIndex,
+  path: string,
+  findings: MarketplaceFindings,
+): readonly MarketplaceEntry[] {
+  const offered: MarketplaceEntry[] = [];
+  for (const entry of raw) {
+    if (entry.dir === undefined) continue;
+    if (!index.isDirectory(entry.dir)) {
+      findings.warn("entry-directory-missing", { path, subject: entry.name, detail: entry.dir === "" ? "." : entry.dir });
+      continue;
+    }
+    if (!hasPluginManifest(childFilesOf(index, entry.dir))) {
+      findings.warn("entry-not-a-plugin", { path, subject: entry.name, detail: entry.dir === "" ? "." : entry.dir });
+      continue;
+    }
+    offered.push({
+      name: entry.name,
+      dir: entry.dir,
+      ...(entry.description !== undefined && { description: entry.description }),
+    });
+  }
+  return offered;
+}
+
+/** 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}/`;
+  return index.filesUnder(dir).map((file) => file.slice(prefix.length));
+}
+
+/**
+ * The defaults, in install order: Stigmer's `defaults` list, or Codex's
+ * `INSTALLED_BY_DEFAULT` entries in file order. A default that names no
+ * listed entry refuses the file; a default whose entry the tree could not
+ * offer is dropped silently, because that entry's own warning already says
+ * why it is missing.
+ */
+function resolveDefaults(
+  object: JsonObject,
+  raw: readonly RawEntry[],
+  offered: readonly MarketplaceEntry[],
+  dialect: MarketplaceDialect,
+  path: string,
+  findings: MarketplaceFindings,
+): readonly string[] {
+  const listed = new Set(raw.map((entry) => entry.name));
+  const offeredNames = new Set(offered.map((entry) => entry.name));
+
+  let named: readonly string[];
+  if (dialect === "stigmer") {
+    const value = object["defaults"];
+    if (value === undefined) {
+      named = [];
+    } else if (!isStringArray(value)) {
+      findings.error("marketplace-field-type", { path, subject: "defaults", detail: "an array of strings" });
+      named = [];
+    } else {
+      named = value;
+    }
+  } else if (dialect === "codex") {
+    named = raw.filter((entry) => entry.installedByDefault).map((entry) => entry.name);
+  } else {
+    named = [];
+  }
+
+  const defaults: string[] = [];
+  for (const name of named) {
+    if (!listed.has(name)) {
+      findings.error("default-unknown", { path, subject: name });
+      continue;
+    }
+    if (offeredNames.has(name) && !defaults.includes(name)) defaults.push(name);
+  }
+  return defaults;
+}

package/src/messages.ts

@@ -11,13 +11,7 @@
  * kind unions, so a kind without a sentence does not compile.
  */
 
-import type {
-  FindingContext,
-  PluginErrorKind,
-  PluginFinding,
-  PluginFindingKind,
-  PluginWarningKind,
-} from "./outcome.js";
+import type { Finding, FindingContext, PluginErrorKind, PluginFindingKind, PluginWarningKind } from "./outcome.js";
 
 /** The canonical `$schema` identifiers the open format pins per version. */
 export const AGENT_PLUGINS_MANIFEST_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
@@ -31,10 +25,12 @@ export const MANIFEST_LOCATIONS = {
   codex: ".codex-plugin/plugin.json",
 } as const;
 
-const q = (value: string | undefined): string => `'${value ?? ""}'`;
-const at = (path: string | undefined): string => (path === undefined ? "" : ` in ${q(path)}`);
+/** Single-quote an identifier for a sentence (the ts-server quoting rule); shared with the marketplace vocabulary. */
+export const q = (value: string | undefined): string => `'${value ?? ""}'`;
+/** ` in '<path>'`, or nothing when the finding names no file. */
+export const at = (path: string | undefined): string => (path === undefined ? "" : ` in ${q(path)}`);
 
-type Sentence = (ctx: FindingContext) => string;
+export type Sentence = (ctx: FindingContext) => string;
 
 const ERROR_MESSAGES: Record<PluginErrorKind, Sentence> = {
   "no-manifest": () =>
@@ -175,27 +171,44 @@ export function isErrorKind(kind: PluginFindingKind): kind is PluginErrorKind {
   return kind in ERROR_MESSAGES;
 }
 
+/** A sentence table over a closed kind vocabulary; `Record` so a kind without a sentence does not compile. */
+export type SentenceTable<K extends string> = Readonly<Record<K, Sentence>>;
+
 /**
- * Collects findings while a read proceeds. The reader never throws on a
- * plugin's content: every problem becomes a finding here, and the read
- * continues so the outcome carries them all.
+ * Collects findings while a read proceeds. A reader never throws on the
+ * content it reads: every problem becomes a finding here, and the read
+ * continues so the outcome carries them all. Generic over the two kind
+ * vocabularies so the plugin reader and the marketplace reader share one
+ * collector and one finding shape while each owns its sentences.
  */
-export class Findings {
-  readonly errors: PluginFinding[] = [];
-  readonly warnings: PluginFinding[] = [];
+export class FindingCollector<E extends string, W extends string> {
+  readonly errors: Finding<E>[] = [];
+  readonly warnings: Finding<W>[] = [];
+
+  constructor(
+    private readonly errorSentences: SentenceTable<E>,
+    private readonly warningSentences: SentenceTable<W>,
+  ) {}
 
-  error(kind: PluginErrorKind, ctx: FindingContext = {}): void {
-    this.errors.push(compose(kind, ctx, errorMessage(kind, ctx)));
+  error(kind: E, ctx: FindingContext = {}): void {
+    this.errors.push(compose(kind, ctx, this.errorSentences[kind](ctx)));
   }
 
-  warn(kind: PluginWarningKind, ctx: FindingContext = {}): void {
-    this.warnings.push(compose(kind, ctx, warningMessage(kind, ctx)));
+  warn(kind: W, ctx: FindingContext = {}): void {
+    this.warnings.push(compose(kind, ctx, this.warningSentences[kind](ctx)));
+  }
+}
+
+/** The plugin reader's collector, bound to the plugin vocabulary. */
+export class Findings extends FindingCollector<PluginErrorKind, PluginWarningKind> {
+  constructor() {
+    super(ERROR_MESSAGES, WARNING_MESSAGES);
   }
 }
 
 // Optional fields are omitted rather than set to `undefined` so a finding
 // serialises to JSON without `null`s and compares structurally in tests.
-function compose(kind: PluginFindingKind, ctx: FindingContext, message: string): PluginFinding {
+function compose<K extends string>(kind: K, ctx: FindingContext, message: string): Finding<K> {
   return {
     kind,
     ...(ctx.path !== undefined && { path: ctx.path }),

package/src/outcome.ts

@@ -102,20 +102,28 @@ export type PluginWarningKind =
 
 export type PluginFindingKind = PluginErrorKind | PluginWarningKind;
 
-export interface PluginFinding {
-  readonly kind: PluginFindingKind;
+/**
+ * One finding over any closed kind vocabulary. The plugin reader and the
+ * marketplace reader (`marketplace/`) each own a vocabulary and a sentence
+ * table; the shape of a finding, and the renderer that prints one, are
+ * shared through this type.
+ */
+export interface Finding<K extends string> {
+  readonly kind: K;
   /** The file, or the declared path, the finding is about. */
   readonly path?: string;
-  /** The skill, server, sub-agent, variable or field the finding names. */
+  /** The skill, server, sub-agent, variable, entry or field the finding names. */
   readonly subject?: string;
   /** A second identifier the sentence needs (a field name, a parser's own message). */
   readonly detail?: string;
-  /** The one sentence for this kind, from `messages.ts`. */
+  /** The one sentence for this kind, from the vocabulary's `messages.ts`. */
   readonly message: string;
 }
 
-/** What `read` needs to compose a finding: everything but the sentence. */
-export type FindingContext = Pick<PluginFinding, "path" | "subject" | "detail">;
+export type PluginFinding = Finding<PluginFindingKind>;
+
+/** What a reader needs to compose a finding: everything but the sentence. */
+export type FindingContext = Pick<Finding<string>, "path" | "subject" | "detail">;
 
 export type PluginReadOutcome =
   | { readonly ok: true; readonly plugin: PluginPackage; readonly warnings: readonly PluginFinding[] }