sillydev 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9102635d2e7ac06f66d36dd44ea361de787e1d8d7357a3cdb677327ecb26974c
+  data.tar.gz: 22131ee43b2a56dcaca660c0d7e45883055da548e5a5acd432c6c547770154e1
+SHA512:
+  metadata.gz: 3df262ecb504008664795fc8780140886fea64729e4ebd6c29675c1c663db2b490188498a1eabb72def712654644cf3fa0047d011f586a5f22b45bbc5effc5ae
+  data.tar.gz: 22d8573315748b14286eb5af88c0d7930ff6ea24f332211b1070408f188dc0f25d689688387d679236c1150d8bb7cc7700bd79d3c5876b2184c8349401901456

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silly Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,277 @@
+# sillydev
+
+The Ruby client for the [Silly Development](https://sillydev.co.uk) panel API: start, stop and restart
+your bots, follow their console live, manage files, backups, schedules and databases, and deploy from
+Git, all from your own code. It also has a `sillydev` command line tool, an MCP server for AI
+assistants and opt-in application monitoring.
+
+Full API docs: <https://sillydev.co.uk/docs/panel>
+
+## Install
+
+```sh
+gem install sillydev
+```
+
+or add `gem "sillydev"` to your Gemfile. Ruby 3.1 or later. No dependencies outside Ruby's standard
+library.
+
+## Quick start
+
+Create an API key in the panel under **Account, API keys** and put it in the `SILLYDEV_API_KEY`
+environment variable. Keys start with `sdevc_` (older `ptlc_` keys keep working).
+
+```ruby
+require "sillydev"
+
+client = SillyDev::Client.new # or SillyDev::Client.new("sdevc_...")
+
+client.panel.servers.list.each do |server|
+  puts "#{server["identifier"]} #{server["name"]}"
+end
+
+client.panel.servers.restart("1a7ce997")
+client.panel.servers.command("1a7ce997", "say Back in a minute")
+```
+
+Each server has an 8-character identifier, shown in the panel and in the `identifier` field of every
+server. Every method takes it (or the full UUID) as its first argument.
+
+Answers are plain hashes and arrays with string keys, as the API sends them, without the
+`{"object", "attributes"}` wrapping.
+
+## What it covers
+
+Every endpoint of the client API, grouped as in the docs:
+
+| `client.panel.` | For example |
+| --- | --- |
+| `servers` | `list`, `get`, `resources`, `wait_for_state`, `power`, `start`, `stop`, `restart`, `kill`, `command`, `activity` |
+| `settings` | `rename`, `reinstall`, `set_docker_image`, `badge` |
+| `startup` | `get`, `set_variable` |
+| `files` | `list`, `read`, `write`, `rename`, `copy`, `compress`, `decompress`, `delete`, `create_folder`, `chmod`, `pull` |
+| `backups` | `list`, `create`, `get`, `download_url`, `toggle_lock`, `restore`, `delete` |
+| `schedules` | `list`, `create`, `update`, `run`, `create_task`, `update_task` |
+| `network` | `list`, `create`, `set_notes`, `set_primary`, `delete` |
+| `subusers` | `list`, `create`, `get`, `update`, `delete` |
+| `git` | `get`, `link`, `deploy`, `cancel_deployment`, `sync_config` |
+| `account` | `get`, `activity` |
+| `server_creation` | `options`, `create` |
+| `databases` | `list`, `create`, `rotate_password`, `move`, `delete` |
+| `billing` | `get`, `checkout`, `database_checkout`, `credit`, `cancel_subscription` |
+| `monitoring` | `list_projects`, `create_key`, `list_issues`, `list_events`, `usage` |
+
+Each method's comment names the API operation it calls (`operationId: sendPowerSignal`), so the
+[API docs](https://sillydev.co.uk/docs/panel) describe its fields.
+
+### Lists
+
+`list` (and `activity`) on paginated endpoints returns an `Enumerator` that fetches the next page
+only when it is reached, so `first(5)` makes one request. The `*_page` twins return one
+`SillyDev::Page`, which also has the list's `meta`:
+
+```ruby
+page = client.panel.backups.list_page("1a7ce997")
+puts "#{page.meta["backup_count"]} backups, page #{page.current_page} of #{page.total_pages}"
+```
+
+### Waiting for a server
+
+```ruby
+client.panel.servers.start("1a7ce997")
+client.panel.servers.wait_for_state("1a7ce997", "running", timeout: 120)
+```
+
+### Files
+
+```ruby
+puts client.panel.files.read("1a7ce997", "/main.rb")
+client.panel.files.write("1a7ce997", "/config.json", JSON.generate(debug: false))
+client.panel.files.write("1a7ce997", "/logo.png", File.binread("logo.png")) # sent as binary
+```
+
+### Deploying from Git
+
+```ruby
+deployment = client.panel.git.deploy("1a7ce997")
+puts deployment["status"]
+```
+
+## Errors
+
+Every error is a `SillyDev::Error`. When the API answers with an error, the class says what kind:
+
+| Class | Status |
+| --- | --- |
+| `SillyDev::BadRequestError` | 400 |
+| `SillyDev::AuthenticationError` | 401 |
+| `SillyDev::PermissionDeniedError` | 403 |
+| `SillyDev::NotFoundError` | 404 |
+| `SillyDev::ConflictError` | 409 |
+| `SillyDev::ValidationError` | 422, with `fields` grouping the messages by field |
+| `SillyDev::RateLimitError` | 429, with `retry_after` |
+| `SillyDev::ServerError` | 5xx |
+| `SillyDev::APIConnectionError` | the panel could not be reached |
+
+Each has `status_code`, `code` and the full `errors` list from the response.
+
+```ruby
+begin
+  client.panel.servers.get("nope")
+rescue SillyDev::NotFoundError => e
+  puts e.message # "404: The requested resource could not be found on the server."
+end
+```
+
+## Retries and options
+
+Requests answered 429 are retried (and reads answered 502, 503 or 504), waiting as long as
+`Retry-After` asks, up to `max_retries` times. Checkouts always send an `Idempotency-Key`, so a
+retried checkout never buys twice.
+
+```ruby
+SillyDev::Client.new(
+  "sdevc_...",
+  base_url: "https://sillydev.co.uk/panel/api/client", # or SILLYDEV_BASE_URL
+  timeout: 60,
+  max_retries: 2,
+  default_headers: { "X-Request-Source" => "my-bot" },
+)
+```
+
+`transport:` takes any object with a `call(request)` that returns a `SillyDev::Response`, which is
+useful for tests.
+
+## Live console
+
+`client.panel.console` follows a server's console live and sends commands to it. It connects over
+the server's websocket, and falls back by itself to a streamed or polled session on the node and
+then to the panel's relay, so it also works where websockets are blocked.
+
+```ruby
+client.panel.console.connect("1a7ce997") do |console|
+  console.on("console output") { |message| puts message.args.first }
+  console.command("say hi")
+  sleep 10
+end # closed when the block ends
+```
+
+Without a block, `connect` returns the console: read it with `console.each(timeout: 1) { |message| ... }`
+(each message has `event` and `args`), and call `console.close` when done. `console.power("restart")`,
+`console.request_stats` and `console.on_close { |error| ... }` are there too. It reconnects after a
+dropped connection and renews its token before it expires.
+
+For the recent output without staying connected:
+
+```ruby
+puts client.panel.console.history("1a7ce997").last(20)
+```
+
+`transport:` picks one way to connect (`"websocket"`, `"stream"`, `"poll"` or `"relay"`) instead of
+trying them in turn. A console that cannot connect raises `SillyDev::ConsoleError`, whose `reason` is
+`"suspended"`, `"booting"`, `"token"`, `"network"` and so on.
+
+## Command line
+
+The gem installs a `sillydev` command. It reads the key from `SILLYDEV_API_KEY` (or `--api-key`), and
+`--json` gives machine-readable output.
+
+```sh
+sillydev servers list
+sillydev status 1a7ce997
+sillydev power 1a7ce997 restart
+sillydev command 1a7ce997 "say hi"
+sillydev logs 1a7ce997
+sillydev console 1a7ce997      # follow live; lines you type are sent as commands
+sillydev deploy 1a7ce997
+sillydev files ls 1a7ce997 /src
+sillydev files cat 1a7ce997 /config.json
+sillydev backups create 1a7ce997 --name before-update
+```
+
+`sillydev --help` lists every command.
+
+## MCP server
+
+`sillydev mcp` runs an [MCP](https://modelcontextprotocol.io) server on stdio, so an AI assistant can
+look after your servers. Its tools list servers, read a server's status, send power actions and
+console commands, read the recent console output, list and read files, deploy from Git and list
+backups. Nothing in it spends money, deletes anything or changes who can reach a server. Give it a key
+limited to the servers you want the assistant to reach.
+
+```json
+{
+  "mcpServers": {
+    "sillydev": {
+      "command": "sillydev",
+      "args": ["mcp"],
+      "env": { "SILLYDEV_API_KEY": "sdevc_..." }
+    }
+  }
+}
+```
+
+## Monitoring (opt-in)
+
+`SillyDev::Monitoring` sends metrics, errors, events and slow operations to Silly Development
+application monitoring. Nothing is loaded by `require "sillydev"`, and nothing is collected, sent or
+started until you call `init` with a monitoring key. Create one in the panel under **Monitoring**
+and put it in `SILLYDEV_MONITORING_KEY`.
+
+```ruby
+require "sillydev/monitoring"
+
+SillyDev::Monitoring.init(service: "web") # reads SILLYDEV_MONITORING_KEY; does nothing without one
+
+SillyDev::Monitoring.increment("orders.created", tags: { plan: "free" })
+SillyDev::Monitoring.gauge("queue.depth", queue.size)
+SillyDev::Monitoring.time("report.build") { build_report }
+SillyDev::Monitoring.event("user.signed_up", { "plan" => "free" })
+
+begin
+  risky
+rescue StandardError => e
+  SillyDev::Monitoring.capture_exception(e, tags: { job: "sync" })
+end
+```
+
+Data is sent in the background every 10 seconds and at exit, along with CPU, memory, GC and thread
+counts (`runtime_metrics: false` turns those off). Exceptions that end the program are reported.
+Values of keys that look secret (`password`, `token`, `api_key`, ...) are replaced with `[redacted]`.
+`sample_rate:` and `before_send: ->(type, item) { item }` (return `nil` to drop) let you send less.
+`SILLYDEV_MONITORING_DISABLED=1` turns it off. Forked workers (Puma, Unicorn) start their own sender.
+
+### Rack, Rails and Sinatra
+
+```ruby
+# config.ru
+require "sillydev/monitoring/rack"
+SillyDev::Monitoring.init
+use SillyDev::Monitoring::Rack
+```
+
+Rails apps can instead load the railtie from the Gemfile,
+`gem "sillydev", require: ["sillydev", "sillydev/monitoring/rails"]`, and call
+`SillyDev::Monitoring.init` in an initializer: the middleware is added for you, and errors reported
+through `Rails.error` are sent too. Each request records `http.server.duration` tagged with the route
+(the router's template on Rails and Sinatra, otherwise the path with ids as `:id`), method and status
+class, reports unhandled exceptions, and records requests slower than `slow_threshold_ms` (1000).
+
+### discordrb
+
+```ruby
+require "discordrb"
+require "sillydev/monitoring/discordrb"
+
+SillyDev::Monitoring.init(service: "bot")
+bot = Discordrb::Commands::CommandBot.new(token: ENV["TOKEN"], prefix: "!")
+SillyDev::Monitoring::Discordrb.monitor(bot)
+bot.run
+```
+
+This times slash commands and prefix commands (`discord.command.duration`), reports errors raised in
+handlers (they still reach discordrb's own logging) and sends the `discord.guilds` gauge.
+
+## License
+
+MIT

data/exe/sillydev

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "sillydev/cli"
+
+SillyDev::CLI.start(ARGV)

data/lib/sillydev/cli.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../sillydev"
+
+module SillyDev
+  # The sillydev command line.
+  #
+  #   sillydev servers list
+  #   sillydev power 1a7ce997 restart
+  #   sillydev command 1a7ce997 "say hi"
+  #   sillydev logs 1a7ce997
+  #   sillydev console 1a7ce997
+  #   sillydev deploy 1a7ce997
+  #   sillydev files ls 1a7ce997 /src
+  #   sillydev backups create 1a7ce997
+  #   sillydev mcp
+  #
+  # The API key comes from --api-key or the SILLYDEV_API_KEY environment variable. Add --json to
+  # any command for machine-readable output.
+  class CLI
+    POWER_SIGNALS = %w[start stop restart kill].freeze
+    TRANSPORTS = (["auto"] + %w[websocket stream poll relay]).freeze
+    PRINTED = ["console output", "install output", "daemon message"].freeze
+
+    USAGE = <<~TEXT
+      Usage: sillydev [options] <command> [arguments]
+
+      Control your Silly Development servers from the command line.
+
+      Commands:
+        servers list [--search TEXT] [--owner]   list the servers the key can reach
+        servers get <server>                     show one server
+        status <server>                          show a server's state and resource use
+        power <server> start|stop|restart|kill   start, stop, restart or kill a server
+        command <server> <command...>            send a console command
+        logs <server> [--transport WAY]          print the server's recent console output
+        console <server> [--transport WAY]       follow the console live; lines typed are sent as
+                                                 commands (Ctrl+C to stop)
+        deploy <server>                          deploy the linked Git repository now
+        files ls <server> [directory]            list a directory
+        files cat <server> <file>                print a file
+        backups list <server>                    list a server's backups
+        backups create <server> [--name NAME] [--locked] [--ignore PATH ...]
+                                                 start a backup
+        mcp                                      run the MCP server on stdio
+
+      WAY is auto (the default: tries websocket, stream, poll and then relay), websocket, stream,
+      poll or relay. <server> is the 8-character identifier or the UUID.
+
+      Options:
+    TEXT
+
+    def self.start(argv = ARGV)
+      exit(new.run(argv))
+    end
+
+    def initialize(stdout: $stdout, stderr: $stderr, stdin: $stdin, client_factory: nil, stop: nil)
+      @out = stdout
+      @err = stderr
+      @in = stdin
+      @client_factory = client_factory || ->(**kwargs) { Client.new(kwargs[:api_key], base_url: kwargs[:base_url]) }
+      @stop = stop
+    end
+
+    # Runs one command and returns the exit status.
+    def run(argv)
+      options = { json: false, transport: "auto", ignore: [] }
+      parser = build_parser(options)
+      args = catch(:done) { parser.parse(argv) }
+      return 0 if args.nil? # --help or --version
+
+      command = args.shift
+      if command.nil?
+        @err.puts(parser.help)
+        return 2
+      end
+      return mcp(options) if command == "mcp"
+
+      client = @client_factory.call(api_key: options[:api_key], base_url: options[:base_url])
+      if command == "console"
+        follow(client, need(args, 0, "server"), options)
+        return 0
+      end
+      data, show = dispatch(client, command, args, options)
+      if options[:json]
+        @out.puts(JSON.pretty_generate(data))
+      else
+        show.call
+      end
+      0
+    rescue OptionParser::ParseError, UsageError => e
+      @err.puts("sillydev: #{e.message}")
+      @err.puts("Run sillydev --help for the commands.")
+      2
+    rescue Error => e
+      if options && options[:json]
+        @err.puts(JSON.generate({ error: e.message, status: e.status_code, errors: e.errors }))
+      else
+        @err.puts("sillydev: #{e.message}")
+      end
+      1
+    end
+
+    private
+
+    class UsageError < StandardError; end
+
+    def build_parser(options)
+      OptionParser.new do |o|
+        o.banner = USAGE
+        o.on("--api-key KEY", "API key (default: $SILLYDEV_API_KEY)") { |v| options[:api_key] = v }
+        o.on("--base-url URL", "API base URL (default: $SILLYDEV_BASE_URL or the public API)") { |v| options[:base_url] = v }
+        o.on("--json", "print JSON") { options[:json] = true }
+        o.on("--search TEXT", "servers list: match the name, identifier, UUID or an ip:port") { |v| options[:search] = v }
+        o.on("--owner", "servers list: only servers you own") { options[:owner] = true }
+        o.on("--transport WAY", TRANSPORTS, "logs, console: how to connect") { |v| options[:transport] = v }
+        o.on("--name NAME", "backups create: the backup's name") { |v| options[:name] = v }
+        o.on("--locked", "backups create: lock it so it cannot be deleted") { options[:locked] = true }
+        o.on("--ignore PATH", "backups create: leave out a path (repeatable)") { |v| options[:ignore] << v }
+        o.on("-v", "--version", "print the version") do
+          @out.puts("sillydev #{VERSION}")
+          throw :done
+        end
+        o.on("-h", "--help", "print this help") do
+          @out.puts(o.help)
+          @out.puts("\nDocs: https://sillydev.co.uk/docs/panel")
+          throw :done
+        end
+      end
+    end
+
+    def need(args, index, name)
+      args[index] or raise UsageError, "missing <#{name}>"
+    end
+
+    def dispatch(client, command, args, options)
+      panel = client.panel
+      case [command, args.first]
+      in ["servers", "list"]
+        type = options[:owner] ? "owner" : nil
+        data = panel.servers.list(search: options[:search], type: type).to_a
+        [data, -> { table([%w[ID NAME NODE]] + data.map { |s| [s["identifier"], s["name"], s["node"]].map(&:to_s) }) }]
+      in ["servers", "get"]
+        data = panel.servers.get(need(args, 1, "server"))
+        [data, -> { @out.puts(JSON.pretty_generate(data)) }]
+      in ["status", _]
+        data = panel.servers.resources(need(args, 0, "server"))
+        [data, -> { show_status(data) }]
+      in ["power", _]
+        server = need(args, 0, "server")
+        signal = need(args, 1, "signal")
+        raise UsageError, "the signal must be start, stop, restart or kill" unless POWER_SIGNALS.include?(signal)
+
+        panel.servers.power(server, signal)
+        [{ ok: true, signal: signal }, -> { @out.puts("Sent #{signal} to #{server}") }]
+      in ["command", _]
+        server = need(args, 0, "server")
+        text = args[1..].join(" ")
+        raise UsageError, "missing <command>" if text.empty?
+
+        panel.servers.command(server, text)
+        [{ ok: true, command: text }, -> { @out.puts("Sent") }]
+      in ["logs", _]
+        lines = panel.console.history(need(args, 0, "server"), transport: options[:transport])
+        [lines, -> { lines.each { |line| @out.puts(line) } }]
+      in ["deploy", _]
+        data = panel.git.deploy(need(args, 0, "server"))
+        [data, -> { @out.puts("Deployment #{data['uuid']} #{data['status']} (#{data['branch']})") }]
+      in ["files", "ls"]
+        data = panel.files.list(need(args, 1, "server"), args[2] || "/")
+        [data, -> { show_files(data) }]
+      in ["files", "cat"]
+        file = need(args, 2, "file")
+        data = panel.files.read(need(args, 1, "server"), file)
+        [{ file: file, contents: data }, -> { @out.write(data) }]
+      in ["backups", "list"]
+        data = panel.backups.list(need(args, 1, "server")).to_a
+        [data, -> { show_backups(data) }]
+      in ["backups", "create"]
+        data = panel.backups.create(need(args, 1, "server"), name: options[:name], is_locked: options[:locked],
+                                                             ignored: options[:ignore].empty? ? nil : options[:ignore])
+        [data, -> { @out.puts("Backup #{data['uuid']} started") }]
+      else
+        raise UsageError, "unknown command: #{[command, args.first].compact.join(' ')}"
+      end
+    end
+
+    def table(rows)
+      return if rows.empty?
+
+      widths = rows.first.each_index.map { |i| rows.map { |row| row[i].to_s.length }.max }
+      rows.each { |row| @out.puts(row.each_with_index.map { |cell, i| cell.to_s.ljust(widths[i]) }.join("  ").rstrip) }
+    end
+
+    def size(bytes)
+      value = Float(bytes)
+      %w[B KiB MiB GiB].each do |unit|
+        return unit == "B" ? "#{value.round} B" : format("%<value>.1f %<unit>s", value: value, unit: unit) if value < 1024 || unit == "GiB"
+
+        value /= 1024
+      end
+    rescue ArgumentError, TypeError
+      "-"
+    end
+
+    def show_status(data)
+      res = data["resources"] || {}
+      @out.puts("state:   #{data['current_state']}")
+      @out.puts("cpu:     #{res['cpu_absolute'] || 0}")
+      @out.puts("memory:  #{size(res['memory_bytes'])}")
+      @out.puts("disk:    #{size(res['disk_bytes'])}")
+      @out.puts("uptime:  #{(res['uptime'] || 0).to_i / 1000}s")
+    end
+
+    def show_files(data)
+      table(data.map do |f|
+        file = f["is_file"]
+        [file ? "-" : "d", f["mode"].to_s, file ? size(f["size"]) : "-", f["modified_at"].to_s,
+         "#{f['name']}#{'/' unless file}"]
+      end)
+    end
+
+    def show_backups(data)
+      rows = [%w[UUID NAME SIZE STATUS CREATED]]
+      data.each do |b|
+        state = if b["completed_at"].nil? then "running"
+                elsif b["is_successful"] then "ok"
+                else "failed"
+                end
+        state += ",locked" if b["is_locked"]
+        rows << [b["uuid"].to_s, b["name"].to_s, size(b["bytes"]), state, b["created_at"].to_s]
+      end
+      table(rows)
+    end
+
+    # Follows the console until Ctrl+C (or the stop latch) or the console ends; lines from stdin
+    # become commands.
+    def follow(client, server, options)
+      console = client.panel.console.connect(server, transport: options[:transport])
+      @err.puts("Connected to #{server} (#{console.transport}). Press Ctrl+C to stop.")
+      @err.flush
+      input = Thread.new do
+        @in&.each_line do |line|
+          break if console.closed? || stopped?
+          next if line.strip.empty?
+
+          begin
+            console.command(line.chomp)
+          rescue Error => e
+            @err.puts("sillydev: #{e.message}")
+          end
+        end
+      end
+      begin
+        # Show the recent output first, as the panel does.
+        console.request_logs
+        until stopped? || console.closed?
+          console.each(timeout: 0.25) do |message|
+            print_message(message, options[:json])
+            break if stopped?
+          end
+        end
+      rescue Interrupt
+        nil
+      ensure
+        reason = console.close_reason
+        console.close
+        input.kill
+      end
+      raise reason if reason
+    end
+
+    def stopped?
+      @stop.respond_to?(:call) ? @stop.call : false
+    end
+
+    def print_message(message, json)
+      if json
+        @out.puts(JSON.generate({ event: message.event, args: message.args }))
+      elsif PRINTED.include?(message.event)
+        @out.puts(message.args.first.to_s)
+      elsif message.event == "status"
+        @err.puts("[#{message.args.first}]")
+      end
+      @out.flush
+    end
+
+    def mcp(options)
+      require_relative "mcp_server"
+      MCPServer.main(api_key: options[:api_key], base_url: options[:base_url], stdin: @in, stdout: @out, stderr: @err)
+    end
+  end
+end