@stigmer/plugin-package 3.16.0 → 3.17.0

package/src/client/select.ts

@@ -0,0 +1,161 @@
+/**
+ * Which files of a tree a plugin push carries, and in what order.
+ *
+ * A client that installs a plugin holds a tree: the CLI a directory on disk,
+ * the console the file list a marketplace host returned. Both must choose
+ * the same files in the same order, because the archive's bytes are the
+ * plugin's identity on the server (`status.digest` is the SHA-256 of what
+ * it received) and the order of the archive's entries is part of those
+ * bytes. This module is that choice, made once.
+ *
+ * The rule is the CLI's original walk (`stigmer push plugin <dir>`): at each
+ * directory the names are sorted by code point, files and directories
+ * interleaved by name, and a directory the matcher ignores is skipped whole,
+ * so no negation inside it can pull a file back. Symlinks never appear (the
+ * CLI walker skips them; a hosted tree has none the client asks for).
+ * `compareWalkOrder` states that order for a flat list of paths so a client
+ * with no directory to walk arrives at the same sequence; it is NOT the plain
+ * code-point order of full paths (`b/x.txt` sorts before `b.txt` here,
+ * because the directory `b` sorts before the file `b.txt` at their level).
+ * The reader in `read-plugin-package.ts` indexes entries by path and is
+ * indifferent to their order; only the archive cares.
+ *
+ * `.gitignore` and `.stigmerignore` are read from the root of the tree being
+ * selected, as the CLI does, never from an ancestor: a marketplace entry is
+ * its own plugin root.
+ */
+
+import type { PluginFileEntry, PluginFiles } from "../files.js";
+import { type IgnoreSources, type Matcher, SOURCE_GITIGNORE, SOURCE_STIGMERIGNORE, buildMatcher } from "./ignore/matcher.js";
+
+/** The tree a client holds before selection: every file it could offer, with its size. */
+export interface CandidateFile {
+  /** Root-relative POSIX path, no leading `./`. */
+  readonly path: string;
+  readonly size: number;
+}
+
+/** What the selection included and left out, for the summary line every client prints. */
+export interface SelectionStats {
+  filesIncluded: number;
+  filesIgnored: number;
+  /** Ignored directories that held at least one candidate; a tree lists no empty directories. */
+  dirsSkipped: number;
+  totalSize: number;
+}
+
+export interface SelectPluginFilesOptions {
+  /** Whether the tree's own root `.gitignore` applies (every push says yes unless asked otherwise). */
+  readonly respectGitignore: boolean;
+  readonly extraIgnore?: readonly string[];
+  readonly extraInclude?: readonly string[];
+}
+
+export interface PluginSelection {
+  readonly files: PluginFiles;
+  readonly stats: SelectionStats;
+  /** The matcher the selection ran, for diagnostics (`push --dry-run` lists its patterns). */
+  readonly matcher: Matcher;
+}
+
+/** The two files at a tree's root that shape its own selection. */
+export const IGNORE_FILE_NAMES = {
+  gitignore: SOURCE_GITIGNORE,
+  stigmerignore: SOURCE_STIGMERIGNORE,
+} as const;
+
+/**
+ * Select the files a push of `candidates` carries. `read` yields a listed
+ * candidate's bytes and is called here only for the two ignore files at the
+ * root, so a client may hand over a lazy reader and pay for the rest only
+ * when the archive is built.
+ */
+export function selectPluginFiles(
+  candidates: readonly CandidateFile[],
+  read: (path: string) => Uint8Array,
+  options: SelectPluginFilesOptions,
+): PluginSelection {
+  const byPath = new Map(candidates.map((candidate) => [candidate.path, candidate]));
+  const sources: IgnoreSources = {
+    includeDefaults: true,
+    ...(options.respectGitignore &&
+      byPath.has(IGNORE_FILE_NAMES.gitignore) && { gitignore: decode(read(IGNORE_FILE_NAMES.gitignore)) }),
+    ...(byPath.has(IGNORE_FILE_NAMES.stigmerignore) && {
+      stigmerignore: decode(read(IGNORE_FILE_NAMES.stigmerignore)),
+    }),
+    ...(options.extraIgnore !== undefined && { extraIgnore: options.extraIgnore }),
+    ...(options.extraInclude !== undefined && { extraInclude: options.extraInclude }),
+  };
+  const matcher = buildMatcher(sources);
+
+  const stats: SelectionStats = { filesIncluded: 0, filesIgnored: 0, dirsSkipped: 0, totalSize: 0 };
+  const skippedDirs = new Set<string>();
+  const entries: PluginFileEntry[] = [];
+
+  for (const candidate of [...candidates].sort((a, b) => compareWalkOrder(a.path, b.path))) {
+    if (underSkippedDir(candidate.path, matcher, skippedDirs, stats)) continue;
+    if (matcher.matchWithReason(candidate.path, false).ignored) {
+      stats.filesIgnored++;
+      continue;
+    }
+    entries.push({ path: candidate.path, size: candidate.size });
+    stats.filesIncluded++;
+    stats.totalSize += candidate.size;
+  }
+
+  return {
+    files: {
+      entries,
+      read(path) {
+        if (!byPath.has(path)) throw new Error(`plugin file '${path}' is not listed`);
+        return read(path);
+      },
+    },
+    stats,
+    matcher,
+  };
+}
+
+/**
+ * The order a sorted directory walk visits files: component by component,
+ * each compared by code point. Two paths never share a prefix that is a
+ * file in one and a directory in the other, so a shorter path is never a
+ * prefix of a longer one at the point they differ.
+ */
+export function compareWalkOrder(a: string, b: string): number {
+  const as = a.split("/");
+  const bs = b.split("/");
+  const depth = Math.min(as.length, bs.length);
+  for (let i = 0; i < depth; i++) {
+    const x = as[i] ?? "";
+    const y = bs[i] ?? "";
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return as.length - bs.length;
+}
+
+/**
+ * True when an ancestor directory of `path` is ignored as a directory. The
+ * walk checks a directory once and skips its subtree, so each ignored
+ * directory counts once whatever it holds.
+ */
+function underSkippedDir(path: string, matcher: Matcher, skipped: Set<string>, stats: SelectionStats): boolean {
+  const parts = path.split("/");
+  let dir = "";
+  for (let i = 0; i < parts.length - 1; i++) {
+    dir = dir === "" ? (parts[i] ?? "") : `${dir}/${parts[i] ?? ""}`;
+    if (skipped.has(dir)) return true;
+    if (matcher.matchWithReason(dir, true).ignored) {
+      skipped.add(dir);
+      stats.dirsSkipped++;
+      return true;
+    }
+  }
+  return false;
+}
+
+const decoder = new TextDecoder();
+
+function decode(bytes: Uint8Array): string {
+  return decoder.decode(bytes);
+}

package/src/client/vocabulary.ts

@@ -0,0 +1,19 @@
+/**
+ * The words every client prints for the same thing.
+ *
+ * The CLI's `validate -f`, `push plugin --dry-run` and `install`, and the
+ * console's install preview, all describe a package to the user; a
+ * platform where the same fact is named differently on two surfaces has
+ * two vocabularies. The labels here are the docs' words
+ * (`docs/vocabulary.md`), kept once.
+ */
+
+import type { PluginDialect } from "../types.js";
+
+/** Human labels for the four dialects, in the vocabulary the docs use. */
+export const DIALECT_LABELS: Readonly<Record<PluginDialect, string>> = {
+  "agent-plugins": "Agent Plugins 1.0",
+  claude: "Claude Code plugin",
+  cursor: "Cursor plugin",
+  codex: "Codex plugin",
+};

package/src/client.ts

@@ -0,0 +1,67 @@
+/**
+ * `@stigmer/plugin-package/client`: what every client that installs a
+ * plugin does identically.
+ *
+ * The main entry reads a package; this entry is for the client that holds
+ * a tree and must turn it into the push the server expects. Two clients do
+ * that today, the CLI from a directory and the console from a marketplace
+ * host's file list, and a plugin installed from either must have one
+ * digest for one tree, be refused with one sentence for one mistake, and be
+ * described in one vocabulary. So the pieces live here, once:
+ *
+ * - the gitignore-compatible ignore engine and the security defaults
+ *   (`ignore/`), pure over the text of the ignore files;
+ * - the selection rule (`select.ts`): which files a push carries, in the
+ *   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 grammars (`refs.ts`): an install ref and a GitHub marketplace
+ *   source, with their refusal sentences;
+ * - 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.
+ */
+
+export { DEFAULT_PATTERNS } from "./client/ignore/defaults.js";
+export { matchName } from "./client/ignore/match.js";
+export {
+  type IgnoreSources,
+  type MatchReason,
+  Matcher,
+  Reason,
+  REASON_TEXT,
+  SOURCE_CLI,
+  SOURCE_DEFAULTS,
+  SOURCE_GITIGNORE,
+  SOURCE_STIGMERIGNORE,
+  buildMatcher,
+} from "./client/ignore/matcher.js";
+export { MatchResult, type Pattern, parsePattern } from "./client/ignore/pattern.js";
+export {
+  type CandidateFile,
+  type PluginSelection,
+  type SelectPluginFilesOptions,
+  type SelectionStats,
+  IGNORE_FILE_NAMES,
+  compareWalkOrder,
+  selectPluginFiles,
+} from "./client/select.js";
+export { DETERMINISTIC_ZIP_MTIME, archivePlugin, digestArchive } from "./client/archive.js";
+export {
+  type GitHubMarketplaceSource,
+  type GitHubSourceOutcome,
+  type InstallRef,
+  type InstallRefOutcome,
+  GITHUB_SOURCE_SHAPE,
+  INSTALL_REF_SHAPE,
+  OFFICIAL_MARKETPLACE_NAME,
+  describeGitHubSource,
+  formatInstallRef,
+  isOwnerRepo,
+  looksLikePath,
+  parseGitHubSource,
+  parseInstallRef,
+} from "./client/refs.js";
+export { DIALECT_LABELS } from "./client/vocabulary.js";

package/src/files.ts

@@ -58,6 +58,12 @@ export const PLUGIN_DOCUMENT_LIMITS = {
   subAgent: 1024 * 1024,
   /** A document under `ai.stigmer/`: a resource YAML. */
   overlay: 1024 * 1024,
+  /**
+   * A marketplace file in any dialect. The largest public catalogue
+   * (`cursor/plugins`, 79 entries with descriptions) is under 32 KB; the cap
+   * leaves room for catalogues an order of magnitude larger.
+   */
+  marketplace: 1024 * 1024,
 } as const;
 
 export type PluginDocumentClass = keyof typeof PLUGIN_DOCUMENT_LIMITS;

package/src/index.ts

@@ -1,11 +1,13 @@
 /**
  * `@stigmer/plugin-package`: the public surface.
  *
- * `readPluginPackage` is the entry; everything else here is what a consumer
- * needs to supply its input (`PluginFiles`, the caps), route a directory
- * (`MANIFEST_LOCATIONS`, `hasPluginManifest`), or render the outcome (the
- * finding kinds and `isErrorKind`). The dialect readers and normalisers are
- * internal: a consumer never composes a partial read.
+ * `readPluginPackage` reads one plugin; `readMarketplace` reads a catalogue
+ * of them. 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
+ * readers and normalisers are internal: a consumer never composes a partial
+ * read.
  */
 
 export { hasPluginManifest, isValidPluginName } from "./detect.js";
@@ -32,6 +34,7 @@ export {
 export { SUB_AGENT_INSTRUCTIONS_MIN, classifyModel } from "./normalise/sub-agents.js";
 export { PLACEHOLDER_PATTERN, VARIABLE_NAME_PATTERN } from "./placeholders.js";
 export type {
+  Finding,
   FindingContext,
   PluginErrorKind,
   PluginFinding,
@@ -39,6 +42,19 @@ export type {
   PluginReadOutcome,
   PluginWarningKind,
 } from "./outcome.js";
+export { MARKETPLACE_LOCATIONS } from "./marketplace/messages.js";
+export type {
+  Marketplace,
+  MarketplaceDialect,
+  MarketplaceEntry,
+  MarketplaceErrorKind,
+  MarketplaceFinding,
+  MarketplaceFindingKind,
+  MarketplaceOwner,
+  MarketplaceReadOutcome,
+  MarketplaceWarningKind,
+} from "./marketplace/outcome.js";
+export { hasMarketplaceFile, readMarketplace } from "./marketplace/read-marketplace.js";
 export { readPluginPackage } from "./read-plugin-package.js";
 export type {
   IgnoredComponent,

package/src/marketplace/messages.ts

@@ -0,0 +1,62 @@
+/**
+ * The one sentence for every marketplace finding kind, and the collector
+ * bound to them.
+ *
+ * The same rule as the plugin vocabulary: copy lives here and nowhere else,
+ * the CLI prints these sentences verbatim, and the `Record` types are
+ * exhaustive so a kind without a sentence does not compile. The four
+ * locations are named in the not-found sentence because that is the one an
+ * author meets first when a file sits in the wrong place (Claude Code's own
+ * issue tracker shows how often).
+ */
+
+import { at, FindingCollector, q, type Sentence } from "../messages.js";
+import type { MarketplaceDialect, MarketplaceErrorKind, MarketplaceWarningKind } from "./outcome.js";
+
+/** The four marketplace file locations, in the precedence the reader applies. */
+export const MARKETPLACE_LOCATIONS: Readonly<Record<MarketplaceDialect, string>> = {
+  stigmer: "marketplace.json",
+  claude: ".claude-plugin/marketplace.json",
+  cursor: ".cursor-plugin/marketplace.json",
+  codex: ".agents/plugins/marketplace.json",
+};
+
+const locationList = Object.values(MARKETPLACE_LOCATIONS)
+  .map((location) => q(location))
+  .join(", ");
+
+const ERROR_MESSAGES: Readonly<Record<MarketplaceErrorKind, Sentence>> = {
+  "marketplace-not-found": () => `no marketplace file found: expected one of ${locationList}`,
+  "marketplace-too-large": (c) => `${q(c.path)} is ${c.subject ?? ""} bytes, above the ${c.detail ?? ""} byte cap for a marketplace file`,
+  "marketplace-unreadable": (c) => `${q(c.path)} is not a readable marketplace file: ${c.detail ?? "parse error"}`,
+  "marketplace-field-type": (c) => `${q(c.path)} field ${q(c.subject)} must be ${c.detail ?? "of another type"}`,
+  "marketplace-name-missing": (c) => `${q(c.path)} has no 'name'; a marketplace needs one so its plugins can be addressed as '<marketplace>/<plugin>'`,
+  "marketplace-name-invalid": (c) =>
+    `${q(c.path)} name ${q(c.subject)} is invalid: 1 to 64 characters of a-z, 0-9, '-' and '.', starting and ending alphanumeric, no '--' or '..'`,
+  "marketplace-plugins-missing": (c) => `${q(c.path)} has no 'plugins' list`,
+  "entry-shape": (c) => `${q(c.path)} plugins[${c.subject ?? ""}] must be an object with 'name' and 'source'`,
+  "entry-name-missing": (c) => `${q(c.path)} plugins[${c.subject ?? ""}] has no 'name'`,
+  "entry-name-invalid": (c) =>
+    `${q(c.path)} plugin ${q(c.subject)} has an invalid name: 1 to 64 characters of a-z, 0-9, '-' and '.', starting and ending alphanumeric, no '--' or '..'`,
+  "entry-name-duplicate": (c) => `${q(c.path)} lists plugin ${q(c.subject)} more than once; 'install ${c.subject ?? ""}' would be ambiguous`,
+  "entry-source-missing": (c) => `${q(c.path)} plugin ${q(c.subject)} has no 'source'`,
+  "entry-source-escapes-root": (c) =>
+    `${q(c.path)} plugin ${q(c.subject)} has source ${q(c.detail)} outside the marketplace root; a source is a directory inside the marketplace`,
+  "default-unknown": (c) => `${q(c.path)} names ${q(c.subject)} as a default but lists no plugin of that name`,
+};
+
+const WARNING_MESSAGES: Readonly<Record<MarketplaceWarningKind, Sentence>> = {
+  "entry-source-unsupported": (c) =>
+    `plugin ${q(c.subject)}${at(c.path)} has source ${q(c.detail)}, a form Stigmer does not fetch (only a directory inside the marketplace); not offered`,
+  "entry-directory-missing": (c) =>
+    `plugin ${q(c.subject)}${at(c.path)} names directory ${q(c.detail)}, which the marketplace does not contain; not offered`,
+  "entry-not-a-plugin": (c) =>
+    `plugin ${q(c.subject)}${at(c.path)} names directory ${q(c.detail)}, which holds no plugin manifest; not offered`,
+};
+
+/** The marketplace reader's collector, bound to the marketplace vocabulary. */
+export class MarketplaceFindings extends FindingCollector<MarketplaceErrorKind, MarketplaceWarningKind> {
+  constructor() {
+    super(ERROR_MESSAGES, WARNING_MESSAGES);
+  }
+}

package/src/marketplace/outcome.ts

@@ -0,0 +1,95 @@
+/**
+ * What a marketplace is once read, and the closed vocabulary of findings a
+ * marketplace read can produce.
+ *
+ * A marketplace is a directory tree with a marketplace file that lists the
+ * plugins it offers, each as a name and a directory inside the tree. That is
+ * the convention Cursor (`.cursor-plugin/marketplace.json`), Claude Code
+ * (`.claude-plugin/marketplace.json`) and Codex (`.agents/plugins/
+ * marketplace.json`) already publish, and the agent-plugins.org
+ * specification leaves marketplaces client-owned, so there is no open
+ * format to defer to; Stigmer's own file sits at the tree root as
+ * `marketplace.json`, the position the open plugin manifest takes. The four
+ * dialects reduce to one shape here: a client that can read this shape can
+ * install from any of the four catalogues.
+ *
+ * Two error postures, stated as the plugin reader states them. A marketplace
+ * FILE that is broken (unreadable, unnamed, no plugin list, a source that
+ * escapes the tree, two entries with one name) refuses the marketplace: a
+ * catalogue that cannot be trusted as a whole is not offered at all. An
+ * ENTRY that cannot be installed (a source form this reader does not fetch,
+ * a directory the tree does not hold, a directory with no plugin manifest)
+ * is dropped with a warning: a user adding a public catalogue of eighty
+ * plugins should still see the seventy-nine that work, and a catalogue's
+ * own static suite asserts zero warnings so the publisher hears about the
+ * one. Every kind has exactly one sentence in `messages.ts` and exactly one
+ * adversarial fixture.
+ */
+
+import type { Finding } from "../outcome.js";
+
+/** The marketplace file dialects, in the precedence the reader applies. */
+export type MarketplaceDialect = "stigmer" | "claude" | "cursor" | "codex";
+
+export type MarketplaceErrorKind =
+  // The file
+  | "marketplace-not-found"
+  | "marketplace-too-large"
+  | "marketplace-unreadable"
+  | "marketplace-field-type"
+  | "marketplace-name-missing"
+  | "marketplace-name-invalid"
+  | "marketplace-plugins-missing"
+  // Entries
+  | "entry-shape"
+  | "entry-name-missing"
+  | "entry-name-invalid"
+  | "entry-name-duplicate"
+  | "entry-source-missing"
+  | "entry-source-escapes-root"
+  // Defaults
+  | "default-unknown";
+
+export type MarketplaceWarningKind =
+  | "entry-source-unsupported"
+  | "entry-directory-missing"
+  | "entry-not-a-plugin";
+
+export type MarketplaceFindingKind = MarketplaceErrorKind | MarketplaceWarningKind;
+
+export type MarketplaceFinding = Finding<MarketplaceFindingKind>;
+
+export interface MarketplaceOwner {
+  readonly name?: string;
+  readonly email?: string;
+  readonly url?: string;
+}
+
+/** One installable plugin the marketplace offers. */
+export interface MarketplaceEntry {
+  /** The name a user installs it by; unique within the marketplace. */
+  readonly name: string;
+  /** The plugin's directory, marketplace-relative with no leading `./`; the empty string is the tree root. */
+  readonly dir: string;
+  /** The catalogue's own one-line description, when the file carries one. */
+  readonly description?: string;
+}
+
+export interface Marketplace {
+  /** The marketplace's identifier, the prefix in `install <marketplace>/<plugin>`. */
+  readonly name: string;
+  readonly description?: string;
+  readonly owner?: MarketplaceOwner;
+  /** The dialect whose file named the marketplace. */
+  readonly dialect: MarketplaceDialect;
+  /** The marketplace file that was read, tree-relative. */
+  readonly path: string;
+  /** Installable entries, in the file's order; entries the reader dropped are in the warnings. */
+  readonly plugins: readonly MarketplaceEntry[];
+  /** Entry names a client bootstraps with, in install order; empty when the file names none. */
+  readonly defaults: readonly string[];
+}
+
+export type MarketplaceReadOutcome =
+  | { readonly ok: true; readonly marketplace: Marketplace; readonly warnings: readonly MarketplaceFinding[] }
+  | { readonly ok: false; readonly errors: readonly MarketplaceFinding[]; readonly warnings: readonly MarketplaceFinding[] };