@start.dev/container 0.0.1

package/dist/_wc-vendored-types.d.ts

@@ -0,0 +1,38 @@
+// AUTO-GENERATED by packages/container/build.ts — do not edit.
+// Vendored public types from @wc/network and @wc/fs so @start.dev/container's emitted
+// declarations are self-contained for external consumers (no monorepo required).
+
+// ── from @wc/network ──
+export interface RelayRequest {
+  requestId: string;
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  bodyBase64?: string;
+}
+export interface RelayResponse {
+  requestId: string;
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  bodyBase64: string;
+  error?: string;
+}
+export declare const RELAY_PROXY_PATH = '/__wc_relay_proxy';
+export interface RelayTransport {
+  send(request: RelayRequest): Promise<RelayResponse>;
+}
+
+// ── from @wc/fs ──
+export type WatchEventType = 'rename' | 'change';
+export type WatchListener = (eventType: WatchEventType, filename: string) => void;
+export interface WatchOptions {
+  recursive?: boolean;
+  signal?: AbortSignal;
+  encoding?: 'utf8' | 'buffer';
+  persistent?: boolean;
+}
+export interface FsWatcher {
+  close(): void;
+}

package/dist/command-resolver.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The spawn() COMMAND RESOLVER for @start.dev/container (WS2).
+ *
+ * Turns a high-level `spawn(command, args)` into a concrete plan the facade can
+ * execute against the mounted MemoryFS, mirroring how a real shell/Node would
+ * resolve it — but browser-pure and over the virtual filesystem:
+ *
+ *   - `node <file> [args]`            → run the real file on the node-compat loader.
+ *   - `npm run <script>` / test / start → read package.json scripts, resolve the
+ *                                         script's command line, and recurse.
+ *   - `npx <bin> [args]` / direct bin → resolve `node_modules/.bin/<cmd>` (or the
+ *                                         package's `bin` field) to a JS entry.
+ *   - `jsh` / `bash` / `sh`          → run the real shell (@wc/shell / just-bash).
+ *   - `npm install`                  → an HONEST stub (pre-vendoring covers deps).
+ *
+ * Anything genuinely unsupported is reported as an explicit error — NEVER faked.
+ *
+ * This module is pure (no DOM/worker): it only reads the VFS to compute a plan, so
+ * it is unit-testable. The facade executes the returned plan.
+ */
+/** A minimal read-only view of the mounted filesystem the resolver needs. */
+export interface ResolverFs {
+    exists(path: string): boolean;
+    readFile(path: string): string;
+    lstat(path: string): {
+        kind: 'file' | 'dir' | 'symlink';
+    };
+    readlink(path: string): string;
+    list(path: string): {
+        name: string;
+    }[];
+}
+/** Run a real Node entry file (script or resolved bin) on the node-compat loader. */
+export interface NodePlan {
+    kind: 'node';
+    /** Absolute VFS path of the entry to evaluate. */
+    entry: string;
+    /** argv after the entry (does NOT include `node` or the entry). */
+    args: string[];
+    /** Working directory for the process. */
+    cwd: string;
+    /** A human label for output/logging (e.g. 'node src/main.js', 'vite build'). */
+    label: string;
+}
+/** Run the real dev server (the existing Vite worker path). */
+export interface DevServerPlan {
+    kind: 'dev-server';
+    label: string;
+}
+/** Run the real shell (@wc/shell / just-bash). */
+export interface ShellPlan {
+    kind: 'shell';
+    /** A command line to execute, or undefined for an interactive shell. */
+    commandLine?: string;
+    cwd: string;
+    label: string;
+}
+/** An honest "not implemented" outcome carrying the exact reason. */
+export interface UnsupportedPlan {
+    kind: 'unsupported';
+    message: string;
+}
+export type SpawnPlan = NodePlan | DevServerPlan | ShellPlan | UnsupportedPlan;
+/** Normalize an absolute-ish path to a clean VFS absolute path. */
+export declare function cleanPath(p: string): string;
+/** Is this command+args the real dev-server path (Vite worker), not a generic node run? */
+export declare function isDevServerCommand(command: string, args: string[]): boolean;
+/**
+ * Tokenize a command line into argv, honoring single/double quotes. Throws on
+ * shell control operators we do not parse yet (&&, ||, |, ;, >, <, &) so a script
+ * that needs a real shell pipeline gets an honest error instead of a wrong run.
+ */
+export declare function tokenize(commandLine: string): string[];
+/**
+ * Resolve a bin command (e.g. `vite`, `eslint`) to its JS entry file over the VFS.
+ * Tries `node_modules/.bin/<cmd>` (a symlink we follow to the package script),
+ * then the package's own `bin` field (`node_modules/<cmd>/package.json`). Returns
+ * the absolute entry path, or undefined if not found.
+ */
+export declare function resolveBin(fs: ResolverFs, cwd: string, cmd: string): string | undefined;
+/**
+ * Resolve a `spawn(command, args)` into an executable plan over the mounted FS.
+ * `cwd` is the absolute VFS working directory (the container's workdir by default).
+ */
+export declare function resolveSpawn(fs: ResolverFs, cwd: string, command: string, args: string[]): SpawnPlan;

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+import { RELAY_PROXY_PATH, type RelayTransport } from './_wc-vendored-types';
+import type { BootOptions, FileSystemAPI, FileSystemTree, MountOptions, Port, SpawnOptions, WebContainerEventMap, WebContainerProcess } from './types';
+export * from './types';
+export { RELAY_PROXY_PATH };
+export type { RelayTransport };
+/**
+ * The same-origin egress relay transport (the StackBlitz remote-proxy model):
+ * POSTs a serialized outbound request to `RELAY_PROXY_PATH` so the host performs
+ * the real external network call and returns it with CORS injected. The Vite
+ * worker auto-wires this internally (loopback/preview stay direct); it is
+ * re-exported here so a consumer can register it in other worker hosts too.
+ */
+export declare function createSameOriginRelayTransport(fetchImpl?: typeof fetch, proxyPath?: string): RelayTransport;
+/** The documented per-file write cap of the runtime (honest limit, not silent truncation). */
+export declare const MAX_FILE_BYTES: number;
+/**
+ * The kind of a preview-origin postMessage payload, identical to
+ * `@webcontainer/api`'s `PreviewMessageType`. Preview iframes post these to the
+ * embedding page; `isPreviewMessage` narrows an arbitrary message to one of them.
+ */
+export declare enum PreviewMessageType {
+    UncaughtException = "PREVIEW_UNCAUGHT_EXCEPTION",
+    UnhandledRejection = "PREVIEW_UNHANDLED_REJECTION",
+    ConsoleError = "PREVIEW_CONSOLE_ERROR"
+}
+/** The base shape every preview message carries (mirrors @webcontainer/api). */
+export interface BasePreviewMessage {
+    type: PreviewMessageType;
+    /** The preview origin port the message originated from. */
+    previewId?: string;
+    /** The preview port the message originated from. */
+    port?: number;
+    /** The preview path the message originated from. */
+    pathname?: string;
+    /** The full preview url the message originated from. */
+    search?: string;
+    hash?: string;
+}
+/** A preview-origin uncaught exception, mirroring @webcontainer/api. */
+export interface UncaughtExceptionMessage extends BasePreviewMessage {
+    type: PreviewMessageType.UncaughtException;
+    message: string;
+    stack: string | undefined;
+}
+/** A preview-origin unhandled promise rejection, mirroring @webcontainer/api. */
+export interface UnhandledRejectionMessage extends BasePreviewMessage {
+    type: PreviewMessageType.UnhandledRejection;
+    message: string;
+    stack: string | undefined;
+}
+/** A preview-origin console.error, mirroring @webcontainer/api. */
+export interface ConsoleErrorMessage extends BasePreviewMessage {
+    type: PreviewMessageType.ConsoleError;
+    args: unknown[];
+    stack: string | undefined;
+}
+export type PreviewMessage = UncaughtExceptionMessage | UnhandledRejectionMessage | ConsoleErrorMessage;
+/**
+ * Narrow an arbitrary postMessage payload to a `PreviewMessage`. Exact behavior
+ * of `@webcontainer/api`'s `isPreviewMessage`: a non-null object whose `type` is
+ * one of the `PreviewMessageType` values.
+ */
+export declare function isPreviewMessage(data: unknown): data is PreviewMessage;
+/**
+ * Reload a preview `<iframe>` element, mirroring `@webcontainer/api`'s
+ * `reloadPreview`. Pure client-side: it re-points `iframe.src` (optionally to a
+ * new `pathname`) so the browser re-navigates the frame. The optional `hardness`
+ * delay matches the upstream signature.
+ */
+export declare function reloadPreview(preview: HTMLIFrameElement, hardnessMs?: number): Promise<void>;
+/** Mirrors @webcontainer/api's auth namespace shape; honest unsupported stubs. */
+export declare const auth: {
+    /** No hosted auth in this runtime; throws an honest unsupported error. */
+    readonly init: () => never;
+    /** No hosted auth in this runtime; throws an honest unsupported error. */
+    readonly startAuthFlow: () => never;
+    /** No hosted auth in this runtime; throws an honest unsupported error. */
+    readonly logout: () => never;
+    /** No session in this runtime; returns null (no token), never a fake one. */
+    readonly loggedIn: () => Promise<void>;
+    /** No event bus in this runtime; registering returns a no-op unsubscribe. */
+    readonly on: () => () => void;
+};
+/**
+ * Mirrors @webcontainer/api's `configureAPIKey`. This unhosted runtime has no
+ * hosted API to key into, so it is an honest no-op kept for import compatibility
+ * (it does not throw, so harmless setup code that always calls it still works,
+ * but it configures nothing — there is no hosted backend to authenticate to).
+ */
+export declare function configureAPIKey(_apiKey: string): void;
+export declare class WebContainer {
+    #private;
+    /** Absolute working directory (e.g. '/proj'); mirrors @webcontainer/api.workdir. */
+    readonly workdir: string;
+    /** The FileSystemAPI facade over the in-page MemoryFS. */
+    readonly fs: FileSystemAPI;
+    /**
+     * Live map of open dev-server port → preview url. Populated when a dev server
+     * becomes ready (the `server-ready` payload's `url`). The start.dev adapter
+     * reads this to point its preview iframe.
+     */
+    readonly routes: Record<Port, string>;
+    private constructor();
+    /**
+     * Boot a WebContainer: assert cross-origin isolation, register the substrate
+     * Service Worker under the preview base, and construct the in-page filesystem.
+     * Mirrors `@webcontainer/api`'s `WebContainer.boot()`.
+     */
+    static boot(options?: BootOptions): Promise<WebContainer>;
+    /**
+     * Mount a nested FileSystemTree into the filesystem (under `workdir`, or
+     * `options.mountPoint`). Identical tree shape to `@webcontainer/api`:
+     * `{ name: { file: { contents } } | { directory: {...} } }`.
+     */
+    mount(tree: FileSystemTree, options?: MountOptions): Promise<void>;
+    /**
+     * Spawn a command (WS2 — the real command resolver). Resolves `command`+`args`
+     * against the mounted MemoryFS the way a real shell/Node would, then executes the
+     * REAL program (never faked output):
+     *
+     *   - `npm run dev` / `pnpm dev` / `yarn dev` / `vite` → the genuine Vite-serve
+     *     worker (preview + HMR bridges, fires `server-ready`). Unchanged.
+     *   - `node <file> [args]` → runs the real file on the node-compat module loader
+     *     over the mounted FS; output streams; exit resolves with the real code.
+     *   - `npm run <script>` / `npm test` / `npm start` → reads package.json scripts,
+     *     resolves the script's command line (which may invoke a local .bin), runs it.
+     *   - `npx <bin>` and direct local bins → resolves `node_modules/.bin/<cmd>` (or a
+     *     package `bin` field, walking up node_modules) to a JS entry and runs it.
+     *   - `jsh` / `bash` / `sh` → the real @wc/shell (just-bash); jsh is StackBlitz's
+     *     shell name, we substitute the real bash interpreter (documented).
+     *   - `npm install` → an HONEST stub (deps are pre-vendored; WS5 owns a real
+     *     installer). Anything genuinely unsupported throws a clear error.
+     */
+    spawn(command: string, args?: string[], options?: SpawnOptions): Promise<WebContainerProcess>;
+    /** Register a listener for a WebContainer event; returns an unsubscribe fn. */
+    on<E extends keyof WebContainerEventMap>(event: E, listener: WebContainerEventMap[E]): () => void;
+    /** Tear down workers + Service Worker + state. Mirrors @webcontainer/api.teardown(). */
+    teardown(): void;
+    /**
+     * `export(path, options)` — serialize a subtree to a FileSystemTree / binary
+     * snapshot, mirroring @webcontainer/api. NOT yet implemented as a public facade
+     * member; MemoryFS does have `snapshot()`, but the @webcontainer/api `export`
+     * format/options (binary, includes/excludes) are not yet mapped. Documented
+     * seam, not faked.
+     */
+    export(): never;
+}