@watasu/sdk 0.1.6 → 0.1.24

package/dist/sandbox.js

@@ -1,35 +1,96 @@
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
 import { DataPlaneClient, ControlClient } from './transport.js';
-import { NotFoundError, SandboxError, unsupported } from './errors.js';
+import { ConflictError, FileNotFoundError, NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
 import { Git } from './git.js';
 import { Pty } from './pty.js';
+import { ProcessManager } from './process.js';
+import { TerminalManager } from './terminal.js';
+/** Paginator for listing sandbox snapshots. */
 export class SnapshotPaginator {
-    loadItems;
-    consumed = false;
+    opts;
     hasNext = true;
     nextToken;
-    constructor(loadItems) {
-        this.loadItems = loadItems;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.nextToken = opts.nextToken;
     }
-    async nextItems() {
-        if (this.consumed)
+    /** Fetch the next page of snapshot metadata. */
+    async nextItems(opts = {}) {
+        if (!this.hasNext)
             throw new SandboxError('No more snapshots to fetch');
-        this.consumed = true;
-        this.hasNext = false;
-        return this.loadItems();
+        const config = new ConnectionConfig({ ...this.opts, ...opts });
+        const control = new ControlClient(config);
+        const payload = await control.get(snapshotListPath(this.opts, this.nextToken), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
+        this.hasNext = this.nextToken !== undefined;
+        const snapshots = Array.isArray(payload.snapshots)
+            ? payload.snapshots
+            : Array.isArray(payload.sandbox_checkpoints) ? payload.sandbox_checkpoints : [];
+        return snapshots.map((item) => snapshotInfo(record(item)));
+    }
+    /** Drain all remaining pages into one list. */
+    async listItems(opts = {}) {
+        const items = [];
+        while (this.hasNext)
+            items.push(...await this.nextItems(opts));
+        return items;
+    }
+}
+/** Paginator for listing sandboxes. */
+export class SandboxPaginator {
+    opts;
+    hasNext = true;
+    nextToken;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.nextToken = opts.nextToken;
+    }
+    /** Fetch the next page of sandbox metadata. */
+    async nextItems(opts = {}) {
+        if (!this.hasNext)
+            throw new SandboxError('No more sandboxes to fetch');
+        const config = new ConnectionConfig({ ...this.opts, ...opts });
+        const control = new ControlClient(config);
+        const payload = await control.get(sandboxListPath(this.opts, this.nextToken), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
+        this.hasNext = this.nextToken !== undefined;
+        const sandboxes = Array.isArray(payload.sandboxes) ? payload.sandboxes : [];
+        return sandboxes.map((item) => sandboxInfo(record(item)));
+    }
+    /** Drain all remaining pages into one list. */
+    async listItems(opts = {}) {
+        const items = [];
+        while (this.hasNext)
+            items.push(...await this.nextItems(opts));
+        return items;
     }
 }
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export class Sandbox {
     /** Default template slug used when create is called without a template. */
     static defaultTemplate = 'base';
+    /** Default template slug used by MCP creation once Watasu supports it. */
+    static defaultMcpTemplate = 'mcp-gateway';
+    /** Default sandbox lifetime in milliseconds. */
+    static defaultSandboxTimeoutMs = 300_000;
     files;
+    filesystem;
     commands;
+    process;
     pty;
+    terminal;
     git;
+    cwd;
+    envVars;
     sandboxId;
+    mcpPort = 50005;
+    mcpToken;
     config;
     control;
     envs;
@@ -40,34 +101,42 @@ export class Sandbox {
         this.config = opts.connectionConfig;
         this.control = opts.control ?? new ControlClient(this.config);
         this.envs = opts.envs ?? {};
+        this.envVars = this.envs;
         this.sandbox = opts.sandbox ?? {};
         const dataPlane = dataPlaneFromSession(opts.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
+        this.filesystem = this.files;
         this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.process = new ProcessManager(this.commands);
         this.pty = new Pty(dataPlane, this.config);
+        this.terminal = new TerminalManager(this.pty);
         this.git = new Git(dataPlane);
     }
+    /** Sandbox id alias used by SDK-compatible code. */
+    get id() {
+        return this.sandboxId;
+    }
     /** Create a sandbox and return it only after the API supplies a data-plane session. */
     static async create(templateOrOpts, opts = {}) {
+        const sandboxOpts = typeof templateOrOpts === 'string' ? opts : templateOrOpts ?? {};
         const template = typeof templateOrOpts === 'string'
             ? templateOrOpts
-            : templateOrOpts?.template ?? Sandbox.defaultTemplate;
-        const sandboxOpts = typeof templateOrOpts === 'string' ? opts : templateOrOpts ?? {};
-        if (sandboxOpts.mcp !== undefined)
-            unsupported('mcp');
+            : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? Sandbox.defaultTemplate : undefined);
         if (sandboxOpts.volumeMounts !== undefined)
             unsupported('volumeMounts');
         const config = new ConnectionConfig(sandboxOpts);
         const control = new ControlClient(config);
         const sandboxPayload = {
-            template_id: template,
             timeout: Math.ceil((sandboxOpts.timeoutMs ?? 300_000) / 1000),
             metadata: sandboxOpts.metadata ?? {},
             env_vars: sandboxOpts.envs ?? {},
             secure: sandboxOpts.secure ?? true,
             allow_internet_access: sandboxOpts.allowInternetAccess ?? true,
         };
+        putIfPresent(sandboxPayload, 'template_id', template);
+        putIfPresent(sandboxPayload, 'mcp', sandboxOpts.mcp);
+        Object.assign(sandboxPayload, networkUpdatePayload(sandboxOpts.network));
         putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
         const response = await control.post('/sandboxes', {
             json: sandboxPayload,
@@ -77,7 +146,7 @@ export class Sandbox {
         const sandboxId = sandbox.id ?? sandbox.sandbox_id;
         if (sandboxId === undefined)
             throw new SandboxError('create response did not include sandbox id');
-        return new Sandbox({
+        const sandboxInstance = new Sandbox({
             sandboxId: String(sandboxId),
             connectionConfig: config,
             control,
@@ -85,13 +154,14 @@ export class Sandbox {
             sandbox,
             envs: sandboxOpts.envs,
         });
+        return sandboxInstance;
     }
     /** Connect to an existing sandbox and return it with a fresh data-plane session. */
     static async connect(sandboxId, opts = {}) {
         const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
         const info = await control.get(`/sandboxes/${sandboxId}`);
-        const response = await control.post(`/sandboxes/${sandboxId}/connect`, {
+        const response = await control.post(`/sandboxes/${sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
         });
@@ -103,9 +173,14 @@ export class Sandbox {
             sandbox: record(response.sandbox ?? info.sandbox ?? {}),
         });
     }
+    static async reconnect(sandboxOrOpts, opts = {}) {
+        if (typeof sandboxOrOpts === 'string')
+            return this.connect(sandboxOrOpts, opts);
+        return this.connect(sandboxOrOpts.sandboxID, sandboxOrOpts);
+    }
     /** Refresh this sandbox's data-plane session in place. */
     async connect(opts = {}) {
-        const response = await this.control.post(`/sandboxes/${this.sandboxId}/connect`, {
+        const response = await this.control.post(`/sandboxes/${this.sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
         });
@@ -113,14 +188,41 @@ export class Sandbox {
         const dataPlane = dataPlaneFromSession(response.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
+        this.filesystem = this.files;
         this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.process = new ProcessManager(this.commands);
         this.pty = new Pty(dataPlane, this.config);
+        this.terminal = new TerminalManager(this.pty);
         this.git = new Git(dataPlane);
         return this;
     }
+    /** Resume a paused sandbox by id. */
+    static async resume(sandboxId, opts = {}) {
+        await Sandbox.connect(sandboxId, opts);
+        return true;
+    }
+    /** Pause a sandbox by id. Returns false when it was already paused. */
+    static async betaPause(sandboxId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        try {
+            await control.post(`/sandboxes/${sandboxId}/pause`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ConflictError)
+                return false;
+            throw error;
+        }
+    }
+    /** Alias for `betaPause`. */
+    static async pause(sandboxId, opts = {}) {
+        return this.betaPause(sandboxId, opts);
+    }
     /** Destroy a sandbox by id. */
     static async kill(sandboxId, opts = {}) {
-        const control = new ControlClient(new ConnectionConfig(opts));
+        const control = new ControlClient(new ConnectionConfig(typeof opts === 'string' ? { apiKey: opts } : opts));
         await control.delete(`/sandboxes/${sandboxId}`);
         return true;
     }
@@ -132,6 +234,18 @@ export class Sandbox {
         });
         return metricsList(payload.metrics ?? payload);
     }
+    /** Atomically replace a sandbox's network egress policy by id. */
+    static async updateNetwork(sandboxId, network, opts = {}) {
+        await this.putNetwork(sandboxId, network, opts);
+    }
+    static async putNetwork(sandboxId, network, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        const response = await control.put(`/sandboxes/${sandboxId}/network`, {
+            json: networkUpdatePayload(network),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return response.sandbox === undefined ? undefined : record(response.sandbox);
+    }
     /** Deprecated alias for `getInfo`. */
     static async getFullInfo(sandboxId, opts = {}) {
         return this.getInfo(sandboxId, opts);
@@ -145,16 +259,9 @@ export class Sandbox {
         });
         return snapshotInfo(record(payload.sandbox_checkpoint ?? payload.snapshot ?? payload));
     }
-    /** List checkpoints for one sandbox using snapshot naming. */
-    static listSnapshots(sandboxId, opts = {}) {
-        return new SnapshotPaginator(async () => {
-            const control = new ControlClient(new ConnectionConfig(opts));
-            const payload = await control.get(`/sandboxes/${sandboxId}/checkpoints`, {
-                requestTimeoutMs: opts.requestTimeoutMs,
-            });
-            const snapshots = Array.isArray(payload.sandbox_checkpoints) ? payload.sandbox_checkpoints : [];
-            return snapshots.map((item) => snapshotInfo(record(item)));
-        });
+    /** List snapshots visible to the configured API key. */
+    static listSnapshots(opts = {}) {
+        return new SnapshotPaginator(opts);
     }
     /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
     static async deleteSnapshot(snapshotId, opts = {}) {
@@ -204,6 +311,10 @@ export class Sandbox {
             json: { timeout: Math.ceil(timeoutMs / 1000) },
         });
     }
+    /** Keep the sandbox alive for `duration` milliseconds. */
+    async keepAlive(duration) {
+        await this.setTimeout(duration);
+    }
     /** Fetch control-plane metadata for a sandbox by id. */
     static async getInfo(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
@@ -233,7 +344,7 @@ export class Sandbox {
     }
     /** List checkpoints for this sandbox using snapshot naming. */
     listSnapshots(opts = {}) {
-        return Sandbox.listSnapshots(this.sandboxId, { ...this.configOptions(), ...opts });
+        return Sandbox.listSnapshots({ ...this.configOptions(), ...opts, sandboxId: this.sandboxId });
     }
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
     async restore(opts = {}) {
@@ -254,12 +365,10 @@ export class Sandbox {
         });
         return sandboxInfo(record(response.sandbox ?? response));
     }
-    /** List sandboxes visible to the configured API key. */
-    static async list(opts = {}) {
-        const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.get(opts.team ? `/sandboxes?team=${encodeURIComponent(opts.team)}` : '/sandboxes');
-        const sandboxes = Array.isArray(payload.sandboxes) ? payload.sandboxes : [];
-        return sandboxes.map((item) => sandboxInfo(record(item)));
+    /** Return a paginator for sandboxes visible to the configured API key. */
+    static list(opts = {}) {
+        const listOpts = typeof opts === 'string' ? { apiKey: opts } : opts;
+        return new SandboxPaginator(listOpts);
     }
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port) {
@@ -270,8 +379,39 @@ export class Sandbox {
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
     }
+    /** Return the public hostname for the sandbox or an exposed sandbox port. */
+    getHostname(port) {
+        if (port !== undefined)
+            return this.getHost(port);
+        return new URL(this.dataPlane.baseUrl).host;
+    }
+    /** Return the conventional MCP URL for this sandbox. */
+    getMcpUrl() {
+        return `https://${this.getHost(this.mcpPort)}/mcp`;
+    }
+    /** Return the MCP gateway token when the sandbox contains one. */
+    async getMcpToken() {
+        if (this.mcpToken !== undefined)
+            return this.mcpToken;
+        try {
+            const token = await this.files.read('/etc/mcp-gateway/.token', { user: 'root' });
+            this.mcpToken = String(token).trim() || undefined;
+            return this.mcpToken;
+        }
+        catch (error) {
+            if (error instanceof FileNotFoundError || error instanceof NotFoundError)
+                return undefined;
+            throw error;
+        }
+    }
+    /** Return a protocol string for a secure or insecure sandbox URL. */
+    getProtocol(baseProtocol = 'http', secure = true) {
+        return `${baseProtocol}${secure ? 's' : ''}`;
+    }
+    /** Close the local SDK attachment. This does not destroy the sandbox. */
+    async close() { }
     /** Get a signed URL that accepts a POST upload for a sandbox file path. */
-    async uploadUrl(path, opts = {}) {
+    async uploadUrl(path = '', opts = {}) {
         const fileUrl = await this.fileUrl('/upload_url', path, opts);
         return fileUrl.url;
     }
@@ -281,17 +421,31 @@ export class Sandbox {
         return fileUrl.url;
     }
     /** Get signed upload URL metadata for a sandbox file path. */
-    async uploadUrlInfo(path, opts = {}) {
+    async uploadUrlInfo(path = '', opts = {}) {
         return this.fileUrl('/upload_url', path, opts);
     }
     /** Get signed download URL metadata for a sandbox file path. */
     async downloadUrlInfo(path, opts = {}) {
         return this.fileUrl('/download_url', path, opts);
     }
-    updateNetwork(..._args) { unsupported('Sandbox.updateNetwork'); }
-    pause() { unsupported('Sandbox.pause'); }
-    betaPause() { unsupported('Sandbox.betaPause'); }
-    resume() { unsupported('Sandbox.resume'); }
+    /** Atomically replace this sandbox's network egress policy. */
+    async updateNetwork(network, opts = {}) {
+        const sandbox = await Sandbox.putNetwork(this.sandboxId, network, { ...this.configOptions(), ...opts });
+        this.sandbox = sandbox ?? this.sandbox;
+    }
+    /** Pause this sandbox. Returns false when it was already paused. */
+    async betaPause(opts = {}) {
+        return Sandbox.betaPause(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Alias for `betaPause`. */
+    async pause(opts = {}) {
+        return this.betaPause(opts);
+    }
+    /** Resume this sandbox and refresh its data-plane session. */
+    async resume(opts = {}) {
+        await this.connect(opts);
+        return true;
+    }
     async fileUrl(route, path, opts) {
         const payload = await this.control.post(`/sandboxes/${this.sandboxId}/files${route}`, {
             json: compactRecord({
@@ -324,6 +478,36 @@ function dataPlaneFromSession(session, config) {
     }
     return new DataPlaneClient(url, token, config);
 }
+function sandboxListPath(opts, nextToken) {
+    const params = new URLSearchParams();
+    if (opts.team)
+        params.set('team', opts.team);
+    if (opts.limit !== undefined)
+        params.set('limit', String(opts.limit));
+    if (nextToken)
+        params.set('next_token', nextToken);
+    if (opts.query?.metadata) {
+        for (const [key, value] of Object.entries(opts.query.metadata)) {
+            params.append(`query[metadata][${key}]`, value);
+        }
+    }
+    for (const state of opts.query?.state ?? []) {
+        params.append('query[state][]', state);
+    }
+    const query = params.toString();
+    return query ? `/sandboxes?${query}` : '/sandboxes';
+}
+function snapshotListPath(opts, nextToken) {
+    const params = new URLSearchParams();
+    if (opts.sandboxId)
+        params.set('sandbox_id', opts.sandboxId);
+    if (opts.limit !== undefined)
+        params.set('limit', String(opts.limit));
+    if (nextToken)
+        params.set('next_token', nextToken);
+    const query = params.toString();
+    return query ? `/sandbox_snapshots?${query}` : '/sandbox_snapshots';
+}
 function fileUrlInfo(payload) {
     return {
         method: String(payload.method ?? ''),
@@ -413,6 +597,26 @@ function putIfPresent(target, key, value) {
     if (value !== undefined && value !== null)
         target[key] = value;
 }
+function networkUpdatePayload(network) {
+    if (network === undefined)
+        return {};
+    if (typeof network !== 'object' || network === null)
+        unsupported('network callable rules');
+    if (network.rules !== undefined)
+        unsupported('network rules');
+    if (network.maskRequestHost !== undefined)
+        unsupported('network request host masking');
+    return compactRecord({
+        allow_out: network.allowOut,
+        deny_out: network.denyOut,
+        allow_internet_access: network.allowInternetAccess,
+        allow_package_registry_access: network.allowPackageRegistryAccess,
+        allow_public_traffic: network.allowPublicTraffic,
+        egress_profile: network.egressProfile,
+        egress_profiles: network.egressProfiles,
+        network_class: network.networkClass,
+    });
+}
 function record(value) {
     return value && typeof value === 'object' ? value : {};
 }

package/dist/template.d.ts

@@ -0,0 +1,232 @@
+import { ConnectionOpts } from './connectionConfig.js';
+export type TemplateBuildStatus = 'building' | 'waiting' | 'ready' | 'error';
+export interface BuildInfo {
+    /** First template alias. Prefer `name` for new code. */
+    alias: string;
+    /** Template name passed to the build call. */
+    name: string;
+    /** Tags assigned to this build. */
+    tags: string[];
+    /** Template identifier. */
+    templateId: string;
+    /** Build identifier. */
+    buildId: string;
+}
+export interface LogEntry {
+    timestamp?: Date;
+    level: string;
+    message: string;
+}
+export interface BuildStatusReason {
+    message: string;
+    step?: string;
+    logEntries: LogEntry[];
+}
+export interface TemplateBuildStatusResponse {
+    buildID: string;
+    templateID: string;
+    status: TemplateBuildStatus;
+    logEntries: LogEntry[];
+    logs: string[];
+    reason?: BuildStatusReason;
+}
+export interface TemplateTagInfo {
+    buildId: string;
+    tags: string[];
+}
+export interface TemplateTag {
+    tag: string;
+    buildId: string;
+    createdAt: Date;
+}
+export interface TemplateOptions {
+    fileContextPath?: string;
+    fileIgnorePatterns?: string[];
+}
+export interface CopyOptions {
+    forceUpload?: true;
+    user?: string;
+    mode?: number;
+    resolveSymlinks?: boolean;
+}
+export interface BasicBuildOptions {
+    alias?: string;
+    tags?: string[];
+    cpuCount?: number;
+    memoryMB?: number;
+    skipCache?: boolean;
+    onBuildLogs?: (entry: LogEntry) => void;
+    team?: string;
+}
+export type BuildOptions = ConnectionOpts & BasicBuildOptions;
+export type GetBuildStatusOptions = ConnectionOpts & {
+    logsOffset?: number;
+};
+export type TemplateClass = TemplateBase;
+export type CopyItem = {
+    src: string | string[];
+    dest: string;
+    forceUpload?: true;
+    user?: string;
+    mode?: number;
+    resolveSymlinks?: boolean;
+};
+export type TemplateBuilder = TemplateBase;
+export type TemplateFinal = TemplateBase;
+export type TemplateFromImage = TemplateBase;
+export type ReadyCommand = string | ReadyCmd;
+interface TemplateFileSpec {
+    path: string;
+    content_b64: string;
+    source_path?: string;
+    mode?: number;
+    user?: string;
+}
+interface BuildSpec {
+    base?: string;
+    packages?: Record<string, string[]>;
+    files?: TemplateFileSpec[];
+    setup?: string[];
+    env?: Record<string, string>;
+    start_cmd?: string;
+    ready_cmd?: string;
+}
+/** Ready-check command wrapper accepted by template builders. */
+export declare class ReadyCmd {
+    private readonly cmd;
+    constructor(cmd: string);
+    /** Return the shell command used as the ready check. */
+    getCmd(): string;
+}
+/** Return a ready check that waits for a TCP port to listen. */
+export declare function waitForPort(port: number): ReadyCmd;
+/** Return a ready check that waits for a URL to return an HTTP status code. */
+export declare function waitForURL(url: string, statusCode?: number): ReadyCmd;
+/** Alias for `waitForURL`. */
+export declare const waitForUrl: typeof waitForURL;
+/** Return a ready check that waits for a process name. */
+export declare function waitForProcess(processName: string): ReadyCmd;
+/** Return a ready check that waits for a file to exist. */
+export declare function waitForFile(filename: string): ReadyCmd;
+/** Return a ready check that waits for a fixed duration in milliseconds. */
+export declare function waitForTimeout(timeout: number): ReadyCmd;
+/** Chainable template builder for Watasu package-spec template builds. */
+export declare class TemplateBase {
+    private base;
+    private packages;
+    private files;
+    private setup;
+    private env;
+    private currentWorkdir;
+    private currentUser;
+    private startCmd;
+    private readyCmd;
+    private force;
+    private readonly fileContextPath;
+    private readonly fileIgnorePatterns;
+    constructor(options?: TemplateOptions);
+    static build(template: TemplateClass, name: string, options?: Omit<BuildOptions, 'alias'>): Promise<BuildInfo>;
+    static build(template: TemplateClass, options: BuildOptions): Promise<BuildInfo>;
+    static buildInBackground(template: TemplateClass, name: string, options?: Omit<BuildOptions, 'alias'>): Promise<BuildInfo>;
+    static buildInBackground(template: TemplateClass, options: BuildOptions): Promise<BuildInfo>;
+    static getBuildStatus(data: Pick<BuildInfo, 'templateId' | 'buildId'>, options?: GetBuildStatusOptions): Promise<TemplateBuildStatusResponse>;
+    static exists(name: string, options?: ConnectionOpts): Promise<boolean>;
+    static aliasExists(alias: string, options?: ConnectionOpts): Promise<boolean>;
+    static assignTags(targetName: string, tags: string | string[], options?: ConnectionOpts): Promise<TemplateTagInfo>;
+    static removeTags(name: string, tags: string | string[], options?: ConnectionOpts): Promise<void>;
+    static getTags(templateId: string, options?: ConnectionOpts): Promise<TemplateTag[]>;
+    static toJSON(template: TemplateClass): Promise<string>;
+    static toDockerfile(template: TemplateClass): string;
+    fromDebianImage(_variant?: string): TemplateBuilder;
+    fromUbuntuImage(_variant?: string): TemplateBuilder;
+    fromPythonImage(_version?: string): TemplateBuilder;
+    fromNodeImage(_variant?: string): TemplateBuilder;
+    fromBunImage(_variant?: string): TemplateBuilder;
+    fromBaseImage(): TemplateBuilder;
+    fromImage(_baseImage: string, _credentials?: {
+        username: string;
+        password: string;
+    }): TemplateBuilder;
+    fromAWSRegistry(_image: string, _credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        region: string;
+    }): TemplateBuilder;
+    fromGCPRegistry(_image: string, _credentials: {
+        serviceAccountJSON: object | string;
+    }): TemplateBuilder;
+    fromTemplate(template: string): TemplateBuilder;
+    fromDockerfile(dockerfileContentOrPath: string): TemplateBuilder;
+    copy(src: string | string[], dest: string, options?: CopyOptions): TemplateBuilder;
+    copyItems(items: CopyItem[]): TemplateBuilder;
+    remove(path: string | string[], options?: {
+        force?: boolean;
+        recursive?: boolean;
+        user?: string;
+    }): TemplateBuilder;
+    rename(src: string, dest: string, options?: {
+        force?: boolean;
+        user?: string;
+    }): TemplateBuilder;
+    makeDir(path: string | string[], options?: {
+        mode?: number;
+        user?: string;
+    }): TemplateBuilder;
+    makeSymlink(src: string, dest: string, options?: {
+        force?: boolean;
+        user?: string;
+    }): TemplateBuilder;
+    runCmd(command: string | string[], options?: {
+        user?: string;
+    }): TemplateBuilder;
+    setWorkdir(workdir: string): TemplateBuilder;
+    setUser(user: string): TemplateBuilder;
+    pipInstall(packages?: string | string[], options?: {
+        g?: boolean;
+    }): TemplateBuilder;
+    npmInstall(packages?: string | string[], options?: {
+        g?: boolean;
+        dev?: boolean;
+    }): TemplateBuilder;
+    bunInstall(packages?: string | string[], options?: {
+        g?: boolean;
+        dev?: boolean;
+    }): TemplateBuilder;
+    aptInstall(packages: string | string[], _options?: {
+        noInstallRecommends?: boolean;
+        fixMissing?: boolean;
+    }): TemplateBuilder;
+    addMcpServer(servers: string | string[]): TemplateBuilder;
+    gitClone(url: string, path?: string, options?: {
+        branch?: string;
+        depth?: number;
+        user?: string;
+    }): TemplateBuilder;
+    setStartCmd(startCommand: string, readyCommand: ReadyCommand): TemplateFinal;
+    setReadyCmd(readyCommand: ReadyCommand): TemplateFinal;
+    setEnvs(envs: Record<string, string>): TemplateBuilder;
+    skipCache(): TemplateBuilder;
+    toBuildSpec(): BuildSpec;
+    private addPackages;
+    private addCopySource;
+    private addFileSpec;
+    private resolveContextPath;
+    private ignored;
+    private commandWithContext;
+    private toDockerfile;
+}
+export interface TemplateFactory {
+    (options?: TemplateOptions): TemplateFromImage;
+    build: typeof TemplateBase.build;
+    buildInBackground: typeof TemplateBase.buildInBackground;
+    getBuildStatus: typeof TemplateBase.getBuildStatus;
+    exists: typeof TemplateBase.exists;
+    aliasExists: typeof TemplateBase.aliasExists;
+    assignTags: typeof TemplateBase.assignTags;
+    removeTags: typeof TemplateBase.removeTags;
+    getTags: typeof TemplateBase.getTags;
+    toJSON: typeof TemplateBase.toJSON;
+    toDockerfile: typeof TemplateBase.toDockerfile;
+}
+export declare const Template: TemplateFactory;
+export {};