bsdkrun 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e78b89f68872f94abe500dba9bc0d69bd2b8ff0488745bb1f7e07ef2658f8a28
-  data.tar.gz: 1effefa03711b90030219d9456edbb6df361591184aa9bb7f01c06e87ad582e2
+  metadata.gz: 86e468aea9e96825db542d4c5e9ddf2fbbc473ddfb4e4b7edfa8ecac48abd685
+  data.tar.gz: 86f792adb80c6218763193a256b16c4f307e68063a494718277e4e4b94d3c0b1
 SHA512:
-  metadata.gz: ce3f123068f4c08775e7308513b727182ece1ce14737de2cc874ed050be8e19979e82c902703202f72a162222d0b12363a6aefc5b9441eeab34038976ed28a1c
-  data.tar.gz: 8eb660e5db46bf1fc617b250f76c55f41f75943f2bc71026994790e812c000ae90aa63384956938e7a5bda406d8f59912ab36ac7f5a5029a615738a1ccb4dca3
+  metadata.gz: e948aea05cab5bffabb28a50a0fb8df66500ab6b6ead6fe0e8a3ff9f07d981f84f19deac1f775e7c4a7665dd037a711d2c6aba19fb15ee4d1cdb7903f8293c40
+  data.tar.gz: 56d75e614b8f78319079302e61cc257cd30a3229e27384d09e6412c9bcb58459a6519d6df4e17a608a0b0fc18e92569e4510fea063bc849b13e60af3a723cea8

data/README.md

@@ -300,6 +300,37 @@ the new machine's id. `run_solo5` boots a MirageOS unikernel under the
 `stop`/`start`/`remove`/`update`/`commit` return a
 `CommandResult` (`exit_code`, `stdout`, `stderr`).
 
+### Snapshots
+
+A snapshot is a **copy-on-write clone of a machine's disk state** — instant to
+take, free until the two sides diverge. `branch` boots a new machine from one
+(or from a machine, which is snapshotted first); `restore`/`rollback` put one
+back, leaving the machine stopped. A BSD guest is powered off to snapshot it:
+a mounted UFS cannot be cloned consistently.
+
+```ruby
+snap = client.snapshot(machine_id, name: "before-upgrade")
+client.snapshots(machine: machine_id)      # newest first
+branch_id = client.branch(snap.name, name: "web-test")
+client.restore(machine_id, snap.name)      # or client.rollback(machine_id)
+client.remove_snapshots(snap.name)
+```
+
+### Docker
+
+bsdkrun runs one `docker:dind` microVM and serves its API on a host unix
+socket, so the host's own `docker` CLI drives the same engine these calls do.
+Starting is idempotent — the VM has a fixed name, so it resumes rather than
+creating a second.
+
+```ruby
+status = client.docker_start(cpus: 4, mem: 4096)   # or just docker_status
+puts status.socket
+client.docker_containers.each { |c| puts "#{c.name} #{c.state} #{c.ports}" }
+client.docker_container("restart", "web")
+puts client.docker_logs("web", tail: 50)
+```
+
 For a live terminal instead of a one-shot `exec`, use `shell`:
 
 ```ruby

data/lib/bsdkrun/ci.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+
+module Bsdkrun
+  # CI workflows defined in code instead of YAML.
+  #
+  # The builder produces exactly the file +bsdkrun ci+ (and tangled's spindle)
+  # consumes — {CIWorkflow#yaml} is that file, {CIWorkflow#save} commits it to
+  # +.tangled/workflows/+, and {CIWorkflow#run} executes it in a microVM
+  # without a file ever touching the repository:
+  #
+  #   Bsdkrun.workflow("test")
+  #     .on_push("main")
+  #     .deps("ruby", "bundler")
+  #     .env("CI_FROM", "sdk")
+  #     .step("install", "bundle install")
+  #     .step("test", "bundle exec rspec")
+  #     .run
+  #
+  # Code is the source of truth and YAML the wire format, in that order —
+  # which is why +save+ writes a generated-file header: a hand-edit there will
+  # be overwritten by the next +save+.
+  class CIWorkflow
+    def initialize(name)
+      @name = name
+      @engine = "nixery"
+      @when = []
+      @deps = {}
+      @env = {}
+      @steps = []
+      @clone_depth = nil
+      @clone_skip = false
+    end
+
+    # Override the engine (+nixery+ by default).
+    def engine(engine)
+      @engine = engine
+      self
+    end
+
+    # Add a push trigger for the given branches.
+    def on_push(*branches)
+      @when << [["push"], branches]
+      self
+    end
+
+    # Add a pull_request trigger targeting the given branches.
+    def on_pull_request(*branches)
+      @when << [["pull_request"], branches]
+      self
+    end
+
+    # Add a trigger with explicit events.
+    def on(events, *branches)
+      @when << [events, branches]
+      self
+    end
+
+    # Add nixpkgs dependencies — the toolchain the steps run against.
+    def deps(*packages)
+      (@deps["nixpkgs"] ||= []).concat(packages)
+      self
+    end
+
+    # Add dependencies from a custom registry (a flake reference).
+    def deps_from(registry, *packages)
+      (@deps[registry] ||= []).concat(packages)
+      self
+    end
+
+    # Set a workflow-level environment variable.
+    def env(key, value)
+      @env[key] = value
+      self
+    end
+
+    # Append a step; steps run serially in one VM, from the workspace root.
+    def step(name, command, env: nil)
+      @steps << { name: name, command: command, env: env || {} }
+      self
+    end
+
+    # Set the clone depth (default 1).
+    def clone_depth(depth)
+      @clone_depth = depth
+      self
+    end
+
+    # Skip the checkout entirely.
+    def skip_clone
+      @clone_skip = true
+      self
+    end
+
+    # The workflow file name {#save} writes: +<name>.yml+.
+    def file_name
+      @name.match?(/\.ya?ml\z/) ? @name : "#{@name}.yml"
+    end
+
+    # Render the workflow file. Scalars are emitted as JSON strings — valid
+    # YAML by construction — and commands as literal blocks when safe, so the
+    # SDK needs no YAML dependency.
+    def yaml
+      out = []
+      q = ->(s) { JSON.generate(s) }
+
+      unless @when.empty?
+        out << "when:"
+        @when.each do |events, branches|
+          out << "  - event: [#{events.map(&q).join(', ')}]"
+          if branches.length == 1
+            out << "    branch: #{q.call(branches[0])}"
+          elsif branches.length > 1
+            out << "    branch: [#{branches.map(&q).join(', ')}]"
+          end
+        end
+        out << ""
+      end
+
+      out << "engine: #{@engine}"
+
+      unless @deps.empty?
+        out << "" << "dependencies:"
+        @deps.keys.sort.each do |reg|
+          out << "  #{q.call(reg)}:"
+          @deps[reg].each { |p| out << "    - #{q.call(p)}" }
+        end
+      end
+
+      unless @env.empty?
+        out << "" << "environment:"
+        @env.keys.sort.each { |k| out << "  #{k}: #{q.call(@env[k])}" }
+      end
+
+      if @clone_skip || @clone_depth
+        out << "" << "clone:"
+        out << "  skip: true" if @clone_skip
+        out << "  depth: #{@clone_depth}" if @clone_depth
+      end
+
+      out << "" << "steps:"
+      @steps.each do |s|
+        out << "  - name: #{q.call(s[:name])}"
+        # Literal blocks read well in a committed file, but cannot carry
+        # trailing spaces or carriage returns byte-for-byte; fall back to a
+        # JSON string rather than silently altering the command.
+        block_safe = !s[:command].empty? &&
+                     !s[:command].include?("\r") &&
+                     s[:command].split("\n", -1).all? { |l| l == l.sub(/ +\z/, "") }
+        if block_safe
+          out << "    command: |"
+          s[:command].sub(/\n+\z/, "").split("\n", -1).each { |l| out << "      #{l}" }
+        else
+          out << "    command: #{q.call(s[:command])}"
+        end
+        next if s[:env].empty?
+
+        out << "    environment:"
+        s[:env].keys.sort.each { |k| out << "      #{k}: #{q.call(s[:env][k])}" }
+      end
+      "#{out.join("\n")}\n"
+    end
+
+    # Write into +<repo>/.tangled/workflows/+ and return the path.
+    def save(repo)
+      dir = File.join(repo, ".tangled", "workflows")
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, file_name)
+      File.write(
+        path,
+        "# Generated by the bsdkrun SDK — edit the code that save()d it instead.\n#{yaml}"
+      )
+      path
+    end
+
+    # Execute the workflow in a microVM, streaming output. The YAML never
+    # touches the repository — it goes to a temp file and +bsdkrun ci run -f+.
+    # Raises {CommandFailed} when a step fails.
+    def run(dir: nil)
+      Dir.mktmpdir("bsdkrun-ci-") do |tmp|
+        file = File.join(tmp, file_name)
+        File.write(file, yaml)
+        args = ["ci", "run", "-f", file]
+        args += ["-w", dir] if dir
+        ok = Process.spawn_interactive(args)
+        unless ok
+          raise CommandFailed.new(
+            exit_code: 1, stdout: "", stderr: "workflow #{@name} failed",
+            command: "bsdkrun ci run"
+          )
+        end
+      end
+      nil
+    end
+  end
+
+  # Start a CI workflow definition.
+  def self.workflow(name)
+    CIWorkflow.new(name)
+  end
+end

data/lib/bsdkrun/client.rb

@@ -35,10 +35,16 @@ module Bsdkrun
     # +web/src/lib/api.ts+'s +MACHINE_FIELDS+ fragment exactly.
     MACHINE_FIELDS = <<~GQL.freeze
       id name image kind command status running exitCode pid detached
-      cpus mem volume stateDir createdAt finishedAt network netIp
+      cpus mem volume stateDir createdAt finishedAt network netIp origin
       ports { bind host guest }
     GQL
 
+    # The +Snapshot+ selection, likewise shared by every snapshot document.
+    SNAPSHOT_FIELDS = <<~GQL.freeze
+      id name machineId machineName kind image path parent description
+      cpus mem size createdAt ports { bind host guest }
+    GQL
+
     # @return [String] the GraphQL endpoint URL (normalized).
     attr_reader :url
 
@@ -242,6 +248,269 @@ module Bsdkrun
       )
     end
 
+    # ---- ai agents -------------------------------------------------------------
+    #
+    # A sandbox is a machine, so its terminal is the ordinary {#shell} with the
+    # argv {#ai_shell_command} returns.
+
+    AI_AGENT_FIELDS = "id label flavor description installed running"
+    AI_SESSION_FIELDS = "id name agent running workspace createdAt"
+
+    # The coding agents, and whether each one's sandbox image is built.
+    # @return [Array<AiAgent>]
+    def ai_agents
+      data = request("{ aiAgents { #{AI_AGENT_FIELDS} } }")
+      (data["aiAgents"] || []).map { |a| AiAgent.from_graphql(a) }
+    end
+
+    # Agent sandboxes, newest first.
+    # @return [Array<AiSession>]
+    def ai_sessions
+      data = request("{ aiSessions { #{AI_SESSION_FIELDS} } }")
+      (data["aiSessions"] || []).map { |s| AiSession.from_graphql(s) }
+    end
+
+    # Start (or reuse) a sandbox; returns its machine id.
+    #
+    # @param agent [String] +claude+, +codex+, ...
+    # @param workspace [String, nil] a directory **on the engine's host**.
+    # @param new [Boolean] boot a second sandbox against the same saved login.
+    # @return [String]
+    def ai_start(agent, cpus: nil, mem: nil, workspace: nil, new: false)
+      data = request(
+        "mutation($input:AiStartInput!){ aiStart(input:$input) }",
+        { input: { agent: agent, cpus: cpus, mem: mem,
+                   workspace: workspace, new: new } }
+      )
+      data["aiStart"].to_s
+    end
+
+    # The argv that starts the agent's TUI — pass it to {#shell}.
+    # @return [Array<String>]
+    def ai_shell_command(agent, machine_id)
+      data = request(
+        "query($agent:String!,$machineId:String!){ " \
+        "aiShellCommand(agent:$agent, machineId:$machineId) }",
+        { agent: agent, machineId: machine_id }
+      )
+      Array(data["aiShellCommand"])
+    end
+
+    # Stop an agent's sandboxes. Its saved login survives.
+    # @return [CommandResult]
+    def ai_stop(agent)
+      run_command_mutation(
+        "aiStop",
+        "mutation($agent:String!){ aiStop(agent:$agent){ exitCode stdout stderr } }",
+        { agent: agent }
+      )
+    end
+
+    # Remove an agent's sandboxes, and unless +keep_home+ its saved login too.
+    # @return [CommandResult]
+    def ai_remove(agent, keep_home: false)
+      run_command_mutation(
+        "aiRemove",
+        "mutation($agent:String!,$keepHome:Boolean!){ " \
+        "aiRemove(agent:$agent, keepHome:$keepHome){ exitCode stdout stderr } }",
+        { agent: agent, keepHome: keep_home }
+      )
+    end
+
+    # ---- docker --------------------------------------------------------------
+    #
+    # bsdkrun runs one +docker:dind+ microVM and serves its API on a host unix
+    # socket, so these drive the same engine the host's +docker+ CLI does.
+
+    DOCKER_STATUS_FIELDS = <<~GQL.freeze
+      running machineId machineRunning socket socketReady apiPort version
+      containers images mounts disk diskSize
+    GQL
+
+    DOCKER_CONTAINER_FIELDS = "id name image command state status ports created"
+
+    # Is the Docker engine up, and where is its socket?
+    # @return [DockerStatus]
+    def docker_status
+      data = request("{ dockerStatus { #{DOCKER_STATUS_FIELDS} } }")
+      DockerStatus.from_graphql(data["dockerStatus"])
+    end
+
+    # Containers in the engine.
+    # @param all [Boolean] include stopped ones (default true).
+    # @return [Array<DockerContainer>]
+    def docker_containers(all: true)
+      data = request(
+        "query($all:Boolean!){ dockerContainers(all:$all){ #{DOCKER_CONTAINER_FIELDS} } }",
+        { all: all }
+      )
+      (data["dockerContainers"] || []).map { |c| DockerContainer.from_graphql(c) }
+    end
+
+    # Start (or resume) the engine, returning its status once it answers.
+    #
+    # Idempotent: the VM has a fixed name, so this resumes the existing one
+    # rather than creating a second.
+    #
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @param mounts [Array<String>] host dirs to share, +PATH+ or +HOST:GUEST+.
+    # @param no_home [Boolean] do not share +$HOME+ (shared by default).
+    # @param publish_bind [String, nil] +mirror+ (default) or a fixed address.
+    # @param disk_size [String, nil] a dedicated image store, e.g. +60G+.
+    # @return [DockerStatus]
+    def docker_start(cpus: nil, mem: nil, mounts: [], no_home: false,
+                     publish_bind: nil, disk_size: nil)
+      data = request(
+        "mutation($input:DockerStartInput!){ dockerStart(input:$input){ " \
+        "#{DOCKER_STATUS_FIELDS} } }",
+        { input: { cpus: cpus, mem: mem, mounts: Array(mounts), noHome: no_home,
+                   publishBind: publish_bind, diskSize: disk_size } }
+      )
+      DockerStatus.from_graphql(data["dockerStart"])
+    end
+
+    # Stop the engine. Images and containers stay on its disk.
+    # @return [CommandResult]
+    def docker_stop
+      run_command_mutation(
+        "dockerStop",
+        "mutation{ dockerStop{ exitCode stdout stderr } }",
+        {}
+      )
+    end
+
+    # start | stop | restart | kill | pause | unpause | rm.
+    # @param action [String]
+    # @param ids [String, Array<String>]
+    # @return [CommandResult]
+    def docker_container(action, ids)
+      run_command_mutation(
+        "dockerContainer",
+        "mutation($action:String!,$ids:[String!]!){ " \
+        "dockerContainer(action:$action, ids:$ids){ exitCode stdout stderr } }",
+        { action: action, ids: Array(ids) }
+      )
+    end
+
+    # One container's logs (stdout+stderr, most recent +tail+ lines).
+    # @param id [String]
+    # @param tail [Integer]
+    # @return [String]
+    def docker_logs(id, tail: 200)
+      data = request(
+        "query($id:String!,$tail:Int!){ dockerContainerLogs(id:$id, tail:$tail) }",
+        { id: id, tail: tail }
+      )
+      data["dockerContainerLogs"].to_s
+    end
+
+    # ---- snapshots ---------------------------------------------------------
+    #
+    # A snapshot is a copy-on-write clone of a machine's disk state: instant to
+    # take, free until the two sides diverge. {#branch} boots a new machine
+    # from one; {#restore}/{#rollback} put one back.
+
+    # List snapshots, newest first.
+    # @param machine [String, nil] only this machine's, when given.
+    # @return [Array<SnapshotInfo>]
+    def snapshots(machine: nil)
+      data = request(
+        "query($machine:String){ snapshots(machine:$machine){ #{SNAPSHOT_FIELDS} } }",
+        { machine: machine }
+      )
+      (data["snapshots"] || []).map { |s| SnapshotInfo.from_graphql(s) }
+    end
+
+    # Capture a machine's disk state.
+    #
+    # A BSD guest is powered off first — a mounted UFS cannot be cloned
+    # consistently — so the machine is left stopped; {#start} brings it back.
+    #
+    # @param id [String]
+    # @param name [String, nil] defaults to +<machine>-<n>+.
+    # @param description [String]
+    # @return [SnapshotInfo]
+    def snapshot(id, name: nil, description: "")
+      data = request(
+        "mutation($id:String!,$name:String,$description:String!){ " \
+        "snapshotMachine(id:$id, name:$name, description:$description){ #{SNAPSHOT_FIELDS} } }",
+        { id: id, name: name, description: description }
+      )
+      SnapshotInfo.from_graphql(data["snapshotMachine"])
+    end
+
+    # Delete snapshots and their data. Machines branched from them are
+    # unaffected.
+    # @param names [String, Array<String>]
+    # @return [CommandResult]
+    def remove_snapshots(names)
+      run_command_mutation(
+        "removeSnapshots",
+        "mutation($names:[String!]!){ removeSnapshots(names:$names){ exitCode stdout stderr } }",
+        { names: Array(names) }
+      )
+    end
+
+    # Put a machine's disk state back to one of its snapshots.
+    #
+    # +force+ stops the machine first (it holds the very files being
+    # replaced); +backup+ snapshots the state being overwritten, which is a
+    # CoW clone and therefore free. The machine is left stopped.
+    #
+    # @param id [String]
+    # @param snapshot [String]
+    # @param force [Boolean]
+    # @param backup [Boolean]
+    # @return [CommandResult]
+    def restore(id, snapshot, force: true, backup: true)
+      run_command_mutation(
+        "restoreMachine",
+        "mutation($id:String!,$snapshot:String!,$force:Boolean!,$backup:Boolean!){ " \
+        "restoreMachine(id:$id, snapshot:$snapshot, force:$force, backup:$backup){ " \
+        "exitCode stdout stderr } }",
+        { id: id, snapshot: snapshot, force: force, backup: backup }
+      )
+    end
+
+    # Restore a machine to its most recent snapshot.
+    # @param id [String]
+    # @param force [Boolean]
+    # @param backup [Boolean]
+    # @return [CommandResult]
+    def rollback(id, force: true, backup: true)
+      run_command_mutation(
+        "rollbackMachine",
+        "mutation($id:String!,$force:Boolean!,$backup:Boolean!){ " \
+        "rollbackMachine(id:$id, force:$force, backup:$backup){ exitCode stdout stderr } }",
+        { id: id, force: force, backup: backup }
+      )
+    end
+
+    # Boot a NEW machine from a snapshot — or from a machine, which is
+    # snapshotted first — and return the new machine's id.
+    #
+    # The state is cloned, never booted in place, so the source is untouched
+    # and one snapshot can be branched any number of times. With no +ports+,
+    # the snapshot's own forwards are inherited, with any host port that is
+    # already taken swapped for a free one.
+    #
+    # @param snapshot [String] snapshot name/id, or a machine id.
+    # @param name [String, nil]
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @param ports [Array<String>]
+    # @param no_ports [Boolean]
+    # @return [String] the new machine's id.
+    def branch(snapshot, name: nil, cpus: nil, mem: nil, ports: [], no_ports: false)
+      data = request(
+        "mutation($input:BranchInput!){ branchSnapshot(input:$input) }",
+        { input: { snapshot: snapshot, name: name, cpus: cpus, mem: mem,
+                   ports: Array(ports), noPorts: no_ports } }
+      )
+      data["branchSnapshot"].to_s
+    end
+
     # One-shot console log fetch. Use {#follow_logs} to stream instead.
     # @param id [String]
     # @param boot [Boolean] bsdkrun's own boot log instead of the guest console.

data/lib/bsdkrun/types.rb

@@ -34,7 +34,7 @@ module Bsdkrun
   SandboxInfo = Data.define(
     :id, :name, :image, :kind, :command, :status, :running, :exit_code,
     :pid, :detached, :cpus, :mem, :volume, :state_dir, :network, :net_ip,
-    :created_at, :finished_at, :ports
+    :created_at, :finished_at, :ports, :origin
   ) do
     # Map a +ps --json+ row (String keys) to a typed instance.
     # @param row [Hash]
@@ -60,7 +60,8 @@ module Bsdkrun
         net_ip: row["net_ip"],
         created_at: row["created_at"].to_i,
         finished_at: to_i_or_nil(row["finished_at"]),
-        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) }
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) },
+        origin: row["origin"]
       )
     end
 
@@ -96,11 +97,190 @@ module Bsdkrun
         net_ip: m["netIp"],
         created_at: m["createdAt"].to_i,
         finished_at: to_i_or_nil(m["finishedAt"]),
-        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) }
+        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) },
+        origin: m["origin"]
       )
     end
   end
 
+  # A machine snapshot: one machine's disk state, captured under a name.
+  #
+  # A copy-on-write clone rather than a memory image — the files the guest
+  # wrote, not what it was executing. {Bsdkrun::Client#branch} boots a new
+  # machine from one; {Bsdkrun::Client#restore} puts one back.
+  SnapshotInfo = Data.define(
+    :id, :name, :machine_id, :machine_name, :kind, :image, :path, :parent,
+    :description, :cpus, :mem, :ports, :size, :created_at
+  ) do
+    # Map a GraphQL +Snapshot+ (camelCase) to a typed instance.
+    # @param s [Hash]
+    # @return [SnapshotInfo]
+    def self.from_graphql(s)
+      new(
+        id: s["id"].to_s,
+        name: s["name"].to_s,
+        machine_id: s["machineId"].to_s,
+        machine_name: (s["machineName"] || "").to_s,
+        kind: s["kind"].to_s,
+        image: (s["image"] || "").to_s,
+        path: (s["path"] || "").to_s,
+        parent: s["parent"],
+        description: (s["description"] || "").to_s,
+        cpus: s["cpus"].to_i,
+        mem: s["mem"].to_i,
+        ports: (s["ports"] || []).map { |p| PortForward.from_row(p) },
+        size: s["size"],
+        created_at: s["createdAt"].to_i
+      )
+    end
+
+    # Map a +bsdkrun snapshots --json+ row (snake_case).
+    # @param row [Hash]
+    # @return [SnapshotInfo]
+    def self.from_row(row)
+      new(
+        id: row["id"].to_s,
+        name: row["name"].to_s,
+        machine_id: row["machine_id"].to_s,
+        machine_name: (row["machine_name"] || "").to_s,
+        kind: row["kind"].to_s,
+        image: (row["image"] || "").to_s,
+        path: (row["path"] || "").to_s,
+        parent: row["parent"],
+        description: (row["description"] || "").to_s,
+        cpus: row["cpus"].to_i,
+        mem: row["mem"].to_i,
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) },
+        size: row["size"],
+        created_at: row["created_at"].to_i
+      )
+    end
+  end
+
+  # A coding agent bsdkrun can sandbox.
+  #
+  # Each runs in a disposable microVM with a persistent login, a shared skills
+  # store, and only the folder you choose to share.
+  AiAgent = Data.define(
+    :id, :label, :flavor, :description, :installed, :running
+  ) do
+    # @param a [Hash]
+    # @return [AiAgent]
+    def self.from_graphql(a)
+      new(
+        id: a["id"].to_s,
+        label: a["label"].to_s,
+        flavor: a["flavor"].to_s,
+        description: (a["description"] || "").to_s,
+        installed: !!a["installed"],
+        running: a["running"].to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
+  # One agent sandbox. It is a machine, so +logs+/+stop+ work on +id+.
+  AiSession = Data.define(
+    :id, :name, :agent, :running, :workspace, :created_at
+  ) do
+    # @param s [Hash]
+    # @return [AiSession]
+    def self.from_graphql(s)
+      new(
+        id: s["id"].to_s,
+        name: s["name"].to_s,
+        agent: s["agent"].to_s,
+        running: !!s["running"],
+        workspace: s["workspace"],
+        created_at: (s["createdAt"] || s["created_at"]).to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
+  # The Docker engine VM: whether it is up, and how to reach it.
+  #
+  # bsdkrun runs one +docker:dind+ microVM and serves its API on a host unix
+  # socket, so the host's own +docker+ CLI drives the same engine.
+  DockerStatus = Data.define(
+    :running, :machine_id, :machine_running, :socket, :socket_ready, :api_port,
+    :version, :containers, :images, :mounts, :disk, :disk_size
+  ) do
+    # @param s [Hash] a GraphQL +DockerStatus+ (camelCase).
+    # @return [DockerStatus]
+    def self.from_graphql(s)
+      new(
+        running: !!s["running"],
+        machine_id: s["machineId"],
+        machine_running: !!s["machineRunning"],
+        socket: s["socket"].to_s,
+        socket_ready: !!s["socketReady"],
+        api_port: to_i_or_nil(s["apiPort"]),
+        version: s["version"],
+        containers: to_i_or_nil(s["containers"]),
+        images: to_i_or_nil(s["images"]),
+        mounts: Array(s["mounts"]),
+        disk: s["disk"],
+        disk_size: to_i_or_nil(s["diskSize"])
+      )
+    end
+
+    # @param row [Hash] a +bsdkrun docker status --json+ row (snake_case).
+    # @return [DockerStatus]
+    def self.from_row(row)
+      new(
+        running: !!row["running"],
+        machine_id: row["machine_id"],
+        machine_running: !!row["machine_running"],
+        socket: row["socket"].to_s,
+        socket_ready: !!row["socket_ready"],
+        api_port: to_i_or_nil(row["api_port"]),
+        version: row["version"],
+        containers: to_i_or_nil(row["containers"]),
+        images: to_i_or_nil(row["images"]),
+        mounts: Array(row["mounts"]),
+        disk: row["disk"],
+        disk_size: to_i_or_nil(row["disk_size"])
+      )
+    end
+  end
+
+  # A container in the Docker engine VM — a trimmed +docker ps+ row.
+  DockerContainer = Data.define(
+    :id, :name, :image, :command, :state, :status, :ports, :created
+  ) do
+    # @return [Boolean] whether the container is up.
+    def running?
+      state == "running"
+    end
+
+    # Both the GraphQL object and +docker ps --json+ use these field names.
+    # @param c [Hash]
+    # @return [DockerContainer]
+    def self.from_graphql(c)
+      new(
+        id: c["id"].to_s,
+        name: c["name"].to_s,
+        image: c["image"].to_s,
+        command: (c["command"] || "").to_s,
+        state: c["state"].to_s,
+        status: c["status"].to_s,
+        ports: Array(c["ports"]),
+        created: c["created"].to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
   # An image as reported by +bsdkrun images --json+.
   ImageInfo = Data.define(:id, :reference, :digest, :size, :rootfs, :created_at) do
     # @param row [Hash]

data/lib/bsdkrun/version.rb

@@ -2,5 +2,5 @@
 
 module Bsdkrun
   # The bsdkrun Ruby SDK version.
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/bsdkrun.rb

@@ -6,6 +6,7 @@ require_relative "bsdkrun/binary"
 require_relative "bsdkrun/process"
 require_relative "bsdkrun/args"
 require_relative "bsdkrun/cache"
+require_relative "bsdkrun/ci"
 require_relative "bsdkrun/filesystem"
 require_relative "bsdkrun/types"
 require_relative "bsdkrun/sandbox"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsdkrun
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Tsiry Sandratraina
@@ -52,6 +52,7 @@ files:
 - lib/bsdkrun/args.rb
 - lib/bsdkrun/binary.rb
 - lib/bsdkrun/cache.rb
+- lib/bsdkrun/ci.rb
 - lib/bsdkrun/client.rb
 - lib/bsdkrun/errors.rb
 - lib/bsdkrun/filesystem.rb