@beachside/freestyle 0.0.0 → 0.12.0

package/dist/process.d.ts

@@ -0,0 +1,72 @@
+import { type NativeProcess, type ProcessStartContext, type ProcessStartInput, type ReadContext } from "@beachside/adapter";
+import { z } from "zod";
+/**
+ * Freestyle's `exec-await` returns only after a command ends, and its terminal sessions merge
+ * stdout and stderr through a TTY. A Beachside process therefore runs as a detached job in
+ * the guest: stdout and stderr go to private files, the exit status is written last, and the
+ * adapter reads new bytes from both files (base64, so they survive the lossy UTF-8 text
+ * channel) until the exit status appears and both files are drained. Pipe stdin is a FIFO
+ * kept open by a holder process; closing stdin, or the job's exit, stops the holder.
+ */
+export declare const PROCESS_RECORD = "BEACHSIDE-PROC-1";
+/** Bytes read from each stream per poll. */
+export declare const POLL_BYTES: number;
+/** Largest stdin chunk written per request (Freestyle's native stdin bound). */
+export declare const MAX_WRITE_BYTES = 1048576;
+export declare const ProcessReference: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"freestyle-job">;
+    sandbox: z.ZodString;
+    directory: z.ZodString;
+    stdin: z.ZodEnum<{
+        closed: "closed";
+        pipe: "pipe";
+    }>;
+}, z.core.$strict>;
+export type ProcessReference = z.infer<typeof ProcessReference>;
+/** Runs one guest command and returns its stdout text; throws an AdapterError otherwise. */
+export type GuestRunner = (command: string, ctx: ReadContext, stdin?: Uint8Array) => Promise<string>;
+export type JobOptions = {
+    run: GuestRunner;
+    /** Delay between polls while the job is quiet. */
+    pollMs: number;
+    /** Bound for one poll or control request. */
+    requestSeconds: number;
+    /**
+     * True while this client is pausing the VM or holds it paused. Every poll is a guest command,
+     * which keeps the VM busy and would wake it, so observation waits instead of polling.
+     */
+    held?: () => Promise<boolean>;
+};
+/** The guest launcher: a private directory, the detached job, then one record line. */
+export declare function launcherScript(input: ProcessStartInput): string;
+/** One poll: exit status (or `-`), both sizes, then new bytes of each stream as base64. */
+export declare function pollScript(directory: string, offsets: {
+    stdout: number;
+    stderr: number;
+}): string;
+type Poll = {
+    gone: true;
+} | {
+    gone: false;
+    exit: number | undefined;
+    sizes: {
+        stdout: number;
+        stderr: number;
+    };
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+};
+export declare function parsePoll(text: string): Poll | null;
+/** Start or reattach to a guest job and observe it until exit or detach. */
+export declare function observeJob(options: JobOptions, reference: ProcessReference, input: {
+    format: "text" | "bytes";
+    capture?: {
+        maxBytes: number;
+    };
+    /** Reopened jobs report output written from now on, not output delivered before. */
+    fromEnd: boolean;
+}, ctx: ProcessStartContext): Promise<NativeProcess>;
+/** Parse the launcher record: the job directory. */
+export declare function parseLauncher(text: string): string | null;
+export {};

package/dist/terminal.d.ts

@@ -0,0 +1,51 @@
+import { type NativeProcess, type ProcessStartContext, type ReadContext, type TerminalDimensions } from "@beachside/adapter";
+import type { PtySessionEvents, PtySessionInfo } from "freestyle";
+import { z } from "zod";
+/** The part of the SDK's `PtySession` a terminal uses. */
+export type PtyHandle = {
+    write(data: Uint8Array): void;
+    resize(options: {
+        cols: number;
+        rows: number;
+    }): void;
+    signal(signal: "sigint" | "sigkill"): void;
+    detach(): void;
+};
+/** Freestyle terminal sessions (`vm.pty`); tests inject a deterministic stand-in. */
+export type PtyDriver = {
+    open(vmId: string, options: {
+        exec: string;
+        cols: number;
+        rows: number;
+        slug: string;
+    } & PtySessionEvents): Promise<PtyHandle>;
+    attach(vmId: string, options: {
+        session: string;
+    } & PtySessionEvents): Promise<PtyHandle>;
+    list(vmId: string, ctx: ReadContext): Promise<PtySessionInfo[]>;
+};
+export declare const TerminalReference: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"freestyle-pty">;
+    sandbox: z.ZodString;
+    session: z.ZodString;
+}, z.core.$strict>;
+export type TerminalReference = z.infer<typeof TerminalReference>;
+export declare function terminalSlug(): string;
+/**
+ * A Beachside terminal on a named Freestyle PTY session. Output is the TTY's byte stream on
+ * stdout; a reattach skips the scrollback Freestyle replays first, so only new output is
+ * reported. Connections never reconnect on their own: a lost connection fails observation,
+ * and the terminal keeps running for a reopen.
+ */
+export declare function openTerminal(driver: PtyDriver, input: {
+    vmId: string;
+    /** A new session's shell command line; absent to reattach to `reference`. */
+    command?: string;
+    terminal?: TerminalDimensions;
+    reference: TerminalReference;
+    format: "text" | "bytes";
+    capture?: {
+        maxBytes: number;
+    };
+}, ctx: ProcessStartContext): Promise<NativeProcess>;

package/dist/transport.d.ts

@@ -0,0 +1,48 @@
+import { AdapterError } from "@beachside/adapter";
+import { Freestyle } from "freestyle";
+/** Fixed Freestyle public API origin; it is not a project-controlled setting. */
+export declare const FREESTYLE_API = "https://api.freestyle.sh";
+/** Largest native response body the adapter accepts, before decoding. */
+export declare const MAX_RESPONSE_BYTES: number;
+/**
+ * Code of the synthetic response a cancelled operation hands the SDK's background poll. The
+ * poll keeps retrying ordinary fetch failures for minutes; an API error ends it at once.
+ */
+export declare const CANCELLED = "BEACHSIDE_CANCELLED";
+/**
+ * Code of the synthetic error that replaces a poll-level failure of a background request. A
+ * stored result carries the request id header; a failure without it (such as a 404 for an
+ * unknown or expired result) says nothing about the operation itself, which may have run.
+ */
+export declare const RESULT_LOST = "BACKGROUND_RESULT_LOST";
+/**
+ * A request the adapter's fetch refused or stopped reading. It deliberately has no `code`
+ * property: the SDK would otherwise read it as a connection failure and replay a read.
+ */
+export declare class FetchRefused extends Error {
+    readonly reason: "bound" | "origin";
+    constructor(reason: "bound" | "origin", message: string);
+}
+/** The fetch signature the adapter accepts and hands to the SDK. */
+export type NativeFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type NativeFailure = {
+    /** HTTP status, or undefined when no response arrived. */
+    status?: number;
+    code?: string;
+    error: AdapterError;
+};
+/** Normalize an SDK throw into a redacted AdapterError plus the native status and code. */
+export declare function nativeFailure(error: unknown, secrets: readonly string[]): NativeFailure;
+/** True only when Freestyle answered with a refusal that proves the request had no effect. */
+export declare function refusedBeforeEffect(failure: NativeFailure): boolean;
+/**
+ * The `fetch` handed to the official SDK for one adapter call. It sends each request exactly
+ * once (the SDK itself replays only bodyless reads), refuses redirects so the API key stays on
+ * the Freestyle origin, ties every request to the call's signal and bounds every body.
+ *
+ * The SDK backgrounds slow requests and polls their result without a cancellation hook; once
+ * the call is cancelled, a poll is answered locally with an API error so the SDK stops polling.
+ */
+export declare function callFetch(base: NativeFetch, signal: AbortSignal, limit?: number): typeof fetch;
+/** A Freestyle SDK client whose every request belongs to one adapter call. */
+export declare function createFreestyleClient(apiKey: string, base: NativeFetch, signal: AbortSignal, limit?: number): Freestyle;

package/package.json

@@ -1,16 +1,46 @@
 {
   "name": "@beachside/freestyle",
-  "version": "0.0.0",
-  "description": "Placeholder for @beachside/freestyle. Install a published Beachside release instead.",
+  "version": "0.12.0",
+  "private": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && bun build src/index.ts --target node --format esm --outdir dist --external @beachside/adapter --external freestyle --external zod && tsc -p tsconfig.build.json --noEmit false --declaration --emitDeclarationOnly --outDir dist && bun ../../../scripts/rewrite-declarations.mjs"
+  },
+  "dependencies": {
+    "freestyle": "0.2.21",
+    "zod": "4.6.6",
+    "@beachside/adapter": "0.12.0"
+  },
+  "devDependencies": {
+    "beachside": "0.12.0"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pandemicsyn/beachside.git",
     "directory": "packages/providers/freestyle"
   },
-  "homepage": "https://github.com/pandemicsyn/beachside#readme",
-  "files": [
-    "README.md",
-    "LICENSE"
-  ]
+  "description": "Experimental Freestyle VMs sandbox provider adapter for Beachside.",
+  "bugs": {
+    "url": "https://github.com/pandemicsyn/beachside/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20"
+  }
 }