@mastra/platform-workspace 1.8.2-alpha.0 → 1.9.0-alpha.1

package/dist/_types/@internal_workspace/dist/file-commands.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shell scripts for the file operations a sandbox can only do atomically (or
+ * without moving file bytes over the network) by running a command inside the
+ * VM. Each builder takes absolute paths and returns one POSIX `sh` script; the
+ * caller runs it with `sh -c` and maps the exit codes below to typed errors.
+ */
+/** Exit codes the scripts use for outcomes the caller turns into typed errors. Any other non-zero code is a plain failure. */
+export declare const FILE_COMMAND_EXIT: {
+    readonly notFound: 20;
+    readonly isDirectory: 21;
+    readonly exists: 22;
+    readonly notDirectory: 23;
+    readonly destIsDirectory: 24;
+};
+/** Single-quote a string for safe POSIX shell interpolation. */
+export declare function shellQuote(value: string): string;
+/**
+ * A sibling temp path for `path`, so a later `ln` / `mv` onto `path` stays on
+ * one filesystem. Hidden, and unique per call.
+ */
+export declare function siblingTempPath(path: string): string;
+export interface CopyCommandOptions {
+    /** Copy a directory and everything under it. Without it a directory source fails with `isDirectory`. */
+    recursive?: boolean;
+    /** `false` fails with `exists` when the destination is taken, atomically. Default `true`. */
+    overwrite?: boolean;
+}
+/**
+ * Copy `src` to `dest` inside the sandbox, creating `dest`'s parent.
+ *
+ * A file source copies its content (a symlinked source is followed). A
+ * directory source with `recursive` copies its contents into `dest`, keeping
+ * symlinks inside the tree as links. With `overwrite: false` the destination
+ * is claimed atomically: a directory with an exclusive `mkdir`, a file by
+ * copying to a temp name and hard-linking it into place (`link(2)` fails when
+ * the destination exists).
+ *
+ * Exits: `notFound` (no source), `isDirectory` (directory source without
+ * `recursive`), `destIsDirectory` (a file onto an existing directory or a link
+ * to one), `exists`.
+ */
+export declare function copyCommand(src: string, dest: string, options?: CopyCommandOptions): string;
+/**
+ * Move `src` to `dest` without replacing anything at `dest`, creating `dest`'s
+ * parent. A skipped `mv -n` is detected by the source surviving, whatever
+ * its exit code. If a directory appears at `dest` between the check and the
+ * move, `mv` moves `src` into it (BSD `mv` has no `-T`), and that is reported
+ * as success; the no-clobber rename itself is atomic.
+ *
+ * Exits: `notFound` (no source), `exists`.
+ */
+export declare function moveNoClobberCommand(src: string, dest: string): string;
+/**
+ * Append the bytes already written to `tmp` onto `dest`, then delete `tmp`.
+ * The content travels as a file rather than a command argument, so it has no
+ * size limit. Creates `dest` (and its parent) when missing.
+ *
+ * Exits: `isDirectory` (dest is a directory).
+ */
+export declare function appendFromCommand(tmp: string, dest: string): string;
+/**
+ * Publish the file already written to `tmp` at `dest` only if nothing is
+ * there, then delete `tmp`. `ln` (`link(2)`) is the atomic exclusivity check;
+ * `tmp` must be on the same filesystem, e.g. from {@link siblingTempPath}.
+ *
+ * Exits: `exists`, `notDirectory` (dest's parent is not a directory).
+ */
+export declare function linkNoClobberCommand(tmp: string, dest: string): string;
+//# sourceMappingURL=file-commands.d.ts.map

package/dist/_types/@internal_workspace/dist/files-api-filesystem.d.ts

@@ -0,0 +1,85 @@
+import { Buffer } from 'node:buffer';
+import type { CopyOptions, FileContent, FileEntry, FileStat, ListOptions, ReadOptions, RemoveOptions, WriteOptions } from '@mastra/core/workspace';
+import { MastraFilesystem } from '@mastra/core/workspace';
+/** One entry as E2B's envd files API reports it (`EntryInfo`), reduced to the fields used here. */
+export interface FilesApiEntry {
+    name: string;
+    /** `'file'` or `'dir'`, resolved through a symlink. Absent for a symlink whose target is missing. */
+    type?: string;
+    path: string;
+    /** The entry's own size: a symlink's is the link's, not its target's. */
+    size: number;
+    modifiedTime?: Date;
+    /** Set only on symlinks. */
+    symlinkTarget?: string;
+}
+/** The envd files calls the filesystem makes (E2B's `sandbox.files`). */
+export interface FilesApi {
+    read(path: string, opts: {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    /** Creates missing parent directories. */
+    write(path: string, data: string | ArrayBuffer): Promise<unknown>;
+    list(path: string, opts?: {
+        depth?: number;
+    }): Promise<FilesApiEntry[]>;
+    /** Recursive; resolves `false` when the directory already exists. */
+    makeDir(path: string): Promise<boolean>;
+    /** Creates missing destination parents and replaces an existing file. */
+    rename(oldPath: string, newPath: string): Promise<unknown>;
+    /** Recursive; a symlink is unlinked, never followed. */
+    remove(path: string): Promise<void>;
+    /** Does not follow the entry itself. */
+    getInfo(path: string): Promise<FilesApiEntry>;
+}
+/**
+ * The file-level answers a provider recognizes in its SDK's errors.
+ * `'not-found'` must not include "the sandbox itself is gone".
+ */
+export type FilesApiErrorKind = 'not-found' | 'invalid-argument';
+export interface FilesCommandResult {
+    exitCode: number;
+    stderr: string;
+}
+/**
+ * A sandbox's disk, read and written through E2B's envd files API, with the
+ * operations the files API can't do in one call (copy, append, no-clobber
+ * writes and moves) run as one shell command inside the VM so they are atomic
+ * and file bytes never round-trip through the host. Paths are absolute inside
+ * the sandbox; this class does not confine paths or symlinks to any root.
+ *
+ * Providers supply how to reach the files API and the shell, and how to read
+ * their SDK's errors.
+ *
+ * If a provider's `runCommand` re-runs a command whose first run already
+ * finished (e.g. a retry after a dropped connection), the second run sees the
+ * first's result: a no-clobber copy, write or move reports `FileExistsError`
+ * or `FileNotFoundError`, and an append fails, even though the work was done.
+ */
+export declare abstract class FilesApiFilesystem extends MastraFilesystem {
+    #private;
+    /** Run `fn` with the provider's files API (starting the sandbox, retrying, … as the provider needs). */
+    protected abstract runFiles<T>(operation: string, fn: (files: FilesApi) => Promise<T>): Promise<T>;
+    /** Run a POSIX `sh` script inside the sandbox. */
+    protected abstract runCommand(operation: string, script: string): Promise<FilesCommandResult>;
+    /** Which file-level answer, if any, a files API error is. Anything else propagates unchanged. */
+    protected abstract errorKind(error: unknown): FilesApiErrorKind | undefined;
+    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
+    appendFile(path: string, content: FileContent): Promise<void>;
+    deleteFile(path: string, options?: RemoveOptions): Promise<void>;
+    /**
+     * One `cp` inside the VM. A recursive copy keeps symlinks inside the tree as
+     * links; `overwrite: false` claims the destination atomically.
+     */
+    copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: RemoveOptions): Promise<void>;
+    readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+}
+//# sourceMappingURL=files-api-filesystem.d.ts.map

package/dist/_types/@internal_workspace/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SETUP_MARKER_DIR, SETUP_MARKER_PATH, WORKSPACE_SETUP_MARKER_PATH, SETUP_FAILED_MARKER_PATH, repoSetupMarkerPath, normalizeSetupCommands, setupMarkerContent, setupMarkerCommand, guardedSetupCommand, type GuardedSetupCommandOptions, } from './setup-marker.js';
+export { repoCloneCommand, type RepoCloneCommandOptions } from './repo-clone.js';
+export { FILE_COMMAND_EXIT, shellQuote, siblingTempPath, copyCommand, moveNoClobberCommand, appendFromCommand, linkNoClobberCommand, type CopyCommandOptions, } from './file-commands.js';
+export { FilesApiFilesystem, type FilesApi, type FilesApiEntry, type FilesApiErrorKind, type FilesCommandResult, } from './files-api-filesystem.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/_types/@internal_workspace/dist/repo-clone.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The one way a repository is cloned into a sandbox, shared by the repo
+ * templates (which bake the clone into an image) and by Factory (which clones
+ * at session start when no image provided one), so both produce the same
+ * checkout: shallow, single branch, `origin` pointing at the plain URL.
+ *
+ * Credentials never enter the URL or `.git/config`. When `tokenEnv` is set,
+ * the token is read from that environment variable at run time and sent as a
+ * per-invocation `Authorization` header, so nothing persists in the checkout.
+ */
+export interface RepoCloneCommandOptions {
+    /** Plain https clone URL, without credentials. */
+    cloneUrl: string;
+    /** Directory to clone into; relative paths resolve against the cwd. */
+    destination: string;
+    /** Branch to check out. Omit for the remote's default branch. */
+    branch?: string;
+    /** Name of the environment variable holding a GitHub installation token. */
+    tokenEnv?: string;
+}
+export declare function repoCloneCommand({ cloneUrl, destination, branch, tokenEnv }: RepoCloneCommandOptions): string;
+//# sourceMappingURL=repo-clone.d.ts.map

package/dist/_types/@internal_workspace/dist/setup-marker.d.ts

@@ -0,0 +1,56 @@
+/** Directory, relative to the template's build cwd, that holds every marker below. */
+export declare const SETUP_MARKER_DIR = ".mastra-sandbox";
+/**
+ * Setup completion marker shared by repo templates and their consumers.
+ *
+ * A repo template writes this file beside the checkout as its last build
+ * step, so it exists only in images where every setup command succeeded. Its
+ * content is a digest of the setup commands the image ran, letting a sandbox
+ * booted from the image tell whether the setup it is about to run already
+ * happened. Relative to the template's build cwd, which is also the runtime
+ * working directory the repo was cloned into.
+ *
+ * This is the single-repository marker. Templates built from a repository
+ * list write one marker per repository instead ({@link repoSetupMarkerPath}).
+ */
+export declare const SETUP_MARKER_PATH = ".mastra-sandbox/setup";
+/**
+ * Marker for the workspace-level setup of a multi-repository template: the
+ * commands that ran at the working directory after every repository was set
+ * up. Written even when there were no such commands, so a consumer can tell
+ * "ran nothing" from "never built".
+ */
+export declare const WORKSPACE_SETUP_MARKER_PATH = ".mastra-sandbox/workspace-setup";
+/**
+ * One line per repository directory whose setup failed while the build was
+ * told to continue. Absent when nothing failed. Consumers check this before
+ * trusting a per-repository marker: that marker means every step ran, not
+ * that every step succeeded.
+ */
+export declare const SETUP_FAILED_MARKER_PATH = ".mastra-sandbox/setup-failed";
+/** Per-repository marker of a multi-repository template, keyed by the clone directory name. */
+export declare function repoSetupMarkerPath(repoDir: string): string;
+/** Blank entries never become build steps, so they never count toward the digest either. */
+export declare function normalizeSetupCommands(setupCommand: string | readonly string[] | undefined): string[];
+/** The marker content for a setup command list: `sha256:<hex>` over the commands joined by newlines. */
+export declare function setupMarkerContent(setupCommand: string | readonly string[] | undefined): string;
+/** Shell step that writes the marker relative to the cwd. `content` is a digest, so it is shell-safe. */
+export declare function setupMarkerCommand(content: string, markerPath?: string): string;
+export interface GuardedSetupCommandOptions {
+    /** Clone directory the command runs in, relative to the build cwd. Shell-safe (`[\w.-]` only). */
+    repoDir: string;
+    /** The setup command, run verbatim inside `repoDir`. */
+    command: string;
+    /** When true a failure appends `repoDir` to {@link SETUP_FAILED_MARKER_PATH} instead of failing the step. */
+    continueOnFailure: boolean;
+}
+/**
+ * Shell step that runs one setup command inside a repository clone.
+ *
+ * Without the guard this is the plain `cd "<dir>" && <cmd>` step. With it,
+ * the `cd` sits inside the parenthesized group so that the failure branch
+ * runs back at the build cwd and the failure list lands at the workspace
+ * level, never inside the repository.
+ */
+export declare function guardedSetupCommand({ repoDir, command, continueOnFailure }: GuardedSetupCommandOptions): string;
+//# sourceMappingURL=setup-marker.d.ts.map

package/dist/_types/@internal_workspace/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/e2b-exec.d.ts

@@ -1,7 +1,28 @@
+import type { EntryInfo } from 'e2b';
 import type { DirectExecOptions, DirectExecResult, ExecLease } from './direct-exec.js';
 export interface E2BExecLease extends ExecLease {
     sandboxId: string;
 }
 export type E2BExecRunner = (lease: E2BExecLease, options: DirectExecOptions) => Promise<DirectExecResult>;
 export declare const execViaE2BLease: E2BExecRunner;
+/**
+ * The subset of E2B's `sandbox.files` API that {@link PlatformSandboxFilesystem}
+ * uses. Tests substitute a fake through `PlatformSandboxOptions.e2bFilesFactory`.
+ */
+export interface E2BFiles {
+    read(path: string, opts: {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    write(path: string, data: string | ArrayBuffer): Promise<unknown>;
+    list(path: string, opts?: {
+        depth?: number;
+    }): Promise<EntryInfo[]>;
+    makeDir(path: string): Promise<boolean>;
+    rename(oldPath: string, newPath: string): Promise<unknown>;
+    remove(path: string): Promise<void>;
+    getInfo(path: string): Promise<EntryInfo>;
+}
+export type E2BFilesFactory = (lease: E2BExecLease) => E2BFiles;
+/** Opens E2B's files API directly against the VM, authenticated by the exec lease. */
+export declare const e2bFilesForLease: E2BFilesFactory;
 //# sourceMappingURL=e2b-exec.d.ts.map

package/dist/e2b-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"e2b-exec.d.ts","sourceRoot":"","sources":["../src/e2b-exec.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIvF,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE3G,eAAO,MAAM,eAAe,EAAE,aAwD7B,CAAC"}
+{"version":3,"file":"e2b-exec.d.ts","sourceRoot":"","sources":["../src/e2b-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAErC,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAIvF,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE3G,eAAO,MAAM,eAAe,EAAE,aAwD7B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,QAAQ,CAAC;AAEhE,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,EAAE,eAOrB,CAAC"}