@checkstack/backend 0.8.2 → 0.9.1

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);
+}

package/src/services/plugin-installers/plugin-install-error.ts

@@ -0,0 +1,37 @@
+/**
+ * Typed error thrown by per-source installers, the bundle resolver, and the
+ * compatibility checker. The router catches these and maps `code` to the
+ * matching oRPC error code so the UI sees a meaningful HTTP status + message
+ * instead of a generic "Internal server error".
+ *
+ * Throw a plain `Error` for genuine unexpected failures — those become 500s.
+ * Throw a `PluginInstallError` for any condition the user can fix (bad
+ * package name, network 404, validation failure, missing GHE token, etc.).
+ */
+export type PluginInstallErrorCode =
+  | "NOT_FOUND" // resource doesn't exist (npm 404, github tag not found, …)
+  | "BAD_REQUEST" // malformed input the user gave us
+  | "UNAUTHORIZED" // auth required (private repo, no token, …)
+  | "FORBIDDEN" // auth provided but rejected by the source
+  | "PAYLOAD_TOO_LARGE" // tarball over the size cap
+  | "BAD_GATEWAY" // upstream registry/github responded with a 5xx
+  | "VALIDATION_FAILED" // metadata schema rejected the package.json
+  | "COMPATIBILITY_FAILED" // dep ranges don't satisfy the platform
+  | "NOT_IMPLEMENTED"; // catalog source (coming soon)
+
+export class PluginInstallError extends Error {
+  constructor(
+    public readonly code: PluginInstallErrorCode,
+    message: string,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "PluginInstallError";
+  }
+}
+
+export function isPluginInstallError(
+  value: unknown,
+): value is PluginInstallError {
+  return value instanceof PluginInstallError;
+}

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

@@ -0,0 +1,80 @@
+import type {
+  PluginInstaller,
+  PluginSource,
+  FetchedTarball,
+  InstalledArtifact,
+  PluginArtifactStore,
+} from "@checkstack/backend-api";
+import { extractPackageJson, tryExtractBundle } from "./tarball-utils";
+import { installFromArtifact } from "./install-from-tarball";
+import { extractErrorMessage } from "@checkstack/common";
+import { PluginInstallError } from "./plugin-install-error";
+
+/**
+ * "Filesystem" / direct-upload installer.
+ *
+ * The tarball bytes are uploaded by the user via a multipart REST endpoint,
+ * temporarily persisted to `plugin_artifacts` (artifactId surfaces in the
+ * source), then this installer just resolves them by id.
+ */
+export class TarballPluginInstaller implements PluginInstaller {
+  constructor(
+    private readonly runtimeDir: string,
+    private readonly artifactStore: PluginArtifactStore,
+  ) {}
+
+  async fetchTarball(source: PluginSource): Promise<FetchedTarball> {
+    if (source.type !== "tarball") {
+      throw new Error(
+        `TarballPluginInstaller cannot handle source type '${source.type}'`,
+      );
+    }
+
+    const stored = await this.artifactStore.fetchById(source.artifactId);
+    if (!stored) {
+      throw new PluginInstallError(
+        "NOT_FOUND",
+        `No uploaded tarball found with id '${source.artifactId}'. ` +
+          `It may have been pruned or the upload did not complete — try uploading again.`,
+      );
+    }
+
+    const bundle = await tryExtractBundle(stored.tarball);
+    if (bundle) {
+      // For bundles, the outer tarball's "package.json" is the primary's.
+      const primary = bundle.siblings.find(
+        (s) => s.packageJson.name === bundle.manifest.primary,
+      );
+      if (!primary) {
+        throw new PluginInstallError(
+          "VALIDATION_FAILED",
+          `Bundle manifest names primary '${bundle.manifest.primary}' but no matching sibling tarball was found in the uploaded archive.`,
+        );
+      }
+      return {
+        tarball: stored.tarball,
+        packageJson: primary.packageJson,
+        bundle,
+      };
+    }
+
+    let packageJson;
+    try {
+      packageJson = await extractPackageJson(stored.tarball);
+    } catch (error) {
+      throw new PluginInstallError(
+        "VALIDATION_FAILED",
+        `Uploaded tarball is not a valid Checkstack plugin: ${extractErrorMessage(error)}`,
+      );
+    }
+    return { tarball: stored.tarball, packageJson };
+  }
+
+  async installFromArtifact(input: {
+    tarball: Uint8Array;
+    pluginName: string;
+    allowInstallScripts?: boolean;
+  }): Promise<InstalledArtifact> {
+    return installFromArtifact({ ...input, runtimeDir: this.runtimeDir });
+  }
+}