okf 1.9.0 → 1.10.0

data/lib/okf/cli/command.rb

@@ -0,0 +1,495 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module OKF
+  class CLI
+    # What every command inherits: the injected streams, and the shared surface
+    # a verb leans on — ref resolution, the flags several of them offer, the
+    # JSON emitters, the list-view printers.
+    #
+    # A command answers four questions about *itself* (.id, .group, .help_rows,
+    # .hidden?) and one about a *run* (#call, returning an exit status). That is
+    # the whole contract, and it is the same one a plugin implements — there is
+    # no second, lesser interface for an addon, because a seam only the base gem
+    # can use is not a seam.
+    #
+    # Privacy is the boundary, the one idea worth taking from Thor without
+    # taking Thor: #call is the entire public surface, so a helper added below
+    # can never become a verb by accident.
+    class Command
+      # What .register checks before admitting a command. Checked at
+      # registration rather than at dispatch, so a malformed addon fails where
+      # it is installed instead of the first time a user types its verb.
+      DUCK_TYPE = %i[id group help_rows hidden? new].freeze
+
+      class << self
+        # The verb this answers to, as a Symbol. The registry is keyed on it.
+        def id
+          raise NotImplementedError, "#{self}.id must name the verb it answers to"
+        end
+
+        # Where the verb sits in the map `okf help` prints. CLI::GROUPS fixes
+        # the order; anything else — which is what a plugin gets by default —
+        # falls to the end, under its own heading.
+        def group
+          :extension
+        end
+
+        # [ [ left-column, description ], … ] — one row per line of the map.
+        # A list rather than a pair because `registry` is an umbrella: five
+        # subcommands under one verb, each of which has to be findable alone.
+        def help_rows
+          []
+        end
+
+        # A command that works but is not advertised.
+        def hidden?
+          false
+        end
+      end
+
+      # `runner:` is the server's injected boot seam and `input:` the terminal
+      # a full-screen command needs. Both live here rather than on the two
+      # commands that want them, so construction is uniform: a plugin is built
+      # exactly the way a built-in is, and the CLI needs to know nothing about
+      # which is which.
+      def initialize(out:, err:, runner: nil, input: nil)
+        @out = out
+        @err = err
+        @runner = runner
+        @input = input
+        @pretty = false
+        @ref_slugs = {}
+      end
+
+      # The run. Returns the exit status; it never calls exit, and never writes
+      # anywhere but the injected streams.
+      def call(argv)
+        raise NotImplementedError, "#{self.class} must implement #call(argv) and return an exit status"
+      end
+
+      private
+
+      # The terminal, for a command that needs one. Nothing built in does —
+      # `okf` is a one-shot tool — but a full-screen addon cannot work without
+      # it, and reaching for $stdin behind the CLI's back would put a command
+      # outside the stream injection every test depends on.
+      attr_reader :input
+
+      # Which slug each @ref resolved to, by absolute path — so a hub built from
+      # refs mounts each bundle under its registered slug, not its dir basename.
+      # Per command instance, which is per run: a command is built fresh for each
+      # dispatch, so the memo cannot outlive the argv that filled it. (It used to
+      # need clearing by hand at the top of #run; one command object per run is
+      # what retired that.)
+      attr_reader :ref_slugs
+
+      # `@all` is a ref, not a flag, and only `search` expands it — but the
+      # refusal the other verbs give lives in the shared resolver, so the
+      # recognizer has to be shared too.
+      def all_ref?(ref)
+        require "okf/registry"
+        OKF::Registry.normalize(ref[1..-1]) == ALL_REF[1..-1]
+      end
+
+      # A registered bundle whose directory cannot be read, noted and skipped.
+      # Shared because both the verbs that tolerate a gap — `search @all` and the
+      # bundle-less `server` — have to skip it the same way, and say so the same
+      # way. A named @slug never lands here: it fails hard instead.
+      def skip_registered(entry)
+        @err.puts "note: skipping #{entry.slug} — cannot read #{entry.path}"
+        nil
+      end
+
+      # Nothing left over. The registry subcommands each take a fixed number of
+      # positionals, and so does every `<dir>` verb through positional_dir — a
+      # trailing argument means the command was misunderstood, not that it can be
+      # answered anyway.
+      def no_extras?(argv)
+        return true if argv.empty?
+
+        @err.puts "error: unexpected argument '#{argv.first}'"
+        false
+      end
+
+      # ── the read views ──
+      # The Catalog / Files / Tags / Stats views the server renders in the browser,
+      # reproduced on the CLI so an agent can read the same knowledge without one.
+      # Each prints a scannable human view by default and machine JSON with --json;
+      # all are advisory reads (exit 0). They share OKF::Bundle#catalog for their data,
+      # and (with `types`) narrow through the same --type/--area/--tag filters the
+      # server UI offers, so browser and CLI can answer the same questions.
+      #
+      # ── their shared --type/--area/--tag narrowing ──
+      # Each view takes the filters orthogonal to it (tags can't filter by tag).
+      # Matching is case-insensitive and exact; a concept at the bundle root lives in
+      # the "(root)" area, which --area also accepts as plain `root` (no shell quoting).
+
+      # The shared back half of `tags` and `types`: load, narrow, print.
+      def print_inverted_index(dir, label, key, plural, options)
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        graph = folder.graph(minimal: true)
+        index = key == :tag ? graph.tag_index : graph.type_index
+        rows = index_rows(index, key, folder, options)
+        if options[:json]
+          print_index_json(dir, plural, key, rows)
+        else
+          titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
+          print_index(dir, label, key, rows, titles)
+        end
+        0
+      end
+
+      # The --json / --pretty pair every emitting verb shares. --json is the compact
+      # machine substrate (the default JSON form, aligned with the server); --pretty
+      # indents it for a human and implies --json. Both route through emit_json.
+      def json_flags(parser, options, desc)
+        parser.on("--json", desc) { options[:json] = true }
+        parser.on("--pretty", "indent the JSON for reading (implies --json)") { options[:json] = true; @pretty = true }
+      end
+
+      # Every parser answers its own -h/--help, so no parser inherits
+      # OptionParser's officious one: that prints to the process's $stdout rather
+      # than @out (an embedding app that injects streams never sees it) and ends
+      # the process with `exit` rather than returning a status (a test that asks a
+      # command for help takes the whole runner down with it). Thrown, not
+      # returned — #run catches it — because a parser is parsed inside
+      # positional_dir, where every other early exit means "exit 2".
+      # on_tail, so help sorts last in the list it is printing.
+      def help_flag(parser)
+        parser.on_tail("-h", "--help", "print this message") do
+          @out.puts parser.help
+          throw :help, 0
+        end
+      end
+
+      # --fields/--except project the JSON down to the properties an agent wants, so it
+      # never pays tokens for fields it will not read. --fields is an allowlist,
+      # --except a denylist (mutually exclusive); both imply --json and apply per item
+      # in a list view (catalog, files, index). Names are the JSON keys, matched
+      # case-insensitively.
+      def projection_flags(parser, options)
+        parser.on("--fields LIST", Array, "emit only these JSON properties (comma-separated)") { |v| options[:json] = true; options[:fields] = v }
+        parser.on("--except LIST", Array, "emit every JSON property but these") { |v| options[:json] = true; options[:except] = v }
+      end
+
+      def filter_flags(parser, options, *keys)
+        parser.on("--type TYPE", "only concepts of this type") { |v| options[:type] = v } if keys.include?(:type)
+        parser.on("--area AREA", "only concepts in this top-level area") { |v| options[:area] = v } if keys.include?(:area)
+        parser.on("--tag TAG", "only concepts carrying this tag") { |v| options[:tag] = v } if keys.include?(:tag)
+      end
+
+      def filter_entries(entries, options)
+        entries.select do |entry|
+          (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
+            (options[:area].nil? || fold(entry[:area]) == fold_area(options[:area])) &&
+            (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
+        end
+      end
+
+      def fold(value)
+        value.to_s.downcase
+      end
+
+      def fold_area(value)
+        folded = fold(value)
+        folded == "root" ? "(root)" : folded
+      end
+
+      # Turn an inverted index ({ value => [id, …] }) into display rows ordered by
+      # count, narrowed to the concepts the active filters select; rows the narrowing
+      # empties drop. With no filters the index passes through whole.
+      def index_rows(index, key, folder, options)
+        keep = filter_ids(folder, options)
+        index.each_with_object([]) do |(value, ids), rows|
+          ids = ids.select { |id| keep.include?(id) } unless keep.nil?
+          rows << { key => value, count: ids.length, concepts: ids } unless ids.empty?
+        end.sort_by { |row| [ -row[:count], row[key] ] }
+      end
+
+      # The ids the filters select, resolved through the catalog metadata — or nil
+      # when no filter is active, meaning keep everything.
+      def filter_ids(folder, options)
+        return nil if options[:type].nil? && options[:area].nil? && options[:tag].nil?
+
+        filter_entries(folder.catalog, options).map { |entry| entry[:id] }
+      end
+
+      # §9 best-effort: the graph is built from concepts that parse. Surface any that
+      # the reader could not parse (to stderr, so JSON on stdout stays clean) rather
+      # than dropping them silently.
+      def report_skipped(folder)
+        note_skipped(folder.bundle.unparseable.size)
+      end
+
+      # The bucket holds two kinds now — frontmatter that would not parse, and a
+      # file that would not open — so the note names neither and points at the verb
+      # that names both. "invalid frontmatter" was a guess the summary had no need
+      # to make: `validate` prints the file and the reason for every one of them.
+      def note_skipped(count)
+        return if count.nil? || count <= 0
+
+        @err.puts "note: skipped #{count} unusable file(s) (run `okf validate` for details)"
+      end
+
+      # Parse options, then require a single bundle positional — a directory, or an
+      # @ref into the registry. Returns the bundle's directory, or nil (after
+      # reporting) so the caller returns 2.
+      def positional_dir(parser, argv)
+        parser.parse!(argv)
+        dir = argv.shift
+        if dir.nil?
+          @err.puts parser.banner
+          return nil
+        end
+        # A second bundle is a question this verb cannot answer: only `search`
+        # merges across bundles and only `server` mounts several. Reading the
+        # first and dropping the rest would answer confidently about a bundle the
+        # user never asked about — the silent-wrong-answer shape, so: exit 2.
+        return nil unless no_extras?(argv)
+
+        resolve_ref(dir)
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        nil
+      end
+
+      # Parse options, then take zero or more bundle positionals (the multi-bundle
+      # server) — directories or @refs. Returns the resolved array (possibly
+      # empty), or nil (after reporting) so the caller returns 2.
+      def positional_dirs(parser, argv)
+        parser.parse!(argv)
+        dirs = argv.map { |dir| resolve_ref(dir) }
+        dirs.include?(nil) ? nil : dirs
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        nil
+      end
+
+      # "@slug" — or bare "@", the registry's default — names a registered bundle
+      # wherever a <dir> goes; anything else must be a directory on disk. A
+      # leading @ always means the registry (a directory literally named that way
+      # stays reachable as ./@name), and the registry loads only when a ref
+      # appears, so plain-dir invocations never pay for it. Returns the bundle's
+      # directory, or nil after reporting.
+      def resolve_ref(arg)
+        return resolve_registered(arg) if arg.start_with?("@")
+
+        unless File.directory?(arg)
+          @err.puts "error: #{arg} is not a directory or a registry ref " \
+                    "(@slug names a registered bundle, @ the default; okf registry list)"
+          return nil
+        end
+        arg
+      end
+
+      # Load the registry, turning a malformed file into a reported usage error
+      # instead of an OKF::Error escaping through whatever verb took an @ref —
+      # only `server` and the `registry` verbs rescue one. Returns nil after
+      # reporting, so every caller returns 2.
+      def load_registry
+        require "okf/registry"
+        OKF::Registry.load
+      rescue OKF::Error => e
+        @err.puts "error: #{e.message}"
+        nil
+      end
+
+      # Resolve one @ref through the registry under $OKF_HOME (default ~/.okf).
+      # The slug part is normalized
+      # exactly as registration normalized it, so @One finds the bundle
+      # registered from dir One — but never through #slugify's mint-a-name
+      # placeholder, so "@***" is a bad ref rather than whatever is slugged
+      # "bundle". An explicit ask fails hard: an unknown slug or a
+      # registered-but-gone directory is a usage error naming the registry file
+      # and the next move, never a silent skip.
+      #
+      # @all never resolves here. `search` expands it before this point; every
+      # other verb takes exactly one bundle, so letting it through would mean
+      # @all lints when one bundle is registered and exits 2 when two are —
+      # behavior that varies with the size of the registry, which is the
+      # silent-wrong-answer shape the second-bundle rule exists to stop. Say what
+      # @all is instead of calling it a bundle nobody registered ("all" cannot be
+      # registered — Registry::RESERVED_SLUGS sees to that).
+      def resolve_registered(ref)
+        @ref_failure = :registry
+        if all_ref?(ref)
+          @err.puts "error: #{ALL_REF} is only supported by `okf search` (it names every registered bundle)"
+          return nil
+        end
+        registry = load_registry
+        return nil unless registry
+
+        asked = ref[1..-1]
+        slug = OKF::Registry.normalize(asked)
+        entry = if asked.empty?
+                  registry.default # bare "@"
+                elsif slug.empty?
+                  nil # "@***" — nothing to look up, and no placeholder to fall back on
+                else
+                  registry.get(slug)
+                end
+        if entry.nil?
+          @ref_failure = :unknown
+          hint = registry.empty? ? "okf registry set <dir>" : "okf registry list"
+          @err.puts "error: not a registered bundle: #{ref} in #{registry.path} (#{hint})"
+          return nil
+        end
+        unless File.directory?(entry.path)
+          @ref_failure = :missing
+          @err.puts "error: #{ref} points to #{entry.path}, which is not a directory (okf registry del #{entry.slug}, or restore it)"
+          return nil
+        end
+        ref_slugs[entry.path] = entry.slug
+        entry.path
+      end
+
+      # Every bundle-scoped output names its bundle in the identity the caller
+      # used: `@handbook (/path)` when they named a registered bundle, the plain
+      # path otherwise. A dir named by path stays a path — inventing a slug for it
+      # would imply a registration that does not exist, and looking one up would
+      # cost a registry read on every plain-dir run.
+      def bundle_label(dir)
+        slug = ref_slugs[dir]
+        slug ? "@#{slug} (#{dir})" : dir.to_s
+      end
+
+      # The JSON head for one bundle. `bundle` is always its directory and `slug`
+      # always a registry slug — never the same key meaning two things — so a
+      # consumer resolves a row to a file without a second lookup.
+      def bundle_head(dir)
+        head = { "bundle" => dir }
+        slug = ref_slugs[dir]
+        head["slug"] = slug if slug
+        head
+      end
+
+      # Parse options, then require a single non-directory positional (e.g. a slug).
+      # Returns it, or nil (after reporting the banner) so the caller returns 2.
+      def positional(parser, argv)
+        parser.parse!(argv)
+        value = argv.shift
+        if value.nil?
+          @err.puts parser.banner
+          return nil
+        end
+        value
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        nil
+      end
+
+      def print_index(dir, label, key, rows, titles)
+        @out.puts "#{label} — #{bundle_label(dir)} (#{rows.size} distinct)"
+        @out.puts
+        width = rows.map { |row| row[key].length }.max || 0
+        rows.each do |row|
+          names = row[:concepts].map { |id| titles[id] || id }.join(", ")
+          @out.puts "  #{row[key].ljust(width)}  #{row[:count].to_s.rjust(3)}   #{truncate(names, 78)}"
+        end
+      end
+
+      def print_index_json(dir, plural, key, rows)
+        emit_json(bundle_head(dir).merge("count" => rows.size, plural => index_rows_json(key, rows)))
+      end
+
+      def index_rows_json(key, rows)
+        rows.map { |row| { key.to_s => row[key], "count" => row[:count], "concepts" => row[:concepts] } }
+      end
+
+      # "3 concepts", "1 concept", "1 of 7 concepts" — the noun agrees with the
+      # number it follows: the size when that is all we show, the total otherwise.
+      def counted(size, total, noun)
+        return "#{size} #{pluralize(size, noun)}" if size == total
+
+        "#{size} of #{total} #{pluralize(total, noun)}"
+      end
+
+      # The gem's whole vocabulary is regular, so a naive +s is not a shortcut —
+      # it is the rule. Callers pass the singular.
+      def pluralize(count, noun)
+        count == 1 ? noun : "#{noun}s"
+      end
+
+      # The single JSON writer. Compact by default — the token-efficient substrate an
+      # agent consumes; --pretty indents it for a human. JSON semantics are identical
+      # either way, so a parser never cares which was emitted.
+      def emit_json(payload)
+        @out.puts(@pretty ? JSON.pretty_generate(payload) : JSON.generate(payload))
+      end
+
+      # Emit a list view's JSON envelope with --fields/--except projection applied to
+      # each item. Returns the verb's exit code (0, or 2 on a bad projection request —
+      # both flags at once, or a field name no item carries).
+      # +dir+ is the bundle's directory — or a ready-made head Hash when the
+      # payload spans bundles (multi-bundle search's "bundles" key).
+      # +key+ names the JSON property the rows land under; +shape+ names the row
+      # shape to check --fields/--except against. They are the same for every view
+      # but search, whose two modes emit the same property from different rows.
+      def emit_list_json(dir, key, items, options, extra = {}, shape = key)
+        return usage_error("--fields and --except are mutually exclusive") if options[:fields] && options[:except]
+
+        unknown = unknown_fields(items, options, shape)
+        return usage_error("unknown field(s): #{unknown.join(", ")} (available: #{available_fields(items, shape).join(", ")})") unless unknown.empty?
+
+        payload = (dir.is_a?(Hash) ? dir.dup : bundle_head(dir)).merge(extra)
+        payload["count"] = items.size
+        payload[key] = project(items, options)
+        emit_json(payload)
+        0
+      end
+
+      # Keep only --fields (allowlist) or drop --except (denylist) from each item's
+      # top-level properties; unset flags pass the items through whole.
+      def project(items, options)
+        return items if options[:fields].nil? && options[:except].nil?
+
+        fields = options[:fields]&.map(&:downcase)
+        except = options[:except]&.map(&:downcase)
+        items.map do |item|
+          fields ? item.select { |k, _| fields.include?(k.to_s.downcase) } : item.reject { |k, _| except.include?(k.to_s.downcase) }
+        end
+      end
+
+      # The declared shape wins over the data's, so the same typo gets the same
+      # answer whether or not the result happened to have rows; a view with no
+      # declared shape falls back to what it actually emitted.
+      def available_fields(items, key = nil)
+        ROW_FIELDS[key] || (items.first ? items.first.keys.map(&:to_s) : [])
+      end
+
+      # Requested field names that no item actually carries — a typo guard (exit 2),
+      # matching how lint rejects unknown check names.
+      def unknown_fields(items, options, key = nil)
+        requested = (Array(options[:fields]) + Array(options[:except])).map(&:downcase)
+        return [] if requested.empty?
+
+        known = available_fields(items, key).map(&:downcase)
+        return [] if known.empty? # an unknown view: no shape to check against, so accept
+
+        requested.reject { |field| known.include?(field) }.uniq
+      end
+
+      def usage_error(message)
+        @err.puts "error: #{message}"
+        2
+      end
+
+      def stringify(hash)
+        hash.map { |key, value| [ key.to_s, value ] }.to_h
+      end
+
+      def truncate(str, max)
+        str.length > max ? "#{str[0, max - 1]}…" : str
+      end
+
+      def paint(text, code)
+        return text unless @out.respond_to?(:tty?) && @out.tty?
+
+        "\e[#{code}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/okf/cli/files.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Every file with its title, grouped by folder — the view for "what is on disk"
+    # rather than "what is modelled".
+    class Files < Command
+      def self.id
+        :files
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "files     <dir|@slug> [--json] [filters]", "list files with titles, by folder" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf files <dir|@slug> [--type T] [--area A] [--tag T] [--json]"
+          json_flags(o, options, "emit the file tree as JSON")
+          projection_flags(o, options)
+          filter_flags(o, options, :type, :area, :tag)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        entries = folder.catalog
+        selected = filter_entries(entries, options)
+        return print_files_json(dir, selected, options) if options[:json]
+
+        print_files(dir, selected, entries.size)
+        0
+      end
+
+      private
+
+      def print_files(dir, entries, total)
+        @out.puts "Files — #{bundle_label(dir)} (#{counted(entries.size, total, "file")})"
+        entries.group_by { |entry| entry[:dir] }.sort_by(&:first).each do |folder, group|
+          width = group.map { |entry| File.basename("#{entry[:id]}.md").length }.max
+          @out.puts
+          @out.puts "  #{folder == "." ? "(root)" : "#{folder}/"}"
+          group.each do |entry|
+            @out.puts "    #{File.basename("#{entry[:id]}.md").ljust(width)}  #{entry[:title]}"
+          end
+        end
+      end
+
+      def print_files_json(dir, entries, options)
+        files = entries.map do |entry|
+          { "path" => "#{entry[:id]}.md", "id" => entry[:id], "dir" => entry[:dir], "type" => entry[:type], "title" => entry[:title],
+            "description" => entry[:description] }
+        end
+        emit_list_json(dir, "files", files, options)
+      end
+    end
+
+    register(Files)
+  end
+end

data/lib/okf/cli/graph.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The knowledge graph as text — nodes, edges and the rollups the browser page
+    # draws, for a reader that has no browser.
+    class Graph < Command
+      def self.id
+        :graph
+      end
+
+      def self.group
+        :graph
+      end
+
+      def self.help_rows
+        [
+          [ "graph     <dir|@slug> [--json] [--minimal] [--hubs]", "print the knowledge graph" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false, minimal: false, body: true, hubs: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf graph <dir|@slug> [--json] [--minimal] [--no-body] [--hubs]"
+          json_flags(o, options, "emit nodes and edges as JSON")
+          o.on("--minimal", "leanest nodes (id + title); adds type/tag indexes") { options[:minimal] = true }
+          o.on("--[no-]body", "include each concept's body (default: yes)") { |v| options[:body] = v }
+          o.on("--hubs", "rank concepts by inbound links, with the source areas") { options[:hubs] = true }
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        return print_hubs(dir, options) if options[:hubs]
+
+        folder = OKF::Bundle::Folder.load(dir)
+        graph = folder.graph(minimal: options[:minimal], body: options[:body])
+        report_skipped(folder)
+        if options[:json]
+          # The head every view carries: a payload of nodes and edges that never
+          # says which bundle they came from is exactly what an agent holding
+          # several bundles has to guess at.
+          payload = bundle_head(dir).merge(graph.to_h)
+          payload = payload.merge(types: graph.type_index, tags: graph.tag_index) if options[:minimal]
+          emit_json(payload)
+        else
+          @out.puts "Graph — #{bundle_label(dir)} (#{graph.nodes.size} #{pluralize(graph.nodes.size, "concept")}, " \
+                    "#{graph.edges.size} #{pluralize(graph.edges.size, "link")})"
+        end
+        0
+      end
+
+      private
+
+      # `graph --hubs`: the inbound ranking with each hub's links grouped by
+      # source area — the "is this hub well-homed?" evidence. A hub whose
+      # inbound majority comes from outside its own area is a move candidate;
+      # --minimal/--no-body shape node payloads and change nothing here.
+      def print_hubs(dir, options)
+        folder = OKF::Bundle::Folder.load(dir)
+        hubs = folder.hubs
+        report_skipped(folder)
+        if options[:json]
+          rows = hubs.map { |row| { "id" => row[:id], "area" => row[:area], "inbound" => row[:inbound], "by_area" => row[:by_area] } }
+          emit_json(bundle_head(dir).merge("count" => hubs.size, "hubs" => rows))
+        else
+          @out.puts "Hubs — #{bundle_label(dir)} (#{counted(hubs.size, folder.concepts.size, "concept")} with inbound links)"
+          @out.puts
+          width = hubs.map { |row| row[:id].length }.max || 0
+          dwidth = hubs.map { |row| row[:inbound].to_s.length }.max || 0
+          hubs.each do |row|
+            sources = row[:by_area].map { |area, count| "#{area} #{count}" }.join(", ")
+            @out.puts "  #{row[:id].ljust(width)}  ×#{row[:inbound].to_s.rjust(dwidth)}   #{sources}"
+          end
+        end
+        0
+      end
+    end
+
+    register(Graph)
+  end
+end