@checkstack/backend 0.8.2 → 0.9.0

package/src/services/plugin-bundle-resolver.ts

@@ -0,0 +1,76 @@
+import type {
+  PluginInstallerRegistry,
+  PluginSource,
+  FetchedTarball,
+  NpmPluginSource,
+} from "@checkstack/backend-api";
+
+/**
+ * Given a `PluginSource`, fetch the primary tarball and recursively resolve
+ * any bundle siblings into a single normalized list.
+ *
+ * - npm: bundle siblings are *separate* npm packages; for each, we issue a
+ *   second `fetchTarball` call against the same registry.
+ * - tarball / github: bundle siblings are *inline* in the outer tarball
+ *   (per the `bundle.json` manifest); the per-source installer already
+ *   extracted them.
+ *
+ * Returns the primary first, then siblings in declared order.
+ */
+export async function resolveBundle({
+  source,
+  installerRegistry,
+}: {
+  source: PluginSource;
+  installerRegistry: PluginInstallerRegistry;
+}): Promise<{
+  primary: FetchedTarball;
+  packages: FetchedTarball[];
+  bundleId?: string;
+}> {
+  const primary = await installerRegistry.fetchTarball(source);
+  const packages: FetchedTarball[] = [primary];
+
+  // Inline bundle (tarball / github)
+  if (primary.bundle) {
+    for (const sib of primary.bundle.siblings) {
+      if (sib.packageJson.name === primary.packageJson.name) continue;
+      packages.push({ tarball: sib.tarball, packageJson: sib.packageJson });
+    }
+    return { primary, packages };
+  }
+
+  // Cross-package bundle for npm: declared via primary's checkstack.bundle
+  const declared = primary.packageJson.checkstack.bundle;
+  if (declared && declared.length > 0) {
+    if (source.type !== "npm") {
+      // Already-inline bundles are handled above; if a non-npm source
+      // declared `checkstack.bundle` without inlining, refuse — the
+      // expectation is the pack CLI produces a bundle tarball.
+      throw new Error(
+        `Plugin ${primary.packageJson.name} declares 'checkstack.bundle' but the source ` +
+          `(${source.type}) did not ship sibling tarballs. Use the GitHub release / tarball ` +
+          `source with a --bundle-mode tarball, or remove 'checkstack.bundle'.`,
+      );
+    }
+    for (const siblingName of declared) {
+      const siblingSource: NpmPluginSource = {
+        type: "npm",
+        packageName: siblingName,
+        // Pin sibling version to primary's exact version — bundles are
+        // released atomically and identical-versioned by convention.
+        version: primary.packageJson.version,
+        registry: source.registry,
+      };
+      const fetched = await installerRegistry.fetchTarball(siblingSource);
+      if (fetched.bundle) {
+        throw new Error(
+          `Sibling '${siblingName}' itself ships a bundle — bundles cannot nest.`,
+        );
+      }
+      packages.push(fetched);
+    }
+  }
+
+  return { primary, packages };
+}

package/src/services/plugin-event-recorder.ts

@@ -0,0 +1,87 @@
+import { desc, eq } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import type { PluginSource } from "@checkstack/common";
+import type {
+  InstallEvent,
+  InstallEventAction,
+  InstallEventPhase,
+  InstallEventStatus,
+} from "@checkstack/pluginmanager-common";
+import { pluginInstallEvents } from "../schema";
+
+/**
+ * Persist install/uninstall lifecycle events.
+ *
+ * Every step of the install/uninstall flow writes a row here:
+ *   - originator: validate / persist / broadcast / destructive-cleanup / audit
+ *   - receiving instances: in-process-load / in-process-unload
+ *
+ * Failures are kept (status="failed") so the admin Events page can surface
+ * partial state for manual remediation. The originator dying mid-flight
+ * leaves a "started" row that never transitions — the UI flags those.
+ */
+export class PluginEventRecorder {
+  constructor(
+    private readonly db: SafeDatabase<Record<string, unknown>>,
+    private readonly instanceId: string,
+  ) {}
+
+  async record(input: {
+    pluginName?: string | null;
+    bundleId?: string | null;
+    action: InstallEventAction;
+    phase: InstallEventPhase;
+    status: InstallEventStatus;
+    source?: PluginSource | null;
+    error?: string | null;
+    userId?: string | null;
+  }): Promise<void> {
+    // Drizzle writes `null` as a real NULL column and `undefined` as
+    // "skip this column"; both map to NULL on insert here, but normalize
+    // to `null` so the row's shape matches the schema-declared
+    // nullable columns.
+    await this.db.insert(pluginInstallEvents).values({
+      pluginName: input.pluginName ?? null,
+      bundleId: input.bundleId ?? null,
+      action: input.action,
+      phase: input.phase,
+      status: input.status,
+      source: input.source ?? null,
+      error: input.error ?? null,
+      instanceId: this.instanceId,
+      userId: input.userId ?? null,
+    });
+  }
+
+  async list(input?: {
+    pluginName?: string;
+    limit?: number;
+  }): Promise<InstallEvent[]> {
+    const limit = input?.limit ?? 100;
+    const where = input?.pluginName
+      ? eq(pluginInstallEvents.pluginName, input.pluginName)
+      : undefined;
+
+    const rows = await this.db
+      .select()
+      .from(pluginInstallEvents)
+      .where(where)
+      .orderBy(desc(pluginInstallEvents.createdAt))
+      .limit(limit);
+
+    return rows.map((row) => ({
+      id: row.id,
+      pluginName: row.pluginName,
+      bundleId: row.bundleId,
+      action: row.action as InstallEventAction,
+      phase: row.phase as InstallEventPhase,
+      status: row.status as InstallEventStatus,
+      source: row.source as PluginSource | null,
+      error: row.error,
+      instanceId: row.instanceId,
+      userId: row.userId,
+      createdAt: row.createdAt.toISOString(),
+    }));
+  }
+
+}

package/src/services/plugin-installers/catalog-installer.ts

@@ -0,0 +1,33 @@
+import type {
+  PluginInstaller,
+  PluginSource,
+  FetchedTarball,
+  InstalledArtifact,
+} from "@checkstack/backend-api";
+import { PluginInstallError } from "./plugin-install-error";
+
+/**
+ * Stub for the future Checkstack catalog/marketplace.
+ *
+ * Surfaces in the UI as a "Coming Soon" tab; calling the install endpoint
+ * with a `catalog` source returns an explicit not-implemented error.
+ */
+export class CatalogPluginInstaller implements PluginInstaller {
+  async fetchTarball(_source: PluginSource): Promise<FetchedTarball> {
+    throw new PluginInstallError(
+      "NOT_IMPLEMENTED",
+      "The Checkstack plugin catalog isn't available yet. Install via npm, GitHub release, or tarball upload in the meantime.",
+    );
+  }
+
+  async installFromArtifact(_input: {
+    tarball: Uint8Array;
+    pluginName: string;
+    allowInstallScripts?: boolean;
+  }): Promise<InstalledArtifact> {
+    throw new PluginInstallError(
+      "NOT_IMPLEMENTED",
+      "The Checkstack plugin catalog isn't available yet.",
+    );
+  }
+}

package/src/services/plugin-installers/github-installer.ts

@@ -0,0 +1,207 @@
+import type {
+  PluginInstaller,
+  PluginSource,
+  FetchedTarball,
+  InstalledArtifact,
+} from "@checkstack/backend-api";
+import {
+  extractPackageJson,
+  tryExtractBundle,
+  MAX_TARBALL_SIZE_BYTES,
+} from "./tarball-utils";
+import { installFromArtifact } from "./install-from-tarball";
+import { rootLogger } from "../../logger";
+import { extractErrorMessage } from "@checkstack/common";
+import { PluginInstallError } from "./plugin-install-error";
+
+interface GithubReleaseAsset {
+  name: string;
+  browser_download_url: string;
+  size: number;
+}
+
+interface GithubRelease {
+  tag_name: string;
+  assets: GithubReleaseAsset[];
+}
+
+/**
+ * Install a plugin from a GitHub release.
+ *
+ * Convention (enforced by the `@checkstack/scripts plugin-pack` CLI):
+ *   - The release for tag `vX.Y.Z` includes exactly one `.tgz` asset.
+ *   - For multi-package plugins (`checkstack.bundle` set on the primary),
+ *     that asset is a `--bundle`-mode outer tarball with `bundle.json`.
+ *
+ * Building never happens at install time — the CLI runs at release time.
+ */
+export class GithubPluginInstaller implements PluginInstaller {
+  constructor(private readonly runtimeDir: string) {}
+
+  async fetchTarball(source: PluginSource): Promise<FetchedTarball> {
+    if (source.type !== "github") {
+      throw new Error(
+        `GithubPluginInstaller cannot handle source type '${source.type}'`,
+      );
+    }
+
+    // Determine API base. Defaults to public github.com; for GitHub
+    // Enterprise the source carries an explicit `apiBaseUrl` like
+    // `https://github.example.com/api/v3`. We strip a trailing slash so
+    // either form (`/api/v3` or `/api/v3/`) is accepted.
+    const apiBase = (
+      source.apiBaseUrl ?? "https://api.github.com"
+    ).replace(/\/$/, "");
+    const releaseUrl = `${apiBase}/repos/${source.owner}/${source.repo}/releases/tags/${source.tag}`;
+    rootLogger.info(`📦 Resolving GitHub release: ${releaseUrl}`);
+
+    // Token resolution: configurable env var name (defaults to
+    // `GITHUB_TOKEN`). Different deployments may need to talk to several
+    // GitHub instances (public + enterprise), so we let the source
+    // declare which env var holds the right PAT.
+    const tokenEnvVar = source.tokenEnvVar ?? "GITHUB_TOKEN";
+    const token = process.env[tokenEnvVar];
+
+    const headers: Record<string, string> = {
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+    };
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+
+    const repoLabel = `${source.owner}/${source.repo}@${source.tag}`;
+
+    let meta: Response;
+    try {
+      meta = await fetch(releaseUrl, { headers });
+    } catch (error) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `Could not reach GitHub at ${apiBase}: ${extractErrorMessage(error)}`,
+      );
+    }
+    if (!meta.ok) {
+      if (meta.status === 404) {
+        throw new PluginInstallError(
+          "NOT_FOUND",
+          `GitHub release '${repoLabel}' not found. Verify the owner, repo, and tag, ` +
+            `and (for private repos) that the platform's PAT in '${tokenEnvVar}' has access.`,
+        );
+      }
+      if (meta.status === 401) {
+        throw new PluginInstallError(
+          "UNAUTHORIZED",
+          token
+            ? `GitHub rejected the token in '${tokenEnvVar}' (HTTP 401). The token may be expired.`
+            : `GitHub release '${repoLabel}' requires authentication. Set a PAT in '${tokenEnvVar}'.`,
+        );
+      }
+      if (meta.status === 403) {
+        throw new PluginInstallError(
+          "FORBIDDEN",
+          `GitHub returned 403 for '${repoLabel}'. Either rate-limited or the token in '${tokenEnvVar}' lacks access.`,
+        );
+      }
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `GitHub release lookup returned HTTP ${meta.status} for ${repoLabel}.`,
+      );
+    }
+    const release = (await meta.json()) as GithubRelease;
+
+    const tgzAssets = release.assets.filter((a) => a.name.endsWith(".tgz"));
+    let asset: GithubReleaseAsset | undefined;
+    if (source.assetName) {
+      asset = release.assets.find((a) => a.name === source.assetName);
+      if (!asset) {
+        throw new PluginInstallError(
+          "NOT_FOUND",
+          `Release '${repoLabel}' has no asset named '${source.assetName}'. ` +
+            `Available .tgz assets: ${
+              tgzAssets.map((a) => a.name).join(", ") || "(none)"
+            }.`,
+        );
+      }
+    } else if (tgzAssets.length === 1) {
+      asset = tgzAssets[0];
+    } else if (tgzAssets.length === 0) {
+      throw new PluginInstallError(
+        "NOT_FOUND",
+        `Release '${repoLabel}' has no .tgz asset. ` +
+          `Run 'bunx @checkstack/scripts plugin-pack' in the plugin repo and attach the produced tarball to the release.`,
+      );
+    } else {
+      throw new PluginInstallError(
+        "BAD_REQUEST",
+        `Release '${repoLabel}' has ${tgzAssets.length} .tgz assets (${tgzAssets
+          .map((a) => a.name)
+          .join(", ")}) — set 'assetName' on the source to disambiguate.`,
+      );
+    }
+
+    if (asset.size > MAX_TARBALL_SIZE_BYTES) {
+      throw new PluginInstallError(
+        "PAYLOAD_TOO_LARGE",
+        `Release asset '${asset.name}' is ${(asset.size / 1024 / 1024).toFixed(
+          1,
+        )}MB, which exceeds the ${(MAX_TARBALL_SIZE_BYTES / 1024 / 1024).toFixed(
+          0,
+        )}MB platform limit.`,
+      );
+    }
+
+    rootLogger.info(`📦 Downloading: ${asset.browser_download_url}`);
+    let tarResp: Response;
+    try {
+      tarResp = await fetch(asset.browser_download_url, {
+        headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+      });
+    } catch (error) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `Could not download release asset '${asset.name}': ${extractErrorMessage(error)}`,
+      );
+    }
+    if (!tarResp.ok) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `Failed to download release asset '${asset.name}': HTTP ${tarResp.status} ${tarResp.statusText}.`,
+      );
+    }
+    const buf = new Uint8Array(await tarResp.arrayBuffer());
+
+    const bundle = await tryExtractBundle(buf);
+    if (bundle) {
+      const primary = bundle.siblings.find(
+        (s) => s.packageJson.name === bundle.manifest.primary,
+      );
+      if (!primary) {
+        throw new PluginInstallError(
+          "VALIDATION_FAILED",
+          `Bundle manifest in '${asset.name}' names primary '${bundle.manifest.primary}' but no matching sibling tarball was found.`,
+        );
+      }
+      return { tarball: buf, packageJson: primary.packageJson, bundle };
+    }
+
+    let packageJson;
+    try {
+      packageJson = await extractPackageJson(buf);
+    } catch (error) {
+      throw new PluginInstallError(
+        "VALIDATION_FAILED",
+        `Release asset '${asset.name}' is not a valid Checkstack plugin tarball: ${extractErrorMessage(error)}`,
+      );
+    }
+    return { tarball: buf, packageJson };
+  }
+
+  async installFromArtifact(input: {
+    tarball: Uint8Array;
+    pluginName: string;
+    allowInstallScripts?: boolean;
+  }): Promise<InstalledArtifact> {
+    return installFromArtifact({ ...input, runtimeDir: this.runtimeDir });
+  }
+}

package/src/services/plugin-installers/install-from-tarball.ts

@@ -0,0 +1,69 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import os from "node:os";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { InstalledArtifact } from "@checkstack/backend-api";
+import { rootLogger } from "../../logger";
+import { extractPackageJson } from "./tarball-utils";
+
+const execAsync = promisify(exec);
+
+/**
+ * Shared post-fetch installer used by every per-source installer.
+ *
+ * Writes the tarball bytes to a tmpfile and runs `bun install <file>` into
+ * the runtime dir. Lifecycle scripts are blocked by default
+ * (`--ignore-scripts`); plugins can opt in via
+ * `package.json#checkstack.allowInstallScripts: true` — surfaced in the
+ * install warning UI.
+ */
+export async function installFromArtifact({
+  tarball,
+  pluginName,
+  allowInstallScripts,
+  runtimeDir,
+}: {
+  tarball: Uint8Array;
+  pluginName: string;
+  allowInstallScripts?: boolean;
+  runtimeDir: string;
+}): Promise<InstalledArtifact> {
+  await fs.mkdir(runtimeDir, { recursive: true });
+
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "checkstack-plugin-"));
+  const tarPath = path.join(tmpDir, "plugin.tgz");
+  try {
+    await fs.writeFile(tarPath, tarball);
+
+    const ignoreScripts = allowInstallScripts ? "" : "--ignore-scripts";
+    const cmd = `bun install "${tarPath}" --cwd "${runtimeDir}" --no-save ${ignoreScripts}`.trim();
+
+    rootLogger.info(`📦 Running: ${cmd}`);
+    const { stderr } = await execAsync(cmd);
+    if (stderr) rootLogger.debug(stderr);
+
+    // After install, validate the installed package.json matches what we
+    // expected. The pkg dir under node_modules can be a scoped path
+    // (`@scope/name`), so resolve via the tarball's package.json name.
+    const expected = await extractPackageJson(tarball);
+    if (expected.name !== pluginName) {
+      throw new Error(
+        `Tarball name mismatch: expected '${pluginName}', got '${expected.name}'`,
+      );
+    }
+
+    const pkgDir = path.join(runtimeDir, "node_modules", expected.name);
+    const installedPkgJson = JSON.parse(
+      await fs.readFile(path.join(pkgDir, "package.json"), "utf8"),
+    );
+
+    return {
+      name: installedPkgJson.name,
+      path: pkgDir,
+      version: installedPkgJson.version,
+    };
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}

package/src/services/plugin-installers/installer-registry.ts

@@ -0,0 +1,51 @@
+import type {
+  PluginInstaller,
+  PluginInstallerRegistry,
+  PluginSource,
+  FetchedTarball,
+  PluginArtifactStore,
+} from "@checkstack/backend-api";
+import { NpmPluginInstaller } from "./npm-installer";
+import { TarballPluginInstaller } from "./tarball-installer";
+import { GithubPluginInstaller } from "./github-installer";
+import { CatalogPluginInstaller } from "./catalog-installer";
+
+/**
+ * Composite registry that routes a `PluginSource` to its installer.
+ *
+ * One instance is registered against `coreServices.pluginInstallerRegistry`
+ * at boot. All plugin install/uninstall flows go through this — the
+ * legacy single-method `PluginInstaller` is gone.
+ */
+export class DefaultPluginInstallerRegistry
+  implements PluginInstallerRegistry
+{
+  private readonly installers: Record<PluginSource["type"], PluginInstaller>;
+
+  constructor({
+    runtimeDir,
+    artifactStore,
+  }: {
+    runtimeDir: string;
+    artifactStore: PluginArtifactStore;
+  }) {
+    this.installers = {
+      npm: new NpmPluginInstaller(runtimeDir),
+      tarball: new TarballPluginInstaller(runtimeDir, artifactStore),
+      github: new GithubPluginInstaller(runtimeDir),
+      catalog: new CatalogPluginInstaller(),
+    };
+  }
+
+  forSource(type: PluginSource["type"]): PluginInstaller {
+    const installer = this.installers[type];
+    if (!installer) {
+      throw new Error(`No plugin installer registered for source type '${type}'`);
+    }
+    return installer;
+  }
+
+  fetchTarball(source: PluginSource): Promise<FetchedTarball> {
+    return this.forSource(source.type).fetchTarball(source);
+  }
+}

package/src/services/plugin-installers/npm-installer.ts

@@ -0,0 +1,156 @@
+import type {
+  PluginInstaller,
+  PluginSource,
+  FetchedTarball,
+  InstalledArtifact,
+} from "@checkstack/backend-api";
+import {
+  extractPackageJson,
+  tryExtractBundle,
+  MAX_TARBALL_SIZE_BYTES,
+} from "./tarball-utils";
+import { installFromArtifact } from "./install-from-tarball";
+import { rootLogger } from "../../logger";
+import { extractErrorMessage } from "@checkstack/common";
+import { PluginInstallError } from "./plugin-install-error";
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+
+/**
+ * Fetch a plugin tarball directly from an npm registry.
+ *
+ * No on-disk install happens here — we hit the registry's metadata API to
+ * resolve `dist.tarball`, then download bytes to memory. The originator
+ * uploads those bytes to `plugin_artifacts`; receiving instances install
+ * from there.
+ */
+export class NpmPluginInstaller implements PluginInstaller {
+  constructor(private readonly runtimeDir: string) {}
+
+  async fetchTarball(source: PluginSource): Promise<FetchedTarball> {
+    if (source.type !== "npm") {
+      throw new Error(
+        `NpmPluginInstaller cannot handle source type '${source.type}'`,
+      );
+    }
+
+    const registry = (source.registry || DEFAULT_REGISTRY).replace(/\/$/, "");
+    const versionPath = source.version ? `/${source.version}` : "/latest";
+    const metaUrl = `${registry}/${encodeNpmName(source.packageName)}${versionPath}`;
+    const versionLabel = source.version ?? "latest";
+
+    rootLogger.info(`📦 Resolving npm metadata: ${metaUrl}`);
+    let metaResp: Response;
+    try {
+      metaResp = await fetch(metaUrl);
+    } catch (error) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `Could not reach npm registry at ${registry}: ${extractErrorMessage(error)}`,
+      );
+    }
+    if (!metaResp.ok) {
+      if (metaResp.status === 404) {
+        throw new PluginInstallError(
+          "NOT_FOUND",
+          `Package '${source.packageName}@${versionLabel}' not found on the npm registry${
+            source.registry ? ` at ${source.registry}` : ""
+          }.`,
+        );
+      }
+      if (metaResp.status === 401 || metaResp.status === 403) {
+        throw new PluginInstallError(
+          metaResp.status === 401 ? "UNAUTHORIZED" : "FORBIDDEN",
+          `Access to '${source.packageName}' on ${registry} was rejected (HTTP ${metaResp.status}). ` +
+            `If this is a private registry, configure auth on the platform.`,
+        );
+      }
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `npm registry returned HTTP ${metaResp.status} for ${source.packageName}@${versionLabel}.`,
+      );
+    }
+    const meta = (await metaResp.json()) as {
+      name: string;
+      version: string;
+      dist?: { tarball?: string };
+    };
+
+    const tarballUrl = meta.dist?.tarball;
+    if (!tarballUrl) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `npm metadata for '${source.packageName}@${versionLabel}' did not include a download URL (dist.tarball missing).`,
+      );
+    }
+
+    rootLogger.info(`📦 Downloading tarball: ${tarballUrl}`);
+    let tarResp: Response;
+    try {
+      tarResp = await fetch(tarballUrl);
+    } catch (error) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `Could not download tarball from ${tarballUrl}: ${extractErrorMessage(error)}`,
+      );
+    }
+    if (!tarResp.ok) {
+      throw new PluginInstallError(
+        "BAD_GATEWAY",
+        `Tarball download for '${source.packageName}@${versionLabel}' failed: HTTP ${tarResp.status} ${tarResp.statusText}.`,
+      );
+    }
+    const buf = new Uint8Array(await tarResp.arrayBuffer());
+    if (buf.byteLength > MAX_TARBALL_SIZE_BYTES) {
+      throw new PluginInstallError(
+        "PAYLOAD_TOO_LARGE",
+        `Tarball for '${source.packageName}' is ${(
+          buf.byteLength /
+          1024 /
+          1024
+        ).toFixed(1)}MB, which exceeds the ${(
+          MAX_TARBALL_SIZE_BYTES /
+          1024 /
+          1024
+        ).toFixed(0)}MB platform limit.`,
+      );
+    }
+
+    const bundle = await tryExtractBundle(buf);
+    if (bundle) {
+      // npm doesn't ship bundle tarballs (those go via GitHub release / direct
+      // upload). If we ever encounter one here it means an external author
+      // mis-published — reject explicitly rather than silently accept.
+      throw new PluginInstallError(
+        "BAD_REQUEST",
+        `Package '${source.packageName}' from npm contains a bundle manifest. ` +
+          `Bundle tarballs must be installed via the GitHub release or tarball-upload sources.`,
+      );
+    }
+
+    let packageJson;
+    try {
+      packageJson = await extractPackageJson(buf);
+    } catch (error) {
+      throw new PluginInstallError(
+        "VALIDATION_FAILED",
+        `Package '${source.packageName}@${versionLabel}' is not a valid Checkstack plugin: ${extractErrorMessage(error)}`,
+      );
+    }
+    return { tarball: buf, packageJson };
+  }
+
+  async installFromArtifact(input: {
+    tarball: Uint8Array;
+    pluginName: string;
+    allowInstallScripts?: boolean;
+  }): Promise<InstalledArtifact> {
+    return installFromArtifact({ ...input, runtimeDir: this.runtimeDir });
+  }
+}
+
+function encodeNpmName(name: string): string {
+  // npm scoped names use `@scope/name`; the registry expects the slash to
+  // remain unencoded but `@` is OK either way.
+  return name.startsWith("@") ? name : encodeURIComponent(name);
+}