@rigkit/provider-freestyle 0.1.8

package/README.md

@@ -0,0 +1,10 @@
+# @rigkit/provider-freestyle
+
+Freestyle provider integration for `rig`.
+
+This package supplies:
+
+- `freestyle.provider(...)` for Freestyle VM/snapshot workflow tasks
+- `freestyle.terminal()` for provider-owned browser terminal sessions targeting Freestyle VMs
+- `createFreestyleProvider(...)` for low-level Freestyle VM operations
+- Freestyle-specific JSON state helpers backed by the Rigkit-owned provider storage table

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@rigkit/provider-freestyle",
+  "version": "0.1.8",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freestyle-sh/rigkit.git",
+    "directory": "packages/provider-freestyle"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "freestyle": "latest",
+    "zod": "^4",
+    "@rigkit/sdk": "0.1.8",
+    "@rigkit/engine": "0.1.8"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,24 @@
+declare const freestyleIdentityIdBrand: unique symbol;
+declare const freestyleTokenIdBrand: unique symbol;
+declare const freestyleTokenBrand: unique symbol;
+
+export type FreestyleIdentityId = string & { readonly [freestyleIdentityIdBrand]: true };
+export type FreestyleTokenId = string & { readonly [freestyleTokenIdBrand]: true };
+export type FreestyleToken = string & { readonly [freestyleTokenBrand]: true };
+
+export function freestyleIdentityId(value: string): FreestyleIdentityId {
+  return nonEmpty(value, "Freestyle identity id") as FreestyleIdentityId;
+}
+
+export function freestyleTokenId(value: string): FreestyleTokenId {
+  return nonEmpty(value, "Freestyle token id") as FreestyleTokenId;
+}
+
+export function freestyleToken(value: string): FreestyleToken {
+  return nonEmpty(value, "Freestyle token") as FreestyleToken;
+}
+
+function nonEmpty(value: string, label: string): string {
+  if (!value) throw new Error(`${label} must be a non-empty string`);
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,166 @@
+import {
+  defineProvider,
+  type WorkflowProviderDefinition,
+} from "@rigkit/sdk";
+import type { BaseProviderPlugin } from "@rigkit/engine";
+import type { WorkflowProviderController } from "@rigkit/engine";
+import { Freestyle } from "freestyle";
+import * as z from "zod/v4-mini";
+import { freestyleIdentityId, freestyleToken, freestyleTokenId } from "./auth.ts";
+import {
+  FREESTYLE_PROVIDER_ID,
+  FREESTYLE_TERMINAL_PROVIDER_ID,
+  createFreestyleTerminalController,
+  createFreestyleWorkflowProvider,
+  isFreestyleVmSnapshotRef,
+} from "./provider.ts";
+import type { FreestyleRuntime, FreestyleTerminalRuntime, FreestyleWorkspaceContext } from "./provider.ts";
+import { createFreestyleStore } from "./store.ts";
+
+const freestyleProviderConfigSchema = z.object({
+  apiKey: z.string().check(z.minLength(1)),
+  image: z.string().check(z.minLength(1)),
+  cpu: z.optional(z.number()),
+  memory: z.optional(z.union([z.string(), z.number()])),
+  disk: z.optional(z.union([z.string(), z.number()])),
+  idleTimeoutSeconds: z.optional(z.nullable(z.number())),
+});
+
+export type FreestyleProviderConfig = z.output<typeof freestyleProviderConfigSchema>;
+
+export type FreestyleProviderDefinition = WorkflowProviderDefinition<
+  typeof FREESTYLE_PROVIDER_ID,
+  FreestyleProviderConfig,
+  FreestyleRuntime,
+  FreestyleWorkspaceContext
+>;
+
+export type FreestyleTerminalProviderDefinition = WorkflowProviderDefinition<
+  typeof FREESTYLE_TERMINAL_PROVIDER_ID,
+  {},
+  FreestyleTerminalRuntime
+>;
+
+export function provider(
+  config: FreestyleProviderDefinition["config"],
+): FreestyleProviderDefinition {
+  return defineProvider(FREESTYLE_PROVIDER_ID, config, freestyleProviderPlugin);
+}
+
+export function terminal(): FreestyleTerminalProviderDefinition {
+  return defineProvider(FREESTYLE_TERMINAL_PROVIDER_ID, {}, freestyleTerminalPlugin);
+}
+
+export const freestyle = {
+  provider,
+  terminal,
+};
+
+export const defineFreestyleProvider = provider;
+
+export const freestyleProviderPlugin: BaseProviderPlugin = {
+  providerId: FREESTYLE_PROVIDER_ID,
+  createProvider({ provider, storage }) {
+    const config = parseFreestyleProviderConfig(provider.config);
+    const { apiKey, ...vm } = config;
+    let controller: Promise<WorkflowProviderController<FreestyleRuntime, FreestyleWorkspaceContext>> | undefined;
+
+    const load = async () => {
+      controller ??= create();
+      return await controller;
+    };
+
+    const create = async () => {
+      const store = createFreestyleStore(storage);
+      const savedIdentity = store.getIdentity();
+      if (savedIdentity) {
+        return createFreestyleWorkflowProvider({
+          apiKey,
+          identityId: savedIdentity.identityId,
+          token: savedIdentity.token,
+          vm,
+        });
+      }
+
+      const client = new Freestyle({ apiKey });
+      const { identity, identityId } = await client.identities.create();
+      const { token, tokenId } = await identity.tokens.create();
+      const createdIdentity = store.saveIdentity({
+        identityId: freestyleIdentityId(identityId),
+        tokenId: freestyleTokenId(tokenId),
+        token: freestyleToken(token),
+      });
+
+      return createFreestyleWorkflowProvider({
+        apiKey,
+        identityId: createdIdentity.identityId,
+        token: createdIdentity.token,
+        vm,
+      });
+    };
+
+    return {
+      providerId: FREESTYLE_PROVIDER_ID,
+      runtime: async (context) => await (await load()).runtime(context),
+      validateArtifact: (ref) => isFreestyleVmSnapshotRef(ref),
+      workspace: {
+        canUse: (ref) => isFreestyleVmSnapshotRef(ref),
+        createWorkspace: async (sourceRef, input) =>
+          await (await load()).workspace!.createWorkspace(sourceRef, input),
+        deleteWorkspace: async (workspace) =>
+          await (await load()).workspace!.deleteWorkspace(workspace),
+        snapshotWorkspace: async (workspace) =>
+          await (await load()).workspace!.snapshotWorkspace(workspace),
+        ssh: async (workspaceOrResourceId, options) =>
+          await (await load()).workspace!.ssh(workspaceOrResourceId, options),
+        workspaceContext: async (workspace) =>
+          await (await load()).workspace!.workspaceContext!(workspace),
+      },
+    } satisfies WorkflowProviderController<FreestyleRuntime, FreestyleWorkspaceContext>;
+  },
+};
+
+export const freestyleTerminalPlugin: BaseProviderPlugin = {
+  providerId: FREESTYLE_TERMINAL_PROVIDER_ID,
+  createProvider() {
+    return createFreestyleTerminalController();
+  },
+};
+
+export {
+  freestyleIdentityId,
+  freestyleToken,
+  freestyleTokenId,
+  type FreestyleIdentityId,
+  type FreestyleToken,
+  type FreestyleTokenId,
+} from "./auth.ts";
+export {
+  FREESTYLE_PROVIDER_ID,
+  FREESTYLE_TERMINAL_PROVIDER_ID,
+  createFreestyleProvider,
+  createFreestyleTerminalController,
+  createFreestyleWorkflowController,
+  createFreestyleWorkflowProvider,
+  isFreestyleVmSnapshotRef,
+} from "./provider.ts";
+export { createFreestyleStore } from "./store.ts";
+export { createFreestyleTerminalSession } from "./terminal-session.ts";
+export { RIGKIT_PROVIDER_FREESTYLE_VERSION } from "./version.ts";
+export type {
+  FreestyleRuntime,
+  FreestyleTerminalRuntime,
+  FreestyleVmConfig,
+  FreestyleVmRuntime,
+  FreestyleVmSnapshotRef,
+  FreestyleWorkspaceContext,
+} from "./provider.ts";
+export type { FreestyleGitRelationship, FreestyleIdentity } from "./store.ts";
+
+function parseFreestyleProviderConfig(value: unknown): FreestyleProviderConfig {
+  const result = z.safeParse(freestyleProviderConfigSchema, value);
+  if (!result.success) {
+    throw new Error(`Invalid Freestyle provider config:\n${z.prettifyError(result.error)}`);
+  }
+  return result.data;
+}

package/src/provider.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import type { ExecOptions, ExecOutputChunk, ExecResult } from "@rigkit/sdk";
+import type {
+  BaseDevMachineProvider,
+  ProviderRuntimeContext,
+  SshConnection,
+  VmHandle,
+  WorkflowEvent,
+} from "@rigkit/engine";
+import { createFreestyleWorkflowController, wrapCommand } from "./provider.ts";
+import type { FreestyleWorkspaceContext } from "./provider.ts";
+
+describe("Freestyle provider command wrapper", () => {
+  test("sets a root HOME fallback for exec commands", () => {
+    expect(wrapCommand("printf '%s\n' \"$HOME\"")).toContain("export HOME=${HOME:-/root}");
+  });
+
+  test("allows callers to override HOME explicitly", () => {
+    const wrapped = wrapCommand("pwd", {
+      env: { HOME: "/workspace/home" },
+    });
+
+    expect(wrapped).toContain("export HOME=${HOME:-/root}");
+    expect(wrapped).toContain("export HOME='\\''/workspace/home'\\''");
+  });
+
+  test("streams VM command output through run events without replaying buffered output", async () => {
+    const chunks: ExecOutputChunk[] = [];
+    const events: WorkflowEvent[] = [];
+    const provider = new StreamingProvider();
+    const controller = createFreestyleWorkflowController(provider);
+    const runtime = await controller.runtime(providerContext(events));
+    const vm = runtime.vms.fromWorkspace({ resourceId: "vm-stream" });
+
+    const result = await vm.exec("printf ready", {
+      name: "stream command",
+      onOutput: (chunk) => {
+        chunks.push(chunk);
+      },
+    });
+
+    expect(result.stdout).toBe("ready\n");
+    expect(chunks).toEqual([{ stream: "stdout", data: "ready\n" }]);
+    expect(events).toEqual([
+      {
+        type: "command.started",
+        nodePath: "workflow.step",
+        commandName: "stream command",
+        command: "printf ready",
+      },
+      {
+        type: "command.output",
+        nodePath: "workflow.step",
+        commandName: "stream command",
+        stream: "stdout",
+        data: "ready\n",
+      },
+      {
+        type: "command.completed",
+        nodePath: "workflow.step",
+        commandName: "stream command",
+        exitCode: 0,
+      },
+    ]);
+  });
+});
+
+const sshConnection: SshConnection = {
+  kind: "ssh",
+  host: "localhost",
+  username: "root",
+  auth: { type: "token", token: "token" },
+  command: "ssh vm-stream",
+};
+
+class StreamingProvider implements BaseDevMachineProvider<FreestyleWorkspaceContext> {
+  readonly providerId = "freestyle";
+
+  async createVm(): Promise<VmHandle> {
+    return { vmId: "vm-stream" };
+  }
+
+  async createVmFromSnapshot(): Promise<VmHandle> {
+    return { vmId: "vm-stream" };
+  }
+
+  async exec(_vm: VmHandle, _command: string, options?: ExecOptions): Promise<ExecResult> {
+    await options?.onOutput?.({ stream: "stdout", data: "ready\n" });
+    return { stdout: "ready\n", stderr: "", exitCode: 0, ok: true };
+  }
+
+  async readFile(): Promise<string> {
+    return "";
+  }
+
+  async writeFile(): Promise<void> {}
+
+  async snapshot(): Promise<{ snapshotId: string; sourceVmId: string }> {
+    return { snapshotId: "snap-stream", sourceVmId: "vm-stream" };
+  }
+
+  async ssh(): Promise<SshConnection> {
+    return sshConnection;
+  }
+
+  async workspaceContext(): Promise<FreestyleWorkspaceContext> {
+    return {
+      ssh: sshConnection,
+      host: sshConnection.host,
+      username: sshConnection.username,
+      vscodeAuthority: "root@localhost",
+    };
+  }
+
+  async deleteVm(): Promise<void> {}
+}
+
+function providerContext(events: WorkflowEvent[]): ProviderRuntimeContext {
+  return {
+    workflow: "workflow",
+    nodePath: "workflow.step",
+    emit: (event) => {
+      events.push(event);
+    },
+    interaction: {
+      present: async () => {
+        throw new Error("unexpected interaction");
+      },
+    },
+    local: {
+      open: async () => {},
+    },
+    metadata: () => {},
+  };
+}