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

package/src/__test-utils__/read.ts

@@ -10,7 +10,7 @@
 import { expect } from "vitest";
 
 import { inMemoryPluginFiles } from "../files.js";
-import type { PluginFinding, PluginReadOutcome } from "../outcome.js";
+import type { Finding, PluginFinding, PluginReadOutcome } from "../outcome.js";
 import { readPluginPackage } from "../read-plugin-package.js";
 import type { PluginFixture } from "../testing.js";
 import type { PluginPackage } from "../types.js";
@@ -47,9 +47,9 @@ export function refused(outcome: PluginReadOutcome): readonly PluginFinding[] {
   return outcome.errors;
 }
 
-/** The one finding of `kind`, failing when it is absent or repeated. */
-export function findingOf(findings: readonly PluginFinding[], kind: string): PluginFinding {
+/** The one finding of `kind`, failing when it is absent or repeated; over either vocabulary. */
+export function findingOf<K extends string>(findings: readonly Finding<K>[], kind: string): Finding<K> {
   const matches = findings.filter((f) => f.kind === kind);
   expect(matches, `exactly one '${kind}' finding`).toHaveLength(1);
-  return matches[0] as PluginFinding;
+  return matches[0] as Finding<K>;
 }

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

@@ -0,0 +1,133 @@
+/**
+ * The ignore engine's table tests: the filepath.Match port, the Pattern
+ * matcher (scoping, dir-only, globs, negation) and the composed matcher's
+ * source precedence with last-match-wins. Moved here with the engine from
+ * the CLI; the matcher is now built from the TEXT of the ignore files, so
+ * the precedence cases hand it text where they once wrote a temp directory.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { matchName } from "../client/ignore/match.js";
+import { buildMatcher } from "../client/ignore/matcher.js";
+import { MatchResult, parsePattern } from "../client/ignore/pattern.js";
+
+describe("matchName (filepath.Match port)", () => {
+  const cases: [string, string, boolean][] = [
+    ["*.go", "main.go", true],
+    ["*.go", "main.rs", false],
+    ["*", "anything", true],
+    ["a?c", "abc", true],
+    ["a?c", "ac", false],
+    ["[abc]", "b", true],
+    ["[abc]", "d", false],
+    ["[a-c]", "b", true],
+    ["[a-c]", "z", false],
+    ["[^a]", "b", true],
+    ["[^a]", "a", false],
+    ["foo*", "foobar", true],
+    ["*bar", "foobar", true],
+    ["h[a-z]llo", "hello", true],
+    ["node_modules", "node_modules", true],
+    ["\\*.go", "*.go", true],
+    // Malformed patterns: Go returns ErrBadPattern → callers treat as no match.
+    ["[", "a", false],
+    ["[a-", "a", false],
+  ];
+  for (const [pattern, name, expected] of cases) {
+    it(`${pattern} ~ ${name} => ${expected}`, () => {
+      expect(matchName(pattern, name)).toBe(expected);
+    });
+  }
+});
+
+describe("parsePattern / Pattern.match", () => {
+  it("directory-only patterns only match directories (or ancestors)", () => {
+    const p = parsePattern("node_modules/", []);
+    expect(p.match(["node_modules"], true)).toBe(MatchResult.Exclude);
+    expect(p.match(["node_modules"], false)).toBe(MatchResult.NoMatch);
+    expect(p.match(["src", "node_modules"], true)).toBe(MatchResult.Exclude);
+  });
+
+  it("simple name patterns match at any depth", () => {
+    const p = parsePattern("*.log", []);
+    expect(p.match(["app.log"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["sub", "app.log"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["app.txt"], false)).toBe(MatchResult.NoMatch);
+  });
+
+  it("leading slash anchors to the domain root", () => {
+    const p = parsePattern("/build", []);
+    expect(p.match(["build"], true)).toBe(MatchResult.Exclude);
+    expect(p.match(["src", "build"], true)).toBe(MatchResult.NoMatch);
+  });
+
+  it("** matches zero-to-many directories", () => {
+    const p = parsePattern("**/foo", []);
+    expect(p.match(["foo"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["a", "b", "foo"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["a", "bar"], false)).toBe(MatchResult.NoMatch);
+  });
+
+  it("negation patterns produce Include", () => {
+    const p = parsePattern("!keep.txt", []);
+    expect(p.inclusion).toBe(true);
+    expect(p.match(["keep.txt"], false)).toBe(MatchResult.Include);
+  });
+
+  it("domain scopes matching below a subtree", () => {
+    const p = parsePattern("*.txt", ["sub"]);
+    expect(p.match(["sub", "a.txt"], false)).toBe(MatchResult.Exclude);
+    expect(p.match(["a.txt"], false)).toBe(MatchResult.NoMatch);
+  });
+});
+
+describe("buildMatcher (source precedence, last-match-wins)", () => {
+  it("applies security defaults including the .env.example negation", () => {
+    const m = buildMatcher({ includeDefaults: true });
+    expect(m.match(".env", false)).toBe(true);
+    expect(m.match(".env.example", false)).toBe(false);
+    expect(m.match("id_rsa", false)).toBe(true);
+    expect(m.match("node_modules", true)).toBe(true);
+  });
+
+  it("honors .gitignore with negation (last match wins)", () => {
+    const m = buildMatcher({ includeDefaults: true, gitignore: "*.draft\n!keep.draft\n" });
+    expect(m.match("notes.draft", false)).toBe(true);
+    expect(m.match("keep.draft", false)).toBe(false);
+  });
+
+  it("an absent .gitignore contributes nothing", () => {
+    const m = buildMatcher({ includeDefaults: true });
+    expect(m.match("notes.draft", false)).toBe(false);
+  });
+
+  it(".stigmerignore outranks .gitignore", () => {
+    const m = buildMatcher({ includeDefaults: true, gitignore: "!shared.draft\n", stigmerignore: "*.draft\n" });
+    expect(m.match("shared.draft", false)).toBe(true);
+  });
+
+  it("caller extra ignore/include override file sources", () => {
+    const m = buildMatcher({
+      includeDefaults: true,
+      gitignore: "*.draft\n",
+      extraIgnore: ["*.tmp"],
+      extraInclude: ["important.draft"],
+    });
+    expect(m.match("scratch.tmp", false)).toBe(true);
+    expect(m.match("important.draft", false)).toBe(false);
+  });
+
+  it("reports the matching source and reason", () => {
+    const m = buildMatcher({ includeDefaults: true });
+    const reason = m.matchWithReason(".env", false);
+    expect(reason.ignored).toBe(true);
+    expect(reason.source).toBe("defaults");
+  });
+
+  it("CRLF ignore files parse line by line", () => {
+    const m = buildMatcher({ includeDefaults: false, gitignore: "*.a\r\n*.b\r\n" });
+    expect(m.match("x.a", false)).toBe(true);
+    expect(m.match("x.b", false)).toBe(true);
+  });
+});

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

@@ -0,0 +1,101 @@
+/**
+ * The two grammars every client parses: an install ref and a GitHub
+ * marketplace source. Pins the splits (`/` then `@`), the path refusal that
+ * gets its own kind so a client can name its folder command, the URL forms
+ * that normalise to `owner/repo[@ref]`, and that a refusal is returned with
+ * a sentence rather than thrown.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  describeGitHubSource,
+  formatInstallRef,
+  isOwnerRepo,
+  looksLikePath,
+  parseGitHubSource,
+  parseInstallRef,
+} from "../client/refs.js";
+
+describe("parseInstallRef", () => {
+  it("a bare name", () => {
+    expect(parseInstallRef("thermos")).toEqual({ ok: true, ref: { name: "thermos" } });
+  });
+
+  it("marketplace/name@version", () => {
+    expect(parseInstallRef("cursor-plugins/thermos@1.0.0")).toEqual({
+      ok: true,
+      ref: { marketplace: "cursor-plugins", name: "thermos", version: "1.0.0" },
+    });
+  });
+
+  it("refuses a path with its own kind", () => {
+    for (const text of ["./thermos", "../x", ".", "..", "/tmp/x", "~/x", "C:\\x", "a\\b"]) {
+      const outcome = parseInstallRef(text);
+      expect(outcome.ok).toBe(false);
+      if (!outcome.ok) expect(outcome.kind).toBe("path");
+    }
+  });
+
+  it("refuses a bad marketplace name, version and plugin name with the shape kind", () => {
+    const bad = ["Upper/thermos", "thermos@", "thermos@1.0!", "Thermos", "a/b/c"];
+    for (const text of bad) {
+      const outcome = parseInstallRef(text);
+      expect(outcome.ok).toBe(false);
+      if (!outcome.ok) expect(outcome.kind).toBe("shape");
+    }
+  });
+
+  it("formatInstallRef is the inverse", () => {
+    const outcome = parseInstallRef("m/n@v");
+    if (!outcome.ok) throw new Error("expected ok");
+    expect(formatInstallRef(outcome.ref)).toBe("m/n@v");
+    expect(formatInstallRef({ name: "n" })).toBe("n");
+  });
+});
+
+describe("parseGitHubSource", () => {
+  it("owner/repo and owner/repo@ref", () => {
+    expect(parseGitHubSource("cursor/plugins")).toEqual({ ok: true, source: { type: "github", repo: "cursor/plugins" } });
+    expect(parseGitHubSource("cursor/plugins@main")).toEqual({
+      ok: true,
+      source: { type: "github", repo: "cursor/plugins", ref: "main" },
+    });
+  });
+
+  it("the browser's URL, with and without /tree/<ref> and .git", () => {
+    for (const text of ["https://github.com/cursor/plugins", "https://www.github.com/cursor/plugins.git", "http://github.com/cursor/plugins/"]) {
+      expect(parseGitHubSource(text)).toEqual({ ok: true, source: { type: "github", repo: "cursor/plugins" } });
+    }
+    expect(parseGitHubSource("https://github.com/cursor/plugins/tree/v1.2")).toEqual({
+      ok: true,
+      source: { type: "github", repo: "cursor/plugins", ref: "v1.2" },
+    });
+  });
+
+  it("refuses what is not a repository", () => {
+    for (const text of ["cursor", "cursor/plugins@", "a/b/c", "https://gitlab.com/a/b", "../x"]) {
+      expect(parseGitHubSource(text).ok).toBe(false);
+    }
+  });
+
+  it("describes a source in one phrase", () => {
+    expect(describeGitHubSource({ type: "github", repo: "a/b" })).toBe("github.com/a/b");
+    expect(describeGitHubSource({ type: "github", repo: "a/b", ref: "r" })).toBe("github.com/a/b@r");
+  });
+});
+
+describe("isOwnerRepo and looksLikePath", () => {
+  it("two segments of GitHub's character set", () => {
+    expect(isOwnerRepo("a/b")).toBe(true);
+    expect(isOwnerRepo("a.b/c-d_e")).toBe(true);
+    expect(isOwnerRepo("./b")).toBe(false);
+    expect(isOwnerRepo("a/../b")).toBe(false);
+    expect(isOwnerRepo("-a/b")).toBe(false);
+  });
+
+  it("a path on any platform", () => {
+    expect(looksLikePath("D:\\plugins")).toBe(true);
+    expect(looksLikePath("thermos")).toBe(false);
+  });
+});

package/src/__tests__/client-select-archive.test.ts

@@ -0,0 +1,152 @@
+/**
+ * The client entry's identity discipline: the same tree selected and
+ * archived from a directory (the CLI's edge) and from a flat in-memory file
+ * list (the console's edge) yields one digest, and that digest is the one
+ * the CLI produced before this module existed.
+ *
+ * The two constants below were computed with the unmodified CLI at
+ * `d75b0724a` (`preparePluginPush` over `plugins/assistant` and over the
+ * vendored `thermos` fixture). `8d1000b4…` is also the digest the live
+ * `assistant` plugin carried after `stigmer up` in that release. If either
+ * changes, every installed plugin would look like an upgrade; this test is
+ * the tripwire.
+ *
+ * The selection cases pin the walk order (component-wise, directories and
+ * files interleaved by name), the whole-subtree skip of an ignored
+ * directory, the root `.gitignore` and `.stigmerignore`, and that a
+ * negation inside a skipped directory cannot pull a file back.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { archivePlugin, digestArchive } from "../client/archive.js";
+import { type CandidateFile, compareWalkOrder, selectPluginFiles } from "../client/select.js";
+
+const FIXTURES = fileURLToPath(new URL("./fixtures/cursor-plugins/", import.meta.url));
+const REPO_PLUGINS = fileURLToPath(new URL("../../../../../../plugins/", import.meta.url));
+
+const BASELINE = {
+  assistant: "8d1000b4a48136a8530509f603805693fc2478d279962d4fade40716435064ce",
+  thermos: "51bc4e5450e24762bb8515765c76bfe262f65c57f9afeda015c5818038396d5a",
+} as const;
+
+const encoder = new TextEncoder();
+
+/** Every file under `root`, unordered, the shape a hosted tree listing has. */
+function listDirectory(root: string): { candidates: CandidateFile[]; read: (path: string) => Uint8Array } {
+  const candidates: CandidateFile[] = [];
+  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 });
+    }
+  };
+  walk(root, "");
+  // Reverse so the test proves selection imposes the order, not the listing.
+  candidates.reverse();
+  return { candidates, read: (path) => new Uint8Array(readFileSync(`${root}/${path}`)) };
+}
+
+function inMemory(files: Record<string, string>): { candidates: CandidateFile[]; read: (path: string) => Uint8Array } {
+  const bytes = new Map(Object.entries(files).map(([path, text]) => [path, encoder.encode(text)]));
+  return {
+    candidates: [...bytes].map(([path, content]) => ({ path, size: content.length })),
+    read: (path) => {
+      const content = bytes.get(path);
+      if (content === undefined) throw new Error(`unlisted ${path}`);
+      return content;
+    },
+  };
+}
+
+const RESPECT = { respectGitignore: true };
+
+describe("parity with the CLI's original walk", () => {
+  it("plugins/assistant archives to the digest stigmer up installed", async () => {
+    const { candidates, read } = listDirectory(`${REPO_PLUGINS}assistant`);
+    const selection = selectPluginFiles(candidates, read, RESPECT);
+    expect(selection.files.entries.map((entry) => entry.path)).toEqual([
+      "ai.stigmer/agent.yaml",
+      "icon.svg",
+      "plugin.json",
+    ]);
+    expect(await digestArchive(archivePlugin(selection.files))).toBe(BASELINE.assistant);
+  });
+
+  it("the thermos fixture archives to the CLI's digest", async () => {
+    const { candidates, read } = listDirectory(`${FIXTURES}thermos`);
+    const selection = selectPluginFiles(candidates, read, RESPECT);
+    expect(selection.stats.filesIncluded).toBe(10);
+    expect(await digestArchive(archivePlugin(selection.files))).toBe(BASELINE.thermos);
+  });
+
+  it("the same bytes from an in-memory listing yield the same digest", async () => {
+    const dir = listDirectory(`${REPO_PLUGINS}assistant`);
+    const memory = inMemory(
+      Object.fromEntries(dir.candidates.map((c) => [c.path, new TextDecoder().decode(dir.read(c.path))])),
+    );
+    const selection = selectPluginFiles(memory.candidates, memory.read, RESPECT);
+    expect(await digestArchive(archivePlugin(selection.files))).toBe(BASELINE.assistant);
+  });
+});
+
+describe("compareWalkOrder", () => {
+  it("visits a directory before a file that sorts after it by name", () => {
+    // A code-point sort of full paths would put "b.txt" before "b/x.txt"
+    // ('.' < '/'); the walk visits the directory `b` first.
+    expect(["b.txt", "b/x.txt", "a.txt"].sort(compareWalkOrder)).toEqual(["a.txt", "b/x.txt", "b.txt"]);
+  });
+
+  it("orders siblings by code point, the CLI's comparison", () => {
+    expect(["B.md", "a.md", "_x.md"].sort(compareWalkOrder)).toEqual(["B.md", "_x.md", "a.md"]);
+  });
+});
+
+describe("selectPluginFiles", () => {
+  it("skips an ignored directory whole, and a negation inside it cannot pull a file back", () => {
+    const { candidates, read } = inMemory({
+      "plugin.json": "{}",
+      ".gitignore": "build/\n!build/keep.txt\n",
+      "build/keep.txt": "x",
+      "build/out.js": "y",
+      "src/a.ts": "z",
+    });
+    const selection = selectPluginFiles(candidates, read, RESPECT);
+    expect(selection.files.entries.map((e) => e.path)).toEqual([".gitignore", "plugin.json", "src/a.ts"]);
+    expect(selection.stats).toEqual({ filesIncluded: 3, filesIgnored: 0, dirsSkipped: 1, totalSize: 26 });
+  });
+
+  it("applies the security defaults and lets .env.example through", () => {
+    const { candidates, read } = inMemory({ "plugin.json": "{}", ".env": "S=1", ".env.example": "S=" });
+    const selection = selectPluginFiles(candidates, read, RESPECT);
+    expect(selection.files.entries.map((e) => e.path)).toEqual([".env.example", "plugin.json"]);
+    expect(selection.stats.filesIgnored).toBe(1);
+  });
+
+  it("ignores .gitignore when told to, and always reads .stigmerignore", () => {
+    const files = { "plugin.json": "{}", ".gitignore": "*.draft\n", ".stigmerignore": "*.tmp\n", "a.draft": "", "b.tmp": "" };
+    const loose = selectPluginFiles(inMemory(files).candidates, inMemory(files).read, { respectGitignore: false });
+    expect(loose.files.entries.map((e) => e.path)).toContain("a.draft");
+    expect(loose.files.entries.map((e) => e.path)).not.toContain("b.tmp");
+    const strict = selectPluginFiles(inMemory(files).candidates, inMemory(files).read, RESPECT);
+    expect(strict.files.entries.map((e) => e.path)).not.toContain("a.draft");
+  });
+
+  it("the selected reader refuses a path it did not list", () => {
+    const { candidates, read } = inMemory({ "plugin.json": "{}" });
+    const selection = selectPluginFiles(candidates, read, RESPECT);
+    expect(() => selection.files.read("missing.md")).toThrow("plugin file 'missing.md' is not listed");
+  });
+});
+
+describe("digestArchive", () => {
+  it("is lowercase hex SHA-256", async () => {
+    const digest = await digestArchive(new Uint8Array([1, 2, 3]));
+    expect(digest).toBe("039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81");
+  });
+});