@crewhaus/template-marketplace-client 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@crewhaus/template-marketplace-client",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Studio Marketplace integration: list / search / install community templates; one-click publish flow (Section 40)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/template-registry": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/template-marketplace-client"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/template-marketplace-client#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LocalRegistrySource, type TemplateManifest } from "@crewhaus/template-registry";
+import { MarketplaceClient, MarketplaceClientError, MarketplacePublisher } from "./index";
+
+const seed = (overrides: Partial<TemplateManifest> = {}): TemplateManifest => ({
+  name: "hello-cli-template",
+  version: "1.0.0",
+  description: "Hello-world CLI template",
+  author: "alice",
+  target: "cli",
+  yaml: "name: hello\ntarget: cli\nagent:\n  model: claude-sonnet-4-6\n",
+  ...overrides,
+});
+
+describe("MarketplaceClient — search (T1)", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "marketplace-test-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function buildClient(rootDir: string, workspaceDir: string): MarketplaceClient {
+    const registry = new LocalRegistrySource({ rootDir });
+    registry.put(seed());
+    registry.put(
+      seed({
+        name: "slack-bot-template",
+        target: "channel",
+        author: "bob",
+        description: "Slack bot template",
+      }),
+    );
+    registry.put(
+      seed({
+        name: "rag-search-template",
+        target: "pipeline",
+        author: "carol",
+        description: "RAG retrieval template",
+      }),
+    );
+    return new MarketplaceClient({ registry, workspaceDir });
+  }
+
+  test("list returns all metadata entries", async () => {
+    const registryDir = join(tmp, "registry");
+    const workspace = join(tmp, "workspace");
+    const client = buildClient(registryDir, workspace);
+    const list = await client.list();
+    expect(list.length).toBe(3);
+  });
+
+  test("search by query matches name + description (case-insensitive)", async () => {
+    const client = buildClient(join(tmp, "r"), join(tmp, "w"));
+    const results = await client.search({ query: "RAG" });
+    expect(results.map((r) => r.metadata.name)).toEqual(["rag-search-template"]);
+  });
+
+  test("search by target filter", async () => {
+    const client = buildClient(join(tmp, "r"), join(tmp, "w"));
+    const results = await client.search({ target: "channel" });
+    expect(results.map((r) => r.metadata.name)).toEqual(["slack-bot-template"]);
+  });
+
+  test("search by author filter", async () => {
+    const client = buildClient(join(tmp, "r"), join(tmp, "w"));
+    const results = await client.search({ author: "alice" });
+    expect(results.map((r) => r.metadata.name)).toEqual(["hello-cli-template"]);
+  });
+
+  test("search ranks name matches above description-only matches", async () => {
+    const client = buildClient(join(tmp, "r"), join(tmp, "w"));
+    const results = await client.search({ query: "template" });
+    // Every entry contains "template" — but name matches should rank
+    // higher when the score is computed; results are sorted by score.
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  test("search limit caps results", async () => {
+    const client = buildClient(join(tmp, "r"), join(tmp, "w"));
+    const results = await client.search({ limit: 2 });
+    expect(results.length).toBe(2);
+  });
+});
+
+describe("MarketplaceClient — install (T1 + T8 path-traversal)", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "marketplace-install-test-"));
+  });
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("installs a template into <workspace>/<name>/crewhaus.yaml", async () => {
+    const registry = new LocalRegistrySource({ rootDir: join(tmp, "r") });
+    registry.put(seed());
+    const workspace = join(tmp, "w");
+    const client = new MarketplaceClient({ registry, workspaceDir: workspace });
+    const result = await client.install("hello-cli-template");
+    expect(result.path).toBe(join(workspace, "hello-cli-template", "crewhaus.yaml"));
+    expect(existsSync(result.path)).toBe(true);
+    const content = readFileSync(result.path, "utf8");
+    expect(content).toContain("target: cli");
+  });
+
+  test("install honors custom subdir + filename", async () => {
+    const registry = new LocalRegistrySource({ rootDir: join(tmp, "r") });
+    registry.put(seed());
+    const client = new MarketplaceClient({ registry, workspaceDir: join(tmp, "w") });
+    const result = await client.install("hello-cli-template", {
+      subdir: "my-custom-dir",
+      filename: "spec.yaml",
+    });
+    expect(result.path.endsWith(join("my-custom-dir", "spec.yaml"))).toBe(true);
+  });
+
+  test("install refuses path-traversal in name", async () => {
+    const registry = new LocalRegistrySource({ rootDir: join(tmp, "r") });
+    registry.put(seed());
+    const client = new MarketplaceClient({ registry, workspaceDir: join(tmp, "w") });
+    await expect(client.install("../escape")).rejects.toThrow(MarketplaceClientError);
+  });
+
+  test("install refuses path-traversal in subdir", async () => {
+    const registry = new LocalRegistrySource({ rootDir: join(tmp, "r") });
+    registry.put(seed());
+    const client = new MarketplaceClient({ registry, workspaceDir: join(tmp, "w") });
+    await expect(client.install("hello-cli-template", { subdir: "../escape" })).rejects.toThrow(
+      MarketplaceClientError,
+    );
+    await expect(client.install("hello-cli-template", { subdir: "evil/path" })).rejects.toThrow(
+      MarketplaceClientError,
+    );
+  });
+
+  test("install refuses path-traversal in filename", async () => {
+    const registry = new LocalRegistrySource({ rootDir: join(tmp, "r") });
+    registry.put(seed());
+    const client = new MarketplaceClient({ registry, workspaceDir: join(tmp, "w") });
+    await expect(
+      client.install("hello-cli-template", { filename: "../etc/passwd" }),
+    ).rejects.toThrow(MarketplaceClientError);
+  });
+});
+
+describe("MarketplacePublisher (T1 + T3)", () => {
+  test("draftPublish builds a PR-ready draft", () => {
+    const publisher = new MarketplacePublisher();
+    const draft = publisher.draftPublish({
+      registryName: "crewhaus/templates",
+      manifest: seed(),
+    });
+    expect(draft.title).toContain("hello-cli-template");
+    expect(draft.title).toContain("v1.0.0");
+    expect(draft.body).toContain("**Target:** cli");
+    expect(draft.body).toContain("**Author:** alice");
+    expect(JSON.parse(draft.manifestJson).name).toBe("hello-cli-template");
+  });
+
+  test("draftPublish refuses invalid template names", () => {
+    const publisher = new MarketplacePublisher();
+    expect(() =>
+      publisher.draftPublish({
+        registryName: "x",
+        manifest: seed({ name: "../escape" }),
+      }),
+    ).toThrow(MarketplaceClientError);
+  });
+
+  test("draftPublish requires registryName", () => {
+    const publisher = new MarketplacePublisher();
+    expect(() => publisher.draftPublish({ registryName: "", manifest: seed() })).toThrow(
+      MarketplaceClientError,
+    );
+  });
+
+  test("writeDraft persists manifest to <workspace>/templates/<name>.json", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "marketplace-publish-test-"));
+    try {
+      const publisher = new MarketplacePublisher();
+      const draft = publisher.draftPublish({
+        registryName: "x",
+        manifest: seed(),
+      });
+      const path = publisher.writeDraft(tmp, draft);
+      expect(path).toBe(join(tmp, "templates", "hello-cli-template.json"));
+      expect(existsSync(path)).toBe(true);
+      expect(JSON.parse(readFileSync(path, "utf8")).name).toBe("hello-cli-template");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,199 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+import type {
+  RegistrySource,
+  TemplateManifest,
+  TemplateMetadata,
+} from "@crewhaus/template-registry";
+
+/**
+ * Catalog F4 `template-marketplace-client` — Section 40 Studio
+ * Marketplace integration.
+ *
+ * Two surfaces:
+ *
+ *   1. **Discover/install**: `MarketplaceClient.search`,
+ *      `MarketplaceClient.install` — wraps a `RegistrySource` from
+ *      §40 `template-registry`, layers on search/filter, and writes
+ *      installed manifests into the user's spec workspace
+ *      (`<workspace>/<name>/crewhaus.yaml`).
+ *
+ *   2. **Publish**: `MarketplacePublisher.draftPublish` — produces a
+ *      `PublishDraft` describing a PR that the caller's git client
+ *      submits to the canonical registry repo (or pushes as a Gist).
+ *      We don't ship a git client here — Studio's existing GitHub
+ *      integration owns the actual transport.
+ *
+ * Layer F4. Pairs with `template-registry` (§40 — backend), Studio
+ * Marketplace tab (§35 surface, integration deferred to Studio UI).
+ */
+
+export class MarketplaceClientError extends CrewhausError {
+  override readonly name = "MarketplaceClientError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export type SearchFilter = {
+  /** Substring match on name + description (case-insensitive). */
+  readonly query?: string;
+  /** Exact match on `target`. */
+  readonly target?: string;
+  /** Exact match on `author`. */
+  readonly author?: string;
+  /** Cap results. Default 50. */
+  readonly limit?: number;
+};
+
+export type InstallOptions = {
+  /** Override the directory under workspaceDir. Default = manifest.name. */
+  readonly subdir?: string;
+  /** Filename. Default = "crewhaus.yaml". */
+  readonly filename?: string;
+};
+
+export type InstallResult = {
+  readonly path: string;
+  readonly manifest: TemplateManifest;
+};
+
+export type PublishDraft = {
+  readonly registryName: string;
+  readonly templateName: string;
+  readonly target: string;
+  readonly author: string;
+  readonly description: string;
+  readonly version: string;
+  readonly manifestJson: string;
+  readonly title: string;
+  readonly body: string;
+};
+
+export type MarketplaceClientOptions = {
+  readonly registry: RegistrySource;
+  readonly workspaceDir: string;
+};
+
+export type MarketplaceSearchResult = {
+  readonly metadata: TemplateMetadata;
+  readonly score: number;
+};
+
+export class MarketplaceClient {
+  constructor(private readonly opts: MarketplaceClientOptions) {
+    if (opts.registry === undefined) {
+      throw new MarketplaceClientError("registry is required");
+    }
+    if (typeof opts.workspaceDir !== "string" || opts.workspaceDir === "") {
+      throw new MarketplaceClientError("workspaceDir is required");
+    }
+  }
+
+  async list(): Promise<ReadonlyArray<TemplateMetadata>> {
+    return this.opts.registry.list();
+  }
+
+  async search(filter: SearchFilter = {}): Promise<ReadonlyArray<MarketplaceSearchResult>> {
+    const all = await this.opts.registry.list();
+    const limit = filter.limit ?? 50;
+    const queryLower = filter.query?.toLowerCase() ?? "";
+    const filtered = all
+      .map((m) => {
+        let score = 0;
+        if (filter.target !== undefined && m.target !== filter.target) return null;
+        if (filter.author !== undefined && m.author !== filter.author) return null;
+        if (queryLower !== "") {
+          const haystack = `${m.name} ${m.description}`.toLowerCase();
+          if (!haystack.includes(queryLower)) return null;
+          // Higher score for name matches than description-only matches.
+          if (m.name.toLowerCase().includes(queryLower)) score += 10;
+          score += haystack.split(queryLower).length - 1;
+        } else {
+          score = 1;
+        }
+        return { metadata: m, score };
+      })
+      .filter((r): r is MarketplaceSearchResult => r !== null);
+    return filtered.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  async install(name: string, opts: InstallOptions = {}): Promise<InstallResult> {
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+      throw new MarketplaceClientError(`invalid template name "${name}"`);
+    }
+    const manifest = await this.opts.registry.fetch(name);
+    const subdir = opts.subdir ?? manifest.name;
+    const filename = opts.filename ?? "crewhaus.yaml";
+    if (subdir.includes("..") || subdir.includes("/") || subdir.includes("\\")) {
+      throw new MarketplaceClientError(`invalid subdir "${subdir}"`);
+    }
+    if (filename.includes("..") || filename.includes("/") || filename.includes("\\")) {
+      throw new MarketplaceClientError(`invalid filename "${filename}"`);
+    }
+    const targetDir = join(this.opts.workspaceDir, subdir);
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    }
+    const path = join(targetDir, filename);
+    writeFileSync(path, manifest.yaml, { mode: 0o600 });
+    return { path, manifest };
+  }
+}
+
+export type DraftPublishOptions = {
+  readonly registryName: string;
+  readonly manifest: TemplateManifest;
+};
+
+export class MarketplacePublisher {
+  /**
+   * Produce a publish-ready `PublishDraft`. The caller's git client
+   * (Studio's GitHub integration, or `gh` from the CLI) opens the PR
+   * against the canonical registry repo with `manifestJson` written
+   * to `templates/<name>.json`.
+   */
+  draftPublish(opts: DraftPublishOptions): PublishDraft {
+    const m = opts.manifest;
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(m.name)) {
+      throw new MarketplaceClientError(`invalid template name "${m.name}"`);
+    }
+    if (typeof opts.registryName !== "string" || opts.registryName === "") {
+      throw new MarketplaceClientError("registryName is required");
+    }
+    const manifestJson = `${JSON.stringify(m, null, 2)}\n`;
+    const title = `Add template ${m.name} v${m.version} (${m.target})`;
+    const body = `# ${m.name} v${m.version}\n\n**Target:** ${m.target}  \n**Author:** ${m.author}\n\n${m.description}\n\n---\n\nFiles added:\n- templates/${m.name}.json\n`;
+    return {
+      registryName: opts.registryName,
+      templateName: m.name,
+      target: m.target,
+      author: m.author,
+      description: m.description,
+      version: m.version,
+      manifestJson,
+      title,
+      body,
+    };
+  }
+
+  /**
+   * Convenience: writes the publish draft to disk so the caller's git
+   * client (or a CI bot) can pick it up. Returns the manifest path.
+   */
+  writeDraft(workspaceDir: string, draft: PublishDraft): string {
+    if (typeof workspaceDir !== "string" || workspaceDir === "") {
+      throw new MarketplaceClientError("workspaceDir is required");
+    }
+    const path = join(workspaceDir, "templates", `${draft.templateName}.json`);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, draft.manifestJson, { mode: 0o600 });
+    return path;
+  }
+}
+
+export {
+  MarketplaceClient as _MarketplaceClientForTest,
+  MarketplacePublisher as _MarketplacePublisherForTest,
+};