@freestyle-sh/with-web-terminal 0.0.1

package/.env

@@ -0,0 +1 @@
+FREESTYLE_API_KEY=NYDNxdzbycbhCF2M6DUhK5-7fPaRDNM7F9cerzZtEacSBgHVgjaZhDoJ9F44kbSWqJN

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import * as freestyle_sandboxes from 'freestyle-sandboxes';
+import { VmWith, VmWithInstance, CreateVmOptions } from 'freestyle-sandboxes';
+
+type TtydConfig = {
+    /** Port to run ttyd on (default: auto-assigned starting at 7682) */
+    port?: number;
+    /** Shell or command to run (default: /bin/bash) */
+    command?: string;
+    /** User to run terminal as (default: current user) */
+    user?: string;
+    /** Working directory (default: user home) */
+    cwd?: string;
+    /** Enable basic auth */
+    credential?: {
+        username: string;
+        password: string;
+    };
+    /** Terminal title shown in browser tab */
+    title?: string;
+    /** Read-only terminal (no input allowed) */
+    readOnly?: boolean;
+};
+type WebTerminalConfig = {
+    id: string;
+} & TtydConfig;
+type ResolvedTerminalConfig = {
+    id: string;
+    port: number;
+    command: string;
+    user: string;
+    cwd: string;
+    credential?: {
+        username: string;
+        password: string;
+    };
+    title: string;
+    readOnly: boolean;
+};
+declare class VmWebTerminal<T extends WebTerminalConfig[] = WebTerminalConfig[]> extends VmWith<VmWebTerminalInstance<T> & TerminalInstances<T>> {
+    private resolvedTerminals;
+    constructor(terminals: T);
+    configure(existingConfig: CreateVmOptions): CreateVmOptions | Promise<CreateVmOptions>;
+    createInstance(): VmWebTerminalInstance<T> & TerminalInstances<T>;
+    installServiceName(): string;
+}
+declare class WebTerminal {
+    readonly id: string;
+    readonly port: number;
+    readonly command: string;
+    private instance;
+    constructor({ id, port, command, instance }: {
+        id: string;
+        port: number;
+        command: string;
+        instance: VmWebTerminalInstance<any>;
+    });
+    /** Expose this terminal publicly via Freestyle routing */
+    route({ domain }: {
+        domain: string;
+    }): Promise<void>;
+}
+type TerminalInstances<T extends WebTerminalConfig[]> = {
+    [K in T[number]["id"]]: WebTerminal;
+};
+declare class VmWebTerminalInstance<T extends WebTerminalConfig[]> extends VmWithInstance {
+    builder: VmWebTerminal<T>;
+    constructor(builder: VmWebTerminal<T>, resolvedTerminals: ResolvedTerminalConfig[]);
+    /** @internal */
+    get _vm(): freestyle_sandboxes.Vm;
+}
+
+export { VmWebTerminal, VmWebTerminalInstance, WebTerminal };
+export type { ResolvedTerminalConfig, TerminalInstances, TtydConfig, WebTerminalConfig };

package/dist/index.js

@@ -0,0 +1,136 @@
+import { VmWith, VmTemplate, VmWithInstance } from 'freestyle-sandboxes';
+
+class VmWebTerminal extends VmWith {
+  resolvedTerminals;
+  constructor(terminals) {
+    super();
+    let nextPort = 7682;
+    this.resolvedTerminals = terminals.map((config) => ({
+      id: config.id,
+      port: config.port ?? nextPort++,
+      command: config.command ?? "bash -l",
+      user: config.user ?? "root",
+      cwd: config.cwd ?? "/root",
+      credential: config.credential,
+      title: config.title ?? config.id,
+      readOnly: config.readOnly ?? false
+    }));
+  }
+  configure(existingConfig) {
+    const installScript = `#!/bin/bash
+set -e
+
+TTYD_VERSION="1.7.7"
+curl -fsSL -o /usr/local/bin/ttyd "https://github.com/tsl0922/ttyd/releases/download/\${TTYD_VERSION}/ttyd.x86_64"
+chmod +x /usr/local/bin/ttyd
+/usr/local/bin/ttyd --version
+`;
+    const services = this.resolvedTerminals.map((t) => {
+      const args = [
+        `/usr/local/bin/ttyd`,
+        `-p ${t.port}`
+      ];
+      if (t.credential) {
+        if (t.credential.username.length === 0 || t.credential.password.length === 0) {
+          throw new Error(
+            `Invalid credential for terminal ${t.id}: username and password cannot be empty`
+          );
+        }
+        if (t.credential.username.includes(":") || t.credential.password.includes(":")) {
+          throw new Error(
+            `Invalid credential for terminal ${t.id}: username and password cannot contain colon (:) character`
+          );
+        }
+        args.push(`--credential ${t.credential.username}:${t.credential.password}`);
+      }
+      if (t.readOnly) {
+        args.push(`--readonly`);
+      } else {
+        args.push(`--writable`);
+      }
+      args.push(t.command);
+      return {
+        name: `web-terminal-${t.id}`,
+        mode: "service",
+        exec: [args.join(" ")],
+        user: t.user,
+        cwd: t.cwd,
+        restart: "always",
+        restartSec: 2,
+        after: ["install-ttyd.service", "systemd-sysusers.service"],
+        requires: ["systemd-sysusers.service"]
+      };
+    });
+    const config = {
+      template: new VmTemplate({
+        additionalFiles: {
+          "/opt/install-ttyd.sh": { content: installScript }
+        },
+        systemd: {
+          services: [
+            {
+              name: "install-ttyd",
+              mode: "oneshot",
+              deleteAfterSuccess: true,
+              exec: ["bash /opt/install-ttyd.sh"],
+              timeoutSec: 120
+            },
+            ...services
+          ]
+        }
+      })
+    };
+    return this.compose(existingConfig, config);
+  }
+  createInstance() {
+    return new VmWebTerminalInstance(this, this.resolvedTerminals);
+  }
+  installServiceName() {
+    return "install-ttyd.service";
+  }
+}
+class WebTerminal {
+  id;
+  port;
+  command;
+  instance;
+  constructor({ id, port, command, instance }) {
+    this.id = id;
+    this.port = port;
+    this.command = command;
+    this.instance = instance;
+  }
+  /** Expose this terminal publicly via Freestyle routing */
+  async route({ domain }) {
+    const vm = this.instance._vm;
+    const freestyle = vm._freestyle;
+    console.log(`Routing terminal ${this.id} on vm ${vm.vmId} at port ${this.port} to domain ${domain}`);
+    await freestyle.domains.mappings.create({
+      domain,
+      vmId: vm.vmId,
+      vmPort: this.port
+    });
+  }
+}
+class VmWebTerminalInstance extends VmWithInstance {
+  builder;
+  constructor(builder, resolvedTerminals) {
+    super();
+    this.builder = builder;
+    for (const config of resolvedTerminals) {
+      const terminal = new WebTerminal({
+        id: config.id,
+        port: config.port,
+        command: config.command,
+        instance: this
+      });
+      this[config.id] = terminal;
+    }
+  }
+  /** @internal */
+  get _vm() {
+    return this.vm;
+  }
+}
+
+export { VmWebTerminal, VmWebTerminalInstance, WebTerminal };

package/examples/basic.ts

@@ -0,0 +1,16 @@
+import "dotenv/config";
+import { freestyle } from "freestyle-sandboxes";
+import { VmWebTerminal } from "../src/index.ts";
+
+const webTerminal = new VmWebTerminal([{ id: "main" }] as const);
+
+const { vm } = await freestyle.vms.create({
+  with: {
+    terminal: webTerminal,
+  },
+});
+
+const domain = `${crypto.randomUUID()}.style.dev`;
+await vm.terminal.main.route({ domain });
+
+console.log(`Terminal available at: https://${domain}`);

package/examples/binary.ts

@@ -0,0 +1,43 @@
+import "dotenv/config";
+import { freestyle, VmSpec } from "freestyle-sandboxes";
+import { VmWebTerminal } from "../src/index.ts";
+
+const id = crypto.randomUUID().slice(0, 8);
+
+const webTerminal = new VmWebTerminal([{ id: "main", command: "bash -lc claude" }] as const);
+
+const { vm } = await freestyle.vms.create({
+  spec: new VmSpec({
+    snapshot: new VmSpec({
+        additionalFiles: {
+            "/opt/install-claude.sh": {
+                content: `#!/bin/bash
+
+                curl -fsSL https://claude.ai/install.sh | bash
+
+                echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc 
+                `,
+            }
+        },
+      systemd: {
+        
+        services: [
+          {
+            name: "install-claude",
+            mode: "oneshot",
+            exec: [
+              `bash /opt/install-claude.sh`,
+            ],
+          },
+        ],
+      },
+    }),
+    with: {
+      terminal: webTerminal,
+    },
+  }),
+});
+
+await vm.terminal.main.route({ domain: `${id}-claude.style.dev` });
+
+console.log(`Main terminal: https://${id}-claude.style.dev`);

package/examples/cred.ts

@@ -0,0 +1,19 @@
+import "dotenv/config";
+import { freestyle } from "freestyle-sandboxes";
+import { VmWebTerminal } from "../src/index.ts";
+
+const webTerminal = new VmWebTerminal([{ id: "main", credential: {
+  username: "admin",
+  password: "password123",
+}}] as const);
+
+const { vm } = await freestyle.vms.create({
+  with: {
+    terminal: webTerminal,
+  },
+});
+
+const domain = `${crypto.randomUUID()}.style.dev`;
+await vm.terminal.main.route({ domain });
+
+console.log(`Terminal available at: https://${domain}`);

package/examples/multi.ts

@@ -0,0 +1,22 @@
+import "dotenv/config";
+import { freestyle } from "freestyle-sandboxes";
+import { VmWebTerminal } from "../src/index.ts";
+
+const id = crypto.randomUUID().slice(0, 8);
+
+const webTerminal = new VmWebTerminal([
+  { id: "public" },
+  { id: "private", credential: { username: "admin", password: "password123" } },
+] as const);
+
+const { vm } = await freestyle.vms.create({
+  with: {
+    terminal: webTerminal,
+  },
+});
+
+await vm.terminal.public.route({ domain: `${id}-noauth.style.dev` });
+await vm.terminal.private.route({ domain: `${id}-auth.style.dev` });
+
+console.log(`Public terminal:  https://${id}-noauth.style.dev`);
+console.log(`Private terminal: https://admin:password123@${id}-auth.style.dev`);

package/examples/readonly.ts

@@ -0,0 +1,22 @@
+import "dotenv/config";
+import { freestyle } from "freestyle-sandboxes";
+import { VmWebTerminal } from "../src/index.ts";
+
+const webTerminal = new VmWebTerminal([
+  {
+    id: "counter",
+    readOnly: true,
+    shell: "watch -n1 date",
+  },
+] as const);
+
+const { vm } = await freestyle.vms.create({
+  with: {
+    terminal: webTerminal,
+  },
+});
+
+const domain = `${crypto.randomUUID().slice(0, 8)}-readonly.style.dev`;
+await vm.terminal.counter.route({ domain });
+
+console.log(`Read-only counter: https://${domain}`);

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@freestyle-sh/with-web-terminal",
+  "version": "0.0.1",
+  "description": "Web terminal for freestyle sandboxes",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "pkgroll",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": ["ttyd", "terminal", "web-terminal", "freestyle"],
+  "author": "",
+  "packageManager": "pnpm@10.11.0",
+  "devDependencies": {
+    "pkgroll": "^2.11.2",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "freestyle-sandboxes": "^0.1.12"
+  }
+}

package/src/index.ts

@@ -0,0 +1,216 @@
+import {
+  VmTemplate,
+  type CreateVmOptions,
+  VmWith,
+  VmWithInstance,
+  Freestyle,
+} from "freestyle-sandboxes";
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+export type TtydConfig = {
+  /** Port to run ttyd on (default: auto-assigned starting at 7682) */
+  port?: number;
+  /** Shell or command to run (default: /bin/bash) */
+  command?: string;
+  /** User to run terminal as (default: current user) */
+  user?: string;
+  /** Working directory (default: user home) */
+  cwd?: string;
+  /** Enable basic auth */
+  credential?: { username: string; password: string };
+  /** Terminal title shown in browser tab */
+  title?: string;
+  /** Read-only terminal (no input allowed) */
+  readOnly?: boolean;
+};
+
+export type WebTerminalConfig = { id: string } & TtydConfig;
+
+export type ResolvedTerminalConfig = {
+  id: string;
+  port: number;
+  command: string;
+  user: string;
+  cwd: string;
+  credential?: { username: string; password: string };
+  title: string;
+  readOnly: boolean;
+};
+
+// ============================================================================
+// Builder Class
+// ============================================================================
+
+export class VmWebTerminal<
+  T extends WebTerminalConfig[] = WebTerminalConfig[]
+> extends VmWith<VmWebTerminalInstance<T> & TerminalInstances<T>> {
+  private resolvedTerminals: ResolvedTerminalConfig[];
+
+  constructor(terminals: T) {
+    super();
+    // Resolve config once with defaults
+    let nextPort = 7682;
+    this.resolvedTerminals = terminals.map((config) => ({
+      id: config.id,
+      port: config.port ?? nextPort++,
+      command: config.command ?? "bash -l",
+      user: config.user ?? "root",
+      cwd: config.cwd ?? "/root",
+      credential: config.credential,
+      title: config.title ?? config.id,
+      readOnly: config.readOnly ?? false,
+    }));
+  }
+
+  override configure(
+    existingConfig: CreateVmOptions
+  ): CreateVmOptions | Promise<CreateVmOptions> {
+
+    // Generate install script
+    const installScript = `#!/bin/bash
+set -e
+
+TTYD_VERSION="1.7.7"
+curl -fsSL -o /usr/local/bin/ttyd "https://github.com/tsl0922/ttyd/releases/download/\${TTYD_VERSION}/ttyd.x86_64"
+chmod +x /usr/local/bin/ttyd
+/usr/local/bin/ttyd --version
+`;
+
+    // Generate systemd service for each terminal
+    const services = this.resolvedTerminals.map((t) => {
+      const args: string[] = [
+        `/usr/local/bin/ttyd`,
+        `-p ${t.port}`,
+      ];
+
+      if (t.credential) {
+        if (t.credential.username.length === 0 || t.credential.password.length === 0) {
+          throw new Error(
+            `Invalid credential for terminal ${t.id}: username and password cannot be empty`
+          );
+        }
+        if (t.credential.username.includes(":") || t.credential.password.includes(":")) {
+          throw new Error(
+            `Invalid credential for terminal ${t.id}: username and password cannot contain colon (:) character`
+          );
+        }
+        args.push(`--credential ${t.credential.username}:${t.credential.password}`);
+      }
+      if (t.readOnly) {
+        args.push(`--readonly`);
+      } else {
+        args.push(`--writable`);
+      }
+
+      // Shell command at the end
+      args.push(t.command);
+
+      return {
+        name: `web-terminal-${t.id}`,
+        mode: "service" as const,
+        exec: [args.join(" ")],
+        user: t.user,
+        cwd: t.cwd,
+        restart: "always" as const,
+        restartSec: 2,
+        after: ["install-ttyd.service", "systemd-sysusers.service"],
+        requires: ["systemd-sysusers.service"],
+      };
+    });
+
+    const config: CreateVmOptions = {
+      template: new VmTemplate({
+        additionalFiles: {
+          "/opt/install-ttyd.sh": { content: installScript },
+        },
+        systemd: {
+          services: [
+            {
+              name: "install-ttyd",
+              mode: "oneshot",
+              deleteAfterSuccess: true,
+              exec: ["bash /opt/install-ttyd.sh"],
+              timeoutSec: 120,
+            },
+            ...services,
+          ],
+        },
+      }),
+    };
+
+    return this.compose(existingConfig, config);
+  }
+
+  createInstance(): VmWebTerminalInstance<T> & TerminalInstances<T> {
+    return new VmWebTerminalInstance(this, this.resolvedTerminals) as VmWebTerminalInstance<T> & TerminalInstances<T>;
+  }
+
+  installServiceName(): string {
+    return "install-ttyd.service";
+  }
+}
+
+// ============================================================================
+// Instance Class (runtime access)
+// ============================================================================
+
+export class WebTerminal {
+  readonly id: string;
+  readonly port: number;
+  readonly command: string;
+  private instance: VmWebTerminalInstance<any>;
+
+  constructor({ id, port, command, instance }: { id: string; port: number; command: string; instance: VmWebTerminalInstance<any> }) {
+    this.id = id;
+    this.port = port;
+    this.command = command;
+    this.instance = instance;
+  }
+
+  /** Expose this terminal publicly via Freestyle routing */
+  async route({ domain }: { domain: string }): Promise<void> {
+    const vm = this.instance._vm;
+    // @ts-expect-error using internal thing
+    const freestyle: Freestyle = vm._freestyle;
+    console.log(`Routing terminal ${this.id} on vm ${vm.vmId} at port ${this.port} to domain ${domain}`);
+    await freestyle.domains.mappings.create({
+      domain: domain,
+      vmId: vm.vmId,
+      vmPort: this.port,
+    })
+  }
+}
+
+export type TerminalInstances<T extends WebTerminalConfig[]> = {
+  [K in T[number]["id"]]: WebTerminal;
+};
+
+export class VmWebTerminalInstance<
+  T extends WebTerminalConfig[]
+> extends VmWithInstance {
+  builder: VmWebTerminal<T>;
+
+  constructor(builder: VmWebTerminal<T>, resolvedTerminals: ResolvedTerminalConfig[]) {
+    super();
+    this.builder = builder;
+
+    // Create terminals as properties using resolved config
+    for (const config of resolvedTerminals) {
+      const terminal = new WebTerminal({
+        id: config.id,
+        port: config.port,
+        command: config.command,
+        instance: this,
+      });
+      (this as any)[config.id] = terminal;
+    }
+  }
+
+  /** @internal */
+  get _vm() {
+    return this.vm;
+  }
+}