canopus 0.4.0 → 0.5.0

data/lib/canopus/language/symbol.rb

@@ -3,5 +3,6 @@
 module Canopus
   module Language
     Symbol = Data.define(:name, :kind, :range, :selection, :depth)
+    DocumentSymbol = Data.define(:id, :name, :kind, :range, :selection, :depth, :parent_id)
   end
 end

data/lib/canopus/language/syntax_worker.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
-require "antares"
+canopus_root = File.expand_path("../../..", __dir__)
+if defined?(Gem::Specification)
+  Gem::Specification.find_all_by_name("canopus")
+    .find { |specification| File.expand_path(specification.full_gem_path) == canopus_root }&.activate
+end
+antares_path = ENV["ANTARES_PATH"]
+antares_path ? require(File.expand_path("lib/antares", File.expand_path(antares_path, canopus_root))) : require("antares")
 require_relative "../../canopus"
 
 module Canopus
@@ -11,6 +17,8 @@ module Canopus
       MAX_CACHE_BYTES = 4 << 20
       MAX_SYMBOLS = 10_000
       MAX_BRACKETS = 8192
+      MAX_SELECTIONS = 256
+      MAX_SELECTION_RANGES = 10_000
 
       def self.call(request)
         source = request.fetch("source")
@@ -41,7 +49,8 @@ module Canopus
         first = request.fetch("first") - request.fetch("base_line")
         last = [request.fetch("last") - request.fetch("base_line"), buffer.line_count - 1].min
         highlighter = document.highlighter(strategy: request.fetch("complete") ? nil : :window,
-          window_context: request.fetch("complete") ? nil : request.fetch("context"))
+          window_context: request.fetch("complete") ? nil : request.fetch("context"),
+          max_seconds: request.fetch("complete") ? 2 : nil)
         rows = first <= last ? highlighter.tokens_in(first..last) : []
         budget = 65_536
         tokens = (request.fetch("first")..request.fetch("last")).map.with_index do |row, index|
@@ -56,9 +65,10 @@ module Canopus
           budget -= values.length
           [row, values]
         end
-        syntax = analyze(document, request.fetch("base"), request.fetch("complete")) if request.fetch("syntax")
+        selections = selection_ranges(document, buffer, request)
+        syntax = analyze(document, request.fetch("base"), request.fetch("base_line"), request.fetch("complete")) if request.fetch("syntax")
         complete = request.fetch("complete") && (!syntax || !syntax.delete("truncated"))
-        {"tokens" => tokens, "syntax" => syntax, "complete" => complete}
+        {"tokens" => tokens, "syntax" => syntax, "selections" => selections, "complete" => complete}
       end
 
       def self.update(buffer, previous, source)
@@ -74,18 +84,60 @@ module Canopus
         buffer.history.clear
       end
 
-      def self.analyze(document, base, complete)
+      def self.selection_ranges(document, buffer, request)
+        positions = request.fetch("selections", [])
+        seen = {}
+        unless positions.is_a?(Array) && positions.length <= MAX_SELECTIONS && positions.all? do |value|
+          value.is_a?(Array) && value.length == 3 && value[0].is_a?(Integer) && value[0].between?(0, MAX_SELECTIONS - 1) &&
+            !seen[value[0]] && (seen[value[0]] = true) && value.drop(1).all? { |item| item.is_a?(Integer) && item >= 0 }
+        end
+          raise ArgumentError, "invalid selection positions"
+        end
+
+        total = 0
+        positions.map do |index, row, column|
+          local_row = row - request.fetch("base_line")
+          point = Denebola::Point.new(local_row, column)
+          cursor = buffer.rope.offset_at(point)
+          candidates = document.highlighter.structure.selection_ranges(local_row, column).map do |region|
+            first = buffer.rope.offset_at(Denebola::Point.new(region.start_line, region.start_column || 0))
+            last = buffer.rope.offset_at(Denebola::Point.new(region.end_line,
+              region.end_column || buffer.line(region.end_line).length))
+            [first, last]
+          end.uniq.sort_by { |first, last| [last - first, -first] }
+          ranges = candidates.each_with_object([]) do |(first, last), nested|
+            next unless first <= cursor && cursor <= last
+            next if nested.last && !(first <= nested.last[0] && nested.last[1] <= last)
+            total += 1
+            raise Error, "too many Antares selection ranges" if total > MAX_SELECTION_RANGES
+            nested << [first, last]
+          end
+          raise Error, "Antares selection range is too deep" if ranges.length > MAX_SELECTIONS
+          [index, ranges.map { |first, last| [request.fetch("base") + first, request.fetch("base") + last] }]
+        end
+      end
+
+      def self.analyze(document, base, base_line, complete)
         all_symbols = document.outline
         outline = all_symbols.first(MAX_SYMBOLS).map do |symbol|
           [symbol.name, symbol.kind.to_s, base + symbol.range.begin, base + symbol.range.end,
             base + symbol.selection.begin, base + symbol.selection.end, symbol.depth]
         end
         diagnostics = complete ? document.diagnostics.first(1000).map { |item| [base + item[:range].begin, base + item[:range].end, item[:message]] } : []
-        all_brackets = document.__send__(:bracket_ranges).values.uniq
-        brackets = all_brackets.first(MAX_BRACKETS).map { |range| [base + range.begin, base + range.end] }
+        all_brackets = document.brackets
+        brackets = all_brackets.first(MAX_BRACKETS).map do |pair|
+          [base + pair.open_range.begin, base + pair.open_range.end, base_line + pair.open_row,
+            base + pair.close_range.begin, base + pair.close_range.end, base_line + pair.close_row, pair.depth]
+        end
+        all_regions = document.structure_regions
+        structure_regions = all_regions.first(MAX_SYMBOLS).map do |region|
+          [base_line + region[:start_line], base_line + region[:end_line], region[:kind].to_s]
+        end
         folds = document.fold_ranges.first(MAX_SYMBOLS).map { |range| [base + range.begin, base + range.end] }
-        {"outline" => outline, "diagnostics" => diagnostics, "brackets" => brackets, "folds" => folds,
-          "truncated" => all_symbols.length > MAX_SYMBOLS || all_brackets.length > MAX_BRACKETS || (complete && document.diagnostics.length > 1000)}
+        {"outline" => outline, "diagnostics" => diagnostics, "brackets" => brackets,
+          "structure_regions" => structure_regions, "folds" => folds,
+          "truncated" => all_symbols.length > MAX_SYMBOLS || all_brackets.length > MAX_BRACKETS ||
+            all_regions.length > MAX_SYMBOLS || (complete && document.diagnostics.length > 1000)}
       end
     end
   end

data/lib/canopus/language.rb

@@ -5,6 +5,8 @@ require_relative "language/symbol"
 
 module Canopus
   module Language
+    Bracket = Data.define(:open_range, :close_range, :open_row, :close_row, :depth)
+
     DEFINITIONS = [
       ["ruby", "ruby", %w[.rb .rake .gemspec Gemfile Rakefile], "#", /(?:^\s*(?:class|module|def|if|unless|case|while|until|for|begin)\b.*|(?:\bdo|[\[{(])(?:\s*\|[^|]*\|)?\s*)$/, /^\s*(?:end\b|else\b|elsif\b|rescue\b|ensure\b|[\]})])/, [["ruby-lsp"]]],
       ["javascript", "javascript", %w[.js .jsx .mjs .cjs], "//", /[\[{(]\s*$/, /^\s*[\]})]/, [["typescript-language-server", "--stdio"]]],
@@ -19,6 +21,7 @@ module Canopus
       ["toml", "toml", %w[.toml], "#", /[\[{]\s*$/, /^\s*[\]}]/, []],
       ["markdown", "markdown", %w[.md .markdown], "<!--", /\A\z/, /\A\z/, []],
       ["html", "html", %w[.html .erb], "<!--", /<[^\/>]+>\s*$/, /^\s*<\//, []],
+      ["xml", "xml", %w[.xml .xhtml .svg], "<!--", /<[^\/>]+>\s*$/, /^\s*<\//, []],
       ["css", "css", %w[.css .scss], "/*", /\{\s*$/, /^\s*}/, []],
       ["shellscript", "shell", %w[.sh .bash .zsh], "#", /\b(?:then|do|case)\s*$/, /^\s*(?:fi|done|esac)\b/, []]
     ].map { |values| Definition.new(*values) }.freeze

data/lib/canopus/minimap.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Canopus
+  # Bounded, edit-aware row textures shared by every pane showing a buffer.
+  class Minimap
+    GENERATION_LIMIT = 24
+    ENTRY_LIMIT = 2_048
+    VARIANT_LIMIT = 4
+    LINE_BYTES = 4_096
+
+    attr_reader :generated
+
+    def initialize
+      @variants, @subscriptions, @search = {}, {}, {}
+      @next_key = @frame = 0
+      @generated, @pending = 0, false
+    end
+
+    def begin_frame(frame, text_system:, font_size:, font_family:, scale_factor:)
+      identity = [text_system&.object_id, text_system&.respond_to?(:font) ? text_system.font.object_id : nil,
+        font_size, font_family, scale_factor]
+      rebuild if @identity && @identity != identity
+      @identity, @text_system, @font_size, @scale_factor = identity, text_system, font_size, scale_factor
+      return if @frame == frame
+
+      @frame, @generated, @pending = frame, 0, false
+    end
+
+    def texture(buffer, row, width:)
+      return unless @text_system && row.is_a?(Integer) && row.between?(0, buffer.line_count - 1)
+      variant = variant(width)
+      pair = [buffer, row]
+      if (entry = variant[:entries].delete(pair))
+        variant[:entries][pair] = entry
+        return variant[:cache].texture(entry[:key], outlines: [])
+      end
+      unless @generated < GENERATION_LIMIT
+        @pending = true
+        return
+      end
+
+      attach(buffer)
+      source = line_source(buffer.rope, row)
+      layout = @text_system.layout_line(source, size: @font_size)
+      outlines = []
+      layout.glyphs.each do |glyph|
+        break if glyph.x * 0.1 >= width
+        begin
+          factor = @font_size.to_f / glyph.font.units_per_em
+          outlines << glyph.font.outline(glyph.id).transform([factor, 0, 0, -factor, glyph.x, layout.ascent])
+        rescue StandardError
+          nil
+        end
+      end
+      key = @next_key += 1
+      texture = variant[:cache].texture(key, outlines: outlines)
+      variant[:entries][pair] = {key: key, offset: buffer.rope.line_start(row)}
+      trim(variant)
+      @generated += 1
+      texture
+    rescue StandardError
+      nil
+    end
+
+    def pending? = @pending
+    def cache_size = @variants.values.sum { |variant| variant[:entries].length }
+    def cached_rows(buffer) = @variants.values.flat_map { |variant| variant[:entries].keys.filter_map { |source, row| row if source.equal?(buffer) } }.uniq.sort
+
+    def record_search(buffer, version, ranges)
+      attach(buffer)
+      rows = ranges.first(10_000).filter_map do |range|
+        buffer.rope.point_at(range.begin).row if range.is_a?(Range) && range.begin.is_a?(Integer)
+      rescue RangeError
+        nil
+      end
+      @search[buffer] = {version: version, rows: rows.sort.uniq.freeze}.freeze
+    end
+
+    def search_rows(buffer, version)
+      entry = @search[buffer]
+      entry && entry[:version] == version ? entry[:rows] : []
+    end
+
+    def release(buffer)
+      @variants.each_value { |variant| remove_buffer(variant, buffer) }
+      @subscriptions.delete(buffer)&.detach
+      @search.delete(buffer)
+      nil
+    end
+
+    def close
+      @subscriptions.each_value(&:detach)
+      @subscriptions.clear
+      rebuild
+      @search.clear
+      nil
+    end
+
+    private
+
+    def variant(width)
+      width = Integer(width)
+      key = [width, @scale_factor]
+      cached = @variants.delete(key)
+      return @variants[key] = cached if cached
+
+      while @variants.length >= VARIANT_LIMIT
+        _old_key, old = @variants.shift
+        old[:cache].close
+      end
+      scale = Float(@scale_factor)
+      texture_width, texture_height, max_bytes = (width * scale).ceil, (2 * scale).ceil, 8 << 20
+      limit = [ENTRY_LIMIT, max_bytes / (texture_width * texture_height)].min.clamp(1, ENTRY_LIMIT)
+      cache = Zaniah::TextSystem::LowResolutionTextCache.new(width: texture_width,
+        height: texture_height, scale: 0.1 * scale, capacity: limit, max_bytes: max_bytes)
+      @variants[key] = {cache: cache, entries: {}, limit: limit}
+    end
+
+    def rebuild
+      @variants.each_value { |variant| variant[:cache].close }
+      @variants.clear
+    end
+
+    def attach(buffer)
+      @subscriptions[buffer] ||= buffer.on_edit { |patch| edited(buffer, patch) }
+    end
+
+    def trim(variant)
+      while variant[:entries].length > variant[:limit]
+        _pair, entry = variant[:entries].shift
+        variant[:cache].invalidate(entry[:key])
+      end
+    end
+
+    def remove_buffer(variant, buffer)
+      variant[:entries].delete_if do |(source, _row), entry|
+        next false unless source.equal?(buffer)
+
+        variant[:cache].invalidate(entry[:key])
+        true
+      end
+    end
+
+    def edited(buffer, patch)
+      @search.delete(buffer)
+      if patch.is_a?(Patch::Reload)
+        @variants.each_value { |variant| remove_buffer(variant, buffer) }
+      else
+        parts = patch.is_a?(Patch::Composite) ? patch.patches : [patch]
+        parts.each do |part|
+          if part.is_a?(Patch::Reload)
+            @variants.each_value { |variant| remove_buffer(variant, buffer) }
+          else
+            apply_patch(buffer, part)
+          end
+        end
+      end
+    end
+
+    def apply_patch(buffer, patch)
+      affected = patch.edits.map do |edit|
+        patch.before.point_at(edit.old_range.begin).row..patch.before.point_at(edit.old_range.end).row
+      end
+      @variants.each_value do |variant|
+        mapped = {}
+        variant[:entries].each do |(source, row), entry|
+          unless source.equal?(buffer)
+            mapped[[source, row]] = entry
+            next
+          end
+          offset = patch.map_offset(entry[:offset], bias: :right)
+          new_row = patch.after.point_at(offset).row
+          changed = affected.any? { |range| range.cover?(row) }
+          aligned = patch.after.line_start(new_row) == offset
+          same_line = !changed || line_source(patch.before, row) == line_source(patch.after, new_row)
+          unless aligned && same_line && !mapped.key?([buffer, new_row])
+            variant[:cache].invalidate(entry[:key])
+            next
+          end
+          mapped[[buffer, new_row]] = {key: entry[:key], offset: offset}
+        end
+        variant[:entries] = mapped
+      end
+    end
+
+    def line_source(rope, row)
+      return rope.line_window(row, max_bytes: LINE_BYTES).first if rope.respond_to?(:line_window)
+
+      first = rope.line_start(row)
+      last = row + 1 < rope.line_count ? rope.line_start(row + 1) : rope.bytesize
+      ending = [first + LINE_BYTES, last].min
+      begin
+        rope.point_at(ending)
+      rescue RangeError
+        ending -= 1
+        retry
+      end
+      rope.byteslice(first, ending - first).to_s.sub(/(?:\r\n|[\r\n\u2028\u2029])\z/, "")
+    end
+  end
+end

data/lib/canopus/patch.rb

@@ -7,7 +7,9 @@ module Canopus
     def initialize(before, after, changes)
       @before, @after = before, after
       delta = 0
-      @edits = changes.sort_by { |range, _| range.begin }.map do |range, text|
+      @edits = changes.each_with_index.sort_by do |((range, _), index)|
+        [range.begin, range.end + (range.exclude_end? ? 0 : 1), index]
+      end.map do |((range, text), _)|
         ending = range.end + (range.exclude_end? ? 0 : 1)
         old = range.begin...ending
         start = range.begin + delta

data/lib/canopus/plugins/api.rb

@@ -9,7 +9,9 @@ module Canopus
         @workspace, @permissions = workspace, permissions
       end
       def permit!(permission)
-        raise Canopus::Plugins::PermissionDenied, "plugin requires #{permission}" unless @permissions.include?(permission)
+        requested = permission.to_s
+        normalized = requested == "process" ? "exec" : requested
+        raise Canopus::Plugins::PermissionDenied, "plugin requires #{requested}" unless @permissions.include?(normalized)
       end
       def text
         permit!("read_buffer")
@@ -25,7 +27,7 @@ module Canopus
       end
       def notify(message) = @workspace.message = message.to_s
       def run(command)
-        permit!("process")
+        permit!("exec")
         raise ArgumentError, "command must be a nonempty argument array" unless command.is_a?(Array) && !command.empty?
         Open3.capture3(*command, chdir: @workspace.root)
       end

data/lib/canopus/plugins/isolated_runtime.rb

@@ -5,7 +5,7 @@ require "open3"
 require "rbconfig"
 
 # Separate-process execution isolates crashes and accidental global state.
-# It is NOT an OS sandbox: Ruby plugins remain trusted executable code.
+# Saiph adds an OS sandbox when the host backend supports the requested policy.
 module Canopus
   module Plugins
     class IsolatedRuntime
@@ -21,7 +21,8 @@ module Canopus
         @context, @permissions, @edits, @messages = context, permissions, [], []
       end
       def permit!(name)
-        raise "plugin requires #{name}" unless @permissions.include?(name)
+        normalized = name.to_s == "process" ? "exec" : name.to_s
+        raise "plugin requires #{name}" unless @permissions.include?(normalized)
       end
       def text
         permit!("read_buffer")
@@ -37,7 +38,7 @@ module Canopus
       end
       def notify(message) = @messages << message.to_s
       def run(command)
-        permit!("process")
+        permit!("exec")
         raise "command must be an argument array" unless command.is_a?(Array) && !command.empty?
         Open3.capture3(*command, chdir: @context.fetch("root"))
       end
@@ -95,12 +96,12 @@ module Canopus
   RUBY
 
       def initialize(workspace, source, path, permissions, timeout: 2)
-        @workspace, @permissions, @timeout = workspace, permissions, timeout
-        @input, @output, @process = Open3.popen2(RbConfig.ruby, "-e", WORKER)
+        @workspace, @permissions, @timeout = workspace, permissions.map { |permission| permission.to_s == "process" ? "exec" : permission.to_s }.uniq, timeout
+        start_process
         @input.sync = true
         @output.binmode
         @pending, @lock = +"".b, Mutex.new
-        @input.puts(JSON.generate(source: source, path: path, permissions: permissions))
+        @input.puts(JSON.generate(source: source, path: path, permissions: @permissions))
         manifest = response
         manifest.fetch("actions").each do |name, description|
           workspace.register_action(name, description: description) { invoke(:action, name) }
@@ -138,12 +139,68 @@ module Canopus
       def close
         @input&.close unless @input&.closed?
         if @process && !@process.join(0.2)
-          Process.kill("KILL", @process.pid) rescue Errno::ESRCH
+          Process.kill("KILL", @pid) rescue Errno::ESRCH
           @process.join
         end
         @output&.close unless @output&.closed?
       end
   private
+      def start_process
+        command = [RbConfig.ruby, "-e", WORKER]
+        mode = @workspace.settings["plugins"].fetch("sandbox", "auto")
+        return start_open3(command) if mode == "off"
+
+        start_saiph(command)
+      rescue StandardError => error
+        raise unless defined?(Saiph::Unsupported) && error.is_a?(Saiph::Unsupported)
+
+        raise Canopus::Error, "plugin sandbox is required: #{error.message}" if mode == "required"
+
+        @workspace.message = "Plugin OS sandbox disabled: #{error.message}"
+        start_open3(command)
+      end
+
+      def start_open3(command)
+        @input, @output, @process = Open3.popen2(*command)
+        @pid = @process.pid
+      end
+
+      def start_saiph(command)
+        load_saiph
+        child_input, input = IO.pipe
+        output, child_output = IO.pipe
+        @pid = Saiph.spawn(command, policy: sandbox_policy, in: child_input, out: child_output)
+        child_input.close
+        child_output.close
+        @input, @output = input, output
+        @process = Process.detach(@pid)
+      rescue Exception
+        child_input&.close unless child_input&.closed?
+        child_output&.close unless child_output&.closed?
+        input&.close unless input&.closed?
+        output&.close unless output&.closed?
+        raise
+      end
+
+      def sandbox_policy
+        load_saiph
+        Saiph::Policy.new(
+          @permissions.include?("read_project") ? [@workspace.root] : [],
+          @permissions.include?("write_project") ? [@workspace.root] : [],
+          @permissions.include?("network"),
+          @permissions.include?("exec"),
+          []
+        )
+      end
+
+      def load_saiph
+        return if defined?(Saiph::Policy)
+
+        saiph_path = ENV["SAIPH_PATH"]
+        saiph_root = File.expand_path("../..", __dir__)
+        saiph_path ? require(File.expand_path("lib/saiph", File.expand_path(saiph_path, saiph_root))) : require("saiph")
+      end
+
       def response
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
         loop do

data/lib/canopus/plugins/registry.rb

@@ -1,17 +1,87 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "json"
+require "tempfile"
+
 module Canopus
   module Plugins
     class Registry
-      PERMISSIONS = %w[read_buffer edit_buffer read_project process network].freeze
+      API_VERSION = "1"
+      NAME_PATTERN = /\Acanopus-plugin-[a-z0-9][a-z0-9-]*\z/
+      PERMISSIONS = Plugins::PERMISSIONS
 
-      def initialize(workspace)
+      def initialize(workspace, state_path: nil)
         @workspace, @loaded = workspace, []
+        @state_path = state_path || File.join(ENV["XDG_STATE_HOME"] || File.expand_path("~/.local/state"), "canopus", "plugins.json")
+        @disabled = load_state
+      end
+
+      def search(query, limit: 20)
+        require "rubygems/spec_fetcher"
+        query = String(query)
+        raise ArgumentError, "plugin search query must not be empty" if query.strip.empty?
+        raise ArgumentError, "invalid plugin search limit" unless limit.is_a?(Integer) && limit.between?(1, 100)
+
+        dependency = Gem::Dependency.new(query.start_with?("canopus-plugin-") ? query : "canopus-plugin-#{query}", Gem::Requirement.default)
+        Gem::SpecFetcher.fetcher.search_for_dependency(dependency).first.filter_map do |entry, _source|
+          spec = entry.is_a?(Array) ? entry.first : entry
+          spec = spec.spec if spec.respond_to?(:spec)
+          name = spec.respond_to?(:name) ? spec.name : nil
+          next unless plugin_name?(name)
+          {name: name, version: spec.respond_to?(:version) ? spec.version.to_s : "", summary: spec.respond_to?(:summary) ? spec.summary.to_s : "",
+           api_version: spec.respond_to?(:metadata) ? spec.metadata["canopus_plugin_api_version"] : nil}
+        end.uniq { |plugin| plugin[:name] }.first(limit)
+      end
+
+      def install(name, version: nil)
+        require "rubygems/dependency_installer"
+        name = validate_name(name)
+        specifications = Gem::DependencyInstaller.new.install(name, version || Gem::Requirement.default)
+        specification = specifications.reverse.find { |candidate| candidate.name == name }
+        validate_specification!(specification)
+        specification
+      rescue Gem::Exception => error
+        raise Canopus::Error, "plugin install failed: #{error.message}"
+      end
+
+      def update(name)
+        install(name)
+      end
+
+      def disable(name)
+        name = validate_name(name)
+        @disabled[name] = true
+        save_state
+        true
+      end
+
+      def enable(name)
+        name = validate_name(name)
+        @disabled.delete(name)
+        save_state
+        true
+      end
+
+      def disabled?(name) = @disabled.key?(validate_name(name))
+
+      def load_gem(name, trusted: false, permissions: [], isolated: true, timeout: 2)
+        name = validate_name(name)
+        raise Canopus::Error, "plugin is disabled: #{name}" if disabled?(name)
+        specification = validate_specification!(Gem::Specification.find_all_by_name(name).max_by(&:version))
+        entrypoint = specification.metadata["canopus_plugin_entrypoint"] || "lib/#{name}.rb"
+        path = File.realpath(File.expand_path(entrypoint, specification.full_gem_path))
+        prefix = File.realpath(specification.full_gem_path) + File::SEPARATOR
+        raise Canopus::Error, "plugin entrypoint escapes gem directory" unless path.start_with?(prefix)
+
+        load(path, trusted: trusted, permissions: permissions, isolated: isolated, timeout: timeout)
+      rescue Errno::ENOENT
+        raise Canopus::Error, "plugin entrypoint not found: #{name}"
       end
 
       def load(path, trusted: false, permissions: [], isolated: true, timeout: 2)
         raise PermissionDenied, "plugins execute Ruby code; explicitly mark this plugin trusted" unless trusted
-        permissions = permissions.map(&:to_s)
+        permissions = permissions.map { |permission| permission.to_s == "process" ? "exec" : permission.to_s }.uniq
         raise PermissionDenied, "unknown plugin permission" unless (permissions - PERMISSIONS).empty?
         source = File.read(path, 256 * 1024 + 1, encoding: "UTF-8")
         raise Error, "plugin source exceeds 256KB" if source.bytesize > 256 * 1024
@@ -25,6 +95,47 @@ module Canopus
       end
 
       def close = @loaded.each(&:close)
+
+      private
+
+      def plugin_name?(name) = NAME_PATTERN.match?(name.to_s)
+
+      def validate_name(name)
+        name = String(name)
+        raise ArgumentError, "plugin gem name must match canopus-plugin-*" unless plugin_name?(name)
+        name
+      end
+
+      def validate_specification!(specification)
+        raise Canopus::Error, "plugin gem was not found" unless specification
+        unless plugin_name?(specification.name)
+          raise Canopus::Error, "plugin gem name must match canopus-plugin-*"
+        end
+        version = specification.metadata["canopus_plugin_api_version"]
+        raise Canopus::Error, "unsupported plugin API version" unless version == API_VERSION
+        specification
+      end
+
+      def load_state
+        return {} unless File.file?(@state_path)
+        value = JSON.parse(File.read(@state_path))
+        value.is_a?(Hash) ? value.select { |name, disabled| plugin_name?(name) && disabled == true } : {}
+      rescue JSON::ParserError, Errno::ENOENT, Errno::EACCES
+        {}
+      end
+
+      def save_state
+        FileUtils.mkdir_p(File.dirname(@state_path))
+        Tempfile.create([".plugins-", ".json"], File.dirname(@state_path)) do |file|
+          file.write(JSON.generate(@disabled))
+          file.flush
+          file.fsync
+          file.close
+          File.rename(file.path, @state_path)
+        end
+      rescue SystemCallError => error
+        raise Canopus::Error, "cannot save plugin state: #{error.message}"
+      end
     end
   end
 end

data/lib/canopus/plugins.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module Canopus
-  module Plugins; end
+  module Plugins
+    PERMISSIONS = %w[read_buffer edit_buffer read_project write_project exec process network].freeze
+    autoload :PermissionDenied, "canopus/plugins/permission_denied"
+    autoload :API, "canopus/plugins/api"
+    autoload :LocalRuntime, "canopus/plugins/local_runtime"
+    autoload :IsolatedRuntime, "canopus/plugins/isolated_runtime"
+    autoload :Registry, "canopus/plugins/registry"
+  end
 end
-
-require_relative "plugins/permission_denied"
-require_relative "plugins/api"
-require_relative "plugins/local_runtime"
-require_relative "plugins/isolated_runtime"
-require_relative "plugins/registry"