@vercel/sandbox 0.0.16 → 0.0.17

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.16 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.17 build /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @vercel/sandbox@0.0.16 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
+> @vercel/sandbox@0.0.17 typecheck /home/runner/work/sandbox-sdk/sandbox-sdk/packages/sandbox
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @vercel/sandbox
 
+## 0.0.17
+
+### Patch Changes
+
+- Sandboxes can now expose up to 4 ports ([#99](https://github.com/vercel/sandbox-sdk/pull/99))
+
+  This applies to all SDK versions, but this SDK release documents the limit.
+
+- Fix bug in Sandbox.writeFile, add support for absolute paths ([#97](https://github.com/vercel/sandbox-sdk/pull/97))
+
 ## 0.0.16
 
 ### Patch Changes

package/dist/api-client/api-client.d.ts

@@ -23,6 +23,7 @@ export declare class APIClient extends BaseClient {
             timeout: number;
             requestedAt: number;
             createdAt: number;
+            cwd: string;
             updatedAt: number;
             duration?: number | undefined;
             startedAt?: number | undefined;
@@ -65,6 +66,7 @@ export declare class APIClient extends BaseClient {
             timeout: number;
             requestedAt: number;
             createdAt: number;
+            cwd: string;
             updatedAt: number;
             duration?: number | undefined;
             startedAt?: number | undefined;
@@ -112,16 +114,19 @@ export declare class APIClient extends BaseClient {
     }): Promise<Parsed<{}>>;
     getFileWriter(params: {
         sandboxId: string;
+        extractDir: string;
     }): {
         response: Promise<Response>;
         writer: FileWriter;
     };
     writeFiles(params: {
         sandboxId: string;
+        cwd: string;
         files: {
             path: string;
             content: Buffer;
         }[];
+        extractDir: string;
     }): Promise<void>;
     readFile(params: {
         sandboxId: string;

package/dist/api-client/api-client.js

@@ -13,6 +13,7 @@ const consume_readable_1 = require("../utils/consume-readable");
 const jsonlines_1 = __importDefault(require("jsonlines"));
 const os_1 = __importDefault(require("os"));
 const stream_1 = require("stream");
+const normalizePath_1 = require("../utils/normalizePath");
 class APIClient extends base_client_1.BaseClient {
     constructor(params) {
         super({
@@ -78,7 +79,10 @@ class APIClient extends base_client_1.BaseClient {
             response: (async () => {
                 return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
                     method: "POST",
-                    headers: { "content-type": "application/gzip" },
+                    headers: {
+                        "content-type": "application/gzip",
+                        "x-cwd": params.extractDir,
+                    },
                     body: await (0, consume_readable_1.consumeReadable)(writer.readable),
                 });
             })(),
@@ -88,9 +92,17 @@ class APIClient extends base_client_1.BaseClient {
     async writeFiles(params) {
         const { writer, response } = this.getFileWriter({
             sandboxId: params.sandboxId,
+            extractDir: params.extractDir,
         });
         for (const file of params.files) {
-            await writer.addFile({ name: file.path, content: file.content });
+            await writer.addFile({
+                name: (0, normalizePath_1.normalizePath)({
+                    filePath: file.path,
+                    extractDir: params.extractDir,
+                    cwd: params.cwd,
+                }),
+                content: file.content,
+            });
         }
         writer.end();
         await (0, base_client_1.parseOrThrow)(validators_1.EmptyResponse, await response);

package/dist/api-client/validators.d.ts

@@ -14,6 +14,7 @@ export declare const Sandbox: z.ZodObject<{
     stoppedAt: z.ZodOptional<z.ZodNumber>;
     duration: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodNumber;
+    cwd: z.ZodString;
     updatedAt: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
     region: string;
@@ -25,6 +26,7 @@ export declare const Sandbox: z.ZodObject<{
     timeout: number;
     requestedAt: number;
     createdAt: number;
+    cwd: string;
     updatedAt: number;
     duration?: number | undefined;
     startedAt?: number | undefined;
@@ -40,6 +42,7 @@ export declare const Sandbox: z.ZodObject<{
     timeout: number;
     requestedAt: number;
     createdAt: number;
+    cwd: string;
     updatedAt: number;
     duration?: number | undefined;
     startedAt?: number | undefined;
@@ -101,6 +104,7 @@ export declare const SandboxResponse: z.ZodObject<{
         stoppedAt: z.ZodOptional<z.ZodNumber>;
         duration: z.ZodOptional<z.ZodNumber>;
         createdAt: z.ZodNumber;
+        cwd: z.ZodString;
         updatedAt: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
         region: string;
@@ -112,6 +116,7 @@ export declare const SandboxResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -127,6 +132,7 @@ export declare const SandboxResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -144,6 +150,7 @@ export declare const SandboxResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -161,6 +168,7 @@ export declare const SandboxResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -183,6 +191,7 @@ export declare const SandboxAndRoutesResponse: z.ZodObject<{
         stoppedAt: z.ZodOptional<z.ZodNumber>;
         duration: z.ZodOptional<z.ZodNumber>;
         createdAt: z.ZodNumber;
+        cwd: z.ZodString;
         updatedAt: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
         region: string;
@@ -194,6 +203,7 @@ export declare const SandboxAndRoutesResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -209,6 +219,7 @@ export declare const SandboxAndRoutesResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -240,6 +251,7 @@ export declare const SandboxAndRoutesResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;
@@ -262,6 +274,7 @@ export declare const SandboxAndRoutesResponse: z.ZodObject<{
         timeout: number;
         requestedAt: number;
         createdAt: number;
+        cwd: string;
         updatedAt: number;
         duration?: number | undefined;
         startedAt?: number | undefined;

package/dist/api-client/validators.js

@@ -16,6 +16,7 @@ exports.Sandbox = zod_1.z.object({
     stoppedAt: zod_1.z.number().optional(),
     duration: zod_1.z.number().optional(),
     createdAt: zod_1.z.number(),
+    cwd: zod_1.z.string(),
     updatedAt: zod_1.z.number(),
 });
 exports.SandboxRoute = zod_1.z.object({

package/dist/command.d.ts

@@ -3,8 +3,11 @@ import { Signal } from "./utils/resolveSignal";
 /**
  * A command executed in a Sandbox.
  *
- * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
- * iterate over their output with {@link logs}.
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
  *
  * @see {@link Sandbox.runCommand} to start a command.
  *
@@ -67,9 +70,14 @@ export declare class Command {
     /**
      * Wait for a command to exit and populate its exit code.
      *
+     * This method is useful for detached commands where you need to wait
+     * for completion. For non-detached commands, {@link Sandbox.runCommand}
+     * automatically waits and returns a {@link CommandFinished} instance.
+     *
      * ```
-     * await cmd.wait()
-     * if (cmd.exitCode != 0) {
+     * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+     * const result = await detachedCmd.wait();
+     * if (result.exitCode !== 0) {
      *   console.error("Something went wrong...")
      * }
      * ```
@@ -117,14 +125,16 @@ export declare class Command {
 /**
  * A command that has finished executing.
  *
- * Contains the exit code of the command.
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
  *
  * @hideconstructor
  */
 export declare class CommandFinished extends Command {
     /**
-     * The exit code of the command, if available. This is set after
-     * {@link wait} has returned.
+     * The exit code of the command. This is always populated for
+     * CommandFinished instances.
      */
     exitCode: number;
     /**
@@ -140,4 +150,13 @@ export declare class CommandFinished extends Command {
         cmd: CommandData;
         exitCode: number;
     });
+    /**
+     * The wait method is not needed for CommandFinished instances since
+     * the command has already completed and exitCode is populated.
+     *
+     * @deprecated This method is redundant for CommandFinished instances.
+     * The exitCode is already available.
+     * @returns This CommandFinished instance.
+     */
+    wait(): Promise<CommandFinished>;
 }

package/dist/command.js

@@ -5,8 +5,11 @@ const resolveSignal_1 = require("./utils/resolveSignal");
 /**
  * A command executed in a Sandbox.
  *
- * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
- * iterate over their output with {@link logs}.
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
  *
  * @see {@link Sandbox.runCommand} to start a command.
  *
@@ -64,9 +67,14 @@ class Command {
     /**
      * Wait for a command to exit and populate its exit code.
      *
+     * This method is useful for detached commands where you need to wait
+     * for completion. For non-detached commands, {@link Sandbox.runCommand}
+     * automatically waits and returns a {@link CommandFinished} instance.
+     *
      * ```
-     * await cmd.wait()
-     * if (cmd.exitCode != 0) {
+     * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+     * const result = await detachedCmd.wait();
+     * if (result.exitCode !== 0) {
      *   console.error("Something went wrong...")
      * }
      * ```
@@ -145,7 +153,9 @@ exports.Command = Command;
 /**
  * A command that has finished executing.
  *
- * Contains the exit code of the command.
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
  *
  * @hideconstructor
  */
@@ -161,5 +171,16 @@ class CommandFinished extends Command {
         super({ ...params });
         this.exitCode = params.exitCode;
     }
+    /**
+     * The wait method is not needed for CommandFinished instances since
+     * the command has already completed and exitCode is populated.
+     *
+     * @deprecated This method is redundant for CommandFinished instances.
+     * The exitCode is already available.
+     * @returns This CommandFinished instance.
+     */
+    async wait() {
+        return this;
+    }
 }
 exports.CommandFinished = CommandFinished;

package/dist/sandbox.d.ts

@@ -31,7 +31,8 @@ export interface CreateSandboxParams {
         url: string;
     };
     /**
-     * Array of port numbers to expose from the sandbox.
+     * Array of port numbers to expose from the sandbox. Sandboxes can
+     * expose up to 4 ports.
      */
     ports?: number[];
     /**
@@ -184,7 +185,7 @@ export declare class Sandbox {
      * @returns A {@link Command} or {@link CommandFinished}, depending on `detached`.
      * @internal
      */
-    _runCommand(params: RunCommandParams): Promise<CommandFinished | Command>;
+    _runCommand(params: RunCommandParams): Promise<Command | CommandFinished>;
     /**
      * Create a directory in the filesystem of this sandbox.
      *
@@ -203,6 +204,8 @@ export declare class Sandbox {
     }): Promise<NodeJS.ReadableStream | null>;
     /**
      * Write files to the filesystem of this sandbox.
+     * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+     * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
      * @returns A promise that resolves when the files are written

package/dist/sandbox.js

@@ -165,6 +165,8 @@ class Sandbox {
     }
     /**
      * Write files to the filesystem of this sandbox.
+     * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+     * Writes files using the `vercel-sandbox` user.
      *
      * @param files - Array of files with path and stream/buffer contents
      * @returns A promise that resolves when the files are written
@@ -172,6 +174,8 @@ class Sandbox {
     async writeFiles(files) {
         return this.client.writeFiles({
             sandboxId: this.sandbox.id,
+            cwd: this.sandbox.cwd,
+            extractDir: "/",
             files: files,
         });
     }

package/dist/utils/normalizePath.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+export declare function normalizePath(params: {
+    filePath: string;
+    cwd: string;
+    extractDir: string;
+}): string;

package/dist/utils/normalizePath.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+const path_1 = __importDefault(require("path"));
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+function normalizePath(params) {
+    if (!path_1.default.posix.isAbsolute(params.cwd)) {
+        throw new Error("cwd dir must be absolute");
+    }
+    if (!path_1.default.posix.isAbsolute(params.extractDir)) {
+        throw new Error("extractDir must be absolute");
+    }
+    const basePath = path_1.default.posix.isAbsolute(params.filePath)
+        ? path_1.default.posix.normalize(params.filePath)
+        : path_1.default.posix.join(params.cwd, params.filePath);
+    return path_1.default.posix.relative(params.extractDir, basePath);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.16";
+export declare const VERSION = "0.0.17";

package/dist/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // Autogenerated by inject-version.ts
-exports.VERSION = "0.0.16";
+exports.VERSION = "0.0.17";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/sandbox",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/api-client/api-client.ts

@@ -20,6 +20,7 @@ import { z } from "zod";
 import jsonlines from "jsonlines";
 import os from "os";
 import { Readable } from "stream";
+import { normalizePath } from "../utils/normalizePath";
 
 export class APIClient extends BaseClient {
   private teamId: string;
@@ -150,13 +151,16 @@ export class APIClient extends BaseClient {
     );
   }
 
-  getFileWriter(params: { sandboxId: string }) {
+  getFileWriter(params: { sandboxId: string; extractDir: string }) {
     const writer = new FileWriter();
     return {
       response: (async () => {
         return this.request(`/v1/sandboxes/${params.sandboxId}/fs/write`, {
           method: "POST",
-          headers: { "content-type": "application/gzip" },
+          headers: {
+            "content-type": "application/gzip",
+            "x-cwd": params.extractDir,
+          },
           body: await consumeReadable(writer.readable),
         });
       })(),
@@ -166,14 +170,24 @@ export class APIClient extends BaseClient {
 
   async writeFiles(params: {
     sandboxId: string;
+    cwd: string;
     files: { path: string; content: Buffer }[];
+    extractDir: string;
   }) {
     const { writer, response } = this.getFileWriter({
       sandboxId: params.sandboxId,
+      extractDir: params.extractDir,
     });
 
     for (const file of params.files) {
-      await writer.addFile({ name: file.path, content: file.content });
+      await writer.addFile({
+        name: normalizePath({
+          filePath: file.path,
+          extractDir: params.extractDir,
+          cwd: params.cwd,
+        }),
+        content: file.content,
+      });
     }
 
     writer.end();

package/src/api-client/validators.ts

@@ -16,6 +16,7 @@ export const Sandbox = z.object({
   stoppedAt: z.number().optional(),
   duration: z.number().optional(),
   createdAt: z.number(),
+  cwd: z.string(),
   updatedAt: z.number(),
 });
 

package/src/command.ts

@@ -4,8 +4,11 @@ import { Signal, resolveSignal } from "./utils/resolveSignal";
 /**
  * A command executed in a Sandbox.
  *
- * You can {@link wait} on commands to access their {@link CommandFinished.exitCode}, and
- * iterate over their output with {@link logs}.
+ * For detached commands, you can {@link wait} to get a {@link CommandFinished} instance
+ * with the populated exit code. For non-detached commands, {@link Sandbox.runCommand}
+ * automatically waits and returns a {@link CommandFinished} instance.
+ *
+ * You can iterate over command output with {@link logs}.
  *
  * @see {@link Sandbox.runCommand} to start a command.
  *
@@ -94,9 +97,14 @@ export class Command {
   /**
    * Wait for a command to exit and populate its exit code.
    *
+   * This method is useful for detached commands where you need to wait
+   * for completion. For non-detached commands, {@link Sandbox.runCommand}
+   * automatically waits and returns a {@link CommandFinished} instance.
+   *
    * ```
-   * await cmd.wait()
-   * if (cmd.exitCode != 0) {
+   * const detachedCmd = await sandbox.runCommand({ cmd: 'sleep', args: ['5'], detached: true });
+   * const result = await detachedCmd.wait();
+   * if (result.exitCode !== 0) {
    *   console.error("Something went wrong...")
    * }
    * ```
@@ -180,14 +188,16 @@ export class Command {
 /**
  * A command that has finished executing.
  *
- * Contains the exit code of the command.
+ * The exit code is immediately available and populated upon creation.
+ * Unlike {@link Command}, you don't need to call wait() - the command
+ * has already completed execution.
  *
  * @hideconstructor
  */
 export class CommandFinished extends Command {
   /**
-   * The exit code of the command, if available. This is set after
-   * {@link wait} has returned.
+   * The exit code of the command. This is always populated for
+   * CommandFinished instances.
    */
   public exitCode: number;
 
@@ -207,4 +217,16 @@ export class CommandFinished extends Command {
     super({ ...params });
     this.exitCode = params.exitCode;
   }
+
+  /**
+   * The wait method is not needed for CommandFinished instances since
+   * the command has already completed and exitCode is populated.
+   *
+   * @deprecated This method is redundant for CommandFinished instances.
+   * The exitCode is already available.
+   * @returns This CommandFinished instance.
+   */
+  async wait(): Promise<CommandFinished> {
+    return this;
+  }
 }

package/src/sandbox.test.ts

@@ -2,10 +2,11 @@ import { it, beforeEach, afterEach, expect } from "vitest";
 import { consumeReadable } from "./utils/consume-readable";
 import { Sandbox } from "./sandbox";
 
+const PORTS = [3000, 4000];
 let sandbox: Sandbox;
 
 beforeEach(async () => {
-  sandbox = await Sandbox.create();
+  sandbox = await Sandbox.create({ ports: PORTS });
 });
 
 afterEach(async () => {
@@ -23,3 +24,43 @@ it("allows to write files and then read them", async () => {
   expect((await consumeReadable(content1!)).toString()).toBe("Hello 1");
   expect((await consumeReadable(content2!)).toString()).toBe("Hello 2");
 });
+
+it("verifies port forwarding works correctly", async () => {
+  const serverScript = `
+const http = require('http');
+const ports = process.argv.slice(2);
+
+for (const port of ports) {
+  const server = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end(\`hello port \${port}\`);
+  });
+
+  server.listen(port, () => {
+    console.log(\`Server running on port \${port}\`);
+  });
+}
+`;
+
+  await sandbox.writeFiles([
+    { path: "server.js", content: Buffer.from(serverScript) },
+  ]);
+
+  const server = await sandbox.runCommand({
+    cmd: "node",
+    args: ["server.js", ...PORTS.map(String)],
+    detached: true,
+    stdout: process.stdout,
+    stderr: process.stderr,
+  });
+
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+
+  for (const port of PORTS) {
+    const response = await fetch(sandbox.domain(port));
+    const text = await response.text();
+    expect(text).toBe(`hello port ${port}`);
+  }
+
+  await server.kill();
+});

package/src/sandbox.ts

@@ -32,7 +32,8 @@ export interface CreateSandboxParams {
       }
     | { type: "tarball"; url: string };
   /**
-   * Array of port numbers to expose from the sandbox.
+   * Array of port numbers to expose from the sandbox. Sandboxes can
+   * expose up to 4 ports.
    */
   ports?: number[];
   /**
@@ -331,6 +332,8 @@ export class Sandbox {
 
   /**
    * Write files to the filesystem of this sandbox.
+   * Defaults to writing to /vercel/sandbox unless an absolute path is specified.
+   * Writes files using the `vercel-sandbox` user.
    *
    * @param files - Array of files with path and stream/buffer contents
    * @returns A promise that resolves when the files are written
@@ -338,6 +341,8 @@ export class Sandbox {
   async writeFiles(files: { path: string; content: Buffer }[]) {
     return this.client.writeFiles({
       sandboxId: this.sandbox.id,
+      cwd: this.sandbox.cwd,
+      extractDir: "/",
       files: files,
     });
   }

package/src/utils/normalizePath.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { normalizePath } from "./normalizePath";
+
+describe("normalizePath", () => {
+  it("handles base cases", () => {
+    expect(
+      normalizePath({
+        filePath: "foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("vercel/sandbox/foo.txt");
+    expect(
+      normalizePath({
+        filePath: "foo/bar/baz.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("vercel/sandbox/foo/bar/baz.txt");
+    expect(
+      normalizePath({ filePath: "bar.txt", cwd: "/", extractDir: "/" }),
+    ).toBe("bar.txt");
+    expect(
+      normalizePath({
+        filePath: "/some/other/dir/foo.txt",
+        cwd: "/bar",
+        extractDir: "/",
+      }),
+    ).toBe("some/other/dir/foo.txt");
+  });
+
+  it("handles base cases (extract dir)", () => {
+    expect(
+      normalizePath({
+        filePath: "foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/vercel",
+      }),
+    ).toBe("sandbox/foo.txt");
+    expect(
+      normalizePath({
+        filePath: "foo/bar/baz.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/vercel",
+      }),
+    ).toBe("sandbox/foo/bar/baz.txt");
+
+    // TODO: Should this be allowed?
+    expect(
+      normalizePath({ filePath: "bar.txt", cwd: "/", extractDir: "/vercel" }),
+    ).toBe("../bar.txt");
+  });
+
+  it("handles normalization", () => {
+    expect(
+      normalizePath({
+        filePath: "/resolves/../this/stuff/foo.txt",
+        cwd: "/bar",
+        extractDir: "/",
+      }),
+    ).toBe("this/stuff/foo.txt");
+    expect(
+      normalizePath({
+        filePath: "/handles//extra-slashes",
+        cwd: "/",
+        extractDir: "/",
+      }),
+    ).toBe("handles/extra-slashes");
+  });
+
+  it("resolves relative paths", () => {
+    expect(
+      normalizePath({
+        filePath: "/../../../foo.txt",
+        cwd: "/",
+        extractDir: "/",
+      }),
+    ).toBe("foo.txt");
+    expect(
+      normalizePath({
+        filePath: "../../../../foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("foo.txt");
+    expect(
+      normalizePath({
+        filePath: "../foo.txt",
+        cwd: "/vercel/sandbox",
+        extractDir: "/",
+      }),
+    ).toBe("vercel/foo.txt");
+  });
+
+  it("validates the cwd", () => {
+    expect(() => {
+      normalizePath({
+        filePath: "doesn't matter",
+        cwd: "relative/root",
+        extractDir: "/",
+      });
+    }).toThrow("cwd dir must be absolute");
+  });
+
+  it("validates the cwd", () => {
+    expect(() => {
+      normalizePath({
+        filePath: "doesn't matter",
+        cwd: "/",
+        extractDir: "some/relative/path",
+      });
+    }).toThrow("extractDir must be absolute");
+  });
+});

package/src/utils/normalizePath.ts

@@ -0,0 +1,33 @@
+import path from "path";
+
+/**
+ * Normalize a path and make it relative to `params.extractDir` for inclusion
+ * in our tar archives.
+ *
+ * Relative paths are first resolved to `params.cwd`.
+ * Absolute paths are normalized and resolved relative to `params.extractDir`.
+ *
+ * In addition, paths are normalized so consecutive slashes are removed and
+ * stuff like `../..` is resolved appropriately.
+ *
+ * This function always returns a path relative to `params.extractDir`.
+ */
+export function normalizePath(params: {
+  filePath: string;
+  cwd: string;
+  extractDir: string;
+}) {
+  if (!path.posix.isAbsolute(params.cwd)) {
+    throw new Error("cwd dir must be absolute");
+  }
+
+  if (!path.posix.isAbsolute(params.extractDir)) {
+    throw new Error("extractDir must be absolute");
+  }
+
+  const basePath = path.posix.isAbsolute(params.filePath)
+    ? path.posix.normalize(params.filePath)
+    : path.posix.join(params.cwd, params.filePath);
+
+  return path.posix.relative(params.extractDir, basePath);
+}

package/src/version.ts

@@ -1,2 +1,2 @@
 // Autogenerated by inject-version.ts
-export const VERSION = "0.0.16";
+export const VERSION = "0.0.17";