@stigmer/cli 3.35.0 → 3.37.0

package/src/marketplace/github.test.ts

@@ -1,394 +0,0 @@
-// Pins the GitHub source over zipballs built in-test: a good tree lands with
-// its top directory stripped; every cap refuses naming itself, from the
-// central directory before anything inflates; an escaping path, a second
-// top-level directory and a lying declared size refuse; 404 and a network
-// failure carry their own exit codes. The peek reads one raw file, the first
-// of the four locations that exists, as declared; a repository with none is
-// not a marketplace, a refused file travels with its sentences, and a
-// network failure carries its exit code.
-
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { zipSync } from "fflate";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { ExitCode } from "../errors/index.js";
-import {
-  GITHUB_ZIPBALL_LIMITS,
-  fetchGitHubTree,
-  peekGitHubMarketplace,
-  rawFileUrl,
-  zipballUrl,
-} from "./github.js";
-
-let dest: string;
-
-beforeEach(() => {
-  dest = mkdtempSync(join(tmpdir(), "stigmer-github-tree-"));
-});
-
-afterEach(() => {
-  rmSync(dest, { recursive: true, force: true });
-});
-
-const encoder = new TextEncoder();
-
-function zipball(files: Record<string, string | Uint8Array>): Uint8Array {
-  const tree: Record<string, Uint8Array> = {};
-  for (const [path, content] of Object.entries(files)) {
-    tree[path] =
-      typeof content === "string" ? encoder.encode(content) : content;
-  }
-  return zipSync(tree, { level: 6 });
-}
-
-function serving(
-  bytes: Uint8Array,
-  init: { status?: number; contentLength?: number } = {},
-): typeof globalThis.fetch {
-  return async () => {
-    const headers = new Headers();
-    if (init.contentLength !== undefined)
-      headers.set("content-length", String(init.contentLength));
-    const body = bytes.buffer.slice(
-      bytes.byteOffset,
-      bytes.byteOffset + bytes.byteLength,
-    ) as ArrayBuffer;
-    return new Response(
-      init.status === undefined || init.status === 200 ? body : "nope",
-      {
-        status: init.status ?? 200,
-        headers,
-      },
-    );
-  };
-}
-
-/**
- * The same archive with one entry's central-directory record rewritten: a
- * declaration that lies (`uncompressedSize`) or a checksum that does not
- * match (`crc32`). The payload is untouched, so only a reader that budgets
- * from the central directory and verifies the CRC can refuse it.
- */
-function declaring(
-  bytes: Uint8Array,
-  entryName: string,
-  patch: { uncompressedSize?: number; crc32?: number },
-): Uint8Array {
-  const patched = new Uint8Array(bytes);
-  const view = new DataView(
-    patched.buffer,
-    patched.byteOffset,
-    patched.byteLength,
-  );
-  const name = encoder.encode(entryName);
-  for (let offset = 0; offset + 46 <= patched.length; offset += 1) {
-    if (view.getUint32(offset, true) !== 0x02014b50) continue;
-    const nameLength = view.getUint16(offset + 28, true);
-    const recorded = patched.subarray(offset + 46, offset + 46 + nameLength);
-    if (
-      recorded.length === name.length &&
-      recorded.every((byte, i) => byte === name[i])
-    ) {
-      if (patch.crc32 !== undefined)
-        view.setUint32(offset + 16, patch.crc32, true);
-      if (patch.uncompressedSize !== undefined)
-        view.setUint32(offset + 24, patch.uncompressedSize, true);
-      return patched;
-    }
-  }
-  throw new Error(`no central directory record for ${entryName}`);
-}
-
-async function refusal(
-  promise: Promise<unknown>,
-): Promise<{ message: string; exitCode: number }> {
-  try {
-    await promise;
-  } catch (error) {
-    const e = error as { message: string; exitCode: number };
-    return { message: e.message, exitCode: e.exitCode };
-  }
-  throw new Error("expected a refusal");
-}
-
-describe("zipballUrl", () => {
-  it("names codeload's HEAD by default and the ref when given", () => {
-    expect(zipballUrl({ repo: "cursor/plugins" })).toBe(
-      "https://codeload.github.com/cursor/plugins/zip/HEAD",
-    );
-    expect(zipballUrl({ repo: "cursor/plugins", ref: "v1" })).toBe(
-      "https://codeload.github.com/cursor/plugins/zip/v1",
-    );
-  });
-});
-
-describe("fetchGitHubTree", () => {
-  it("extracts the tree with the zipball's top directory stripped", async () => {
-    const bytes = zipball({
-      "plugins-HEAD/.cursor-plugin/marketplace.json": JSON.stringify({
-        name: "cursor-plugins",
-        plugins: [],
-      }),
-      "plugins-HEAD/thermos/.cursor-plugin/plugin.json": JSON.stringify({
-        name: "thermos",
-      }),
-      "plugins-HEAD/thermos/skills/x/SKILL.md":
-        "---\nname: x\ndescription: d\n---\nbody\n",
-    });
-    await fetchGitHubTree(
-      { repo: "cursor/plugins" },
-      { destDir: dest, fetchImpl: serving(bytes) },
-    );
-    expect(existsSync(join(dest, "plugins-HEAD"))).toBe(false);
-    expect(
-      JSON.parse(
-        readFileSync(join(dest, ".cursor-plugin", "marketplace.json"), "utf8"),
-      ).name,
-    ).toBe("cursor-plugins");
-    expect(
-      readFileSync(join(dest, "thermos", "skills", "x", "SKILL.md"), "utf8"),
-    ).toContain("body");
-  });
-
-  it("refuses an archive over the download cap from content-length, before reading the body", async () => {
-    const bytes = zipball({ "r-HEAD/marketplace.json": "{}" });
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        {
-          destDir: dest,
-          fetchImpl: serving(bytes, {
-            contentLength: GITHUB_ZIPBALL_LIMITS.downloadBytes + 1,
-          }),
-        },
-      ),
-    );
-    expect(outcome.message).toMatch(/over the 64\.0 MiB download cap/);
-    expect(outcome.exitCode).toBe(ExitCode.Usage);
-  });
-
-  it("refuses more entries than the cap from the central directory", async () => {
-    const files: Record<string, string> = {};
-    for (let i = 0; i <= GITHUB_ZIPBALL_LIMITS.entries; i += 1)
-      files[`r-HEAD/f${i}`] = "";
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        { destDir: dest, fetchImpl: serving(zipball(files)) },
-      ),
-    );
-    expect(outcome.message).toMatch(/entries, over the 20000 cap/);
-    expect(existsSync(join(dest, "f0"))).toBe(false);
-  });
-
-  it("refuses a declared inflated size over the cap from the central directory, before inflating", async () => {
-    const bytes = declaring(
-      zipball({ "r-HEAD/marketplace.json": "{}", "r-HEAD/big.bin": "tiny" }),
-      "r-HEAD/big.bin",
-      {
-        uncompressedSize: GITHUB_ZIPBALL_LIMITS.inflatedBytes + 1,
-      },
-    );
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        { destDir: dest, fetchImpl: serving(bytes) },
-      ),
-    );
-    expect(outcome.message).toMatch(
-      /inflates to 256\.0 MiB, over the 256\.0 MiB cap/,
-    );
-    expect(existsSync(join(dest, "marketplace.json"))).toBe(false);
-  });
-
-  it("refuses an entry whose declared size undercounts what it inflates to", async () => {
-    const bytes = declaring(
-      zipball({
-        "r-HEAD/marketplace.json": "{}",
-        "r-HEAD/liar.txt": "twelve bytes, and then some more text",
-      }),
-      "r-HEAD/liar.txt",
-      { uncompressedSize: 3 },
-    );
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        { destDir: dest, fetchImpl: serving(bytes) },
-      ),
-    );
-    expect(outcome.message).toMatch(
-      /entry 'liar\.txt' inflated past its declared size/,
-    );
-  });
-
-  it("refuses an entry whose bytes do not match its checksum", async () => {
-    const bytes = declaring(
-      zipball({
-        "r-HEAD/marketplace.json": "{}",
-        "r-HEAD/tampered.txt": "some content here",
-      }),
-      "r-HEAD/tampered.txt",
-      { crc32: 0xdeadbeef },
-    );
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        { destDir: dest, fetchImpl: serving(bytes) },
-      ),
-    );
-    expect(outcome.message).toMatch(
-      /entry 'tampered\.txt' failed its checksum/,
-    );
-  });
-
-  it("refuses an entry that would escape the destination", async () => {
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        {
-          destDir: dest,
-          fetchImpl: serving(
-            zipball({ "r-HEAD/marketplace.json": "{}", "r-HEAD/../evil": "x" }),
-          ),
-        },
-      ),
-    );
-    expect(outcome.message).toMatch(/would escape the destination directory/);
-    expect(existsSync(join(dest, "..", "evil"))).toBe(false);
-  });
-
-  it("refuses an archive with more than one top-level directory", async () => {
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        {
-          destDir: dest,
-          fetchImpl: serving(
-            zipball({
-              "one/marketplace.json": "{}",
-              "two/marketplace.json": "{}",
-            }),
-          ),
-        },
-      ),
-    );
-    expect(outcome.message).toMatch(
-      /more than one top-level directory \('one' and 'two'\)/,
-    );
-  });
-
-  it("refuses bytes that are not a zip", async () => {
-    const outcome = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        {
-          destDir: dest,
-          fetchImpl: serving(encoder.encode("<html>not a zip</html>")),
-        },
-      ),
-    );
-    expect(outcome.message).toMatch(/not a readable zip/);
-  });
-
-  it("maps 404 to NotFound and a network failure to Connection, each with its own sentence", async () => {
-    const missing = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b", ref: "v9" },
-        {
-          destDir: dest,
-          fetchImpl: serving(new Uint8Array(), { status: 404 }),
-        },
-      ),
-    );
-    expect(missing.message).toBe(
-      "GitHub has no public repository 'a/b' at ref 'v9'",
-    );
-    expect(missing.exitCode).toBe(ExitCode.NotFound);
-
-    const offline = await refusal(
-      fetchGitHubTree(
-        { repo: "a/b" },
-        {
-          destDir: dest,
-          fetchImpl: async () => {
-            throw new Error("ENOTFOUND");
-          },
-        },
-      ),
-    );
-    expect(offline.message).toBe("could not reach GitHub for a/b");
-    expect(offline.exitCode).toBe(ExitCode.Connection);
-  });
-});
-
-/** A fetch answering raw.githubusercontent.com from a path map, 404 elsewhere. */
-function rawServing(
-  files: Record<string, string>,
-): typeof globalThis.fetch {
-  return async (input) => {
-    const url = String(input);
-    const prefix = "https://raw.githubusercontent.com/a/b/HEAD/";
-    const path = url.startsWith(prefix) ? url.slice(prefix.length) : undefined;
-    const content = path === undefined ? undefined : files[path];
-    return content === undefined
-      ? new Response("Not Found", { status: 404 })
-      : new Response(content, { status: 200 });
-  };
-}
-
-describe("rawFileUrl", () => {
-  it("names raw.githubusercontent.com at HEAD by default and the ref when given", () => {
-    expect(rawFileUrl({ repo: "a/b" }, ".cursor-plugin/marketplace.json")).toBe(
-      "https://raw.githubusercontent.com/a/b/HEAD/.cursor-plugin/marketplace.json",
-    );
-    expect(rawFileUrl({ repo: "a/b", ref: "v1" }, "marketplace.json")).toBe(
-      "https://raw.githubusercontent.com/a/b/v1/marketplace.json",
-    );
-  });
-});
-
-describe("peekGitHubMarketplace", () => {
-  it("reads the first location present in the library's precedence, as declared, tree unverified", async () => {
-    const peek = await peekGitHubMarketplace(
-      { repo: "a/b" },
-      rawServing({
-        ".cursor-plugin/marketplace.json": JSON.stringify({
-          name: "acme",
-          plugins: [{ name: "thermos", source: "thermos" }],
-        }),
-      }),
-    );
-    expect(peek.ok).toBe(true);
-    if (!peek.ok) return;
-    expect(peek.peeked.location).toBe(".cursor-plugin/marketplace.json");
-    expect(peek.peeked.marketplace.plugins.map((p) => p.name)).toEqual([
-      "thermos",
-    ]);
-  });
-
-  it("is not-a-marketplace when no location exists, and refused with the library's sentences when the file is broken", async () => {
-    expect(await peekGitHubMarketplace({ repo: "a/b" }, rawServing({}))).toEqual({
-      ok: false,
-      kind: "not-a-marketplace",
-    });
-    const refused = await peekGitHubMarketplace(
-      { repo: "a/b" },
-      rawServing({ "marketplace.json": JSON.stringify({ plugins: "no" }) }),
-    );
-    expect(refused.ok).toBe(false);
-    if (refused.ok || refused.kind !== "refused") throw new Error("expected refused");
-    expect(refused.location).toBe("marketplace.json");
-    expect(refused.errors.length).toBeGreaterThan(0);
-  });
-
-  it("carries the connection exit code when GitHub cannot be reached", async () => {
-    const offline = await peekGitHubMarketplace({ repo: "a/b" }, async () => {
-      throw new Error("ENOTFOUND");
-    }).catch((e: unknown) => e);
-    expect(offline).toMatchObject({
-      message: "could not reach GitHub for a/b",
-      exitCode: ExitCode.Connection,
-    });
-  });
-});

package/src/marketplace/install.test.ts

@@ -1,261 +0,0 @@
-// Pins how a ref becomes a prepared push: an offered entry prepares through
-// the same walker `push plugin` uses (one digest for one tree); a version
-// pin is an assertion; a bare name is searched across the known sources and
-// must land in exactly one; a GitHub source is asked through its marketplace
-// file alone and its zipball fetched only when the file declares the name (a
-// repository with no file declares nothing; a declared entry the tree does
-// not hold is not a holder); every temp tree a search opened is disposed,
-// whatever the outcome.
-
-import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { zipSync } from "fflate";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { preparePluginPush } from "../resources/plugin.js";
-import { writeCursorMarketplace } from "./__fixtures__/cursor-marketplace.js";
-import { type MarketplaceListing, OFFICIAL_MARKETPLACE } from "./config.js";
-import { assertVersion, locateEntry, prepareEntry } from "./install.js";
-import { readMarketplaceTree } from "./read.js";
-import { parseInstallRef } from "./ref.js";
-
-let root: string;
-
-beforeAll(() => {
-  root = mkdtempSync(join(tmpdir(), "stigmer-marketplace-install-"));
-  writeCursorMarketplace(root);
-});
-
-afterAll(() => {
-  rmSync(root, { recursive: true, force: true });
-});
-
-describe("prepareEntry", () => {
-  it("prepares an offered entry exactly as push plugin would prepare its directory", async () => {
-    const tree = readMarketplaceTree(root);
-    const viaMarketplace = await prepareEntry(tree, "codeforge");
-    const viaFolder = await preparePluginPush(join(root, "third_party", "codeforge"));
-    expect(viaMarketplace.plugin.name).toBe("codeforge");
-    expect(viaMarketplace.digest).toBe(viaFolder.digest);
-    expect(
-      Buffer.from(viaMarketplace.archive).equals(
-        Buffer.from(viaFolder.archive),
-      ),
-    ).toBe(true);
-  });
-
-  it("refuses an entry the marketplace does not offer, quoting the drop sentence when there is one", async () => {
-    const tree = readMarketplaceTree(root);
-    await expect(prepareEntry(tree, "ghost")).rejects.toThrow(
-      /does not offer a plugin named 'ghost'\n\n.*ghost.*\n\nRun 'stigmer marketplace show acme-plugins' to see the 2 it offers/s,
-    );
-    await expect(prepareEntry(tree, "nope")).rejects.toThrow(
-      /does not offer a plugin named 'nope'\n\nRun 'stigmer marketplace show/,
-    );
-  });
-});
-
-describe("assertVersion", () => {
-  it("passes without a pin or with the offered version, refuses another naming the offered one", async () => {
-    const prepared = await prepareEntry(readMarketplaceTree(root), "warmer");
-    expect(() => assertVersion(prepared, undefined, "warmer")).not.toThrow();
-    expect(() =>
-      assertVersion(prepared, "1.0.0", "warmer@1.0.0"),
-    ).not.toThrow();
-    expect(() =>
-      assertVersion(prepared, "9.9.9", "acme-plugins/warmer@9.9.9"),
-    ).toThrow(
-      /pins version 9\.9\.9, but the marketplace offers 'warmer' at 1\.0\.0\n\nInstall it as 'acme-plugins\/warmer@1\.0\.0'/,
-    );
-  });
-});
-
-describe("locateEntry", () => {
-  const encoder = new TextEncoder();
-
-  /**
-   * A GitHub source served from memory: raw.githubusercontent.com answers a
-   * single file from the map (404 when absent), codeload answers the tree
-   * zipped under one top directory. `requests` records every URL asked.
-   */
-  function servingZipOf(
-    files: Record<string, string>,
-    top = "r-HEAD",
-    requests: string[] = [],
-  ): typeof globalThis.fetch {
-    const tree: Record<string, Uint8Array> = {};
-    for (const [path, content] of Object.entries(files))
-      tree[`${top}/${path}`] = encoder.encode(content);
-    const bytes = zipSync(tree);
-    return async (input) => {
-      const url = String(input);
-      requests.push(url);
-      const raw = url.match(/^https:\/\/raw\.githubusercontent\.com\/[^/]+\/[^/]+\/[^/]+\/(.+)$/);
-      if (raw !== null) {
-        const content = files[raw[1] ?? ""];
-        return content === undefined
-          ? new Response("Not Found", { status: 404 })
-          : new Response(content, { status: 200 });
-      }
-      return new Response(bytes, { status: 200 });
-    };
-  }
-
-  const remoteFiles = {
-    "marketplace.json": JSON.stringify({
-      name: "remote",
-      plugins: [{ name: "warmer", source: "./warmer" }],
-    }),
-    "warmer/plugin.json": JSON.stringify({
-      name: "warmer",
-      version: "3.0.0",
-    }),
-  };
-
-  function listing(...extra: MarketplaceListing["known"]): MarketplaceListing {
-    return { known: [OFFICIAL_MARKETPLACE, ...extra], unreadable: [] };
-  }
-
-  it("opens the marketplace a prefixed ref names and refuses an unknown prefix", async () => {
-    const local = {
-      name: "acme-plugins",
-      source: { type: "local", path: root } as const,
-    };
-    const located = await locateEntry(
-      parseInstallRef("acme-plugins/warmer"),
-      listing(local),
-    );
-    try {
-      expect(located.marketplace.name).toBe("acme-plugins");
-      expect(located.tree.root).toBe(root);
-    } finally {
-      located.open.dispose();
-    }
-    await expect(
-      locateEntry(parseInstallRef("nowhere/warmer"), listing(local)),
-    ).rejects.toThrow(/no marketplace named 'nowhere' is configured/);
-  });
-
-  it("searches a bare name across every marketplace and lands in the one holder, disposing the rest", async () => {
-    const local = {
-      name: "acme-plugins",
-      source: { type: "local", path: root } as const,
-    };
-    const located = await locateEntry(
-      parseInstallRef("codeforge"),
-      listing(local),
-    );
-    try {
-      expect(located.marketplace.name).toBe("acme-plugins");
-    } finally {
-      located.open.dispose();
-    }
-  });
-
-  it("refuses a bare name nobody offers, naming what was searched and what could not be read", async () => {
-    const local = {
-      name: "acme-plugins",
-      source: { type: "local", path: root } as const,
-    };
-    await expect(
-      locateEntry(parseInstallRef("nope"), {
-        known: [OFFICIAL_MARKETPLACE, local],
-        unreadable: [{ name: "broken", reason: "x" }],
-      }),
-    ).rejects.toThrow(
-      /no configured marketplace offers a plugin named 'nope'\n\nSearched: stigmer, acme-plugins\. Not searched.*broken/,
-    );
-  });
-
-  it("refuses a bare name two marketplaces offer, naming each qualified ref, and leaves no temp tree behind", async () => {
-    const local = {
-      name: "acme-plugins",
-      source: { type: "local", path: root } as const,
-    };
-    const remote = {
-      name: "remote",
-      source: { type: "github", repo: "a/b" } as const,
-    };
-    const before = countTempTrees();
-    await expect(
-      locateEntry(parseInstallRef("warmer"), listing(local, remote), {
-        fetchImpl: servingZipOf(remoteFiles),
-      }),
-    ).rejects.toThrow(
-      /offered by more than one marketplace: acme-plugins, remote\n\nName the one you mean: acme-plugins\/warmer or remote\/warmer/,
-    );
-    expect(countTempTrees()).toBe(before);
-  });
-
-  it("asks a GitHub source through its marketplace file alone and downloads the zipball only for a holder", async () => {
-    const local = {
-      name: "acme-plugins",
-      source: { type: "local", path: root } as const,
-    };
-    const remote = {
-      name: "remote",
-      source: { type: "github", repo: "a/b" } as const,
-    };
-    const requests: string[] = [];
-    // `codeforge` is offered by the local fixture alone: the remote is peeked, not downloaded.
-    const located = await locateEntry(parseInstallRef("codeforge"), listing(local, remote), {
-      fetchImpl: servingZipOf(remoteFiles, "r-HEAD", requests),
-    });
-    located.open.dispose();
-    expect(requests.some((url) => url.startsWith("https://raw.githubusercontent.com/a/b/"))).toBe(true);
-    expect(requests.some((url) => url.startsWith("https://codeload.github.com/"))).toBe(false);
-  });
-
-  it("treats a GitHub repository with no marketplace file as declaring nothing, and a declared entry the tree lacks as not held", async () => {
-    const empty = {
-      name: "empty",
-      source: { type: "github", repo: "a/b" } as const,
-    };
-    await expect(
-      locateEntry(parseInstallRef("nope"), listing(empty), {
-        fetchImpl: servingZipOf({}),
-      }),
-    ).rejects.toThrow(/no configured marketplace offers a plugin named 'nope'\n\nSearched: stigmer, empty\./);
-
-    const phantom = {
-      name: "phantom",
-      source: { type: "github", repo: "a/b" } as const,
-    };
-    const before = countTempTrees();
-    await expect(
-      locateEntry(parseInstallRef("ghost"), listing(phantom), {
-        fetchImpl: servingZipOf({
-          "marketplace.json": JSON.stringify({
-            name: "phantom",
-            plugins: [{ name: "ghost", source: "./ghost" }],
-          }),
-        }),
-      }),
-    ).rejects.toThrow(/no configured marketplace offers a plugin named 'ghost'/);
-    expect(countTempTrees()).toBe(before);
-  });
-
-  it("disposes a fetched tree when the located entry is released", async () => {
-    const remote = {
-      name: "remote",
-      source: { type: "github", repo: "a/b" } as const,
-    };
-    const located = await locateEntry(
-      parseInstallRef("remote/warmer"),
-      listing(remote),
-      {
-        fetchImpl: servingZipOf(remoteFiles),
-      },
-    );
-    expect(existsSync(located.tree.root)).toBe(true);
-    located.open.dispose();
-    expect(existsSync(located.tree.root)).toBe(false);
-  });
-});
-
-/** The temp trees `openMarketplace` creates (`stigmer-marketplace-` plus mkdtemp's suffix and nothing else). */
-function countTempTrees(): number {
-  return readdirSync(tmpdir()).filter((name) =>
-    /^stigmer-marketplace-[A-Za-z0-9]+$/.test(name),
-  ).length;
-}