markdownr 0.7.1 → 0.8.0

data/lib/markdown_server/csv_browser/addon_registry.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module MarkdownServer
+  module CsvBrowser
+    # Holds one add-on's declarative definition: its `actions` block and a set of
+    # `on :action_id` handler blocks. Created via the DSL inside `register`.
+    class AddonDefinition
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.to_sym
+        @actions_block = nil
+        @handlers = {}
+      end
+
+      def actions(&block)
+        @actions_block = block
+      end
+
+      def on(action_id, &block)
+        @handlers[action_id.to_sym] = block
+      end
+
+      # Returns [{ id:, label:, enabled:, ... }, ...] for the given row context.
+      def actions_for(ctx)
+        return [] unless @actions_block
+
+        result = @actions_block.call(ctx)
+        Array(result).map do |entry|
+          h = entry.dup
+          h[:id] = h[:id].to_sym
+          h[:enabled] = h.key?(:enabled) ? !!h[:enabled] : true
+          h
+        end
+      end
+
+      def handler_for(action_id)
+        @handlers[action_id.to_sym]
+      end
+    end
+
+    # Global registry of CSV add-ons.
+    #
+    # Lifecycle:
+    # 1. A Ruby file calls `MarkdownServer::CsvAddonRegistry.register(:name) { ... }`
+    #    at load time. That block is `instance_exec`'d against a fresh
+    #    `AddonDefinition`, populating its `actions` and `on` entries.
+    # 2. At startup, `load(addons_config, root_dir)` receives the `csv_addons`
+    #    mapping from .markdownr.yml and `require`s each absolute path; missing
+    #    files warn but don't halt startup.
+    # 3. `for_table(db, table)` returns the definitions a given table has
+    #    attached via its `addons:` list; unknown add-on names warn and are
+    #    dropped.
+    class CsvAddonRegistry
+      @definitions = {}
+      @loaded_config = {}
+
+      class << self
+        attr_reader :definitions, :loaded_config
+
+        def reset!
+          @definitions = {}
+          @loaded_config = {}
+        end
+
+        def register(name, &block)
+          defn = AddonDefinition.new(name)
+          defn.instance_exec(&block) if block
+          @definitions[name.to_sym] = defn
+          defn
+        end
+
+        def [](name)
+          @definitions[name.to_sym]
+        end
+
+        def load(addons_config, _root_dir = nil)
+          @loaded_config = (addons_config || {}).each_with_object({}) do |(k, v), h|
+            h[k.to_sym] = v
+          end
+
+          @loaded_config.each do |name, path|
+            unless File.exist?(path.to_s)
+              $stderr.puts "\n\e[1;33mWarning: csv_addon '#{name}' file not found: #{path}\e[0m\n\n"
+              next
+            end
+            # Use Kernel#load (not require) so repeated calls re-evaluate the
+            # add-on file — important after `reset!` in tests and to let users
+            # refresh their add-on without restarting (the gate is the
+            # absolute path in .markdownr.yml).
+            Kernel.load(path.to_s)
+          end
+        end
+
+        # Returns an array of AddonDefinition instances attached to the table.
+        # Unknown names (declared on the table but not registered) produce a
+        # one-time warning per (table, name) and are skipped.
+        def for_table(_database, table)
+          attached = Array(table.addons).map { |entry| normalize_attachment(entry) }
+          attached.filter_map do |att|
+            defn = @definitions[att[:name]]
+            unless defn
+              key = [table.key, att[:name]]
+              @warned_missing ||= {}
+              unless @warned_missing[key]
+                $stderr.puts "\n\e[1;33mWarning: table '#{table.key}' references unknown csv_addon '#{att[:name]}'\e[0m\n\n"
+                @warned_missing[key] = true
+              end
+              next
+            end
+            { definition: defn, options: att[:options] }
+          end
+        end
+
+        private
+
+        def normalize_attachment(entry)
+          case entry
+          when String, Symbol
+            { name: entry.to_sym, options: {} }
+          when Hash
+            sym = entry.transform_keys(&:to_sym)
+            opts = sym[:options] || {}
+            opts = opts.transform_keys(&:to_sym) if opts.is_a?(Hash)
+            { name: (sym[:id] || sym[:name]).to_sym, options: opts }
+          else
+            { name: :__invalid__, options: {} }
+          end
+        end
+      end
+    end
+  end
+
+  # Top-level alias so add-on files can write:
+  #   MarkdownServer::CsvAddonRegistry.register(:name) { ... }
+  CsvAddonRegistry = CsvBrowser::CsvAddonRegistry
+end

data/lib/markdown_server/csv_browser/config_loader.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "csv"
+require "yaml"
+require "json_schemer"
+
+module MarkdownServer
+  module CsvBrowser
+    # Loads database definitions from YAML files.
+    # Each YAML file defines one database with its tables, schemas, and views.
+    # CSV paths are resolved relative to the YAML file's directory.
+    class ConfigLoader
+      Database = Struct.new(:key, :title, :tables, :yaml_path, :group_by_directory, :show_record_counts, keyword_init: true)
+      Table = Struct.new(:key, :title, :csv_path, :columns, :required, :schema, :views, :color, :addons, keyword_init: true)
+      Column = Struct.new(:key, :title, :type, :constraints, :references, keyword_init: true)
+      View = Struct.new(:key, :title, :columns, keyword_init: true)
+
+      def initialize(yaml_paths, root_dir)
+        @yaml_paths = yaml_paths
+        @root_dir = root_dir
+        @databases = yaml_paths.filter_map { |path| load_database(path) }
+      end
+
+      attr_reader :databases
+
+      def reload!
+        config_path = File.join(@root_dir, ".markdownr.yml")
+        if File.exist?(config_path)
+          yaml = YAML.safe_load(File.read(config_path), permitted_classes: [Symbol], aliases: true) rescue nil
+          paths = yaml&.dig("csv_databases") || yaml&.dig("plugins", "csv_browser", "databases")
+          @yaml_paths = paths if paths.is_a?(Array) && !paths.empty?
+        end
+        @databases = @yaml_paths.filter_map { |path| load_database(path) }
+      end
+
+      def database(key)
+        @databases.find { |db| db.key == key }
+      end
+
+      # Returns Database if real_path matches a configured YAML database file
+      def find_database_by_yaml_path(real_path)
+        @databases.find { |db| db.yaml_path == real_path }
+      end
+
+      # Builds FK lookup maps for a table's columns that have references.
+      # Returns { "column_key" => { id_value => display_value, ... }, ... }
+      def resolve_references(database, table)
+        lookups = {}
+        table.columns.each do |col|
+          next unless col.references
+          ref_table = database.tables.find { |t| t.key == col.references[:table] }
+          next unless ref_table
+          next unless File.exist?(ref_table.csv_path)
+
+          map = {}
+          CSV.foreach(ref_table.csv_path, headers: true) do |row|
+            key_val = row[col.references[:column]]
+            display_val = row[col.references[:display]]
+            map[key_val] = display_val if key_val && display_val
+          end
+          lookups[col.key] = map
+        end
+        lookups
+      end
+
+      # Finds other tables in the database that have FK columns pointing at this table.
+      # Returns [{ table: "enrollments", label: "Enrollments", column: "class_id", references_column: "id" }, ...]
+      def resolve_reverse_references(database, table)
+        reverse = []
+        database.tables.each do |other_table|
+          next if other_table.key == table.key
+          other_table.columns.each do |col|
+            next unless col.references && col.references[:table] == table.key
+            entry = {
+              table: other_table.key,
+              title: other_table.title,
+              column: col.key,
+              references_column: col.references[:column]
+            }
+            entry[:color] = other_table.color if other_table.color
+            reverse << entry
+          end
+        end
+        reverse
+      end
+
+      # Returns [database, table] if real_path matches a table's CSV file, or nil
+      def find_table_by_csv_path(real_path)
+        @databases.each do |db|
+          db.tables.each do |table|
+            return [db, table] if table.csv_path == real_path
+          end
+        end
+        nil
+      end
+
+      # Returns CSV file paths under root_dir that aren't claimed by any database table.
+      # Each entry is { path: "/abs/path.csv", relative: "sub/dir/file.csv" }.
+      def unmapped_csv_files
+        referenced = Set.new
+        @databases.each do |db|
+          db.tables.each { |t| referenced << t.csv_path }
+        end
+
+        root = File.realpath(@root_dir)
+        Dir.glob(File.join(root, "**", "*.csv")).filter_map do |path|
+          real = File.realpath(path)
+          next if referenced.include?(real)
+          relative = real.delete_prefix("#{root}/")
+          { path: real, relative: relative }
+        end.sort_by { |e| e[:relative] }
+      end
+
+      private
+
+      def load_database(relative_path)
+        path = File.expand_path(relative_path, @root_dir)
+        $stdout.write "[csv-browser] Loading #{relative_path}..."
+        $stdout.flush
+
+        unless File.exist?(path)
+          puts "\n\n  \e[33mnot found: #{path}\e[0m\n\n"
+          return nil
+        end
+
+        yaml_dir = File.dirname(path)
+        config = YAML.safe_load(File.read(path), permitted_classes: [Symbol], aliases: true)
+        db_key = File.basename(path, ".*")
+
+        tables = (config["tables"] || {}).filter_map do |table_key, table_def|
+          build_table(table_key, table_def, yaml_dir)
+        end
+
+        group = config.fetch("group_by_directory", true)
+        counts = config.fetch("show_record_counts", true)
+        db = Database.new(key: db_key, title: config["title"] || config["label"] || db_key.capitalize,
+                          tables: tables, yaml_path: File.realpath(path),
+                          group_by_directory: group, show_record_counts: counts)
+        puts " ok (#{tables.length} tables)"
+        db
+      rescue => e
+        puts "\n\n  \e[31merror: #{e.message}\e[0m\n\n"
+        nil
+      end
+
+      def build_table(key, definition, yaml_dir)
+        properties = definition["properties"] || {}
+        required = definition["required"] || []
+
+        columns = properties.map do |col_key, col_def|
+          ref = col_def["references"]
+          Column.new(
+            key: col_key,
+            title: col_def["title"] || col_key.capitalize,
+            type: col_def["type"] || "string",
+            constraints: col_def.except("type", "title", "references"),
+            references: ref ? { table: ref["table"], column: ref["column"], display: ref["display"] } : nil
+          )
+        end
+
+        views = (definition["views"] || { "all" => { "title" => "All" } }).map do |view_key, view_def|
+          View.new(
+            key: view_key,
+            title: view_def["title"] || view_def["label"] || view_key.capitalize,
+            columns: view_def["columns"]
+          )
+        end
+
+        schema = build_json_schema(key, properties, required, definition)
+
+        default_title = key.tr("_", " ").split.map(&:capitalize).join(" ")
+        csv_path = File.expand_path(definition["csv"], yaml_dir)
+
+        unless File.exist?(csv_path)
+          warn "[csv-browser] Skipping table '#{key}': CSV not found at #{csv_path}"
+          return nil
+        end
+
+        Table.new(
+          key: key,
+          title: definition["title"] || default_title,
+          csv_path: File.realpath(csv_path),
+          columns: columns,
+          required: required,
+          schema: schema,
+          views: views,
+          color: definition["color"],
+          addons: definition["addons"] || []
+        )
+      end
+
+      def build_json_schema(table_key, properties, required, definition = {})
+        json_props = properties.transform_values do |col_def|
+          prop = {}
+          case col_def["type"]
+          when "integer"
+            prop["type"] = "integer"
+          when "number"
+            prop["type"] = "number"
+          else
+            prop["type"] = "string"
+          end
+          prop["title"] = col_def["title"] if col_def["title"]
+          prop["enum"] = col_def["enum"] if col_def["enum"]
+          prop["pattern"] = col_def["pattern"] if col_def["pattern"]
+          prop["format"] = col_def["format"] if col_def["format"]
+          prop["minimum"] = col_def["minimum"] if col_def["minimum"]
+          prop["maximum"] = col_def["maximum"] if col_def["maximum"]
+          prop["minLength"] = col_def["minLength"] if col_def["minLength"]
+          prop["maxLength"] = col_def["maxLength"] if col_def["maxLength"]
+          prop
+        end
+
+        schema = {
+          "$schema" => "https://json-schema.org/draft/2020-12/schema",
+          "title" => table_key,
+          "type" => "object",
+          "properties" => json_props,
+          "required" => required
+        }
+
+        schema["if"] = definition["if"] if definition["if"]
+        schema["then"] = definition["then"] if definition["then"]
+        schema["else"] = definition["else"] if definition["else"]
+        schema["allOf"] = definition["allOf"] if definition["allOf"]
+
+        JSONSchemer.schema(schema)
+      end
+    end
+  end
+end

data/lib/markdown_server/csv_browser/row_context.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module MarkdownServer
+  module CsvBrowser
+    # Context object passed to add-on action blocks. Exposes the active
+    # row/table/options/input/state and provides table read/write primitives
+    # that all flow through TableReader (so validation and CSV writes behave
+    # exactly like the row-editor path).
+    #
+    # A RowContext represents one HTTP invocation. For a multi-round prompt,
+    # a fresh RowContext is created per POST; state is what carries data
+    # across rounds (round-tripping through the client).
+    class RowContext
+      attr_reader :database, :table, :row_index, :row, :options, :input, :state
+
+      def initialize(database:, table:, row_index:, row:, options: {}, input: nil, state: nil)
+        @database = database
+        @table = table
+        @row_index = row_index
+        @row = row || {}
+        @options = options || {}
+        @input = symbolize_keys(input)
+        @state = StateHash.wrap(state)
+      end
+
+      # List rows from any table in this database.
+      # Returns an array of plain hashes keyed by column name (strings).
+      def read_table(table_name, where: {})
+        t = resolve_table(table_name)
+        return [] unless t && File.exist?(t.csv_path)
+
+        rows = []
+        CSV.foreach(t.csv_path, headers: true) do |row|
+          h = row.to_h
+          next unless where.empty? || where.all? { |k, v| h[k.to_s].to_s == v.to_s }
+
+          rows << h
+        end
+        rows
+      end
+
+      def insert_row(table_name, values, at: nil)
+        reader = TableReader.new(resolve_table!(table_name))
+        reader.insert_row(stringify_values(values), at: at)
+      end
+
+      def update_row(table_name, row_index, changes)
+        reader = TableReader.new(resolve_table!(table_name))
+        reader.update_row(row_index, stringify_values(changes))
+      end
+
+      def delete_row(table_name, row_index)
+        reader = TableReader.new(resolve_table!(table_name))
+        reader.delete_row(row_index)
+      end
+
+      # Return-value helpers — each produces the shape the HTTP layer will
+      # serialize back to the client.
+      def prompt(title:, fields:, state: {})
+        { kind: "prompt", title: title, fields: fields, state: stringify_state(state) }
+      end
+
+      def done(reload: true)
+        { kind: "done", reload: reload }
+      end
+
+      def error(message, fields: nil)
+        h = { kind: "error", message: message }
+        h[:fields] = fields if fields
+        h
+      end
+
+      private
+
+      def resolve_table(table_name)
+        return table_name if table_name.is_a?(ConfigLoader::Table)
+
+        key = table_name.to_s
+        @database.tables.find { |t| t.key == key }
+      end
+
+      def resolve_table!(table_name)
+        t = resolve_table(table_name)
+        raise ArgumentError, "unknown table: #{table_name.inspect}" unless t
+
+        t
+      end
+
+      def stringify_values(values)
+        values.each_with_object({}) { |(k, v), h| h[k.to_s] = v.nil? ? nil : v.to_s }
+      end
+
+      def stringify_state(state)
+        return {} if state.nil?
+
+        state.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      end
+
+      def symbolize_keys(h)
+        return nil if h.nil?
+        return h unless h.is_a?(Hash)
+
+        h.each_with_object({}) { |(k, v), out| out[k.to_sym] = v }
+      end
+
+      # Hash wrapper that allows symbol OR string key access, so handlers can
+      # write `ctx.state[:step]` regardless of JSON round-trip. Values are
+      # plain JSON-serializable objects (the round-trip strips Ruby symbols —
+      # use strings for step identifiers).
+      class StateHash
+        def self.wrap(h)
+          return new({}) if h.nil?
+          return h if h.is_a?(StateHash)
+
+          new(h)
+        end
+
+        def initialize(h)
+          @h = h.is_a?(Hash) ? h : {}
+        end
+
+        def [](key)
+          @h[key] || @h[key.to_s] || @h[key.to_sym]
+        end
+
+        def []=(key, value)
+          @h[key.to_s] = value
+        end
+
+        def key?(key)
+          @h.key?(key) || @h.key?(key.to_s) || @h.key?(key.to_sym)
+        end
+
+        def to_h
+          @h.dup
+        end
+
+        def empty?
+          @h.empty?
+        end
+      end
+    end
+  end
+end