freestyle-sandboxes 0.1.17 → 0.1.18

package/README.md

@@ -2,6 +2,102 @@
 
 Learn more at [docs.freestyle.sh](https://docs.freestyle.sh)
 
+## Installation
+
+```bash
+npm install freestyle-sandboxes
+```
+
+## CLI Usage
+
+The Freestyle SDK includes a command-line interface for managing your Freestyle resources.
+
+### Setup
+
+Set the environment variable with your API key:
+
+```bash
+export FREESTYLE_API_KEY="your-api-key"
+```
+
+Or create a `.env` file in your project directory:
+
+```
+FREESTYLE_API_KEY=your-api-key
+```
+
+### Commands
+
+#### Virtual Machines
+
+```bash
+# Create a new VM
+freestyle vm create --name my-vm
+
+# Create a VM from a snapshot (for debugging)
+freestyle vm create --snapshot <snapshot-id>
+
+# Create a VM with domain
+freestyle vm create --domain myapp.example.com --port 3000
+
+# Create VM and SSH into it (auto-deletes on exit)
+freestyle vm create --ssh
+
+# Create VM from snapshot and SSH into it
+freestyle vm create --snapshot <snapshot-id> --ssh
+
+# List all VMs
+freestyle vm list
+
+# SSH into a VM
+freestyle vm ssh <vmId>
+
+# SSH into a VM and delete it on exit
+freestyle vm ssh <vmId> --delete-on-exit
+
+# Execute a command on a VM
+freestyle vm exec <vmId> "ls -la"
+
+# Delete a VM
+freestyle vm delete <vmId>
+```
+
+#### Serverless Deployments
+
+```bash
+# Deploy from inline code
+freestyle deploy --code "export default () => 'Hello World'"
+
+# Deploy from a file
+freestyle deploy --file ./my-function.js
+
+# Deploy from a Git repository
+freestyle deploy --repo <repoId>
+
+# Add environment variables
+freestyle deploy --code "..." --env API_KEY=secret --env DEBUG=true
+```
+
+#### Serverless Runs
+
+```bash
+# Execute a one-off function from inline code
+freestyle run --code "console.log('Hello!')"
+
+# Execute from a file
+freestyle run --file ./script.js
+```
+
+#### Utilities
+
+```bash
+# Get help for any command
+freestyle --help
+freestyle vm --help
+```
+
+## SDK Usage
+
 ```ts
 import { freestyle } from "freestyle-sandboxes";
 

package/cli.mjs

@@ -0,0 +1,512 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { Freestyle, VmSpec } from './index.mjs';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as dotenv from 'dotenv';
+import { spawn } from 'child_process';
+
+function getFreestyleClient() {
+  const apiKey = process.env.FREESTYLE_API_KEY;
+  const baseUrl = process.env.FREESTYLE_API_URL;
+  if (!apiKey) {
+    console.error("Error: FREESTYLE_API_KEY environment variable is not set.");
+    console.error('Run "freestyle init" to set it up, or set it manually.');
+    process.exit(1);
+  }
+  return new Freestyle({ apiKey, baseUrl });
+}
+function handleError(error) {
+  if (error.response) {
+    console.error("API Error:", error.response.data);
+  } else if (error.message) {
+    console.error("Error:", error.message);
+  } else {
+    console.error("Error:", error);
+  }
+  process.exit(1);
+}
+function loadEnv() {
+  const envPath = path.join(process.cwd(), ".env");
+  if (fs.existsSync(envPath)) {
+    dotenv.config({ path: envPath });
+  }
+}
+function formatTable(headers, rows) {
+  const colWidths = headers.map((h, i) => {
+    const maxRowWidth = Math.max(...rows.map((r) => (r[i] || "").length));
+    return Math.max(h.length, maxRowWidth);
+  });
+  const headerRow = headers.map((h, i) => h.padEnd(colWidths[i])).join("  ");
+  const separator = colWidths.map((w) => "-".repeat(w)).join("  ");
+  console.log(headerRow);
+  console.log(separator);
+  rows.forEach((row) => {
+    console.log(row.map((cell, i) => (cell || "").padEnd(colWidths[i])).join("  "));
+  });
+}
+
+async function sshIntoVm(vmId, options = {}) {
+  const freestyle = getFreestyleClient();
+  console.log("Setting up SSH connection...");
+  const { identity, identityId } = await freestyle.identities.create();
+  console.log(`Created identity: ${identityId}`);
+  await identity.permissions.vms.grant({ vmId });
+  const { token, tokenId } = await identity.tokens.create();
+  const sshCommand = `ssh ${vmId}:${token}@vm-ssh.freestyle.sh -p 22`;
+  console.log(`Connecting to VM ${vmId}...`);
+  console.log(`Command: ${sshCommand}
+`);
+  return new Promise((resolve, reject) => {
+    const sshProcess = spawn(sshCommand, {
+      shell: true,
+      stdio: "inherit"
+    });
+    sshProcess.on("close", async (code) => {
+      console.log("\nSSH session ended.");
+      try {
+        console.log("Cleaning up identity and token...");
+        await identity.tokens.revoke({ tokenId });
+        await freestyle.identities.delete({ identityId });
+        console.log("\u2713 Cleanup complete");
+        if (options.deleteOnExit) {
+          console.log(`Deleting VM ${vmId}...`);
+          await freestyle.vms.delete({ vmId });
+          console.log("\u2713 VM deleted");
+        }
+        resolve();
+      } catch (error) {
+        console.error("Error during cleanup:", error);
+        reject(error);
+      }
+    });
+    sshProcess.on("error", (error) => {
+      console.error("Error starting SSH:", error);
+      reject(error);
+    });
+  });
+}
+const vmCommand = {
+  command: "vm <action>",
+  describe: "Manage Virtual Machines",
+  builder: (yargs) => {
+    return yargs.command(
+      "create",
+      "Create a new VM",
+      (yargs2) => {
+        return yargs2.option("name", {
+          alias: "n",
+          type: "string",
+          description: "VM name/discriminator"
+        }).option("domain", {
+          alias: "d",
+          type: "string",
+          description: "Custom domain to attach"
+        }).option("port", {
+          alias: "p",
+          type: "number",
+          description: "VM port to expose (default: 3000)",
+          default: 3e3
+        }).option("apt", {
+          type: "array",
+          description: "APT packages to install",
+          default: []
+        }).option("snapshot", {
+          alias: "s",
+          type: "string",
+          description: "Snapshot ID to create VM from"
+        }).option("exec", {
+          alias: "e",
+          type: "string",
+          description: "Execute a command on the VM after creation"
+        }).option("ssh", {
+          type: "boolean",
+          description: "SSH into VM after creation and delete VM on exit (for debugging)",
+          default: false
+        }).option("delete", {
+          type: "boolean",
+          description: "Delete VM after exec completes or when SSH session ends",
+          default: false
+        }).option("json", {
+          type: "boolean",
+          description: "Output as JSON",
+          default: false
+        });
+      },
+      async (argv) => {
+        loadEnv();
+        const args = argv;
+        try {
+          const freestyle = getFreestyleClient();
+          let createOptions = {};
+          if (args.snapshot) {
+            createOptions.snapshotId = args.snapshot;
+          } else {
+            const spec = new VmSpec({
+              discriminator: args.name,
+              aptDeps: args.apt
+            });
+            createOptions.snapshot = spec;
+          }
+          if (args.domain) {
+            createOptions.domains = [
+              {
+                domain: args.domain,
+                vmPort: args.port
+              }
+            ];
+          }
+          console.log("Creating VM...");
+          const result = await freestyle.vms.create(createOptions);
+          let execResult;
+          if (args.exec) {
+            const vm = freestyle.vms.ref({ vmId: result.vmId });
+            console.log(`Executing command on VM ${result.vmId}...`);
+            execResult = await vm.exec({
+              command: args.exec
+            });
+          }
+          if (args.json && !args.ssh) {
+            if (execResult) {
+              console.log(
+                JSON.stringify(
+                  {
+                    vm: result,
+                    exec: execResult
+                  },
+                  null,
+                  2
+                )
+              );
+            } else {
+              console.log(JSON.stringify(result, null, 2));
+            }
+          } else {
+            console.log("\n\u2713 VM created successfully!");
+            console.log(`  VM ID: ${result.vmId}`);
+            const domainStr = result.domains?.[0];
+            if (domainStr) {
+              console.log(`  Domain: https://${domainStr}`);
+            }
+            if (execResult) {
+              if (execResult.stdout) {
+                console.log("\nExec output:");
+                console.log(execResult.stdout);
+              }
+              if (execResult.stderr) {
+                console.error("\nExec errors:");
+                console.error(execResult.stderr);
+              }
+              console.log(`
+Exec exit code: ${execResult.statusCode || 0}`);
+            }
+          }
+          if (args.ssh) {
+            console.log("");
+            await sshIntoVm(result.vmId, { deleteOnExit: args.delete });
+          } else if (args.delete) {
+            console.log(`Deleting VM ${result.vmId}...`);
+            await freestyle.vms.delete({ vmId: result.vmId });
+            console.log("\u2713 VM deleted");
+          }
+        } catch (error) {
+          handleError(error);
+        }
+      }
+    ).command(
+      "list",
+      "List all VMs",
+      (yargs2) => {
+        return yargs2.option("json", {
+          type: "boolean",
+          description: "Output as JSON",
+          default: false
+        });
+      },
+      async (argv) => {
+        loadEnv();
+        const args = argv;
+        try {
+          const freestyle = getFreestyleClient();
+          const vms = await freestyle.vms.list();
+          if (args.json) {
+            console.log(JSON.stringify(vms, null, 2));
+          } else {
+            if (vms.vms.length === 0) {
+              console.log("No VMs found.");
+              return;
+            }
+            const rows = vms.vms.map((vm) => [
+              vm.id,
+              vm.state || "unknown",
+              vm.createdAt ? new Date(vm.createdAt).toLocaleString() : "N/A"
+            ]);
+            formatTable(["VM ID", "Status", "Created"], rows);
+          }
+        } catch (error) {
+          handleError(error);
+        }
+      }
+    ).command(
+      "ssh <vmId>",
+      "SSH into a VM",
+      (yargs2) => {
+        return yargs2.positional("vmId", {
+          type: "string",
+          description: "VM ID to SSH into",
+          demandOption: true
+        }).option("delete", {
+          type: "boolean",
+          description: "Delete VM when SSH session ends",
+          default: false
+        });
+      },
+      async (argv) => {
+        loadEnv();
+        const args = argv;
+        try {
+          await sshIntoVm(args.vmId, {
+            deleteOnExit: args.delete
+          });
+        } catch (error) {
+          handleError(error);
+        }
+      }
+    ).command(
+      "exec <vmId> <command>",
+      "Execute a command on a VM",
+      (yargs2) => {
+        return yargs2.positional("vmId", {
+          type: "string",
+          description: "VM ID",
+          demandOption: true
+        }).positional("command", {
+          type: "string",
+          description: "Command to execute",
+          demandOption: true
+        }).option("json", {
+          type: "boolean",
+          description: "Output as JSON",
+          default: false
+        });
+      },
+      async (argv) => {
+        loadEnv();
+        const args = argv;
+        try {
+          const freestyle = getFreestyleClient();
+          const vm = freestyle.vms.ref({ vmId: args.vmId });
+          console.log(`Executing command on VM ${args.vmId}...`);
+          const result = await vm.exec({
+            command: args.command
+          });
+          if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+          } else {
+            if (result.stdout) {
+              console.log("\nOutput:");
+              console.log(result.stdout);
+            }
+            if (result.stderr) {
+              console.error("\nErrors:");
+              console.error(result.stderr);
+            }
+            console.log(`
+Exit code: ${result.statusCode || 0}`);
+          }
+        } catch (error) {
+          handleError(error);
+        }
+      }
+    ).command(
+      "delete <vmId>",
+      "Delete a VM",
+      (yargs2) => {
+        return yargs2.positional("vmId", {
+          type: "string",
+          description: "VM ID to delete",
+          demandOption: true
+        });
+      },
+      async (argv) => {
+        loadEnv();
+        const args = argv;
+        try {
+          const freestyle = getFreestyleClient();
+          console.log(`Deleting VM ${args.vmId}...`);
+          await freestyle.vms.delete({ vmId: args.vmId });
+          console.log("\u2713 VM deleted successfully!");
+        } catch (error) {
+          handleError(error);
+        }
+      }
+    ).demandCommand(1, "You need to specify a vm action");
+  },
+  handler: () => {
+  }
+};
+
+const deployCommand = {
+  command: "deploy",
+  describe: "Deploy a serverless function",
+  builder: (yargs) => {
+    return yargs.option("code", {
+      alias: "c",
+      type: "string",
+      description: "Inline code to deploy"
+    }).option("file", {
+      alias: "f",
+      type: "string",
+      description: "File path containing code to deploy"
+    }).option("repo", {
+      alias: "r",
+      type: "string",
+      description: "Git repository ID to deploy"
+    }).option("env", {
+      alias: "e",
+      type: "array",
+      description: "Environment variables (KEY=VALUE)",
+      default: []
+    }).option("json", {
+      type: "boolean",
+      description: "Output as JSON",
+      default: false
+    }).check((argv) => {
+      const hasCode = !!argv.code;
+      const hasFile = !!argv.file;
+      const hasRepo = !!argv.repo;
+      if (!hasCode && !hasFile && !hasRepo) {
+        throw new Error(
+          "You must specify one of --code, --file, or --repo"
+        );
+      }
+      if ([hasCode, hasFile, hasRepo].filter(Boolean).length > 1) {
+        throw new Error(
+          "You can only specify one of --code, --file, or --repo"
+        );
+      }
+      return true;
+    });
+  },
+  handler: async (argv) => {
+    loadEnv();
+    const args = argv;
+    try {
+      const freestyle = getFreestyleClient();
+      let code;
+      let repo;
+      if (args.code) {
+        code = args.code;
+      } else if (args.file) {
+        code = fs.readFileSync(args.file, "utf-8");
+      } else if (args.repo) {
+        repo = args.repo;
+      }
+      const env = {};
+      if (args.env) {
+        for (const envVar of args.env) {
+          const [key, ...valueParts] = envVar.split("=");
+          if (key) {
+            env[key] = valueParts.join("=");
+          }
+        }
+      }
+      console.log("Creating deployment...");
+      const result = await freestyle.serverless.deployments.create({
+        ...code ? { code } : {},
+        ...repo ? { repo } : {},
+        env: Object.keys(env).length > 0 ? env : void 0
+      });
+      if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log("\n\u2713 Deployment created successfully!");
+        console.log(`  Deployment ID: ${result.deploymentId}`);
+        if (result.url) {
+          console.log(`  URL: ${result.url}`);
+        }
+      }
+    } catch (error) {
+      handleError(error);
+    }
+  }
+};
+
+const runCommand = {
+  command: "run",
+  describe: "Execute a one-off serverless function",
+  builder: (yargs) => {
+    return yargs.option("code", {
+      alias: "c",
+      type: "string",
+      description: "Inline code to execute"
+    }).option("file", {
+      alias: "f",
+      type: "string",
+      description: "File path containing code to execute"
+    }).option("env", {
+      alias: "e",
+      type: "array",
+      description: "Environment variables (KEY=VALUE)",
+      default: []
+    }).option("json", {
+      type: "boolean",
+      description: "Output as JSON",
+      default: false
+    }).check((argv) => {
+      const hasCode = !!argv.code;
+      const hasFile = !!argv.file;
+      if (!hasCode && !hasFile) {
+        throw new Error("You must specify either --code or --file");
+      }
+      if (hasCode && hasFile) {
+        throw new Error("You can only specify one of --code or --file");
+      }
+      return true;
+    });
+  },
+  handler: async (argv) => {
+    loadEnv();
+    const args = argv;
+    try {
+      const freestyle = getFreestyleClient();
+      let code;
+      if (args.code) {
+        code = args.code;
+      } else if (args.file) {
+        code = fs.readFileSync(args.file, "utf-8");
+      } else {
+        throw new Error("Code is required");
+      }
+      const env = {};
+      if (args.env) {
+        for (const envVar of args.env) {
+          const [key, ...valueParts] = envVar.split("=");
+          if (key) {
+            env[key] = valueParts.join("=");
+          }
+        }
+      }
+      console.log("Executing serverless function...");
+      const result = await freestyle.serverless.runs.create({
+        code,
+        env: Object.keys(env).length > 0 ? env : void 0
+      });
+      if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log("\n\u2713 Function executed successfully!");
+        console.log(`  Run ID: ${result.runId}`);
+        if (result.output) {
+          console.log(`  Output: ${result.output}`);
+        }
+      }
+    } catch (error) {
+      handleError(error);
+    }
+  }
+};
+
+yargs(hideBin(process.argv)).scriptName("freestyle").usage("$0 <command> [options]").command(vmCommand).command(deployCommand).command(runCommand).demandCommand(1, "You need to specify a command").help().alias("help", "h").version().alias("version", "v").strict().parse();