@stigmer/cli 3.16.0 → 3.16.1-dev.20260917224426

package/src/marketplace/config.test.ts

@@ -0,0 +1,245 @@
+// Pins the marketplace list over the real config file (HOME redirected):
+// the official one is always first and never stored; add and remove round-
+// trip through the file's own dialect (`type`); a hand-edited entry the CLI
+// cannot read is listed with its reason, kept on save, and named when a
+// command asks for it; the reserved name and --standalone refuse.
+
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { configPath, load } from "../config/index.js";
+import { setStandalone } from "../runtime.js";
+import {
+  OFFICIAL_MARKETPLACE_NAME,
+  addMarketplace,
+  describeSource,
+  findMarketplace,
+  isOwnerRepo,
+  listMarketplaces,
+  narrowEntry,
+  removeMarketplace,
+} from "./config.js";
+
+let home: string;
+let originalHome: string | undefined;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  home = mkdtempSync(join(tmpdir(), "stigmer-marketplace-config-"));
+  process.env.HOME = home;
+});
+
+afterEach(() => {
+  setStandalone(false);
+  if (originalHome === undefined) delete process.env.HOME;
+  else process.env.HOME = originalHome;
+  rmSync(home, { recursive: true, force: true });
+});
+
+function writeConfig(yaml: string): void {
+  mkdirSync(join(home, ".stigmer"), { recursive: true });
+  writeFileSync(configPath(), yaml);
+}
+
+describe("listMarketplaces", () => {
+  it("is the official marketplace alone on a fresh machine", () => {
+    const listing = listMarketplaces();
+    expect(listing.known.map((m) => m.name)).toEqual([
+      OFFICIAL_MARKETPLACE_NAME,
+    ]);
+    expect(listing.known[0]?.source).toEqual({ type: "official" });
+    expect(listing.unreadable).toEqual([]);
+  });
+
+  it("lists configured entries after the official one, in file order, and names the unreadable ones", () => {
+    writeConfig(
+      [
+        "backend:",
+        "  type: local",
+        "marketplaces:",
+        "  cursor-plugins:",
+        "    type: github",
+        "    repo: cursor/plugins",
+        "  pinned:",
+        "    type: github",
+        "    repo: anthropics/claude-code",
+        "    ref: v1.2.3",
+        "  team:",
+        "    type: local",
+        "    path: /srv/plugins",
+        "  broken:",
+        "    type: gitlab",
+        "    repo: a/b",
+        "  typeless:",
+        "    repo: a/b",
+        "",
+      ].join("\n"),
+    );
+    const listing = listMarketplaces();
+    expect(listing.known.map((m) => m.name)).toEqual([
+      "stigmer",
+      "cursor-plugins",
+      "pinned",
+      "team",
+    ]);
+    expect(listing.known[1]?.source).toEqual({
+      type: "github",
+      repo: "cursor/plugins",
+    });
+    expect(listing.known[2]?.source).toEqual({
+      type: "github",
+      repo: "anthropics/claude-code",
+      ref: "v1.2.3",
+    });
+    expect(listing.known[3]?.source).toEqual({
+      type: "local",
+      path: "/srv/plugins",
+    });
+    expect(listing.unreadable).toEqual([
+      {
+        name: "broken",
+        reason: "unknown type 'gitlab' (expected 'github' or 'local')",
+      },
+      { name: "typeless", reason: "no 'type' (expected 'github' or 'local')" },
+    ]);
+  });
+});
+
+describe("addMarketplace and removeMarketplace", () => {
+  it("round-trips a github source and a local source through the file", () => {
+    addMarketplace("cursor-plugins", {
+      type: "github",
+      repo: "cursor/plugins",
+    });
+    addMarketplace("team", { type: "local", path: "/srv/plugins" });
+    const text = readFileSync(configPath(), "utf8");
+    expect(text).toContain("marketplaces:");
+    expect(text).toContain("type: github");
+    expect(text).toContain("repo: cursor/plugins");
+    expect(text).not.toContain("ref:");
+    expect(text).toContain("path: /srv/plugins");
+    expect(listMarketplaces().known.map((m) => m.name)).toEqual([
+      "stigmer",
+      "cursor-plugins",
+      "team",
+    ]);
+
+    removeMarketplace("cursor-plugins");
+    expect(listMarketplaces().known.map((m) => m.name)).toEqual([
+      "stigmer",
+      "team",
+    ]);
+    removeMarketplace("team");
+    expect(load().marketplaces).toBeUndefined();
+    expect(readFileSync(configPath(), "utf8")).not.toContain("marketplaces");
+  });
+
+  it("keeps the rest of the config and an unreadable entry across a save", () => {
+    writeConfig(
+      "backend:\n  type: cloud\nbackends:\n  cloud:\n    type: cloud\n    token: t\ncurrent_backend: cloud\nmarketplaces:\n  broken:\n    type: gitlab\n",
+    );
+    addMarketplace("team", { type: "local", path: "/srv/plugins" });
+    const after = load();
+    expect(after.current_backend).toBe("cloud");
+    expect(after.backends?.["cloud"]?.token).toBe("t");
+    expect(after.marketplaces?.["broken"]).toEqual({ type: "gitlab" });
+    expect(after.marketplaces?.["team"]).toEqual({
+      type: "local",
+      path: "/srv/plugins",
+    });
+  });
+
+  it("refuses the reserved name, a duplicate, an unknown removal, and the reserved removal", () => {
+    expect(() =>
+      addMarketplace("stigmer", { type: "local", path: "/x" }),
+    ).toThrow(/built-in marketplace/);
+    addMarketplace("team", { type: "local", path: "/srv/plugins" });
+    expect(() =>
+      addMarketplace("team", { type: "local", path: "/other" }),
+    ).toThrow(/already configured/);
+    expect(() => removeMarketplace("nope")).toThrow(
+      /no marketplace named 'nope'/,
+    );
+    expect(() => removeMarketplace("stigmer")).toThrow(/cannot be removed/);
+  });
+
+  it("refuses under --standalone instead of writing a default file over the user's", () => {
+    writeConfig(
+      "backend:\n  type: cloud\nbackends:\n  cloud:\n    type: cloud\n    token: t\ncurrent_backend: cloud\n",
+    );
+    setStandalone(true);
+    expect(() => addMarketplace("team", { type: "local", path: "/x" })).toThrow(
+      /--standalone/,
+    );
+    expect(() => removeMarketplace("team")).toThrow(/--standalone/);
+    setStandalone(false);
+    expect(load().backends?.["cloud"]?.token).toBe("t");
+  });
+});
+
+describe("findMarketplace", () => {
+  it("finds the official and configured ones, returns undefined for an unknown name, and names an unreadable entry", () => {
+    writeConfig(
+      "backend:\n  type: local\nmarketplaces:\n  team:\n    type: local\n    path: /srv\n  broken:\n    type: gitlab\n",
+    );
+    expect(findMarketplace("stigmer")?.source).toEqual({ type: "official" });
+    expect(findMarketplace("team")?.source).toEqual({
+      type: "local",
+      path: "/srv",
+    });
+    expect(findMarketplace("nope")).toBeUndefined();
+    expect(() => findMarketplace("broken")).toThrow(
+      /configured but cannot be read: unknown type 'gitlab'/,
+    );
+  });
+});
+
+describe("narrowEntry, describeSource, isOwnerRepo", () => {
+  it("refuses a github entry without a repo and a local entry without a path", () => {
+    expect(narrowEntry({ type: "github" })).toEqual({
+      ok: false,
+      reason: "type 'github' needs 'repo: owner/repo'",
+    });
+    expect(narrowEntry({ type: "github", repo: "not-a-repo" })).toEqual({
+      ok: false,
+      reason: "type 'github' needs 'repo: owner/repo'",
+    });
+    expect(narrowEntry({ type: "github", repo: "a/b", ref: "" })).toEqual({
+      ok: false,
+      reason: "'ref' must be a non-empty branch, tag or commit",
+    });
+    expect(narrowEntry({ type: "local" })).toEqual({
+      ok: false,
+      reason: "type 'local' needs 'path: <directory>'",
+    });
+  });
+
+  it("describes each source in one phrase", () => {
+    expect(describeSource({ type: "official" })).toBe("built in");
+    expect(describeSource({ type: "github", repo: "cursor/plugins" })).toBe(
+      "github.com/cursor/plugins",
+    );
+    expect(
+      describeSource({ type: "github", repo: "cursor/plugins", ref: "main" }),
+    ).toBe("github.com/cursor/plugins@main");
+    expect(describeSource({ type: "local", path: "/srv/plugins" })).toBe(
+      "/srv/plugins",
+    );
+  });
+
+  it("accepts owner/repo as GitHub spells it and nothing else", () => {
+    expect(isOwnerRepo("cursor/plugins")).toBe(true);
+    expect(isOwnerRepo("my-org/my.repo_1")).toBe(true);
+    expect(isOwnerRepo("cursor")).toBe(false);
+    expect(isOwnerRepo("a/b/c")).toBe(false);
+    expect(isOwnerRepo("../x")).toBe(false);
+    expect(isOwnerRepo("a/")).toBe(false);
+  });
+});

package/src/marketplace/config.ts

@@ -0,0 +1,236 @@
+// The marketplaces a CLI knows: the official one, built in, and the ones a
+// user added under the `marketplaces` key of ~/.stigmer/config.yaml.
+//
+// A marketplace is client-side configuration, never a server resource: the
+// server only ever sees the plugin archive a client pushes. That is why the
+// list lives beside the named backends and the context, and why `stigmer
+// marketplace` is a noun group like `config` and `auth`.
+//
+// The config module keeps the on-disk entry loose (`MarketplaceEntryConfig`,
+// every field optional) so a hand-edited entry this CLI cannot read survives
+// the next save; this module is where the entry is narrowed into a
+// `MarketplaceSource` the fetchers act on, and where an unreadable entry
+// becomes a reason `stigmer marketplace list` prints instead of a silent gap.
+
+import {
+  type Config,
+  type MarketplaceEntryConfig,
+  load as loadConfig,
+  save as saveConfig,
+} from "../config/index.js";
+import {
+  type GitHubMarketplaceSource,
+  OFFICIAL_MARKETPLACE_NAME,
+  describeGitHubSource,
+  isOwnerRepo,
+} from "@stigmer/plugin-package/client";
+import { UsageError } from "../errors/index.js";
+import { isStandalone } from "../runtime.js";
+
+export { OFFICIAL_MARKETPLACE_NAME, isOwnerRepo };
+
+/** Where a marketplace tree comes from. Every source yields a directory. */
+export type MarketplaceSource =
+  /** The catalogue this CLI ships with: the repo tree in dev, `@stigmer/plugins` otherwise. */
+  | { readonly type: "official" }
+  /** A public GitHub repository, fetched as a zipball of `ref` (the default branch when absent); the console reads the same record. */
+  | GitHubMarketplaceSource
+  /** A directory on this machine, stored absolute. */
+  | { readonly type: "local"; readonly path: string };
+
+/** A marketplace the CLI can act on. */
+export interface KnownMarketplace {
+  readonly name: string;
+  readonly source: MarketplaceSource;
+}
+
+/** A configured entry this CLI cannot read; listed with its reason, never dropped. */
+export interface UnreadableMarketplace {
+  readonly name: string;
+  readonly reason: string;
+}
+
+export interface MarketplaceListing {
+  /** The official marketplace first, then the config's entries in file order. */
+  readonly known: readonly KnownMarketplace[];
+  readonly unreadable: readonly UnreadableMarketplace[];
+}
+
+export const OFFICIAL_MARKETPLACE: KnownMarketplace = {
+  name: OFFICIAL_MARKETPLACE_NAME,
+  source: { type: "official" },
+};
+
+/** Every marketplace the config names, the official one first. */
+export function listMarketplaces(
+  config: Config = loadConfig(),
+): MarketplaceListing {
+  const known: KnownMarketplace[] = [OFFICIAL_MARKETPLACE];
+  const unreadable: UnreadableMarketplace[] = [];
+  for (const [name, entry] of Object.entries(config.marketplaces ?? {})) {
+    const narrowed = narrowEntry(entry);
+    if (narrowed.ok) known.push({ name, source: narrowed.source });
+    else unreadable.push({ name, reason: narrowed.reason });
+  }
+  return { known, unreadable };
+}
+
+/** The marketplace called `name`, or `undefined`; an unreadable entry refuses with its reason. */
+export function findMarketplace(
+  name: string,
+  config: Config = loadConfig(),
+): KnownMarketplace | undefined {
+  const listing = listMarketplaces(config);
+  const known = listing.known.find((marketplace) => marketplace.name === name);
+  if (known !== undefined) return known;
+  const broken = listing.unreadable.find(
+    (marketplace) => marketplace.name === name,
+  );
+  if (broken !== undefined) {
+    throw new UsageError(
+      `marketplace '${name}' is configured but cannot be read: ${broken.reason}\n\n` +
+        `Fix the entry under 'marketplaces.${name}' in the config file, or remove it with 'stigmer marketplace remove ${name}'.`,
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Record a marketplace under `name` and save. Refuses the reserved name, a
+ * name already taken, and a run under `--standalone` (the config file is
+ * ignored there, so there is nothing to add to; saving would write a fresh
+ * default file over the user's own).
+ */
+export function addMarketplace(
+  name: string,
+  source: Exclude<MarketplaceSource, { type: "official" }>,
+): void {
+  refuseStandalone("add");
+  if (name === OFFICIAL_MARKETPLACE_NAME) {
+    throw new UsageError(
+      `'${OFFICIAL_MARKETPLACE_NAME}' is the built-in marketplace and cannot be added or replaced\n\n` +
+        "Pass --name <other-name> to add this source under a different name.",
+    );
+  }
+  const config = loadConfig();
+  if (config.marketplaces?.[name] !== undefined) {
+    throw new UsageError(
+      `a marketplace named '${name}' is already configured\n\n` +
+        `Remove it first with 'stigmer marketplace remove ${name}', or pass --name <other-name>.`,
+    );
+  }
+  saveConfig({
+    ...config,
+    marketplaces: { ...config.marketplaces, [name]: toEntry(source) },
+  });
+}
+
+/** Remove the marketplace called `name` and save. Refuses the reserved name and an unknown one. */
+export function removeMarketplace(name: string): void {
+  refuseStandalone("remove");
+  if (name === OFFICIAL_MARKETPLACE_NAME) {
+    throw new UsageError(
+      `'${OFFICIAL_MARKETPLACE_NAME}' is the built-in marketplace and cannot be removed`,
+    );
+  }
+  const config = loadConfig();
+  if (config.marketplaces?.[name] === undefined) {
+    throw new UsageError(
+      `no marketplace named '${name}' is configured\n\nRun 'stigmer marketplace list' to see the configured names.`,
+    );
+  }
+  const { [name]: _removed, ...rest } = config.marketplaces;
+  saveConfig({
+    ...config,
+    marketplaces: Object.keys(rest).length === 0 ? undefined : rest,
+  });
+}
+
+function refuseStandalone(verb: string): void {
+  if (isStandalone()) {
+    throw new UsageError(
+      `--standalone ignores the config file, so there is no marketplace list to ${verb} to\n\n` +
+        "Run without --standalone to change the configured marketplaces.",
+    );
+  }
+}
+
+type NarrowedEntry =
+  | { readonly ok: true; readonly source: MarketplaceSource }
+  | { readonly ok: false; readonly reason: string };
+
+/** The loose on-disk entry as a source, or the reason it is not one. */
+export function narrowEntry(entry: MarketplaceEntryConfig): NarrowedEntry {
+  switch (entry.type) {
+    case "github": {
+      if (typeof entry.repo !== "string" || !isOwnerRepo(entry.repo)) {
+        return { ok: false, reason: "type 'github' needs 'repo: owner/repo'" };
+      }
+      if (
+        entry.ref !== undefined &&
+        (typeof entry.ref !== "string" || entry.ref === "")
+      ) {
+        return {
+          ok: false,
+          reason: "'ref' must be a non-empty branch, tag or commit",
+        };
+      }
+      return {
+        ok: true,
+        source: {
+          type: "github",
+          repo: entry.repo,
+          ...(entry.ref !== undefined && { ref: entry.ref }),
+        },
+      };
+    }
+    case "local": {
+      if (typeof entry.path !== "string" || entry.path === "") {
+        return { ok: false, reason: "type 'local' needs 'path: <directory>'" };
+      }
+      return { ok: true, source: { type: "local", path: entry.path } };
+    }
+    case undefined:
+      return { ok: false, reason: "no 'type' (expected 'github' or 'local')" };
+    default:
+      return {
+        ok: false,
+        reason: `unknown type '${String(entry.type)}' (expected 'github' or 'local')`,
+      };
+  }
+}
+
+function toEntry(
+  source: Exclude<MarketplaceSource, { type: "official" }>,
+): MarketplaceEntryConfig {
+  switch (source.type) {
+    case "github":
+      return {
+        type: "github",
+        repo: source.repo,
+        ...(source.ref !== undefined && { ref: source.ref }),
+      };
+    case "local":
+      return { type: "local", path: source.path };
+    default: {
+      const exhaustive: never = source;
+      return exhaustive;
+    }
+  }
+}
+
+/** One sentence naming where a source comes from, for lists and sentences. */
+export function describeSource(source: MarketplaceSource): string {
+  switch (source.type) {
+    case "official":
+      return "built in";
+    case "github":
+      return describeGitHubSource(source);
+    case "local":
+      return source.path;
+    default: {
+      const exhaustive: never = source;
+      return exhaustive;
+    }
+  }
+}