sandlot 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +145 -518
- package/dist/build-emitter.d.ts +47 -0
- package/dist/build-emitter.d.ts.map +1 -0
- package/dist/builder.d.ts +370 -0
- package/dist/builder.d.ts.map +1 -0
- package/dist/bundler.d.ts +3 -3
- package/dist/bundler.d.ts.map +1 -1
- package/dist/commands/compile.d.ts +13 -0
- package/dist/commands/compile.d.ts.map +1 -0
- package/dist/commands/index.d.ts +17 -0
- package/dist/commands/index.d.ts.map +1 -0
- package/dist/commands/packages.d.ts +17 -0
- package/dist/commands/packages.d.ts.map +1 -0
- package/dist/commands/run.d.ts +40 -0
- package/dist/commands/run.d.ts.map +1 -0
- package/dist/commands/types.d.ts +141 -0
- package/dist/commands/types.d.ts.map +1 -0
- package/dist/fs.d.ts +60 -42
- package/dist/fs.d.ts.map +1 -1
- package/dist/index.d.ts +5 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +304 -491
- package/dist/internal.d.ts +5 -0
- package/dist/internal.d.ts.map +1 -1
- package/dist/internal.js +174 -95
- package/dist/runner.d.ts +314 -0
- package/dist/runner.d.ts.map +1 -0
- package/dist/sandbox-manager.d.ts +45 -33
- package/dist/sandbox-manager.d.ts.map +1 -1
- package/dist/sandbox.d.ts +144 -70
- package/dist/sandbox.d.ts.map +1 -1
- package/dist/shared-modules.d.ts +22 -3
- package/dist/shared-modules.d.ts.map +1 -1
- package/dist/shared-resources.d.ts +0 -3
- package/dist/shared-resources.d.ts.map +1 -1
- package/dist/typechecker.d.ts +1 -1
- package/package.json +3 -17
- package/src/build-emitter.ts +64 -0
- package/src/builder.ts +498 -0
- package/src/bundler.ts +86 -57
- package/src/commands/compile.ts +236 -0
- package/src/commands/index.ts +51 -0
- package/src/commands/packages.ts +154 -0
- package/src/commands/run.ts +245 -0
- package/src/commands/types.ts +172 -0
- package/src/fs.ts +90 -216
- package/src/index.ts +34 -12
- package/src/internal.ts +5 -2
- package/src/sandbox.ts +214 -220
- package/src/shared-modules.ts +74 -4
- package/src/shared-resources.ts +0 -3
- package/src/ts-libs.ts +1 -1
- package/src/typechecker.ts +1 -1
- package/dist/react.d.ts +0 -159
- package/dist/react.d.ts.map +0 -1
- package/dist/react.js +0 -149
- package/src/commands.ts +0 -733
- package/src/react.tsx +0 -331
- package/src/sandbox-manager.ts +0 -490
package/dist/runner.d.ts
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* High-level runner for sandbox-based agent workflows.
|
|
3
|
+
*
|
|
4
|
+
* Provides simple wrappers that handle sandbox creation and build result capture,
|
|
5
|
+
* letting the caller focus on their agent logic.
|
|
6
|
+
*/
|
|
7
|
+
import { type Sandbox, type SandboxOptions } from "./sandbox";
|
|
8
|
+
import type { BundleResult } from "./bundler";
|
|
9
|
+
/**
|
|
10
|
+
* Options for building with a sandbox (one-off usage).
|
|
11
|
+
*/
|
|
12
|
+
export interface BuildWithSandboxOptions<T> {
|
|
13
|
+
/**
|
|
14
|
+
* Existing sandbox to use. If not provided, a new sandbox is created.
|
|
15
|
+
*
|
|
16
|
+
* Use this when you want to:
|
|
17
|
+
* - Reuse a sandbox across multiple builds
|
|
18
|
+
* - Pre-configure the sandbox with specific files or settings
|
|
19
|
+
* - Share a sandbox between different operations
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```ts
|
|
23
|
+
* const sandbox = await createSandbox({
|
|
24
|
+
* initialFiles: { '/src/index.ts': 'export const x = 1;' },
|
|
25
|
+
* });
|
|
26
|
+
*
|
|
27
|
+
* const result = await buildWithSandbox({
|
|
28
|
+
* sandbox,
|
|
29
|
+
* build: async (sb) => { ... },
|
|
30
|
+
* });
|
|
31
|
+
* ```
|
|
32
|
+
*/
|
|
33
|
+
sandbox?: Sandbox;
|
|
34
|
+
/**
|
|
35
|
+
* Options for creating a new sandbox (only used if `sandbox` is not provided).
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* ```ts
|
|
39
|
+
* const result = await buildWithSandbox({
|
|
40
|
+
* sandboxOptions: {
|
|
41
|
+
* initialFiles: { '/src/index.ts': 'export const x = 1;' },
|
|
42
|
+
* sharedModules: ['react', 'react-dom/client'],
|
|
43
|
+
* },
|
|
44
|
+
* build: async (sandbox) => { ... },
|
|
45
|
+
* });
|
|
46
|
+
* ```
|
|
47
|
+
*/
|
|
48
|
+
sandboxOptions?: SandboxOptions;
|
|
49
|
+
/**
|
|
50
|
+
* The function to run with the sandbox.
|
|
51
|
+
*
|
|
52
|
+
* This receives the sandbox and can do anything with it—run bash commands,
|
|
53
|
+
* write files, execute an agent loop, etc.
|
|
54
|
+
*
|
|
55
|
+
* The return value becomes `result` in the output.
|
|
56
|
+
*
|
|
57
|
+
* @example
|
|
58
|
+
* ```ts
|
|
59
|
+
* const { result, bundle } = await buildWithSandbox({
|
|
60
|
+
* build: async (sandbox) => {
|
|
61
|
+
* await sandbox.bash.exec('echo "hello" > /test.txt');
|
|
62
|
+
* const buildResult = await sandbox.bash.exec('build /src/index.ts');
|
|
63
|
+
* return { buildExitCode: buildResult.exitCode };
|
|
64
|
+
* },
|
|
65
|
+
* });
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
build: (sandbox: Sandbox) => Promise<T>;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Result of building with a sandbox.
|
|
72
|
+
*/
|
|
73
|
+
export interface BuildResult<T> {
|
|
74
|
+
/**
|
|
75
|
+
* Whatever the `build` function returned, or `undefined` if it threw.
|
|
76
|
+
*/
|
|
77
|
+
result: T | undefined;
|
|
78
|
+
/**
|
|
79
|
+
* The error thrown by the `build` function, or `null` if it succeeded.
|
|
80
|
+
*
|
|
81
|
+
* When an error occurs, the bundle and module may still be available
|
|
82
|
+
* if a build succeeded before the error was thrown.
|
|
83
|
+
*/
|
|
84
|
+
error: Error | null;
|
|
85
|
+
/**
|
|
86
|
+
* The last successful build result, or null if no build succeeded.
|
|
87
|
+
*
|
|
88
|
+
* This captures the bundle from any successful `build` command executed
|
|
89
|
+
* during the run. If multiple builds succeed, this contains the last one.
|
|
90
|
+
*
|
|
91
|
+
* **Important**: This is available even if the `build` function threw an error,
|
|
92
|
+
* as long as a build succeeded before the error occurred.
|
|
93
|
+
*/
|
|
94
|
+
bundle: BundleResult | null;
|
|
95
|
+
/**
|
|
96
|
+
* The loaded module exports, or null if no bundle or loading failed.
|
|
97
|
+
*
|
|
98
|
+
* When a build succeeds, the bundle is automatically loaded and the
|
|
99
|
+
* exports are available here. Use type assertions or runtime checks
|
|
100
|
+
* to access specific exports.
|
|
101
|
+
*
|
|
102
|
+
* @example
|
|
103
|
+
* ```ts
|
|
104
|
+
* const run = await buildWithSandbox({ build: myAgent });
|
|
105
|
+
*
|
|
106
|
+
* if (run.module) {
|
|
107
|
+
* const App = run.module.App as React.ComponentType;
|
|
108
|
+
* return <App />;
|
|
109
|
+
* }
|
|
110
|
+
* ```
|
|
111
|
+
*/
|
|
112
|
+
module: Record<string, unknown> | null;
|
|
113
|
+
/**
|
|
114
|
+
* Error that occurred while loading the module, or null if loading succeeded.
|
|
115
|
+
*
|
|
116
|
+
* This is separate from `error` (agent error) to distinguish:
|
|
117
|
+
* - Agent failed → `error` is set, `module` may still be available
|
|
118
|
+
* - Agent succeeded but load failed → `moduleError` is set
|
|
119
|
+
* - No bundle produced → both `module` and `moduleError` are null
|
|
120
|
+
*/
|
|
121
|
+
moduleError: Error | null;
|
|
122
|
+
/**
|
|
123
|
+
* The sandbox that was used.
|
|
124
|
+
*
|
|
125
|
+
* Useful when the wrapper created an ephemeral sandbox—you can inspect
|
|
126
|
+
* its state, save it, or reuse it for another build.
|
|
127
|
+
*/
|
|
128
|
+
sandbox: Sandbox;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Build with a sandbox, automatically capturing build results.
|
|
132
|
+
*
|
|
133
|
+
* This is the recommended way to use sandlot for one-off builds. It:
|
|
134
|
+
* 1. Creates a sandbox (or uses one you provide)
|
|
135
|
+
* 2. Sets up build result capture
|
|
136
|
+
* 3. Runs your function
|
|
137
|
+
* 4. Returns everything: your result, the bundle (if any), and the sandbox
|
|
138
|
+
*
|
|
139
|
+
* For reusable agent workflows, see `createBuilder()` which wraps this
|
|
140
|
+
* function and adds prompt support.
|
|
141
|
+
*
|
|
142
|
+
* The caller handles their own timeout/cancellation logic—this wrapper
|
|
143
|
+
* stays minimal and doesn't impose opinions on error handling.
|
|
144
|
+
*
|
|
145
|
+
* @example Basic usage with an agent
|
|
146
|
+
* ```ts
|
|
147
|
+
* import { buildWithSandbox } from 'sandlot';
|
|
148
|
+
*
|
|
149
|
+
* const run = await buildWithSandbox({
|
|
150
|
+
* build: async (sandbox) => {
|
|
151
|
+
* const agent = new MyAgent({
|
|
152
|
+
* tools: {
|
|
153
|
+
* bash: (command: string) => sandbox.bash.exec(command),
|
|
154
|
+
* },
|
|
155
|
+
* });
|
|
156
|
+
*
|
|
157
|
+
* return agent.run('Create a React component that shows "Hello"');
|
|
158
|
+
* },
|
|
159
|
+
* });
|
|
160
|
+
*
|
|
161
|
+
* // Module is auto-loaded if build succeeded
|
|
162
|
+
* if (run.module) {
|
|
163
|
+
* const App = run.module.App as React.ComponentType;
|
|
164
|
+
* return <App />;
|
|
165
|
+
* }
|
|
166
|
+
* ```
|
|
167
|
+
*
|
|
168
|
+
* @example Handling all failure modes
|
|
169
|
+
* ```ts
|
|
170
|
+
* const run = await buildWithSandbox({
|
|
171
|
+
* build: async (sandbox) => myAgent.run('...'),
|
|
172
|
+
* });
|
|
173
|
+
*
|
|
174
|
+
* // Check what happened
|
|
175
|
+
* if (run.error) {
|
|
176
|
+
* console.log('Agent failed:', run.error.message);
|
|
177
|
+
* }
|
|
178
|
+
* if (run.moduleError) {
|
|
179
|
+
* console.log('Module failed to load:', run.moduleError.message);
|
|
180
|
+
* }
|
|
181
|
+
*
|
|
182
|
+
* // Module available even if agent errored (if build succeeded first)
|
|
183
|
+
* if (run.module) {
|
|
184
|
+
* const App = run.module.App as React.ComponentType;
|
|
185
|
+
* return <App />;
|
|
186
|
+
* }
|
|
187
|
+
*
|
|
188
|
+
* // No module - check why
|
|
189
|
+
* if (!run.bundle) {
|
|
190
|
+
* console.log('No build was produced');
|
|
191
|
+
* }
|
|
192
|
+
* ```
|
|
193
|
+
*/
|
|
194
|
+
export declare function buildWithSandbox<T>(options: BuildWithSandboxOptions<T>): Promise<BuildResult<T>>;
|
|
195
|
+
/**
|
|
196
|
+
* Options for creating a reusable builder function.
|
|
197
|
+
*/
|
|
198
|
+
export interface CreateBuilderOptions<T> {
|
|
199
|
+
/**
|
|
200
|
+
* Existing sandbox to reuse across all calls.
|
|
201
|
+
*
|
|
202
|
+
* When provided, the same sandbox is used for every call to the returned
|
|
203
|
+
* builder function. Files and state persist between runs—useful for
|
|
204
|
+
* iterative workflows where you want to build on previous work.
|
|
205
|
+
*
|
|
206
|
+
* @example
|
|
207
|
+
* ```ts
|
|
208
|
+
* const sandbox = await createSandbox({
|
|
209
|
+
* initialFiles: { '/src/utils.ts': 'export const PI = 3.14;' },
|
|
210
|
+
* });
|
|
211
|
+
*
|
|
212
|
+
* const runAgent = createBuilder({
|
|
213
|
+
* sandbox, // Reused across all calls
|
|
214
|
+
* build: async (sb, prompt) => myAgent.run(sb, prompt),
|
|
215
|
+
* });
|
|
216
|
+
*
|
|
217
|
+
* await runAgent("Create a circle component"); // Uses existing utils.ts
|
|
218
|
+
* await runAgent("Add a square component"); // Still has circle + utils
|
|
219
|
+
* ```
|
|
220
|
+
*/
|
|
221
|
+
sandbox?: Sandbox;
|
|
222
|
+
/**
|
|
223
|
+
* Options for creating fresh sandboxes (only used if `sandbox` is not provided).
|
|
224
|
+
*
|
|
225
|
+
* Each call to the returned builder function creates a new sandbox with
|
|
226
|
+
* these options. Use this when you want isolated runs.
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```ts
|
|
230
|
+
* const runAgent = createBuilder({
|
|
231
|
+
* sandboxOptions: {
|
|
232
|
+
* sharedModules: ['react', 'react-dom/client'],
|
|
233
|
+
* },
|
|
234
|
+
* build: async (sandbox, prompt) => myAgent.run(sandbox, prompt),
|
|
235
|
+
* });
|
|
236
|
+
*
|
|
237
|
+
* // Each call gets a fresh sandbox
|
|
238
|
+
* await runAgent("Create a counter"); // Fresh sandbox
|
|
239
|
+
* await runAgent("Create a todo list"); // Another fresh sandbox
|
|
240
|
+
* ```
|
|
241
|
+
*/
|
|
242
|
+
sandboxOptions?: SandboxOptions;
|
|
243
|
+
/**
|
|
244
|
+
* The function to build with the sandbox and prompt.
|
|
245
|
+
*
|
|
246
|
+
* This receives the sandbox and the prompt string, and should return
|
|
247
|
+
* whatever result your agent produces.
|
|
248
|
+
*
|
|
249
|
+
* @example
|
|
250
|
+
* ```ts
|
|
251
|
+
* const runAgent = createBuilder({
|
|
252
|
+
* build: async (sandbox, prompt) => {
|
|
253
|
+
* const agent = new MyAgent({
|
|
254
|
+
* tools: { bash: sandbox.bash.exec },
|
|
255
|
+
* });
|
|
256
|
+
* return agent.run(prompt);
|
|
257
|
+
* },
|
|
258
|
+
* });
|
|
259
|
+
* ```
|
|
260
|
+
*/
|
|
261
|
+
build: (sandbox: Sandbox, prompt: string) => Promise<T>;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* Create a reusable builder function for running prompts in a sandbox.
|
|
265
|
+
*
|
|
266
|
+
* This wraps `buildWithSandbox()` to create a convenient function that
|
|
267
|
+
* just takes a prompt. Define your agent logic once, then call it with
|
|
268
|
+
* different prompts.
|
|
269
|
+
*
|
|
270
|
+
* **Sandbox behavior:**
|
|
271
|
+
* - If you provide `sandbox`: The same sandbox is reused for every call
|
|
272
|
+
* (files persist, good for iteration)
|
|
273
|
+
* - If you provide `sandboxOptions` (or nothing): A fresh sandbox is created
|
|
274
|
+
* for each call (isolated runs)
|
|
275
|
+
*
|
|
276
|
+
* @example Basic usage
|
|
277
|
+
* ```ts
|
|
278
|
+
* import { createBuilder } from 'sandlot';
|
|
279
|
+
*
|
|
280
|
+
* const runAgent = createBuilder({
|
|
281
|
+
* sandboxOptions: { sharedModules: ['react', 'react-dom/client'] },
|
|
282
|
+
* build: async (sandbox, prompt) => {
|
|
283
|
+
* const agent = new MyAgent({ tools: { bash: sandbox.bash.exec } });
|
|
284
|
+
* return agent.run(prompt);
|
|
285
|
+
* },
|
|
286
|
+
* });
|
|
287
|
+
*
|
|
288
|
+
* // Use it multiple times with different prompts
|
|
289
|
+
* const result1 = await runAgent("Create a counter component");
|
|
290
|
+
* const result2 = await runAgent("Create a todo list");
|
|
291
|
+
*
|
|
292
|
+
* if (result1.module?.App) {
|
|
293
|
+
* const Counter = result1.module.App as React.ComponentType;
|
|
294
|
+
* }
|
|
295
|
+
* ```
|
|
296
|
+
*
|
|
297
|
+
* @example Iterative workflow with shared sandbox
|
|
298
|
+
* ```ts
|
|
299
|
+
* const sandbox = await createSandbox();
|
|
300
|
+
*
|
|
301
|
+
* const runAgent = createBuilder({
|
|
302
|
+
* sandbox, // Same sandbox for all calls
|
|
303
|
+
* build: async (sb, prompt) => myAgent.run(sb, prompt),
|
|
304
|
+
* });
|
|
305
|
+
*
|
|
306
|
+
* // First prompt creates initial component
|
|
307
|
+
* await runAgent("Create a button component");
|
|
308
|
+
*
|
|
309
|
+
* // Second prompt can build on the first
|
|
310
|
+
* await runAgent("Add a click counter to the button");
|
|
311
|
+
* ```
|
|
312
|
+
*/
|
|
313
|
+
export declare function createBuilder<T>(options: CreateBuilderOptions<T>): (prompt: string) => Promise<BuildResult<T>>;
|
|
314
|
+
//# sourceMappingURL=runner.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAiB,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;;OAEG;IACH,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC;IAEtB;;;;;OAKG;IACH,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;;;;;;;OAQG;IACH,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAEvC;;;;;;;OAOG;IACH,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IAE1B;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAClC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAsCzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAW7C"}
|
|
@@ -1,38 +1,40 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* SandboxManager - Manages
|
|
2
|
+
* SandboxManager - Manages lifecycle and orchestration for multiple sandboxes.
|
|
3
3
|
*
|
|
4
4
|
* When running many sandboxes concurrently (e.g., for multiple AI agents),
|
|
5
|
-
* this manager
|
|
5
|
+
* this manager provides:
|
|
6
6
|
*
|
|
7
|
-
* -
|
|
8
|
-
* -
|
|
7
|
+
* - ID-based tracking and lookup of sandboxes
|
|
8
|
+
* - Batch operations (saveAll, destroyAll, getDirtySandboxes)
|
|
9
|
+
* - Manager-level default options inherited by all sandboxes
|
|
10
|
+
* - Statistics and introspection
|
|
11
|
+
*
|
|
12
|
+
* Note: Resources (TypeScript libs, bundler) are shared via a global singleton
|
|
13
|
+
* regardless of whether you use the manager or standalone sandbox functions.
|
|
14
|
+
* The manager's value is lifecycle management, not resource efficiency.
|
|
9
15
|
*
|
|
10
16
|
* Usage:
|
|
11
17
|
* ```ts
|
|
12
18
|
* const manager = await createSandboxManager();
|
|
13
19
|
*
|
|
14
|
-
* // Create multiple sandboxes
|
|
15
|
-
* const sandbox1 = await manager.createSandbox({ ... });
|
|
16
|
-
* const sandbox2 = await manager.createSandbox({ ... });
|
|
20
|
+
* // Create multiple sandboxes with automatic ID tracking
|
|
21
|
+
* const sandbox1 = await manager.createSandbox({ id: "agent-1", ... });
|
|
22
|
+
* const sandbox2 = await manager.createSandbox({ id: "agent-2", ... });
|
|
17
23
|
*
|
|
18
|
-
* //
|
|
24
|
+
* // Lookup, batch operations, etc.
|
|
25
|
+
* manager.getSandbox("agent-1");
|
|
26
|
+
* manager.getDirtySandboxes();
|
|
27
|
+
* await manager.saveAll();
|
|
19
28
|
*
|
|
20
|
-
* // Clean up
|
|
29
|
+
* // Clean up all at once
|
|
21
30
|
* manager.destroyAll();
|
|
22
31
|
* ```
|
|
23
32
|
*/
|
|
24
33
|
import { defineCommand } from "just-bash/browser";
|
|
25
34
|
import { type IndexedDbFsOptions } from "./fs";
|
|
26
35
|
import { type BundleResult } from "./bundler";
|
|
27
|
-
import { type SharedResources
|
|
28
|
-
import type { Sandbox } from "./sandbox";
|
|
29
|
-
export type { BundleResult } from "./bundler";
|
|
30
|
-
export type { TypecheckResult } from "./typechecker";
|
|
31
|
-
export type { SharedResources, TypesCache } from "./shared-resources";
|
|
32
|
-
export type { PackageManifest, InstallResult } from "./packages";
|
|
33
|
-
export { installPackage, uninstallPackage, listPackages, getPackageManifest } from "./packages";
|
|
34
|
-
export { InMemoryTypesCache } from "./shared-resources";
|
|
35
|
-
export { loadModule, loadExport, loadDefault, getExportNames, hasExport, createModuleUrl, revokeModuleUrl, ModuleLoadError, ExportNotFoundError, } from "./loader";
|
|
36
|
+
import { type SharedResources } from "./shared-resources";
|
|
37
|
+
import type { Sandbox, SandboxBashOptions } from "./sandbox";
|
|
36
38
|
/**
|
|
37
39
|
* Options for creating a sandbox via the manager
|
|
38
40
|
*/
|
|
@@ -83,6 +85,13 @@ export interface ManagedSandboxOptions {
|
|
|
83
85
|
* @see SandboxOptions.sharedModules for full documentation
|
|
84
86
|
*/
|
|
85
87
|
sharedModules?: string[];
|
|
88
|
+
/**
|
|
89
|
+
* Options passed through to the just-bash Bash constructor.
|
|
90
|
+
* Overrides manager-level bashOptions for this sandbox.
|
|
91
|
+
*
|
|
92
|
+
* @see SandboxOptions.bashOptions for full documentation
|
|
93
|
+
*/
|
|
94
|
+
bashOptions?: SandboxBashOptions;
|
|
86
95
|
}
|
|
87
96
|
/**
|
|
88
97
|
* A sandbox instance managed by the SandboxManager.
|
|
@@ -121,11 +130,7 @@ export interface SandboxManagerStats {
|
|
|
121
130
|
/**
|
|
122
131
|
* Options for creating a SandboxManager
|
|
123
132
|
*/
|
|
124
|
-
export interface SandboxManagerOptions
|
|
125
|
-
/**
|
|
126
|
-
* TypeScript libs to load. Defaults to browser libs (ES2020 + DOM).
|
|
127
|
-
*/
|
|
128
|
-
libs?: string[];
|
|
133
|
+
export interface SandboxManagerOptions {
|
|
129
134
|
/**
|
|
130
135
|
* Default shared modules for all sandboxes created by this manager.
|
|
131
136
|
* Individual sandboxes can override with their own sharedModules option.
|
|
@@ -142,9 +147,20 @@ export interface SandboxManagerOptions extends SharedResourcesOptions {
|
|
|
142
147
|
* ```
|
|
143
148
|
*/
|
|
144
149
|
sharedModules?: string[];
|
|
150
|
+
/**
|
|
151
|
+
* Default bash options for all sandboxes created by this manager.
|
|
152
|
+
* Individual sandboxes can override with their own bashOptions.
|
|
153
|
+
*
|
|
154
|
+
* @see SandboxOptions.bashOptions for full documentation
|
|
155
|
+
*/
|
|
156
|
+
bashOptions?: SandboxBashOptions;
|
|
145
157
|
}
|
|
146
158
|
/**
|
|
147
|
-
* Manager for creating and managing multiple sandboxes
|
|
159
|
+
* Manager for creating and managing multiple sandboxes.
|
|
160
|
+
*
|
|
161
|
+
* Provides lifecycle management, ID-based tracking, and batch operations
|
|
162
|
+
* for multiple concurrent sandboxes. Resources (TypeScript libs, bundler)
|
|
163
|
+
* are shared via a global singleton.
|
|
148
164
|
*/
|
|
149
165
|
export declare class SandboxManager {
|
|
150
166
|
private resources;
|
|
@@ -155,15 +171,15 @@ export declare class SandboxManager {
|
|
|
155
171
|
private options;
|
|
156
172
|
constructor(options?: SandboxManagerOptions);
|
|
157
173
|
/**
|
|
158
|
-
* Initialize
|
|
174
|
+
* Initialize the manager by loading shared resources.
|
|
159
175
|
* Called automatically on first sandbox creation, but can be called
|
|
160
|
-
* explicitly to pre-warm.
|
|
176
|
+
* explicitly to pre-warm the global resource cache.
|
|
161
177
|
*/
|
|
162
178
|
initialize(): Promise<void>;
|
|
163
179
|
private doInitialize;
|
|
164
180
|
/**
|
|
165
181
|
* Create a new managed sandbox.
|
|
166
|
-
*
|
|
182
|
+
* The sandbox is tracked by the manager and can be looked up by ID.
|
|
167
183
|
*/
|
|
168
184
|
createSandbox(options?: ManagedSandboxOptions): Promise<ManagedSandbox>;
|
|
169
185
|
/**
|
|
@@ -179,7 +195,8 @@ export declare class SandboxManager {
|
|
|
179
195
|
*/
|
|
180
196
|
closeSandbox(id: string): boolean;
|
|
181
197
|
/**
|
|
182
|
-
* Close all sandboxes
|
|
198
|
+
* Close all sandboxes managed by this manager.
|
|
199
|
+
* Does not affect the global shared resources.
|
|
183
200
|
*/
|
|
184
201
|
destroyAll(): void;
|
|
185
202
|
/**
|
|
@@ -216,11 +233,6 @@ export declare class SandboxManager {
|
|
|
216
233
|
* Get the shared resources (for advanced use cases)
|
|
217
234
|
*/
|
|
218
235
|
getResources(): SharedResources | null;
|
|
219
|
-
/**
|
|
220
|
-
* Get the shared lib files (for advanced use cases)
|
|
221
|
-
* @deprecated Use getResources().libFiles instead
|
|
222
|
-
*/
|
|
223
|
-
getLibFiles(): Map<string, string>;
|
|
224
236
|
}
|
|
225
237
|
/**
|
|
226
238
|
* Create a new SandboxManager instance.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../src/sandbox-manager.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"sandbox-manager.d.ts","sourceRoot":"","sources":["../src/sandbox-manager.ts"],"names":[],"mappings":"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"}
|