@prisma/compute-sdk 0.28.0 → 0.30.0

package/src/config/frameworks.ts

@@ -13,6 +13,7 @@ export type FrameworkBuildType =
   | "astro"
   | "nestjs"
   | "tanstack-start"
+  | "custom"
   | "bun";
 
 export interface FrameworkDescriptor {
@@ -138,6 +139,18 @@ export const FRAMEWORKS: readonly FrameworkDescriptor[] = [
     hasLocalDevServer: false,
     defaultHttpPort: 3000,
   },
+  {
+    key: "custom",
+    displayName: "Custom",
+    buildType: "custom",
+    aliases: ["custom"],
+    detectPackages: [],
+    detectConfigFiles: [],
+    usesEntrypoint: false,
+    defaultEntrypoint: null,
+    hasLocalDevServer: false,
+    defaultHttpPort: 3000,
+  },
   {
     key: "bun",
     displayName: "Bun",
@@ -154,14 +167,14 @@ export const FRAMEWORKS: readonly FrameworkDescriptor[] = [
 
 export const FRAMEWORK_KEYS = FRAMEWORKS.map((framework) => framework.key);
 
-/**
- * Build types whose preview build consumes committed build settings. The
- * others (nuxt, astro) run their framework CLI and stage fixed output, so a
- * config `build` block has nothing to apply to.
- */
+/** Build types whose preview build consumes committed build settings. */
 export const CONFIG_BACKED_BUILD_TYPES = [
   "nextjs",
+  "nuxt",
+  "astro",
+  "nestjs",
   "tanstack-start",
+  "custom",
   "bun",
 ] as const satisfies readonly FrameworkBuildType[];
 

package/src/config/normalize.ts

@@ -2,7 +2,7 @@ import path from "node:path";
 
 import { Result, TaggedError } from "better-result";
 
-import { frameworkByKey, isConfigBackedBuildType } from "./frameworks.ts";
+import { frameworkByKey } from "./frameworks.ts";
 import { COMPUTE_FRAMEWORKS, type ComputeFramework } from "./types.ts";
 
 export interface ComputeDeployTargetBuild {
@@ -10,6 +10,11 @@ export interface ComputeDeployTargetBuild {
   command: string | null | undefined;
   /** Normalized output path relative to the app root, undefined when not configured. */
   outputDirectory: string | undefined;
+  /**
+   * Normalized configured entrypoint. With outputDirectory it is relative to
+   * that output directory; otherwise it is relative to the app root.
+   */
+  entrypoint: string | undefined;
 }
 
 export interface ComputeDeployTarget {
@@ -19,6 +24,7 @@ export interface ComputeDeployTarget {
   /** Normalized app directory relative to the config file, or null for the config directory. */
   root: string | null;
   framework: ComputeFramework | null;
+  /** Runtime/source entrypoint normalized from `entry` or an entrypoint-backed `build.entrypoint`. */
   entry: string | null;
   httpPort: number | null;
   /** Env inputs in deploy order: dotenv file paths first, then NAME=VALUE assignments. */
@@ -104,7 +110,7 @@ const KNOWN_APP_KEYS = [
   "build",
 ] as const;
 const KNOWN_ENV_KEYS = ["file", "vars"] as const;
-const KNOWN_BUILD_KEYS = ["command", "outputDirectory"] as const;
+const KNOWN_BUILD_KEYS = ["command", "outputDirectory", "entrypoint"] as const;
 
 /**
  * Validates and normalizes a config module's default export. Reports every
@@ -343,7 +349,8 @@ function normalizeAppEntry(
     }
   }
 
-  if (entry && framework && !frameworkByKey(framework).usesEntrypoint) {
+  const frameworkDescriptor = framework ? frameworkByKey(framework) : null;
+  if (entry && frameworkDescriptor && !frameworkDescriptor.usesEntrypoint) {
     issues.push(
       `\`${label}.entry\` is not supported with the ${framework} framework; it derives its entrypoint from build output.`,
     );
@@ -367,22 +374,53 @@ function normalizeAppEntry(
 
   const envInputs = normalizeEnvConfig(value.env, `${label}.env`, issues);
   const build = normalizeBuildConfig(value.build, `${label}.build`, issues);
+  if (framework === "custom") {
+    if (!build) {
+      issues.push(
+        `\`${label}.build\` is required with the custom framework and must set \`outputDirectory\` and \`entrypoint\`.`,
+      );
+    } else {
+      if (!build.outputDirectory) {
+        issues.push(
+          `\`${label}.build.outputDirectory\` is required with the custom framework.`,
+        );
+      }
+      if (!build.entrypoint) {
+        issues.push(
+          `\`${label}.build.entrypoint\` is required with the custom framework.`,
+        );
+      }
+    }
+  } else if (
+    build?.outputDirectory &&
+    build.outputDirectory !== "." &&
+    !build.entrypoint &&
+    frameworkDescriptor?.usesEntrypoint
+  ) {
+    issues.push(
+      `\`${label}.build.entrypoint\` is required when \`${label}.build.outputDirectory\` is set with the ${framework} framework.`,
+    );
+  }
   if (
-    build &&
-    framework &&
-    !isConfigBackedBuildType(frameworkByKey(framework).buildType)
+    entry &&
+    build?.entrypoint &&
+    frameworkDescriptor?.usesEntrypoint &&
+    entry !== build.entrypoint
   ) {
     issues.push(
-      `\`${label}.build\` is not supported with the ${framework} framework; its build runs automatically during deploy.`,
+      `\`${label}.entry\` and \`${label}.build.entrypoint\` both configure the runtime entrypoint; set only one, or make them match.`,
     );
   }
-
   return {
     key,
     name,
     root,
     framework,
-    entry,
+    entry:
+      entry ??
+      (frameworkDescriptor?.usesEntrypoint || !frameworkDescriptor
+        ? (build?.entrypoint ?? null)
+        : null),
     httpPort,
     envInputs,
     build,
@@ -400,7 +438,7 @@ function normalizeBuildConfig(
 
   if (!isPlainObject(value)) {
     issues.push(
-      `\`${label}\` must be an object with \`command\` and/or \`outputDirectory\`.`,
+      `\`${label}\` must be an object with \`command\`, \`outputDirectory\`, and/or \`entrypoint\`.`,
     );
     return null;
   }
@@ -444,14 +482,37 @@ function normalizeBuildConfig(
     }
   }
 
-  if (command === undefined && outputDirectory === undefined) {
+  let entrypoint: string | undefined;
+  if (value.entrypoint !== undefined) {
+    const normalized =
+      typeof value.entrypoint === "string"
+        ? normalizeRelativePath(value.entrypoint)
+        : undefined;
+    if (!normalized) {
+      issues.push(
+        `\`${label}.entrypoint\` must be a relative path that stays inside its base directory.`,
+      );
+    } else if (normalized === ".") {
+      issues.push(
+        `\`${label}.entrypoint\` must be a relative file path inside its base directory.`,
+      );
+    } else {
+      entrypoint = normalized;
+    }
+  }
+
+  if (
+    command === undefined &&
+    outputDirectory === undefined &&
+    entrypoint === undefined
+  ) {
     issues.push(
-      `\`${label}\` must set \`command\` and/or \`outputDirectory\`.`,
+      `\`${label}\` must set \`command\`, \`outputDirectory\`, and/or \`entrypoint\`.`,
     );
     return null;
   }
 
-  return { command, outputDirectory };
+  return { command, outputDirectory, entrypoint };
 }
 
 function normalizeEnvConfig(

package/src/config/types.ts

@@ -13,6 +13,7 @@ export const COMPUTE_FRAMEWORKS = [
   "hono",
   "nestjs",
   "tanstack-start",
+  "custom",
   "bun",
 ] as const;
 
@@ -34,6 +35,8 @@ export interface ComputeBuildConfig {
   command?: string | null;
   /** Framework output path relative to the app root, e.g. ".next/standalone". */
   outputDirectory?: string;
+  /** Entrypoint for the built artifact, relative to `outputDirectory` when one is set. */
+  entrypoint?: string;
 }
 
 export interface ComputeAppConfig {

package/src/configured-artifact.ts

@@ -0,0 +1,169 @@
+import { cp, mkdtemp, realpath, rm, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { normalizeArtifactSymlinks } from "./artifact-postprocess.ts";
+import type { BuildArtifact } from "./build-strategy.ts";
+import {
+  defaultHttpPortForBuildType,
+  type FrameworkBuildType,
+} from "./config/frameworks.ts";
+
+export async function stageConfiguredArtifact(options: {
+  appPath: string;
+  outputDirectory: string;
+  entrypoint: string;
+  buildType: FrameworkBuildType;
+  label: string;
+  missingEntrypointMessage?: string;
+  signal?: AbortSignal;
+}): Promise<BuildArtifact> {
+  options.signal?.throwIfAborted();
+  const outputDir = resolvePathInside(
+    options.appPath,
+    options.outputDirectory,
+    `${options.label} build output directory must be a relative path inside the app directory`,
+  );
+  const outputStat = await stat(outputDir).catch(() => null);
+  if (!outputStat?.isDirectory()) {
+    throw new Error(
+      `${options.label} build output directory does not exist: ${options.outputDirectory}`,
+    );
+  }
+
+  const [realAppPath, realOutputDir] = await Promise.all([
+    realpath(path.resolve(options.appPath)),
+    realpath(outputDir),
+  ]);
+  if (!isPathWithin(realAppPath, realOutputDir)) {
+    throw new Error(
+      `${options.label} build output directory must stay inside the app directory`,
+    );
+  }
+
+  const entrypoint = await resolveConfiguredArtifactEntrypoint({
+    directory: realOutputDir,
+    entrypoint: options.entrypoint,
+    label: options.label,
+    displayDirectory: options.outputDirectory,
+    missingEntrypointMessage: options.missingEntrypointMessage,
+  });
+
+  const outDir = await mkdtemp(path.join(os.tmpdir(), "compute-build-"));
+  try {
+    const artifactDir = path.join(outDir, "app");
+    await cp(realOutputDir, artifactDir, {
+      recursive: true,
+      verbatimSymlinks: true,
+    });
+    await normalizeArtifactSymlinks(
+      artifactDir,
+      options.appPath,
+      options.signal,
+    );
+
+    return {
+      directory: artifactDir,
+      entrypoint,
+      defaultPortMapping: {
+        http: defaultHttpPortForBuildType(options.buildType),
+      },
+      cleanup: () => rm(outDir, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    await rm(outDir, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function resolveConfiguredArtifactEntrypoint(options: {
+  directory: string;
+  entrypoint: string;
+  label: string;
+  displayDirectory?: string;
+  missingEntrypointMessage?: string;
+}): Promise<string> {
+  const entrypoint = normalizeConfiguredArtifactEntrypoint(
+    options.entrypoint,
+    options.label,
+  );
+  const entryPath = path.join(options.directory, entrypoint);
+  const entryStat = await stat(entryPath).catch(() => null);
+  if (!entryStat?.isFile()) {
+    if (options.missingEntrypointMessage) {
+      throw new Error(options.missingEntrypointMessage);
+    }
+    const directory = options.displayDirectory ?? options.directory;
+    throw new Error(
+      `${options.label} build entrypoint does not exist: ${directory}/${entrypoint}`,
+    );
+  }
+  return entrypoint;
+}
+
+export function normalizeConfiguredArtifactEntrypoint(
+  entrypoint: string,
+  label: string,
+): string {
+  const normalized = path.posix.normalize(
+    entrypoint.trim().replace(/\\/g, "/"),
+  );
+  if (
+    normalized.length === 0 ||
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../") ||
+    path.win32.isAbsolute(entrypoint) ||
+    path.posix.isAbsolute(normalized) ||
+    /^[A-Za-z]:/.test(normalized)
+  ) {
+    throw new Error(
+      `${label} build entrypoint must be a relative path inside the output directory`,
+    );
+  }
+
+  return normalized;
+}
+
+function resolvePathInside(
+  root: string,
+  relativePath: string,
+  errorMessage: string,
+): string {
+  const raw = relativePath.trim().replace(/\\/g, "/");
+  const normalized = path.posix.normalize(raw);
+  if (
+    raw.length === 0 ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../") ||
+    path.win32.isAbsolute(relativePath) ||
+    path.posix.isAbsolute(normalized) ||
+    /^[A-Za-z]:/.test(normalized)
+  ) {
+    throw new Error(errorMessage);
+  }
+
+  const resolved = path.resolve(root, normalized);
+  const relative = path.relative(root, resolved);
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error(errorMessage);
+  }
+
+  return resolved;
+}
+
+function isPathWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) &&
+      relative !== ".." &&
+      !path.isAbsolute(relative))
+  );
+}

package/src/custom-build.ts

@@ -0,0 +1,73 @@
+import { type BuildSettings, resolveBuildSettings } from "./build-settings.ts";
+import {
+  type BuildArtifact,
+  type BuildStrategy,
+  runBuildSettingsCommand,
+} from "./build-strategy.ts";
+import {
+  normalizeConfiguredArtifactEntrypoint,
+  stageConfiguredArtifact,
+} from "./configured-artifact.ts";
+import type { BuildCommandIo } from "./workspace.ts";
+
+/**
+ * Generic artifact strategy for frameworks the SDK does not know about yet.
+ * Runs an optional command, stages a configured output directory as-is, and
+ * starts the configured entrypoint from inside that artifact.
+ */
+export class CustomBuild implements BuildStrategy {
+  readonly #appPath: string;
+  readonly #entrypoint?: string;
+  readonly #buildSettings?: BuildSettings;
+  readonly #io?: BuildCommandIo;
+
+  constructor(options: {
+    appPath: string;
+    entrypoint?: string;
+    buildSettings?: BuildSettings;
+    io?: BuildCommandIo;
+  }) {
+    this.#appPath = options.appPath;
+    this.#entrypoint = options.entrypoint;
+    this.#buildSettings = options.buildSettings;
+    this.#io = options.io;
+  }
+
+  async canBuild(_signal?: AbortSignal): Promise<boolean> {
+    return Boolean(this.#entrypoint ?? this.#buildSettings?.entrypoint);
+  }
+
+  async execute(signal?: AbortSignal): Promise<BuildArtifact> {
+    signal?.throwIfAborted();
+    const settings =
+      this.#buildSettings ??
+      (await resolveBuildSettings({
+        appPath: this.#appPath,
+        buildType: "custom",
+        signal,
+      }));
+
+    const entrypoint = this.#entrypoint ?? settings.entrypoint;
+    if (!entrypoint) {
+      throw new Error("Custom build entrypoint is required");
+    }
+    normalizeConfiguredArtifactEntrypoint(entrypoint, "Custom");
+
+    await runBuildSettingsCommand({
+      appPath: this.#appPath,
+      settings,
+      failurePrefix: "Custom",
+      io: this.#io,
+      signal,
+    });
+
+    return stageConfiguredArtifact({
+      appPath: this.#appPath,
+      outputDirectory: settings.outputDirectory,
+      entrypoint,
+      buildType: "custom",
+      label: "Custom",
+      signal,
+    });
+  }
+}

package/src/errors.ts

@@ -37,57 +37,61 @@ export class ArtifactError extends TaggedError("ArtifactError")<{
 }>() {}
 
 export class TimeoutError extends TaggedError("TimeoutError")<{
-  versionId: string;
+  deploymentId: string;
   elapsedMs: number;
   lastStatus: string;
   message: string;
 }>() {
   constructor(args: {
-    versionId: string;
+    deploymentId: string;
     elapsedMs: number;
     lastStatus: string;
   }) {
     super({
       ...args,
-      message: `Timed out waiting for version ${args.versionId} to reach target state (last status: ${args.lastStatus}, elapsed: ${Math.round(args.elapsedMs / 1000)}s)`,
+      message: `Timed out waiting for deployment ${args.deploymentId} to reach target state (last status: ${args.lastStatus}, elapsed: ${Math.round(args.elapsedMs / 1000)}s)`,
     });
   }
 }
 
-export class VersionFailedError extends TaggedError("VersionFailedError")<{
-  versionId: string;
+export class DeploymentFailedError extends TaggedError(
+  "DeploymentFailedError",
+)<{
+  deploymentId: string;
   message: string;
 }>() {
-  constructor(args: { versionId: string }) {
+  constructor(args: { deploymentId: string }) {
     super({
-      versionId: args.versionId,
-      message: `Version ${args.versionId} transitioned to failed status`,
+      deploymentId: args.deploymentId,
+      message: `Deployment ${args.deploymentId} transitioned to failed status`,
     });
   }
 }
 
-export class NoExistingVersionError extends TaggedError(
-  "NoExistingVersionError",
+export class NoExistingDeploymentError extends TaggedError(
+  "NoExistingDeploymentError",
 )<{
-  serviceId: string;
+  appId: string;
   message: string;
 }>() {
-  constructor(args: { serviceId: string }) {
+  constructor(args: { appId: string }) {
     super({
-      serviceId: args.serviceId,
-      message: `Service ${args.serviceId} has no existing versions. Environment-only updates require at least one prior deployment.`,
+      appId: args.appId,
+      message: `App ${args.appId} has no existing deployments. Environment-only updates require at least one prior deployment.`,
     });
   }
 }
 
-export class NoVersionsFoundError extends TaggedError("NoVersionsFoundError")<{
-  serviceId: string;
+export class NoDeploymentsFoundError extends TaggedError(
+  "NoDeploymentsFoundError",
+)<{
+  appId: string;
   message: string;
 }>() {
-  constructor(args: { serviceId: string }) {
+  constructor(args: { appId: string }) {
     super({
-      serviceId: args.serviceId,
-      message: `Service ${args.serviceId} has no versions`,
+      appId: args.appId,
+      message: `App ${args.appId} has no deployments`,
     });
   }
 }
@@ -104,19 +108,19 @@ export class DestroyAggregateError extends TaggedError(
   "DestroyAggregateError",
 )<{
   message: string;
-  succeededVersionIds: string[];
-  failures: Array<{ versionId: string; error: VersionOperationError }>;
-  serviceDeleted: boolean;
+  succeededDeploymentIds: string[];
+  failures: Array<{ deploymentId: string; error: DeploymentOperationError }>;
+  appDeleted: boolean;
 }>() {
   constructor(args: {
-    succeededVersionIds: string[];
-    failures: Array<{ versionId: string; error: VersionOperationError }>;
-    serviceDeleted: boolean;
+    succeededDeploymentIds: string[];
+    failures: Array<{ deploymentId: string; error: DeploymentOperationError }>;
+    appDeleted: boolean;
   }) {
-    const failedIds = args.failures.map((f) => f.versionId).join(", ");
+    const failedIds = args.failures.map((f) => f.deploymentId).join(", ");
     super({
       ...args,
-      message: `Failed to destroy ${args.failures.length} version(s): ${failedIds}`,
+      message: `Failed to destroy ${args.failures.length} deployment(s): ${failedIds}`,
     });
   }
 }
@@ -138,7 +142,7 @@ export type DeployError =
   | BuildError
   | ArtifactError
   | TimeoutError
-  | VersionFailedError
+  | DeploymentFailedError
   | CancelledError;
 
 export type UpdateEnvError =
@@ -146,21 +150,21 @@ export type UpdateEnvError =
   | ApiError
   | MissingArgumentError
   | InvalidOptionsError
-  | NoExistingVersionError
+  | NoExistingDeploymentError
   | TimeoutError
-  | VersionFailedError
+  | DeploymentFailedError
   | CancelledError;
 
-export type DestroyVersionError =
+export type DestroyDeploymentError =
   | CancelledError
   | MissingArgumentError
-  | NoVersionsFoundError
+  | NoDeploymentsFoundError
   | AuthenticationError
   | ApiError
   | TimeoutError
-  | VersionFailedError;
+  | DeploymentFailedError;
 
-export type DestroyServiceError =
+export type DestroyAppError =
   | CancelledError
   | AuthenticationError
   | ApiError
@@ -170,16 +174,16 @@ export type PromoteError =
   | AuthenticationError
   | ApiError
   | MissingArgumentError
-  | NoVersionsFoundError
+  | NoDeploymentsFoundError
   | TimeoutError
-  | VersionFailedError
+  | DeploymentFailedError
   | CancelledError;
 
 export type ApiRequestError = CancelledError | AuthenticationError | ApiError;
 
-export type VersionOperationError =
+export type DeploymentOperationError =
   | CancelledError
   | AuthenticationError
   | ApiError
   | TimeoutError
-  | VersionFailedError;
+  | DeploymentFailedError;