@mastra/railway 0.0.0 → 0.1.0

package/dist/sandbox/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Railway Sandbox Provider
+ *
+ * A Railway sandbox implementation for Mastra workspaces. Provisions an
+ * ephemeral, isolated Linux VM on Railway, runs commands in it via the
+ * Railway TypeScript SDK, and destroys it on teardown.
+ *
+ * @see https://docs.railway.com/sandboxes
+ */
+import type { CommandResult, ExecuteCommandOptions, InstructionsOption, MastraSandboxOptions, ProviderStatus, SandboxInfo } from '@mastra/core/workspace';
+import { MastraSandbox } from '@mastra/core/workspace';
+import { Sandbox } from 'railway';
+import type { SandboxNetworkIsolation, SandboxTemplate } from 'railway';
+import { RailwayProcessManager } from './process-manager.js';
+/**
+ * Railway sandbox provider configuration.
+ */
+export interface RailwaySandboxOptions extends Omit<MastraSandboxOptions, 'processes'> {
+    /** Unique identifier for this sandbox instance. */
+    id?: string;
+    /** Railway API token. Falls back to the RAILWAY_API_TOKEN env var. */
+    token?: string;
+    /** Railway environment ID. Falls back to the RAILWAY_ENVIRONMENT_ID env var. */
+    environmentId?: string;
+    /**
+     * Reattach to an existing Railway sandbox by its Railway ID instead of
+     * creating a new one. When set, `start()` calls `Sandbox.connect()`.
+     */
+    sandboxId?: string;
+    /**
+     * How long the sandbox can sit idle (no `exec` interaction) before Railway
+     * destroys it automatically. Range depends on plan (1–120 minutes on
+     * Hobby/Pro, 1–5 on Trial/Free). Defaults to the plan default when omitted.
+     */
+    idleTimeoutMinutes?: number;
+    /**
+     * Network isolation mode.
+     * - `ISOLATED` (default): outbound internet only, no private network access.
+     * - `PRIVATE`: joins the environment's private network.
+     */
+    networkIsolation?: SandboxNetworkIsolation;
+    /** Environment variables baked into the sandbox, available to every command. */
+    env?: Record<string, string>;
+    /**
+     * Provision the sandbox from a custom base image built with the Railway
+     * template builder. Use this to pre-install packages or run setup steps so
+     * every sandbox created from it starts ready.
+     *
+     * - Builder callback — receives the base `Sandbox.template()` and returns the
+     *   configured template. The template is built (`.build()`) on first
+     *   `start()` if not already built.
+     *   ```ts
+     *   template: t => t.withPackages('git', 'curl').run('npm i -g pnpm')
+     *   ```
+     * - Pre-built `SandboxTemplate` — pass a template you built yourself to reuse
+     *   it across sandboxes without rebuilding.
+     *
+     * Ignored when `sandboxId` is set (reattach) or when forking.
+     */
+    template?: SandboxTemplate | ((base: SandboxTemplate) => SandboxTemplate);
+    /**
+     * Default execution timeout in milliseconds applied to commands that don't
+     * specify their own timeout. When omitted, commands run until they exit.
+     */
+    timeout?: number;
+    /**
+     * Custom instructions that override the default instructions returned by
+     * `getInstructions()`.
+     *
+     * - `string` — Fully replaces the default instructions. Pass an empty string
+     *   to suppress instructions entirely.
+     * - `(opts) => string` — Receives the default instructions and optional
+     *   request context so you can extend or customise per-request.
+     */
+    instructions?: InstructionsOption;
+}
+/**
+ * Railway sandbox provider for Mastra workspaces.
+ *
+ * Features:
+ * - Ephemeral, isolated Linux VM via the Railway TypeScript SDK
+ * - Command execution with streaming output and timeouts
+ * - Configurable idle timeout and network isolation
+ * - Reattach to an existing sandbox by Railway ID
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Workspace } from '@mastra/core/workspace';
+ * import { RailwaySandbox } from '@mastra/railway';
+ *
+ * const sandbox = new RailwaySandbox({
+ *   // token + environmentId read from RAILWAY_API_TOKEN / RAILWAY_ENVIRONMENT_ID
+ *   idleTimeoutMinutes: 30,
+ * });
+ *
+ * const workspace = new Workspace({ sandbox });
+ * const result = await workspace.executeCode('console.log("Hello!")');
+ * ```
+ *
+ * @example Private networking
+ * ```typescript
+ * const sandbox = new RailwaySandbox({
+ *   networkIsolation: 'PRIVATE',
+ *   env: { NODE_ENV: 'production' },
+ * });
+ * ```
+ */
+export declare class RailwaySandbox extends MastraSandbox {
+    readonly id: string;
+    readonly name = "RailwaySandbox";
+    readonly provider = "railway";
+    status: ProviderStatus;
+    readonly processes: RailwayProcessManager;
+    private _sandbox;
+    private _createdAt;
+    private readonly _token?;
+    private readonly _environmentId?;
+    private readonly _sandboxId?;
+    private readonly _idleTimeoutMinutes?;
+    private readonly _networkIsolation?;
+    private readonly _env;
+    private readonly _timeout?;
+    private readonly _instructionsOverride?;
+    private readonly _templateOption?;
+    constructor(options?: RailwaySandboxOptions);
+    private generateId;
+    /**
+     * Get the underlying Railway Sandbox instance for direct SDK access.
+     *
+     * @throws {SandboxNotReadyError} If the sandbox has not been started.
+     */
+    get railway(): Sandbox;
+    /**
+     * Start the Railway sandbox.
+     *
+     * Reattaches to an existing sandbox when `sandboxId` is configured,
+     * otherwise provisions a new one. Resolves once the sandbox is RUNNING.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the Railway sandbox.
+     *
+     * Railway sandboxes have no separate "stopped" state — they're either
+     * running or destroyed — so stopping destroys the sandbox.
+     */
+    stop(): Promise<void>;
+    /**
+     * Destroy the Railway sandbox and release its resources.
+     */
+    destroy(): Promise<void>;
+    private _teardown;
+    /**
+     * Build the configured template into a ready-to-use base. Accepts either a
+     * pre-built `SandboxTemplate` or a builder callback over `Sandbox.template()`.
+     * Calls `.build()` so the recipe is materialised before `Sandbox.create()`.
+     */
+    private _resolveTemplate;
+    /**
+     * Fork this running sandbox into a new, independent `RailwaySandbox`.
+     *
+     * Clones the filesystem (a fresh boot, not live processes) into the same
+     * environment. The returned sandbox is already started and reattached to the
+     * forked Railway sandbox; it inherits this sandbox's credentials and defaults
+     * unless overridden via `options`.
+     *
+     * @throws {SandboxNotReadyError} If this sandbox has not been started.
+     */
+    fork(options?: Pick<RailwaySandboxOptions, 'id' | 'idleTimeoutMinutes' | 'networkIsolation' | 'env'>): Promise<RailwaySandbox>;
+    getInfo(): Promise<SandboxInfo>;
+    getInstructions(): string;
+    private _buildDefaultInstructions;
+    /**
+     * Execute a command in the sandbox and return the result.
+     */
+    executeCommand(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<CommandResult>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/process-manager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Railway Process Manager
+ *
+ * Implements SandboxProcessManager for Railway sandboxes.
+ * Wraps the Railway SDK's `Sandbox.exec()` API.
+ *
+ * Railway's `exec(command)` returns an `ExecHandle` that runs the command
+ * server-side, independently of the client. Each spawn() starts one exec.
+ * The handle streams output via `onStdout`/`onStderr` callbacks wired to
+ * `emitStdout`/`emitStderr`, exposes a durable `sessionName`, and can be
+ * terminated with `kill(signal)`.
+ */
+import { ProcessHandle, SandboxProcessManager } from '@mastra/core/workspace';
+import type { ProcessInfo, SpawnProcessOptions } from '@mastra/core/workspace';
+import type { RailwaySandbox } from './index.js';
+export declare const LOG_PREFIX = "[RailwaySandbox]";
+/**
+ * Build a shell command that applies a working directory and environment
+ * variables, since Railway's `exec` takes neither per-call. Env vars are
+ * exported via `env` so they apply to the command's process group.
+ */
+export declare function buildSpawnCommand(command: string, cwd?: string, env?: Record<string, string>): string;
+export interface RailwayProcessManagerOptions {
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Railway implementation of SandboxProcessManager.
+ * Uses the Railway SDK's `Sandbox.exec()` with one exec per spawned process.
+ */
+export declare class RailwayProcessManager extends SandboxProcessManager<RailwaySandbox> {
+    private _spawnCounter;
+    constructor(opts?: RailwayProcessManagerOptions);
+    spawn(command: string, options?: SpawnProcessOptions): Promise<ProcessHandle>;
+    /**
+     * List tracked processes.
+     *
+     * Railway has no API to enumerate running exec sessions by sandbox, so this
+     * reports the processes this manager spawned.
+     */
+    list(): Promise<ProcessInfo[]>;
+}
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/sandbox/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../../src/sandbox/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,KAAK,EAAiB,WAAW,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,UAAU,qBAAqB,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CASzG;AA2GD,MAAM,WAAW,4BAA4B;IAC3C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,qBAAqB,CAAC,cAAc,CAAC;IAC9E,OAAO,CAAC,aAAa,CAAK;gBAEd,IAAI,GAAE,4BAAiC;IAI7C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC;IA2BvF;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAQrC"}

package/dist/utils/shell-quote.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shell-quote a single argument for safe use in a command string.
+ *
+ * Arguments containing only safe characters are returned as-is.
+ * All others are wrapped in single quotes with embedded single quotes escaped.
+ */
+export declare function shellQuote(arg: string): string;
+//# sourceMappingURL=shell-quote.d.ts.map

package/dist/utils/shell-quote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-quote.d.ts","sourceRoot":"","sources":["../../src/utils/shell-quote.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/railway",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Railway cloud sandbox provider for Mastra workspaces",
   "type": "module",
   "main": "dist/index.js",
@@ -18,33 +18,23 @@
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "build": "tsup --silent --config tsup.config.ts",
-    "build:lib": "pnpm build",
-    "build:watch": "pnpm build --watch",
-    "test:unit": "vitest run --exclude '**/*.integration.test.ts'",
-    "test:watch": "vitest watch",
-    "test": "vitest run ./src/**/*.integration.test.ts",
-    "test:cloud": "pnpm test",
-    "lint": "eslint ."
-  },
   "license": "Apache-2.0",
   "dependencies": {
     "railway": "^3.1.1"
   },
   "devDependencies": {
-    "@internal/lint": "workspace:*",
-    "@internal/types-builder": "workspace:*",
-    "@internal/workspace-test-utils": "workspace:*",
-    "@mastra/core": "workspace:*",
     "@types/node": "22.19.15",
-    "@vitest/coverage-v8": "catalog:",
-    "@vitest/ui": "catalog:",
+    "@vitest/coverage-v8": "4.1.5",
+    "@vitest/ui": "4.1.5",
     "dotenv": "^17.3.1",
     "eslint": "^10.4.1",
     "tsup": "^8.5.1",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
+    "typescript": "^6.0.3",
+    "vitest": "4.1.5",
+    "@internal/lint": "0.0.104",
+    "@internal/types-builder": "0.0.79",
+    "@internal/workspace-test-utils": "0.0.48",
+    "@mastra/core": "1.42.0"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.12.0-0 <2.0.0-0"
@@ -64,5 +54,15 @@
   },
   "engines": {
     "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsup --silent --config tsup.config.ts",
+    "build:lib": "pnpm build",
+    "build:watch": "pnpm build --watch",
+    "test:unit": "vitest run --exclude '**/*.integration.test.ts'",
+    "test:watch": "vitest watch",
+    "test": "vitest run ./src/**/*.integration.test.ts",
+    "test:cloud": "pnpm test",
+    "lint": "eslint ."
   }
-}
+}