@stigmer/plugin-package 3.15.3-dev.20260916211208 → 3.16.1-dev.20260917224426

package/src/client/ignore/match.ts

@@ -0,0 +1,158 @@
+// Faithful port of Go's path/filepath Match, used by the gitignore pattern
+// engine to match a single glob against a single path component.
+//
+// The separator is fixed to "/" (paths are normalized to forward slashes and
+// individual components never contain a separator). Matching operates on UTF-16
+// code units rather than runes — correct for the ASCII glob syntax gitignore
+// patterns use; exotic multi-byte classes are out of scope.
+//
+// Go returns ErrBadPattern for malformed patterns; every go-git caller treats
+// that as "no match", so `matchName` swallows the error and returns false.
+
+const SEPARATOR = "/";
+
+class BadPatternError extends Error {}
+
+/** Match `name` against the glob `pattern` (Go filepath.Match semantics). */
+export function matchName(pattern: string, name: string): boolean {
+  try {
+    return matchImpl(pattern, name);
+  } catch (err) {
+    if (err instanceof BadPatternError) return false;
+    throw err;
+  }
+}
+
+function matchImpl(pattern: string, name: string): boolean {
+  outer: while (pattern.length > 0) {
+    const [star, chunk, rest] = scanChunk(pattern);
+    pattern = rest;
+
+    if (star && chunk === "") {
+      // Trailing `*` matches the rest of the component (which has no separator).
+      return !name.includes(SEPARATOR);
+    }
+
+    const [t, ok] = matchChunk(chunk, name);
+    if (ok && (t.length === 0 || pattern.length > 0)) {
+      name = t;
+      continue;
+    }
+
+    if (star) {
+      for (let i = 0; i < name.length && name[i] !== SEPARATOR; i++) {
+        const [t2, ok2] = matchChunk(chunk, name.slice(i + 1));
+        if (ok2) {
+          if (pattern.length === 0 && t2.length > 0) continue;
+          name = t2;
+          continue outer;
+        }
+      }
+    }
+    return false;
+  }
+  return name.length === 0;
+}
+
+function scanChunk(pattern: string): [boolean, string, string] {
+  let star = false;
+  while (pattern.length > 0 && pattern[0] === "*") {
+    pattern = pattern.slice(1);
+    star = true;
+  }
+
+  let inrange = false;
+  let i = 0;
+  scan: for (i = 0; i < pattern.length; i++) {
+    switch (pattern[i]) {
+      case "\\":
+        if (i + 1 < pattern.length) i++;
+        break;
+      case "[":
+        inrange = true;
+        break;
+      case "]":
+        inrange = false;
+        break;
+      case "*":
+        if (!inrange) break scan;
+        break;
+    }
+  }
+  return [star, pattern.slice(0, i), pattern.slice(i)];
+}
+
+function matchChunk(chunk: string, s: string): [string, boolean] {
+  let failed = false;
+  while (chunk.length > 0) {
+    if (!failed && s.length === 0) failed = true;
+
+    const c = chunk[0];
+    if (c === "[") {
+      let r = "";
+      if (!failed) {
+        r = s[0] ?? "";
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+      let negated = false;
+      if (chunk.length > 0 && chunk[0] === "^") {
+        negated = true;
+        chunk = chunk.slice(1);
+      }
+      let match = false;
+      let nrange = 0;
+      for (;;) {
+        if (chunk.length > 0 && chunk[0] === "]" && nrange > 0) {
+          chunk = chunk.slice(1);
+          break;
+        }
+        let lo: string;
+        [lo, chunk] = getEsc(chunk);
+        let hi = lo;
+        if (chunk[0] === "-") {
+          [hi, chunk] = getEsc(chunk.slice(1));
+        }
+        if (lo <= r && r <= hi) match = true;
+        nrange++;
+      }
+      if (match === negated) failed = true;
+    } else if (c === "?") {
+      if (!failed) {
+        if (s[0] === SEPARATOR) failed = true;
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+    } else if (c === "\\") {
+      chunk = chunk.slice(1);
+      if (chunk.length === 0) throw new BadPatternError("bad pattern");
+      if (!failed) {
+        if (chunk[0] !== s[0]) failed = true;
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+    } else {
+      if (!failed) {
+        if (chunk[0] !== s[0]) failed = true;
+        s = s.slice(1);
+      }
+      chunk = chunk.slice(1);
+    }
+  }
+  if (failed) return ["", false];
+  return [s, true];
+}
+
+function getEsc(chunk: string): [string, string] {
+  if (chunk.length === 0 || chunk[0] === "-" || chunk[0] === "]") {
+    throw new BadPatternError("bad pattern");
+  }
+  if (chunk[0] === "\\") {
+    chunk = chunk.slice(1);
+    if (chunk.length === 0) throw new BadPatternError("bad pattern");
+  }
+  const r = chunk[0] ?? "";
+  const nchunk = chunk.slice(1);
+  if (nchunk.length === 0) throw new BadPatternError("bad pattern");
+  return [r, nchunk];
+}

package/src/client/ignore/matcher.ts

@@ -0,0 +1,156 @@
+// Ignore matcher: composes pattern sources with gitignore precedence (defaults
+// → .gitignore → .stigmerignore → caller flags), evaluating "last match wins".
+// A faithful port of the Go CLI's pkg/ignore Matcher.
+//
+// The matcher is pure over the TEXT of the ignore files. Where that text
+// comes from is the caller's edge: the CLI reads `.gitignore` and
+// `.stigmerignore` from the directory it is about to package, the console
+// finds them among the files a marketplace tree lists. Both build the same
+// matcher from the same sources, which is what makes a plugin selected in
+// the browser the same set of files the CLI would have selected.
+
+import { DEFAULT_PATTERNS } from "./defaults.js";
+import { MatchResult, type Pattern, parsePattern } from "./pattern.js";
+
+export const SOURCE_DEFAULTS = "defaults";
+export const SOURCE_GITIGNORE = ".gitignore";
+export const SOURCE_STIGMERIGNORE = ".stigmerignore";
+export const SOURCE_CLI = "cli";
+
+export enum Reason {
+  NoMatch = 0,
+  Excluded = 1,
+  Included = 2,
+  DefaultDeny = 3,
+}
+
+export const REASON_TEXT: Readonly<Record<Reason, string>> = {
+  [Reason.NoMatch]: "no pattern matched",
+  [Reason.Excluded]: "excluded by pattern",
+  [Reason.Included]: "included by negation pattern",
+  [Reason.DefaultDeny]: "excluded by security default",
+};
+
+export interface MatchReason {
+  readonly ignored: boolean;
+  readonly reason: Reason;
+  readonly source: string;
+  readonly pattern: string;
+}
+
+interface PatternEntry {
+  readonly pattern: Pattern;
+  readonly source: string;
+  readonly raw: string;
+}
+
+/** The pattern sources a matcher is built from, in precedence order (later wins). */
+export interface IgnoreSources {
+  /** Whether the built-in security defaults apply (every push says yes). */
+  readonly includeDefaults: boolean;
+  /** The text of the root `.gitignore`, or `undefined` when absent or not respected. */
+  readonly gitignore?: string;
+  /** The text of the root `.stigmerignore`, or `undefined` when absent. */
+  readonly stigmerignore?: string;
+  /** Extra exclusion patterns from the caller (`--ignore`). */
+  readonly extraIgnore?: readonly string[];
+  /** Extra inclusion patterns from the caller (`--include`), negated if not already. */
+  readonly extraInclude?: readonly string[];
+}
+
+export class Matcher {
+  private readonly entries: readonly PatternEntry[];
+
+  constructor(entries: readonly PatternEntry[]) {
+    this.entries = entries;
+  }
+
+  /** Decide whether a path (relative, forward-slash) is ignored, with reason. */
+  matchWithReason(path: string, isDir: boolean): MatchReason {
+    const components = pathToComponents(path);
+    if (components.length === 0) {
+      return { ignored: false, reason: Reason.NoMatch, source: "", pattern: "" };
+    }
+
+    let lastMatch: PatternEntry | undefined;
+    let lastResult = MatchResult.NoMatch;
+    for (const entry of this.entries) {
+      const result = entry.pattern.match(components, isDir);
+      if (result !== MatchResult.NoMatch) {
+        lastMatch = entry;
+        lastResult = result;
+      }
+    }
+
+    if (lastMatch === undefined) {
+      return { ignored: false, reason: Reason.NoMatch, source: "", pattern: "" };
+    }
+
+    if (lastResult === MatchResult.Exclude) {
+      const reason = lastMatch.source === SOURCE_DEFAULTS ? Reason.DefaultDeny : Reason.Excluded;
+      return { ignored: true, reason, source: lastMatch.source, pattern: lastMatch.raw };
+    }
+    // Include (negation): explicitly un-ignored.
+    return { ignored: false, reason: Reason.Included, source: lastMatch.source, pattern: lastMatch.raw };
+  }
+
+  /** Whether the path should be excluded from the artifact. */
+  match(path: string, isDir: boolean): boolean {
+    return this.matchWithReason(path, isDir).ignored;
+  }
+
+  /** All loaded patterns as "[source] pattern" (for dry-run diagnostics). */
+  patterns(): string[] {
+    return this.entries.map((entry) => `[${entry.source}] ${entry.raw}`);
+  }
+}
+
+/** Build a matcher from its sources; the pure core every reader shares. */
+export function buildMatcher(sources: IgnoreSources): Matcher {
+  const entries: PatternEntry[] = [];
+  if (sources.includeDefaults) {
+    entries.push(...parseEntries(DEFAULT_PATTERNS, SOURCE_DEFAULTS));
+  }
+  if (sources.gitignore !== undefined) {
+    entries.push(...parseEntries(sources.gitignore.split(/\r?\n/), SOURCE_GITIGNORE));
+  }
+  if (sources.stigmerignore !== undefined) {
+    entries.push(...parseEntries(sources.stigmerignore.split(/\r?\n/), SOURCE_STIGMERIGNORE));
+  }
+
+  const extraIgnore = sources.extraIgnore ?? [];
+  const extraInclude = sources.extraInclude ?? [];
+  if (extraIgnore.length > 0 || extraInclude.length > 0) {
+    entries.push(...loadCliPatterns(extraIgnore, extraInclude));
+  }
+
+  return new Matcher(entries);
+}
+
+function parseEntries(patterns: readonly string[], source: string): PatternEntry[] {
+  const entries: PatternEntry[] = [];
+  for (const raw of patterns) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    entries.push({ pattern: parsePattern(trimmed, []), source, raw: trimmed });
+  }
+  return entries;
+}
+
+function loadCliPatterns(ignore: readonly string[], include: readonly string[]): PatternEntry[] {
+  const entries = parseEntries(ignore, SOURCE_CLI);
+  const negations: string[] = [];
+  for (const pattern of include) {
+    const trimmed = pattern.trim();
+    if (trimmed === "") continue;
+    negations.push(trimmed.startsWith("!") ? trimmed : `!${trimmed}`);
+  }
+  entries.push(...parseEntries(negations, SOURCE_CLI));
+  return entries;
+}
+
+function pathToComponents(path: string): string[] {
+  const normalized = path.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (normalized === "" || normalized === ".") return [];
+  return normalized.split("/");
+}

package/src/client/ignore/pattern.ts

@@ -0,0 +1,131 @@
+// Faithful port of go-git's plumbing/format/gitignore Pattern (ParsePattern +
+// Match). This is what gives `push` its exact gitignore semantics: domain
+// scoping, directory-only patterns, single-name vs glob matching, and the
+// `**` zero-to-many-directories wildcard.
+
+import { matchName } from "./match.js";
+
+export enum MatchResult {
+  NoMatch = 0,
+  Exclude = 1,
+  Include = 2,
+}
+
+const INCLUSION_PREFIX = "!";
+const ZERO_TO_MANY = "**";
+const DIR_SEP = "/";
+
+export interface Pattern {
+  /** Whether this is a negation (`!`) pattern — needed for source ordering. */
+  readonly inclusion: boolean;
+  match(path: readonly string[], isDir: boolean): MatchResult;
+}
+
+class GitignorePattern implements Pattern {
+  readonly inclusion: boolean;
+  private readonly domain: readonly string[];
+  private readonly parts: readonly string[];
+  private readonly dirOnly: boolean;
+  private readonly isGlob: boolean;
+
+  constructor(domain: readonly string[], parts: readonly string[], inclusion: boolean, dirOnly: boolean, isGlob: boolean) {
+    this.domain = domain;
+    this.parts = parts;
+    this.inclusion = inclusion;
+    this.dirOnly = dirOnly;
+    this.isGlob = isGlob;
+  }
+
+  match(path: readonly string[], isDir: boolean): MatchResult {
+    const matchResult = this.inclusion ? MatchResult.Include : MatchResult.Exclude;
+
+    if (path.length <= this.domain.length) return MatchResult.NoMatch;
+    for (let i = 0; i < this.domain.length; i++) {
+      if (path[i] !== this.domain[i]) return MatchResult.NoMatch;
+    }
+
+    const scoped = path.slice(this.domain.length);
+    const matched = this.isGlob ? this.globMatch(scoped, isDir) : this.simpleNameMatch(scoped, isDir);
+    return matched ? matchResult : MatchResult.NoMatch;
+  }
+
+  private simpleNameMatch(path: readonly string[], isDir: boolean): boolean {
+    for (let i = 0; i < path.length; i++) {
+      if (!matchName(this.parts[0] ?? "", path[i] ?? "")) continue;
+      if (this.dirOnly && !isDir && i === path.length - 1) return false;
+      return true;
+    }
+    return false;
+  }
+
+  private globMatch(path: readonly string[], isDir: boolean): boolean {
+    let matched = false;
+    let canTraverse = false;
+    let remaining = path;
+
+    for (let i = 0; i < this.parts.length; i++) {
+      const part = this.parts[i] ?? "";
+      if (part === "") {
+        canTraverse = false;
+        continue;
+      }
+      if (part === ZERO_TO_MANY) {
+        if (i === this.parts.length - 1) break;
+        canTraverse = true;
+        continue;
+      }
+      if (part.includes(ZERO_TO_MANY)) return false;
+      if (remaining.length === 0) return false;
+
+      if (canTraverse) {
+        canTraverse = false;
+        for (;;) {
+          if (remaining.length === 0) {
+            matched = false;
+            break;
+          }
+          const e = remaining[0] ?? "";
+          remaining = remaining.slice(1);
+          if (matchName(part, e)) {
+            matched = true;
+            break;
+          }
+        }
+      } else {
+        if (!matchName(part, remaining[0] ?? "")) return false;
+        matched = true;
+        remaining = remaining.slice(1);
+      }
+    }
+
+    if (matched && this.dirOnly && !isDir && remaining.length === 0) {
+      matched = false;
+    }
+    return matched;
+  }
+}
+
+/** Parse a gitignore pattern string into a matchable Pattern (go-git parity). */
+export function parsePattern(raw: string, domain: readonly string[]): Pattern {
+  let p = raw;
+  let inclusion = false;
+
+  if (p.startsWith(INCLUSION_PREFIX)) {
+    inclusion = true;
+    p = p.slice(1);
+  }
+
+  if (!p.endsWith("\\ ")) {
+    p = p.replace(/ +$/, "");
+  }
+
+  let dirOnly = false;
+  if (p.endsWith(DIR_SEP)) {
+    dirOnly = true;
+    p = p.slice(0, -1);
+  }
+
+  const isGlob = p.includes(DIR_SEP);
+  const parts = p.split(DIR_SEP);
+  return new GitignorePattern(domain, parts, inclusion, dirOnly, isGlob);
+}

package/src/client/refs.ts

@@ -0,0 +1,170 @@
+/**
+ * The two grammars a user types at any marketplace surface, and the words
+ * every client uses for what they name.
+ *
+ * `install [marketplace/]name[@version]`: the plugin's name in its
+ * marketplace, optionally qualified by the marketplace's name and pinned to
+ * the version the entry's manifest must carry. Both names obey the plugin
+ * name rule (`isValidPluginName`: lowercase letters, digits, `.` and `-`,
+ * never `/` or `@`), which is what makes the grammar unambiguous: the first
+ * `/` splits the marketplace off, the first `@` splits the version off, and
+ * anything else is not a ref. A path (`./thermos`, `/tmp/x`, `..`) is the
+ * one likely mistake and gets its own sentence, so a client can point at
+ * the command that installs a folder.
+ *
+ * A GitHub marketplace source: `owner/repo[@ref]`, or the URL a browser
+ * shows for that repository (`https://github.com/owner/repo[/tree/<ref>]`),
+ * normalised to one record. Every vendor keeps its marketplace file at the
+ * repository root, so a subdirectory grammar is not offered.
+ *
+ * Refusals are returned, not thrown: the CLI wraps one in its `UsageError`
+ * and the console renders it, and the sentence is the same in both. A
+ * client adds the second paragraph naming its own command.
+ */
+
+import { isValidPluginName } from "../detect.js";
+
+/** The built-in marketplace's name: the prefix in `install stigmer/<plugin>`; reserved in every client. */
+export const OFFICIAL_MARKETPLACE_NAME = "stigmer";
+
+export interface InstallRef {
+  /** The marketplace named before the `/`, or `undefined` when the name stands alone. */
+  readonly marketplace?: string;
+  readonly name: string;
+  /** The version named after the `@`, asserted against the entry's manifest. */
+  readonly version?: string;
+}
+
+export type InstallRefOutcome =
+  | { readonly ok: true; readonly ref: InstallRef }
+  | {
+      readonly ok: false;
+      /** `path` when the text names a folder rather than a plugin; `shape` for every other refusal. */
+      readonly kind: "path" | "shape";
+      readonly message: string;
+    };
+
+/** The characters a `@version` may carry: the plugin's tag pattern, so what a ref pins is a tag the server can hold. */
+const VERSION_PATTERN = /^[a-zA-Z0-9._-]+$/;
+
+/** The grammar in the user's terms, quoted by every refusal. */
+export const INSTALL_REF_SHAPE =
+  "[marketplace/]name[@version], for example 'thermos', 'cursor-plugins/thermos' or 'thermos@1.0.0'";
+
+export function parseInstallRef(text: string): InstallRefOutcome {
+  if (looksLikePath(text)) {
+    return {
+      ok: false,
+      kind: "path",
+      message: `'${text}' is a path, and 'install' takes a plugin's name in a marketplace`,
+    };
+  }
+  let rest = text;
+  let marketplace: string | undefined;
+  const slash = rest.indexOf("/");
+  if (slash !== -1) {
+    marketplace = rest.slice(0, slash);
+    rest = rest.slice(slash + 1);
+    if (!isValidPluginName(marketplace)) {
+      return { ok: false, kind: "shape", message: `'${marketplace}' is not a marketplace name` };
+    }
+  }
+  let version: string | undefined;
+  const at = rest.indexOf("@");
+  if (at !== -1) {
+    version = rest.slice(at + 1);
+    rest = rest.slice(0, at);
+    if (version === "" || !VERSION_PATTERN.test(version)) {
+      return { ok: false, kind: "shape", message: `'${version}' is not a version` };
+    }
+  }
+  if (!isValidPluginName(rest)) {
+    return { ok: false, kind: "shape", message: `'${rest}' is not a plugin name` };
+  }
+  return {
+    ok: true,
+    ref: {
+      ...(marketplace !== undefined && { marketplace }),
+      name: rest,
+      ...(version !== undefined && { version }),
+    },
+  };
+}
+
+/** The grammar's own text for a ref, the inverse of `parseInstallRef`. */
+export function formatInstallRef(ref: InstallRef): string {
+  const prefix = ref.marketplace === undefined ? "" : `${ref.marketplace}/`;
+  const suffix = ref.version === undefined ? "" : `@${ref.version}`;
+  return `${prefix}${ref.name}${suffix}`;
+}
+
+/** Whether `text` reads as a filesystem path on any platform (relative, home, absolute, Windows). */
+export function looksLikePath(text: string): boolean {
+  return (
+    text === "." ||
+    text === ".." ||
+    text.startsWith("./") ||
+    text.startsWith("../") ||
+    text.startsWith("~") ||
+    text.startsWith("/") ||
+    text.includes("\\") ||
+    /^[A-Za-z]:/.test(text)
+  );
+}
+
+/** A public GitHub repository at a ref; the default branch when `ref` is absent. */
+export interface GitHubMarketplaceSource {
+  readonly type: "github";
+  /** `owner/repo`. */
+  readonly repo: string;
+  /** Branch, tag or commit. */
+  readonly ref?: string;
+}
+
+export type GitHubSourceOutcome =
+  | { readonly ok: true; readonly source: GitHubMarketplaceSource }
+  | { readonly ok: false; readonly message: string };
+
+/** What a GitHub source may be typed as, quoted by every refusal. */
+export const GITHUB_SOURCE_SHAPE =
+  "a GitHub repository as 'owner/repo' or 'owner/repo@ref', or that repository's URL (https://github.com/owner/repo)";
+
+const GITHUB_URL = /^https?:\/\/(?:www\.)?github\.com\/([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:\/tree\/([^\s#?]+))?\/?$/;
+
+/**
+ * `owner/repo[@ref]` or a github.com URL as one source. The URL form is
+ * tried first because it contains a `/` too; a text that is neither is
+ * refused with the shape.
+ */
+export function parseGitHubSource(text: string): GitHubSourceOutcome {
+  const url = GITHUB_URL.exec(text);
+  if (url !== null) {
+    const repo = `${url[1] ?? ""}/${url[2] ?? ""}`;
+    if (!isOwnerRepo(repo)) {
+      return { ok: false, message: `'${text}' does not name a GitHub repository` };
+    }
+    const ref = url[3];
+    return { ok: true, source: { type: "github", repo, ...(ref !== undefined && ref !== "" && { ref }) } };
+  }
+
+  const at = text.indexOf("@");
+  const repo = at === -1 ? text : text.slice(0, at);
+  const ref = at === -1 ? undefined : text.slice(at + 1);
+  if (isOwnerRepo(repo) && (ref === undefined || ref !== "")) {
+    return { ok: true, source: { type: "github", repo, ...(ref !== undefined && { ref }) } };
+  }
+  return { ok: false, message: `'${text}' is not a GitHub 'owner/repo'` };
+}
+
+/** One phrase naming a GitHub source, for lists and sentences. */
+export function describeGitHubSource(source: GitHubMarketplaceSource): string {
+  return source.ref === undefined ? `github.com/${source.repo}` : `github.com/${source.repo}@${source.ref}`;
+}
+
+const OWNER_REPO_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** `owner/repo` as GitHub spells it: two segments, no `.git` suffix required or refused. */
+export function isOwnerRepo(value: string): boolean {
+  const parts = value.split("/");
+  return parts.length === 2 && parts.every((part) => OWNER_REPO_SEGMENT.test(part) && part !== "." && part !== "..");
+}